leaudit-platform-backend/docs/内部公文模块/实施边界锁定后的补齐修复计划.md

# 实施边界锁定后的补齐修复计划

## 1. 文档目的

在 [迁移前后业务语义对照分析.md](./迁移前后业务语义对照分析.md) 已经明确“业务逻辑保持一致、代码实现按当前平台规范重构”的前提下，本文档进一步回答 4 个问题：

- 当前内部公文模块还差哪些补齐项
- 这些补齐项里哪些是 P0 / P1 / P2
- 应该按什么顺序推进，才能低风险落地
- 每一阶段完成后，什么算真正完成

本文档不再讨论“要不要按旧系统照搬”，而是直接面向实施。

---

## 2. 总体判断

当前 `govdoc` 模块的状态不是“从零开始”，也不是“只差几个 bug”。

更准确地说：

- **业务骨架已迁入平台**
- **执行主链已基本打通**
- **但交付语义还没有完全恢复**

因此后续工作重点不是继续铺骨架，而是：

- **把已经迁进来的骨架收口成一套完整、可验收的业务闭环**

从实施角度看，当前缺口应分成三层：

- `P0`：不补就不构成完整业务闭环
- `P1`：主链能跑，但结果质量或体验还不满足验收
- `P2`：结构性优化和后续治理项

---

## 3. 实施总原则

后续所有修复都必须同时满足：

1. **业务语义对齐迁移前项目**
2. **代码实现遵守当前 `leaudit-platform` 规范**

落到执行上，就是三条硬规则：

- 不允许为了快，直接把旧项目代码原样塞进当前平台
- 不允许为了平台化，削弱旧项目已成立的业务语义
- 不允许只把接口点亮，而不恢复正式结果闭环

---

## 4. 当前待补齐项总览

## 4.1 P0：必须先收口的闭环项

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

当前问题：

- `run` 完成后，后端报告读取接口虽然存在，但产物生成链路并未真正闭环
- 前端详情页和列表页已经暴露了 `报告 HTML / 批注 DOCX` 能力
- 这会形成“页面有入口、业务无结果”的假闭环

业务原因：

- 旧项目里报告产物是正式业务结果，不是附属能力

实施目标：

- 每次 `govdoc run` 成功后，必须形成并持久化：
  - `annotated.docx`
  - `report.html`
  - `paragraphs.html`
- 平台侧应将这些产物写入正式索引，并稳定提供读取能力

对应代码区域：

- `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`

完成判定：

- `run completed` 后，详情页 `批注 DOCX` 和 `报告 HTML` 均真实可用
- `GetRunParagraphs()` 返回稳定可渲染段落视图
- 列表页“报告”入口可直接打开真实 HTML 报告

---

### P0-2 规则生效链路正式化

当前问题：

- 接口已出现 `ruleVersionId`
- 但当前执行时仍主要依赖固定 `rules.yaml` 路径解析
- 这意味着“参数存在”与“规则真正生效”不是一回事

业务原因：

- 旧项目至少保证“当前生效规则集明确、审查结果知道自己用了哪版规则”
- 平台化后不能退回到长期硬编码规则路径

实施目标：

- `ruleVersionId` 必须真正进入 `govdoc` 执行链路
- 审查结果必须可追溯到本次使用的规则版本
- `/govdoc/rules` 与 `/govdoc/rules/{ruleId}` 的返回语义必须与实际生效规则一致

对应代码区域：

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

完成判定：

- 上传或创建 run 时指定规则版本，执行链路实际按该版本生效
- 结果页、规则页、审查记录三处能追溯同一规则版本
- 不再依赖长期硬编码路径作为正式方案

---

### P0-3 详情结果对象收口

当前问题：

- 底层已是 `document + run`
- 但详情结果仍有多接口拼接、不完全稳定、产物和结果状态不同步的问题

业务原因：

- 旧项目详情页拿到的是一份完整审查结果
- 当前平台即使分对象存储，也必须对前端恢复同样的完整语义

实施目标：

- 以 `documentId` 为详情主入口保持不变
- 对外提供一份完整、稳定、可直接渲染的详情结果对象
- `summary / findings / checked_rules / entities / structure / outline / reports` 必须共同成立

对应代码区域：

- `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`

完成判定：

- 详情页不再依赖“接口凑合可用”
- 数据对象语义稳定，状态与产物一致
- 多次历史 run 下，默认最新 run，且可正确切换结果

---

### P0-4 数据库与环境初始化正式化

当前问题：

- 当前依赖运行时 `_ensureGovdocSchema()` 做大量兜底建表
- 这虽然能保命，但不是正式交付方式

业务原因：

- 环境初始化不稳定会直接造成模块“今天能跑、明天因表缺失又挂”

实施目标：

- 将 `govdoc` 相关表结构、索引、必要种子数据纳入正式初始化方案
- 运行时兜底可保留，但不应再作为主方案

对应代码区域：

- `scripts/创建sql/schema_add_govdoc_module.sql`
- 权限/entry module seed SQL
- `fastapi_modules/fastapi_leaudit/services/impl/govdocServiceImpl.py`

完成判定：

- 新环境按正式 SQL / migration 能直接初始化
- 不依赖首次访问接口触发表自动创建
- 菜单、权限、模块入口在环境中可直接可用

---

## 4.2 P1：影响验收质量的补齐项

### P1-1 识别与规则结果质量调优

当前问题：

- 主链能跑不代表结果可验收
- 标题、发文字号、日期、署名、主送机关等核心实体识别仍偏弱
- 规则命中质量尚未达到正式交付水位

业务原因：

- 内部公文模块交付的是“审查结果质量”，不是“接口运行成功率”

实施目标：

- 优先提高核心实体识别准确率
- 优先修正高频规则误判/漏判
- 保证结构、实体、findings 三者结果相互一致

重点区域：

- `govdoc_engine/parser/docx_parser.py`
- `govdoc_engine/parser/role_tagger_rule.py`
- `govdoc_engine/parser/entity_builder.py`
- `rules/govdoc/govdoc_general/rules.yaml`

完成判定：

- 典型正反例文档结果可解释
- 核心实体识别达到可验收水平
- 主要规则不再出现大面积误判

---

### P1-2 文件能力与前端展示对齐

当前问题：

- 旧项目业务支持 `.docx / .doc / .wps`
- 当前平台后端上传只支持 `.docx`
- 但列表筛选和部分前端文案仍残留 `.doc / .wps`

业务原因：

- 如果平台决定暂时只支持 `.docx`，这必须是明确业务决策，不是前后端不一致

实施目标：

- 明确当前阶段文件支持范围
- 前端上传、筛选、提示、错误返回统一
- 若恢复 `.doc / .wps`，则补齐转换链路；若不恢复，则前端彻底收口到 `.docx`

对应代码区域：

- `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`

完成判定：

- 页面展示、接口能力、错误文案三者一致
- 用户不会被“页面可选但后台不支持”的假能力误导

---

### P1-3 列表、详情、报告入口行为统一

当前问题：

- 列表页、详情页、报告入口的行为已经大体搭起来
- 但部分入口仍受到底层状态缺口影响

业务原因：

- 旧项目交互语义很明确，迁移后不能出现“有的入口跳详情，有的入口拿不到结果”的不稳定体验

实施目标：

- 列表页保持文档主入口语义
- 详情页保持完整审查结果页语义
- 报告入口、原文入口、历史入口行为一致可预期

对应代码区域：

- `legal-platform-frontend/components/govdoc-audit/audits.tsx`
- `legal-platform-frontend/components/govdoc-audit/audit.tsx`
- `legal-platform-frontend/lib/api/govdoc-audit/api.ts`

完成判定：

- 列表到详情、详情到报告、详情到原文的链路无歧义
- 同一文档在不同入口下看到的是一致结果

---

### P1-4 历史 run 与最新结果语义补全

当前问题：

- 当前业务已确认“文档为主、run 为辅、默认展示最新 run、保留历史 run”
- 但这套能力还没有完全收口为正式产品语义

实施目标：

- 详情页默认展示最新 run
- 历史 run 清晰可切换
- 首页统计、列表状态、详情摘要统一按最新 run 计算

完成判定：

- 同一文档多次执行后，结果语义稳定
- 用户能明确看到“当前结果”和“历史结果”的边界

---

## 4.3 P2：结构治理与后续优化项

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

当前问题：

- 实体结果目前主要通过 `result_summary_json` 承载
- 这在短期内可用，但不利于后续检索、统计和演进

实施目标：

- 评估是否需要独立 `govdoc_entities` 或等价结构化承载
- 不影响 P0/P1 交付前提下，作为后续演进项

---

### P2-2 文档与实施说明同步

当前问题：

- 部分文档仍反映旧阶段问题，和当前代码状态不完全一致

实施目标：

- 在完成 P0/P1 后，同步更新：
  - 运行依赖说明
  - 对接补齐计划
  - 接口与权限说明

---

### P2-3 运行数据清理与演示样本整理

当前问题：

- 历史失败 run、临时测试数据、旧入口痕迹容易干扰验收

实施目标：

- 在提测前统一清理历史无效 run
- 整理一套正反例验收文档

---

## 5. 推荐实施顺序

建议严格按以下顺序推进。

## 第一阶段：恢复正式闭环

目标：

- 先让模块从“能跑”变成“能完整交付”

顺序：

1. 报告产物闭环恢复
2. 详情结果对象收口
3. 数据库与初始化正式化

阶段完成标志：

- 上传一份文档，能够形成完整 run 结果
- 详情页可稳定展示完整结果
- HTML 报告、批注 DOCX、段落预览全部真实可用

---

## 第二阶段：恢复规则正式语义

目标：

- 把“临时规则文件方案”升级为“平台规则生效方案”

顺序：

1. `ruleVersionId` 真正接入执行链路
2. 当前生效规则集与规则详情统一
3. 审查结果规则追溯打通

阶段完成标志：

- 指定规则版本可以真实生效
- 规则页、审查页、结果记录三者语义一致

---

## 第三阶段：提高结果质量与交互一致性

目标：

- 让结果从“可用”提升为“可验收”

顺序：

1. 核心实体识别调优
2. 高频规则误判修正
3. 文件能力与前端展示对齐
4. 历史 run 与入口行为统一

阶段完成标志：

- 典型样本结果可解释
- 页面行为稳定
- 用户不会在上传、列表、详情、报告之间遇到语义冲突

---

## 第四阶段：治理与收尾

目标：

- 为长期维护和后续扩展做准备

顺序：

1. 实体结构化治理
2. 文档更新
3. 历史测试数据与演示数据收尾

---

## 6. 每阶段实施时的约束

### 6.1 第一阶段禁止事项

- 禁止继续增加新页面能力
- 禁止先把按钮点亮再补后端产物
- 禁止绕开正式存储方案临时返回假链接

### 6.2 第二阶段禁止事项

- 禁止长期保留硬编码规则路径作为正式方案
- 禁止出现“前端选了规则版本，后端实际没用”的假配置

### 6.3 第三阶段禁止事项

- 禁止在未确认业务收缩前，默默砍掉 `.doc / .wps`
- 禁止用前端文案掩盖后端能力缺失

---

## 7. 验收口径

后续每轮实施完成后，建议按下面口径验收。

## 7.1 P0 验收口径

- 上传文档后自动创建并完成一条 run
- 列表可见文档最新结果
- 详情页可稳定打开
- `findings / checked_rules / entities / structure / outline` 全部正常
- `原始文件 / 批注 DOCX / 报告 HTML / 段落预览` 全部真实可用

## 7.2 P1 验收口径

- 核心正反例样本结果合理
- 核心实体识别基本稳定
- 列表筛选、分数分段、详情交互一致
- 文件类型能力与页面提示一致

## 7.3 P2 验收口径

- 结构治理方案明确
- 文档同步到当前代码状态
- 演示和测试环境数据整洁

---

## 8. 结论

接下来的实施重点，不是继续扩功能，而是：

- **先把旧项目已经成立的业务语义完整恢复到平台实现中**

最重要的优先级顺序应固定为：

1. 恢复报告与详情闭环
2. 恢复规则正式生效语义
3. 提升结果质量和前端一致性
4. 做结构治理和文档收尾

只要坚持这个顺序，内部公文模块就能在不改业务逻辑的前提下，按当前项目规范稳妥完成迁移收口。