# 按阶段执行任务拆解清单

## 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. 最终结论

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

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

作为唯一标准。

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