# 按阶段执行任务拆解清单 ## 1. 文档目的 本文档基于以下两份已确认文档继续往下拆： - [迁移前后业务语义对照分析.md](./迁移前后业务语义对照分析.md) - [实施边界锁定后的补齐修复计划.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. 最终结论 后续实施不应再以“能不能先跑起来”为目标，而应以： - **是否恢复完整业务闭环** - **是否符合当前平台规范** 作为唯一标准。 按这个拆解顺序执行，内部公文模块就能在不改业务逻辑的前提下，逐阶段恢复为一套真正可验收、可维护、可持续扩展的正式模块。