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>
3.8 KiB
3.8 KiB
CAPI 错误码与状态枚举
版本：0.1.0 | 更新：2026-05-24
HTTP 错误码
| HTTP | message | 触发场景 |
|---|---|---|
| 200 | — | 成功 |
| 201 | — | 创建成功 |
| 400 | — | 请求参数校验失败（DTO validation） |
| 401 | "请先登录" | 未携带 Token |
| 401 | "登录已过期，请重新登录" | Token 过期或无效 |
| 401 | "账号已被禁用" | 用户 status ≠ active |
| 401 | "账号不存在或已注销" | 用户不存在或 deletedAt 不为空 |
| 401 | "无效的访问令牌" | 管理员 Token 访问 CAPI |
| 401 | "Apple 登录未配置，请联系管理员" | Apple 登录未配置 |
| 401 | "刷新令牌无效或已过期" | Refresh Token 无效 |
| 401 | "账号已注销" | 刷新时发现用户已注销 |
| 403 | "dev-login is disabled in production" | 生产环境尝试 dev-login |
| 404 | "资源不存在" | 资源未找到 |
| 500 | — | 服务器内部错误 |
模型状态枚举
User
| 字段 | 可选值 |
|---|---|
status |
active, disabled |
role |
USER, ADMIN |
KnowledgeBase
| 字段 | 可选值 |
|---|---|
status |
active, archived, deleted |
KnowledgeItem
| 字段 | 可选值 |
|---|---|
status |
active, archived |
itemType |
note, flashcard, concept |
KnowledgeSource
| 字段 | 可选值 |
|---|---|
parseStatus |
pending, parsing, completed, failed |
indexStatus |
pending, indexing, completed, failed |
learningStatus |
pending, learning, completed, skipped |
type |
file, link, manual, paste |
DocumentImport
| 字段 | 可选值 |
|---|---|
status |
QUEUED, CLAIMED, DOWNLOADING, PARSING, OCR_PROCESSING, VISION_PROCESSING, CLEANING, CHUNKING, EMBEDDING, INDEXING, GENERATING_CANDIDATES, COMPLETED, FAILED, FAILED_FINAL |
ImportCandidate
| 字段 | 可选值 |
|---|---|
status |
PENDING, ACCEPTED, REJECTED |
LearningSession
| 字段 | 可选值 |
|---|---|
status |
active, completed, cancelled |
mode |
active_recall, feynman, review, reading |
AiAnalysisJob
| 字段 | 可选值 |
|---|---|
status |
pending, processing, completed, failed |
jobType |
active_recall_analysis, feynman_evaluation |
ReviewCard
| 字段 | 可选值 |
|---|---|
status |
active, completed, archived |
scheduleState |
new, learning, review, relearning |
difficulty |
数值（0.0–1.0，SM-2 算法） |
ReviewPlan
| 字段 | 可选值 |
|---|---|
status |
active, completed, skipped |
FocusItem
| 字段 | 可选值 |
|---|---|
status |
open, completed |
priority |
high, normal, low |
Feedback
| 字段 | 可选值 |
|---|---|
type |
bug, feature, general |
status |
pending, reviewed, resolved, closed |
Notification
| 字段 | 可选值 |
|---|---|
scope |
user, admin |
iOS 处理建议
状态优先级
- UI 关心的状态子集：
| 模块 | 展示用状态 | 说明 |
|---|---|---|
| DocumentImport | QUEUED → PROCESSING(any intermediate) → COMPLETED / FAILED |
中间态统一显示为"处理中" |
| ReviewCard | new / learning / review / relearning |
scheduleState 比 status 更有用 |
| FocusItem | open / completed |
简单二态 |
| LearningSession | active / completed |
— |
-
轮询策略：
- DocumentImport 状态：初始 2s，后续 5s
- AI 分析作业：2s 间隔
- 最多轮询 5 分钟，超时提示用户
-
错误本地化：
- 后端返回中文错误消息
- 建议 iOS 端做本地化映射（中 → 英/其他语言）