rag/docs/文档审查报告.md

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

审查范围：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 对象结构与文档不符

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

{
  "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 要求说明