## 文档与代码一致性审查报告

审查范围：`docs/后端对接规范.md`、`docs/curl测试手册.md` vs 实际代码实现

审查方式：代码静态分析 + 生产模式服务实测（`DEV_MODE=false`，端口 5001）

---

### 一、严重问题（会导致后端开发出错）

**1. `/documents/list` 分页参数不存在**

curl测试手册中记载该接口支持 `page` 和 `page_size` 查询参数，但实际代码（`api/document_routes.py` 第385-440行）完全不读取这两个参数，只支持 `collection`/`kb_name` 过滤。实测传入 `page=1&page_size=2` 后返回了全部 4 条记录，分页无效。后端如果按文档实现分页将会静默失败。

**2. `/feedback/list` 查询参数不匹配**

curl测试手册记载参数为 `page` 和 `page_size`。实际代码（`api/feedback_routes.py` 第119-144行）接受的参数是 `rating`、`user_id`、`start_date`、`end_date`、`limit`（默认100），完全没有 `page`/`page_size`。后端按文档传参将无法控制返回数量。

**3. `/faq` GET 查询参数不匹配**

curl测试手册记载参数为 `page` 和 `page_size`。实际代码（`api/feedback_routes.py` 第177-193行）接受 `status` 和 `limit`（默认50），无分页支持。

**4. `/faq/suggestions` 查询参数不匹配**

与上同理，curl测试手册记载 `page`/`page_size`，实际代码使用 `status`（默认"pending"）和 `limit`（默认50）。

**5. `/documents/<path>/chunks` 分页参数不存在**

curl测试手册记载该接口支持 `page` 和 `page_size`，实际代码（`api/document_routes.py` 第637-678行）不接受任何查询参数，直接返回全部切片。

**6. 出题接口返回的 `question` 对象结构与文档不符**

后端对接规范文档中展示的出题响应结构为：

```json
{
  "question_type": "single_choice",
  "difficulty": 3,
  "content": { "stem": "...", "data": {...}, "answer": "B", "explanation": "..." },
  "source_trace": { ... }
}
```

但 `exam_pkg/api.py` 的 docstring 注释（第72行）写的是 `question_type` 嵌套在 `metadata` 对象中。不过经核查 `exam_pkg/generator.py` 第826-828行，实际返回结构与后端对接规范文档一致（`question_type` 在顶层），代码注释是错的但实际行为是对的。这不会导致功能问题，但如果有人参照代码注释来解析响应就会出错。

**7. 错误响应格式文档与实际不匹配**

后端对接规范「十、错误响应格式」声称所有错误遵循 `{"error": "xxx", "message": "xxx"}` 格式。但实际代码中混用两套格式：`api/response_utils.py` 的统一格式返回 `{"success": false, "status": "failed", "error_code": "xxx", "status_code": N, "message": "xxx"}`，而部分路由（如 feedback_routes、document_routes 的异常处理）直接返回 `{"error": str(e)}`。后端开发者需要同时处理两种错误格式。

---

### 二、中等问题（描述不准确，可能导致混淆）

**8. 环境配置变量名不一致**

后端对接规范第四节写的配置是 `APP_ENV=prod`，认证方式部分写的模式切换变量是 `DEV_MODE=false`。实际认证模块 `auth/gateway.py` 第98行读取的是 `DEV_MODE` 环境变量。而 `config.py` 中定义了 `APP_ENV` 但没有定义 `DEV_MODE`。两者是独立的变量：`APP_ENV` 控制 `IS_PROD`/`IS_DEV` 及关联功能开关（如 ENABLE_SESSION），`DEV_MODE` 单独控制认证行为。文档应将两者都列出并说明其区别。

**9. `/rag` 接口 `collections` 参数必需性描述矛盾**

后端对接规范中标注 `collections` 为「必需」，curl测试手册标注为「可选，默认 `["public_kb"]`」。代码实际行为是可选的（不传时默认 `["public_kb"]`）。对后端来说，应明确说明：如果不传 `collections`，将默认检索 `public_kb`，而非返回错误。

**10. 同步接口响应格式文档与代码不一致**

后端对接规范中 `/sync/start` 和 `/sync/stop` 响应为 `{"message": "文件监控已启动"}`。实际代码返回的是 `{"status": "success", "status_code": 3001, "message": "文件监控已启动"}`，多了 `status` 和 `status_code` 字段。curl测试手册是正确的。

**11. `/exam/generate` 和 `/exam/generate-smart` 的 `collection` 参数类型标注不完整**

curl测试手册标注为 `string`，后端对接规范标注为 `string 或 string[]`。实际代码（`exam_pkg/manager.py` 第212行和第286-289行）确实同时支持两种格式。curl测试手册应补充说明支持数组。

**12. curl测试手册中 `/exam/generate` 和 `/exam/generate-smart` 需要 Authorization header 的说明具有误导性**

文档提到「需要传 Authorization header」，curl 示例中也包含 `-H "Authorization: Bearer mock-token-admin"`。但在生产模式下（DEV_MODE=false），mock token 逻辑被跳过，认证直接放行，用户默认为 `backend-caller`。这个 header 在生产环境中完全无效，会误导后端以为必须传递。

---

### 三、轻微问题（不影响功能，但不够精确）

**13. 后端对接规范中 `/chat` 的 `chat_history` 参数**

文档参数说明中列出了 `chat_history`（生产环境必需）和 `history`（旧参数名）。但 `/chat` 普通聊天接口实际上只需要 `message`，`history`/`chat_history` 是可选参数。文档对 `/chat` 和 `/rag` 的 `chat_history` 必需性描述有混淆。

**14. curl测试手册中 `/exam/generate-smart` 章节重复**

文档中该接口的描述出现了两次（内容高度重复），应删除其中一个。

**15. 后端对接规范中的 `require_role('admin')` 描述**

文档在 FAQ 创建、审批等接口旁标注了需要管理员角色。但实际 `auth/gateway.py` 中的 `require_role` 装饰器是空操作（passthrough），不做任何权限检查。在生产模式下默认用户角色是 `user`，但所有标注 admin 的接口都能正常调用。文档描述虽符合设计意图，但与当前实现不符。

**16. curl测试手册中 `/feedback` POST 的 `answer` 字段标注**

文档标注 `answer` 为必需，但实际代码中 `answer` 字段是可选的（可以为空字符串）。

**17. 代码中存在文档未记录的端点**

以下端点存在于代码但未在文档中列出（多为开发调试用，不影响后端对接）：`/auth/login`、`/auth/me`、`/auth/users`、`/auth/change-password`、`/stats`、`/debug/scan`、`/collections/sync-vlm-cache`、`/collections/<name>/reindex`、`/chunks/batch`、`/documents/<path>/raw`。

**18. `/feedback/list` 返回的 `sources` 字段**

curl测试手册的响应示例中 `sources` 为空数组 `[]`，但实际测试中有些反馈记录包含非空的 `sources` 数组（包含来源文档信息）。文档的示例不够完整。

---

### 四、文档间不一致

| 对比项 | 后端对接规范 | curl测试手册 | 实际代码 |
|--------|-------------|-------------|---------|
| `/rag` collections 必需性 | 必需 | 可选，默认 `["public_kb"]` | 可选 |
| `/documents/list` 分页 | 未提及 | `page`/`page_size` | 不支持 |
| `/feedback/list` 参数 | 未详述 | `page`/`page_size` | `limit`/`rating` 等 |
| `/faq` 参数 | `GET/POST` | `page`/`page_size` | `status`/`limit` |
| `/sync/start` 响应 | 简单格式 | 含 status_code | 含 status_code（curl手册正确） |
| 环境配置 | `APP_ENV=prod` | `DEV_MODE=false` | 两者各自控制不同功能 |

---

### 五、生产服务实测结果

| 端点 | 状态 | 备注 |
|------|------|------|
| `GET /health` | 正常 | 返回 ok |
| `GET /collections` | 正常 | 返回 3 个向量库 |
| `GET /documents/list` | 正常 | 分页参数无效，返回全部 |
| `GET /feedback/stats` | 正常 | |
| `GET /feedback/list` | 正常 | page/page_size 无效，返回全部 |
| `GET /faq` | 正常 | page/page_size 无效 |
| `GET /sync/status` | 正常 | |
| `GET /exam/health` | 正常 | |

---

### 六、修改建议优先级

1. **立即修复**（影响后端开发正确性）：修正 `/documents/list`、`/feedback/list`、`/faq`、`/faq/suggestions`、`/documents/<path>/chunks` 的查询参数描述，改为代码实际支持的参数
2. **尽快修复**（影响对接体验）：统一错误响应格式文档，列出两种格式及适用场景
3. **建议修复**（改善文档质量）：补充 `APP_ENV` 与 `DEV_MODE` 的区别说明、修正 `/rag` collections 必需性、删除 `/exam/generate-smart` 重复章节、移除出题接口中不必要的 Authorization header 要求说明