# 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 端做本地化映射（中 → 英/其他语言）