startup-plan/技术设计/capi-contract-for-ios.md

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 续期。

响应格式

// 成功
{ "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 登录响应：

{
  "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? }

状态响应：

{
  "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）