wren
445 lines
11 KiB
Markdown
445 lines
11 KiB
Markdown
# 按阶段执行任务拆解清单
|
|
|
|
## 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. 最终结论
|
|
|
|
后续实施不应再以“能不能先跑起来”为目标，而应以：
|
|
|
|
- **是否恢复完整业务闭环**
|
|
- **是否符合当前平台规范**
|
|
|
|
作为唯一标准。
|
|
|
|
按这个拆解顺序执行，内部公文模块就能在不改业务逻辑的前提下，逐阶段恢复为一套真正可验收、可维护、可持续扩展的正式模块。
|