# iOS CAPI 接口契约

> 版本：0.1.0 | 更新：2026-05-24 | 基础 URL：`https://api.longde.cloud`

## 通用约定

### 认证

所有 `/api/*` 端点需要 JWT Bearer Token：

```
Authorization: Bearer <access_token>
```

Token 通过 Apple 登录获取，有效期 1 小时，用 refresh token 续期。

### 响应格式

```json
// 成功
{ "success": true, "data": <资源>, "timestamp": "2026-05-24T..." }

// 失败
{ "success": false, "statusCode": 401, "message": "请先登录" }
```

### 分页

请求参数：`?page=1&limit=20`（limit 上限 100）

响应格式因端点而异，无统一分页包装。常见结构为数据数组 + 通过 Data 字段间接判断。

### 错误码

| HTTP | 含义 |
|------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误（DTO 校验失败） |
| 401 | 未登录 / Token 过期 / 账号禁用 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 接口清单

### 1. 认证 `/api/auth`

| 方法 | 路径 | 说明 | Body |
|------|------|------|------|
| POST | `/api/auth/apple` | Apple 登录 | `{ identityToken, fullName?, email? }` |
| POST | `/api/auth/refresh` | 刷新 Token | `{ refreshToken }` |
| POST | `/api/auth/logout` | 登出 | `{ refreshToken }` |

**Apple 登录响应：**
```json
{
  "accessToken": "eyJ...",
  "refreshToken": "abc123...",
  "user": {
    "id": "cuid",
    "email": "user@example.com",
    "nickname": "用户",
    "avatarUrl": null,
    "role": "USER",
    "status": "active",
    "onboardingCompleted": false
  }
}
```

### 2. 用户 `/api/users`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/users/me` | 当前用户信息 |
| PATCH | `/api/users/me` | 更新用户信息 |
| GET | `/api/users/me/profile` | 用户资料 |
| PATCH | `/api/users/me/profile` | 更新资料 |
| PATCH | `/api/users/me/preferences` | 偏好设置 |
| GET | `/api/users/me/membership` | 会员信息 |
| DELETE | `/api/users/me` | 注销账号 |

### 3. 文件上传 `/api/files`

| 方法 | 路径 | 说明 | Body |
|------|------|------|------|
| POST | `/api/files/upload-url` | 获取预签名上传 URL | `{ filename, mimeType, sizeBytes }` |
| POST | `/api/files/complete` | 确认上传完成 | `{ objectKey, checksum? }` |
| GET | `/api/files/:id` | 获取文件信息 |
| DELETE | `/api/files/:id` | 删除文件 |

**上传流程：**
1. `POST /api/files/upload-url` → 获取 `{ uploadUrl, objectKey }`
2. iOS 直接 `PUT <uploadUrl>` 到 COS（腾讯云对象存储）
3. `POST /api/files/complete` → 确认完成，获取 `fileId`

### 4. 知识库 `/api/knowledge-bases`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/knowledge-bases` | 创建知识库 |
| GET | `/api/knowledge-bases` | 知识库列表 |
| GET | `/api/knowledge-bases/:id` | 知识库详情 |
| PATCH | `/api/knowledge-bases/:id` | 更新 |
| DELETE | `/api/knowledge-bases/:id` | 删除 |

### 5. 知识源 `/api/knowledge-bases/:kbId/sources`

| 方法 | 路径 | 说明 | Body DTO |
|------|------|------|----------|
| POST | `/api/knowledge-bases/:kbId/sources` | 添加资料来源 | `AddSourceDto` |
| GET | `/api/knowledge-bases/:kbId/sources` | 资料列表 | — |
| GET | `/api/knowledge-bases/:kbId/sources/:id` | 资料详情 | — |
| DELETE | `/api/knowledge-bases/:kbId/sources/:id` | 删除 | — |

**AddSourceDto：** `{ fileId?, type?, title?, originalFilename?, mimeType?, sizeBytes?, originalObjectKey? }`
- `type` 枚举：`file` | `link` | `manual` | `paste`

### 6. 文档导入 `/api/imports`

| 方法 | 路径 | 说明 | Body DTO |
|------|------|------|----------|
| POST | `/api/imports` | 创建导入任务 | `CreateImportDto` |
| GET | `/api/imports/:id/status` | 查询导入状态 | — |

**CreateImportDto：** `{ userId?, knowledgeBaseId?, fileName?, sourceType?, rawText? }`

**状态响应：**
```json
{
  "id": "import-001",
  "fileName": "笔记.pdf",
  "status": "QUEUED",
  "progress": 0,
  "message": "任务已加入队列"
}
```

### 7. 学习会话 `/api/learning-sessions`

| 方法 | 路径 | 说明 | Body DTO |
|------|------|------|----------|
| POST | `/api/learning-sessions` | 开始学习 | `StartSessionDto` |
| POST | `/api/learning-sessions/:id/end` | 结束会话 | — |
| GET | `/api/learning-sessions` | 会话列表 | Query: `?page=1&limit=20` |

**StartSessionDto：** `{ knowledgeItemId?, knowledgeBaseId?, mode? }`
- `mode` 枚举：`active_recall` | `feynman` | `review` | `reading`

### 8. 主动回忆 `/api/active-recalls`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/active-recalls` | 获取题目列表 |
| POST | `/api/active-recalls/:id/submit` | 提交回答 |

### 9. AI 分析 `/api/ai-analysis`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/ai-analysis` | 发起主动回忆分析 |
| POST | `/api/ai-analysis/feynman` | 发起费曼评估 |
| GET | `/api/ai-analysis/jobs/:id` | 查询作业状态 |
| GET | `/api/ai-analysis/:id` | 获取分析结果 |

### 10. 复习 `/api/reviews`

| 方法 | 路径 | 说明 | Body |
|------|------|------|------|
| GET | `/api/reviews/due` | 今日待复习 | — |
| POST | `/api/reviews/:id/submit` | 提交复习结果 | `SubmitReviewDto` |
| POST | `/api/reviews/generate-cards` | 生成卡片 | — |

### 11. 薄弱项 `/api/focus-items`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/focus-items` | 薄弱项列表 |
| POST | `/api/focus-items` | 创建 |
| PATCH | `/api/focus-items/:id` | 更新 |
| POST | `/api/focus-items/:id/complete` | 标记完成 |

### 12. 学习活动 `/api/activity`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/activity/heatmap` | 学习热力图 |
| GET | `/api/activity/summary` | 活动摘要 |
| GET | `/api/activity/trend` | 学习趋势 |
| GET | `/api/activity/streak` | 连续打卡天数 |
| GET | `/api/activity/recommendations` | 学习推荐 |

### 13. RAG 对话 `/api/rag-chat`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/rag-chat/sessions` | 创建对话 |
| GET | `/api/rag-chat/sessions` | 对话列表 |
| POST | `/api/rag-chat/sessions/:id/messages` | 发送消息 |
| GET | `/api/rag-chat/sessions/:id/messages` | 消息历史 |
| DELETE | `/api/rag-chat/sessions/:id` | 删除对话 |

### 14. 通知 `/api/notifications`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/notifications` | 通知列表 |
| POST | `/api/notifications/:id/read` | 标记已读 |
| POST | `/api/notifications/read-all` | 全部已读 |
| GET/PATCH | `/api/notifications/preferences` | 通知偏好 |
| GET/POST/DELETE | `/api/notifications/push-tokens` | Push Token 管理 |

### 15. 其他

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/feedback` | 提交反馈（type: bug/feature/general） |
| GET | `/api/workspace/dashboard` | 工作台首页 |
| GET | `/api/workspace/recent` | 最近记录 |
| POST | `/api/workspace/favorites` | 收藏 |
| GET | `/api/workspace/search` | 搜索 |
| GET | `/api/workspace/search-history` | 搜索历史 |

---

## 全局请求头

| Header | 说明 |
|--------|------|
| `Authorization` | `Bearer <access_token>` |
| `Content-Type` | `application/json` |

## 限制

- 请求体大小：10MB（全局 pipe 限制）
- 文件上传大小：20MB（单个文件）
- Token 有效期：1 小时（access），7 天（refresh）