文档审核流程总结
一、整体设计理念
文档审核系统的核心目标是：在"内容发布"这个关键节点引入一个可配置的人工审核卡口，确保对外发布的知识库文档都经过审核员审查后才能进入 RAG 检索管线（建立向量索引、全文搜索、知识图谱）。
系统通过环境变量 DOCUMENT_REQUIRE_APPROVAL 控制是否开启审核模式，使得同一套代码可以在不同环境中灵活调整：
- 开发环境可关闭审核，快速迭代；
- 生产环境开启审核，保障内容质量。
二、文档状态说明
系统中的文档一共有四种状态，形成一个状态机，所有生命周期操作都在这几个状态之间流转：
| 状态 | 含义 |
|---|---|
| 草稿（Draft） | 文档初始状态，仅作者可见，内容未进入任何检索索引 |
| 待审核（PendingReview） | 作者已提交审核，文档进入冻结状态，禁止编辑，等待审核员处理 |
| 已发布（Published） | 文档对外可见，已进入 RAG 向量索引、全文搜索、知识图谱 |
| 已归档（Archived） | 文档下架，已从检索管线中清除，不再对外展示 |
三、核心业务流程
3.1 文档创建
作者通过编辑器撰写文档，创建时状态默认为草稿。
- 开启审核模式下：禁止创建时直接将文档设置为"已发布"，必须先创建草稿，再通过发布操作进入审核流程。
- 关闭审核模式下：允许创建时直接指定状态为已发布，系统会同步触发索引构建。
3.2 提交审核（作者操作）
当作者认为内容已准备好，点击"发布"后，系统根据审核开关判断走哪条路径：
路径 A：开启审核模式
- 系统在审核流水表中新建一条待审记录，记录提审前的文档状态（before_status）；
- 文档主表状态变更为待审核（PendingReview）；
- 若该文档提审前已处于"已发布"状态（例如对已上线文档修改后再次提审），系统会同步将该文档从检索管线中清除（下架旧索引），避免读者检索到修改中的内容；
- 文档进入冻结状态：待审核期间，作者无法再修改文档的正文和标题，确保审核员看到的内容和最终发布的内容一致。
路径 B：关闭审核模式
- 文档直接变更为**已发布（Published）**状态；
- 系统同步向消息队列投递发布任务，异步触发 RAG 分块与向量化、全文搜索索引、知识图谱建图，文档立即可被检索。
3.3 审核员处理（审核员操作）
审核员在工作台可查看所有待审文档列表，也可以按状态筛选（待办 / 已通过 / 已驳回）。审核员在阅读文档内容后，进行如下操作之一：
审核通过
- 审核记录回填审核结果（通过）、审核员信息、审核意见、审核时间；
- 文档主表状态变更为已发布（Published），发布时间更新为当前时刻；
- 系统向消息队列投递发布任务，触发 RAG 向量构建、全文搜索索引、知识图谱建图；
- 文档正式对外可见，可被用户检索和引用。
审核驳回
- 审核记录回填审核结果（驳回）、审核员信息和必填的驳回意见；
- 文档主表状态回退至草稿（Draft），文档冻结解除，作者可重新编辑；
- 作者修改文档后，可再次提交审核，开启新一轮审核流程；
- 每次提审都会在流水表产生独立的一条审核记录，完整保留审核历史。
3.4 文档归档（作者/管理员操作）
已发布的文档可以主动归档，将其从对外检索中撤除：
- 文档状态变更为已归档（Archived）；
- 系统向消息队列投递下架任务，清除该文档在 RAG 向量库、全文搜索、知识图谱中的所有数据。
3.5 退回草稿（作者操作）
已发布的文档可以退回草稿重新编辑：
- 文档状态变更为草稿（Draft）；
- 系统同步清除检索索引；
- 作者完成修改后，再次走提审 → 审核通过的完整流程。
3.6 软删除
作者或管理员删除文档时，系统执行软删除（不物理清除数据）：
- 如果文档当前处于已发布状态，删除前先清除检索索引，避免残留脏数据；
- 草稿、待审核、已归档状态的文档无需清索引，直接标记删除即可。
四、状态流转全图
创建
│
▼
草稿（Draft）
│
│ 点击发布
│
├──【开启审核】──▶ 待审核（PendingReview）──【通过】──▶ 已发布（Published）
│ │ │
│ └──【驳回】──▶ 草稿（Draft） │
│ │
└──【免审模式】──────────────────────────────────────▶ 已发布（Published）
│
┌───────────────────┤
│ │
归档 ▼ 退回草稿 ▼
已归档（Archived） 草稿（Draft）
(索引已清) (索引已清)五、异步索引管线（Claim-Check 模式）
无论是"审核通过发布"还是"免审直接发布"，文档的索引构建均采用异步消息队列驱动的方式，而非在接口请求中同步执行：
- 应用层只向 RabbitMQ 投递一条轻量消息（仅含文档 ID），接口立即返回，不阻塞用户操作；
- 消费端（PipelineOrchestrator）接收到消息后，自行从 PostgreSQL 加载元数据、从 MongoDB 加载正文内容；
- 消费端执行 RAG 分块与向量化、全文搜索建索引、知识图谱建图等耗时操作；
- 即使索引构建失败，也不会影响文档本身的发布状态，失败信息仅记录警告日志，不对用户报错。
这种设计确保了发布接口的高可用性，并将计算密集型任务与主业务流程完全解耦。
六、审核流水记录机制
系统为每次审核操作在独立的审核流水表（kh_document_review）中留下完整的历史记录，每条记录包含：
- 提审前状态：记录文档提审时的原始状态，便于驳回后准确回退；
- 审核员信息：审核员 ID 与姓名；
- 审核结果：待审 / 通过 / 驳回（结果为空表示尚未处理）；
- 审核意见：驳回时必填，通过时可选；
- 审核时间：精确到毫秒的审核完成时间；
- 提审时间：记录在记录的创建时间中。
同一篇文档允许存在多条历史流水，但任意时刻最多只有一条结果为空的待审记录，确保审核状态的唯一性。审核员和作者均可随时查询某篇文档的全部历史审核记录，追溯每一次审核的完整过程。