leaudit-platform-backend/docs/内部公文模块/按阶段执行任务拆解清单.md

按阶段执行任务拆解清单

1. 文档目的

本文档基于以下两份已确认文档继续往下拆：

• 迁移前后业务语义对照分析.md
• 实施边界锁定后的补齐修复计划.md

目标是把后续工作拆成可执行任务，方便逐项审核、排期、实施和验收。

---

2. 执行总原则

每项任务都按同一口径执行：

• 业务语义按旧项目保持一致
• 代码实现按当前 leaudit-platform 规范落地
• 先做 P0，再做 P1，最后做 P2

每项任务都要求明确：

• 改什么
• 改哪里
• 不改什么
• 做完怎么验

---

3. 第一阶段：P0 闭环恢复

3.1 P0-1 恢复报告产物闭环

目标

恢复一次 govdoc run 完成后的正式产物闭环：

• annotated.docx
• report.html
• paragraphs.html

后端任务

1. 将旧项目报告生成逻辑映射到当前 govdoc_bridge 执行链路。
2. 在 run 执行完成后，正式生成报告产物，而不是只写规则结果。
3. 将生成后的产物上传到平台正式存储。
4. 将产物索引写入 govdoc_report_artifacts。
5. 确保同一 run 重复执行时，产物记录的覆盖/新增策略明确。

前端任务

1. 详情页的 批注 DOCX、报告 HTML 仅在真实产物存在时开放。
2. 列表页“报告”入口指向真实 HTML 报告。
3. 如果产物不存在，页面应明确呈现“未生成”，不能假成功。

SQL / 环境任务

1. 核对 govdoc_report_artifacts 字段是否满足产物索引需要。
2. 明确 OSS 路径命名规则和产物类型枚举。

重点文件

• fastapi_modules/fastapi_leaudit/govdoc_bridge/result_adapter.py
• fastapi_modules/fastapi_leaudit/govdoc_bridge/runner.py
• fastapi_modules/fastapi_leaudit/govdoc_bridge/storage_adapter.py
• fastapi_modules/fastapi_leaudit/services/impl/govdocServiceImpl.py
• legal-platform-frontend/components/govdoc-audit/audit.tsx
• legal-platform-frontend/components/govdoc-audit/audits.tsx

不改事项

• 不改现有文档主档模型
• 不改 document + run 结构
• 不改页面主入口语义

完成标准

• 新上传一份文档，run 完成后可下载批注 DOCX
• 新上传一份文档，run 完成后可打开 HTML 报告
• 段落视图可正常渲染并联动 findings

---

3.2 P0-2 收口详情结果对象

目标

把当前分散在多个接口里的详情结果，收口为稳定可渲染的完整业务对象。

后端任务

1. 明确详情页主接口的返回语义。
2. 确保以下数据在同一条业务语义上成立：
   • summary
   • findings
   • checked_rules
   • entities
   • structure
   • outline
   • reports
3. 明确“默认 latest run”和“指定历史 run”的组装规则。
4. 保证 checked_rules、findings、summary 三者统计一致。

前端任务

1. 详情页 API 适配层统一按 documentId 工作。
2. 历史 run 切换后，页面所有标签页和产物入口同步切换。
3. 错误态统一，不再出现部分接口成功、部分接口失败导致的半渲染页面。

SQL / 环境任务

1. 核对 run 结果摘要字段与详情页所需数据是否匹配。
2. 明确 result_summary_json 的职责边界，避免前后重复计算。

重点文件

• fastapi_modules/fastapi_leaudit/services/impl/govdocServiceImpl.py
• legal-platform-frontend/lib/api/govdoc-audit/api.ts
• legal-platform-frontend/components/govdoc-audit/audit.tsx

不改事项

• 不把详情入口改回 runId 主入口
• 不把前端强行改成只看局部接口数据

完成标准

• 详情页首次打开就能完整稳定渲染
• 切换历史 run 后，结果、报告、段落视图一致切换
• 不再依赖“某几个接口恰好成功”才能正常展示

---

3.3 P0-3 规则版本正式接入执行链路

目标

把 ruleVersionId 从“接口参数”变成“实际生效规则版本”。

后端任务

1. 明确 govdoc 模块应如何接入平台现有规则版本治理。
2. 打通：
   • 上传文档传入 ruleVersionId
   • 手动创建 run 传入 ruleVersionId
   • run 执行阶段解析规则版本
   • 实际加载该版本规则内容
3. 在 run 记录中保存本次实际使用的规则版本信息。
4. GetRuleDetail / ListRules 应与当前生效规则版本一致。

前端任务

1. 如果当前阶段不开放规则版本选择，则隐藏选择能力，避免假入口。
2. 如果开放规则版本选择，则页面选中的版本必须真生效。

SQL / 环境任务

1. 明确 govdoc 与平台规则版本表的关联方式。
2. 如需新增字段或绑定关系，纳入正式 schema / migration。

重点文件

• fastapi_modules/fastapi_leaudit/controllers/govdocController.py
• fastapi_modules/fastapi_leaudit/services/impl/govdocServiceImpl.py
• fastapi_modules/fastapi_leaudit/govdoc_bridge/tasks.py
• 平台规则版本治理相关实现

不改事项

• 不长期依赖硬编码本地规则路径作为正式方案

完成标准

• 指定规则版本后，执行结果能证明使用的是该版本
• 审查结果页、规则页、run 记录的规则版本信息一致

---

3.4 P0-4 数据库与初始化正式化

目标

将当前运行时兜底初始化，收口为正式初始化方案。

后端任务

1. 梳理 govdoc 所需正式表、索引、字段、默认值。
2. 明确哪些保留运行时兜底，哪些必须前置初始化。
3. 去掉“必须先访问接口一次，表才建出来”的隐性依赖。

前端任务

1. 无直接改动要求，主要配合环境验证。

SQL / 环境任务

1. 整理并核对：
   • govdoc_runs
   • govdoc_rule_results
   • govdoc_report_artifacts
   • leaudit_documents.engine_type
2. 核对权限、菜单、entry module 种子 SQL。
3. 新环境按正式 SQL 能一次初始化完成。

重点文件

• scripts/创建sql/schema_add_govdoc_module.sql
• 权限与 entry module 相关 seed SQL
• fastapi_modules/fastapi_leaudit/services/impl/govdocServiceImpl.py

不改事项

• 不删除必要兜底逻辑前，先保证正式初始化可跑通

完成标准

• 全新环境初始化后可直接运行
• 不再出现缺表导致的 404/500

---

4. 第二阶段：P1 质量与一致性补齐

4.1 P1-1 核心实体识别调优

目标

优先把对业务最关键的实体识别稳定下来：

• 标题
• 发文字号
• 日期
• 署名
• 主送机关
• 文种

后端任务

1. 梳理旧项目实体抽取逻辑与当前 govdoc_engine 的差异。
2. 逐项修正：
   • docx_parser
   • role_tagger_rule
   • entity_builder
3. 确保“先结构化抽取，后差量 LLM 抽取”的语义不变。

前端任务

1. 实体页展示逻辑跟随后端真实结果，不自行兜假值。

验证任务

1. 选取典型正反例文档做实体识别比对。
2. 建一组固定验收样本。

完成标准

• 核心实体识别达到可验收水平
• 正反例结果基本符合业务预期

---

4.2 P1-2 高频规则误判修正

目标

优先解决最影响结果可信度的规则误判/漏判。

后端任务

1. 梳理当前高频错判规则。
2. 修正规则 YAML、规则执行逻辑或实体依赖。
3. 确保 findings 与 checked_rules 状态一致。

重点文件

• rules/govdoc/govdoc_general/rules.yaml
• 相关 parser / engine check 实现

完成标准

• 典型样本下不再出现明显错误结论
• 高优先级规则结果可解释

---

4.3 P1-3 文件能力与页面提示统一

目标

把“系统真正支持什么文件”和“页面告诉用户支持什么文件”统一起来。

后端任务

1. 明确当前阶段是否恢复 .doc / .wps -> docx 转换能力。
2. 如果恢复，补齐转换链路。
3. 如果不恢复，统一收口为 .docx，并形成明确业务口径。

前端任务

1. 上传页提示、accept、错误提示与后端能力一致。
2. 列表筛选文件类型与实际能力一致。

重点文件

• fastapi_modules/fastapi_leaudit/services/impl/govdocServiceImpl.py
• legal-platform-frontend/components/govdoc-audit/upload-zone.tsx
• legal-platform-frontend/components/govdoc-audit/audits.tsx

完成标准

• 用户不会再看到“页面允许、后端拒绝”的不一致

---

4.4 P1-4 列表、详情、历史 run 语义统一

目标

把文档主模型和历史 run 语义真正落成产品行为。

后端任务

1. 明确列表展示的是“文档最新结果”。
2. 明确详情默认 latest run，支持历史 run 切换。
3. 明确首页统计按文档 latest run 计算。

前端任务

1. 列表跳详情统一按 documentId。
2. 历史 run 的显示、切换、当前标识明确。
3. 避免再混用 documentId 和 runId 做同一主键字段。

完成标准

• 同一文档多次执行后，用户能看懂当前结果和历史结果
• 列表、详情、统计三处的“最新结果”口径一致

---

5. 第三阶段：P2 治理与收尾

5.1 P2-1 实体结果结构化治理

目标

评估是否需要独立实体表或更正式的结构化结果域。

任务

1. 梳理现有 result_summary_json 承载内容。
2. 明确哪些长期适合 JSON，哪些适合结构化。
3. 如需拆表，作为后续治理任务安排，不阻塞 P0/P1。

---

5.2 P2-2 文档同步更新

目标

让内部文档反映当前真实代码状态和业务边界。

任务

1. 更新运行依赖说明。
2. 更新现状偏差与补齐计划。
3. 更新接口、权限、环境说明。

---

5.3 P2-3 测试与演示数据收尾

目标

为提测和演示整理稳定环境。

任务

1. 清理历史失败 run 和无效测试文档。
2. 沉淀一组固定验收样本。
3. 明确演示环境初始化步骤。

---

6. 推荐执行顺序

建议实际开发顺序如下：

1. P0-1 报告产物闭环
2. P0-2 详情结果对象收口
3. P0-4 数据库与初始化正式化
4. P0-3 规则版本正式接入
5. P1-1 核心实体识别调优
6. P1-2 高频规则误判修正
7. P1-3 文件能力与页面提示统一
8. P1-4 列表、详情、历史 run 语义统一
9. P2 治理与文档收尾

之所以把 P0-4 放到 P0-3 前面，是因为：

• 没有稳定环境初始化，规则接入和报告链路都容易被环境问题反复干扰

---

7. 建议的每轮交付节奏

为了避免一次改太大，建议每轮只交付一个可验证闭环。

第一轮

• 报告产物闭环
• 详情页真实可下载/可打开报告

第二轮

• 规则版本正式接入
• 规则页与执行结果规则版本一致

第三轮

• 核心实体识别调优
• 高频规则误判修正

第四轮

• 文件能力统一
• 历史 run 与列表/详情语义统一

第五轮

• 文档、数据、治理收尾

---

8. 最终结论

后续实施不应再以“能不能先跑起来”为目标，而应以：

• 是否恢复完整业务闭环
• 是否符合当前平台规范

作为唯一标准。

按这个拆解顺序执行，内部公文模块就能在不改业务逻辑的前提下，逐阶段恢复为一套真正可验收、可维护、可持续扩展的正式模块。