keyboard_backend/README.md

# Keyborad Backend

基于 Spring Boot 3.5.5 的后端服务，集成了 AI 能力、向量搜索、Apple 登录等功能。

## 技术栈

- **Java 17** + **Spring Boot 3.5.5**
- **Spring AI** - LLM 对话和文本嵌入（OpenAI 兼容 API）
- **Qdrant** - 向量数据库，支持语义搜索
- **PostgreSQL** - 关系型数据库
- **MyBatis Plus** - ORM 框架
- **Redis** - 会话存储和缓存
- **Sa-Token** - 认证授权框架
- **Knife4j** - API 文档
- **X-File-Storage** - 文件上传（Cloudflare R2）
- **MailerSend** - 邮件服务

## 核心功能

### 认证系统
- Apple Sign-In JWT 验证
- Sa-Token 会话管理
- 请求签名校验（防篡改/防重放）

### AI 能力
- LLM 对话（支持流式响应）
- 文本嵌入（1536 维向量）
- 语义搜索（Qdrant 向量检索）

### 通用功能
- 统一响应格式
- 全局异常处理
- 国际化支持（i18n）
- 请求日志记录

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.8+
- PostgreSQL 14+
- Redis 6+

### 本地运行

1. 克隆项目
```bash
git clone <repository-url>
cd keyborad-backend
```

2. 配置数据库和 Redis
```yaml
# 修改 src/main/resources/application-dev.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/keyborad_db
    username: your_username
    password: your_password
  redis:
    host: localhost
    port: 6379
```

3. 启动应用
```bash
mvn spring-boot:run
```

4. 访问 API 文档
```
http://localhost:7529/api/doc.html
```

## 项目结构

```
src/main/java/com/yolo/keyborad/
├── controller/     # REST API 端点
├── service/        # 业务逻辑层
│   └── impl/       # 服务实现
├── mapper/         # MyBatis 数据库映射
├── model/
│   ├── entity/     # 数据库实体
│   ├── dto/        # 请求数据传输对象
│   └── vo/         # 响应视图对象
├── config/         # Spring 配置类
├── aop/            # AOP 拦截器
├── Interceptor/    # 请求拦截器
├── filter/         # Servlet 过滤器
├── exception/      # 异常处理
├── common/         # 通用工具类
└── utils/          # 工具类
```

## 配置说明

| 配置项 | 说明 | 默认值 |
|-------|------|-------|
| `server.port` | 服务端口 | 7529 |
| `server.servlet.context-path` | 上下文路径 | /api |
| `spring.profiles.active` | 激活配置文件 | dev |

## API 认证

### Sa-Token 认证
需要在请求头中携带 `satoken` 字段。

### 请求签名
部分接口需要签名校验，请求头需包含：
- `X-App-Id` - 应用 ID
- `X-Timestamp` - 时间戳
- `X-Nonce` - 随机数
- `X-Sign` - 签名

## 开发指南

详细的开发指南请参考 [CLAUDE.md](./CLAUDE.md)。

## License

MIT License