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>
123 lines
3.8 KiB
Markdown
123 lines
3.8 KiB
Markdown
# 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 处理建议
|
||
|
||
### 状态优先级
|
||
|
||
1. **UI 关心的状态子集：**
|
||
|
||
| 模块 | 展示用状态 | 说明 |
|
||
|------|-----------|------|
|
||
| DocumentImport | `QUEUED` → `PROCESSING`(any intermediate) → `COMPLETED` / `FAILED` | 中间态统一显示为"处理中" |
|
||
| ReviewCard | `new` / `learning` / `review` / `relearning` | scheduleState 比 status 更有用 |
|
||
| FocusItem | `open` / `completed` | 简单二态 |
|
||
| LearningSession | `active` / `completed` | — |
|
||
|
||
2. **轮询策略：**
|
||
- DocumentImport 状态：初始 2s，后续 5s
|
||
- AI 分析作业：2s 间隔
|
||
- 最多轮询 5 分钟，超时提示用户
|
||
|
||
3. **错误本地化：**
|
||
- 后端返回中文错误消息
|
||
- 建议 iOS 端做本地化映射（中 → 英/其他语言）
|