WangDL
0eb5f53873
- iOS integration readiness audit (blocker list, module map, deployment check) - CAPI contract for iOS (15 modules, 80+ endpoints) - CAPI error codes and status enums - iOS auth flow, file upload import flow, learning review flow - Web product page nginx fix (reenable longde.cloud) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
241 lines
7.3 KiB
Markdown
241 lines
7.3 KiB
Markdown
# 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）
|