wren
13 KiB
13 KiB
实施边界锁定后的补齐修复计划
1. 文档目的
在 迁移前后业务语义对照分析.md 已经明确“业务逻辑保持一致、代码实现按当前平台规范重构”的前提下，本文档进一步回答 4 个问题：
- 当前内部公文模块还差哪些补齐项
- 这些补齐项里哪些是 P0 / P1 / P2
- 应该按什么顺序推进，才能低风险落地
- 每一阶段完成后，什么算真正完成
本文档不再讨论“要不要按旧系统照搬”，而是直接面向实施。
2. 总体判断
当前 govdoc 模块的状态不是“从零开始”，也不是“只差几个 bug”。
更准确地说：
- 业务骨架已迁入平台
- 执行主链已基本打通
- 但交付语义还没有完全恢复
因此后续工作重点不是继续铺骨架，而是：
- 把已经迁进来的骨架收口成一套完整、可验收的业务闭环
从实施角度看，当前缺口应分成三层：
P0：不补就不构成完整业务闭环P1：主链能跑，但结果质量或体验还不满足验收P2：结构性优化和后续治理项
3. 实施总原则
后续所有修复都必须同时满足：
- 业务语义对齐迁移前项目
- 代码实现遵守当前
leaudit-platform规范
落到执行上，就是三条硬规则：
- 不允许为了快，直接把旧项目代码原样塞进当前平台
- 不允许为了平台化，削弱旧项目已成立的业务语义
- 不允许只把接口点亮，而不恢复正式结果闭环
4. 当前待补齐项总览
4.1 P0：必须先收口的闭环项
P0-1 报告产物闭环恢复
当前问题：
run完成后，后端报告读取接口虽然存在，但产物生成链路并未真正闭环- 前端详情页和列表页已经暴露了
报告 HTML / 批注 DOCX能力 - 这会形成“页面有入口、业务无结果”的假闭环
业务原因：
- 旧项目里报告产物是正式业务结果，不是附属能力
实施目标：
- 每次
govdoc run成功后，必须形成并持久化：annotated.docxreport.htmlparagraphs.html
- 平台侧应将这些产物写入正式索引，并稳定提供读取能力
对应代码区域：
fastapi_modules/fastapi_leaudit/govdoc_bridge/result_adapter.pyfastapi_modules/fastapi_leaudit/govdoc_bridge/runner.pyfastapi_modules/fastapi_leaudit/govdoc_bridge/storage_adapter.pyfastapi_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.pyfastapi_modules/fastapi_leaudit/controllers/govdocController.pyfastapi_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.pylegal-platform-frontend/lib/api/govdoc-audit/api.tslegal-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.pygovdoc_engine/parser/role_tagger_rule.pygovdoc_engine/parser/entity_builder.pyrules/govdoc/govdoc_general/rules.yaml
完成判定：
- 典型正反例文档结果可解释
- 核心实体识别达到可验收水平
- 主要规则不再出现大面积误判
P1-2 文件能力与前端展示对齐
当前问题：
- 旧项目业务支持
.docx / .doc / .wps - 当前平台后端上传只支持
.docx - 但列表筛选和部分前端文案仍残留
.doc / .wps
业务原因：
- 如果平台决定暂时只支持
.docx，这必须是明确业务决策，不是前后端不一致
实施目标：
- 明确当前阶段文件支持范围
- 前端上传、筛选、提示、错误返回统一
- 若恢复
.doc / .wps，则补齐转换链路；若不恢复，则前端彻底收口到.docx
对应代码区域：
fastapi_modules/fastapi_leaudit/services/impl/govdocServiceImpl.pylegal-platform-frontend/components/govdoc-audit/upload-zone.tsxlegal-platform-frontend/components/govdoc-audit/audits.tsx
完成判定：
- 页面展示、接口能力、错误文案三者一致
- 用户不会被“页面可选但后台不支持”的假能力误导
P1-3 列表、详情、报告入口行为统一
当前问题：
- 列表页、详情页、报告入口的行为已经大体搭起来
- 但部分入口仍受到底层状态缺口影响
业务原因：
- 旧项目交互语义很明确，迁移后不能出现“有的入口跳详情，有的入口拿不到结果”的不稳定体验
实施目标：
- 列表页保持文档主入口语义
- 详情页保持完整审查结果页语义
- 报告入口、原文入口、历史入口行为一致可预期
对应代码区域：
legal-platform-frontend/components/govdoc-audit/audits.tsxlegal-platform-frontend/components/govdoc-audit/audit.tsxlegal-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. 推荐实施顺序
建议严格按以下顺序推进。
第一阶段：恢复正式闭环
目标：
- 先让模块从“能跑”变成“能完整交付”
顺序：
- 报告产物闭环恢复
- 详情结果对象收口
- 数据库与初始化正式化
阶段完成标志：
- 上传一份文档，能够形成完整 run 结果
- 详情页可稳定展示完整结果
- HTML 报告、批注 DOCX、段落预览全部真实可用
第二阶段：恢复规则正式语义
目标：
- 把“临时规则文件方案”升级为“平台规则生效方案”
顺序：
ruleVersionId真正接入执行链路- 当前生效规则集与规则详情统一
- 审查结果规则追溯打通
阶段完成标志：
- 指定规则版本可以真实生效
- 规则页、审查页、结果记录三者语义一致
第三阶段：提高结果质量与交互一致性
目标：
- 让结果从“可用”提升为“可验收”
顺序：
- 核心实体识别调优
- 高频规则误判修正
- 文件能力与前端展示对齐
- 历史 run 与入口行为统一
阶段完成标志：
- 典型样本结果可解释
- 页面行为稳定
- 用户不会在上传、列表、详情、报告之间遇到语义冲突
第四阶段：治理与收尾
目标：
- 为长期维护和后续扩展做准备
顺序：
- 实体结构化治理
- 文档更新
- 历史测试数据与演示数据收尾
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. 结论
接下来的实施重点，不是继续扩功能，而是：
- 先把旧项目已经成立的业务语义完整恢复到平台实现中
最重要的优先级顺序应固定为：
- 恢复报告与详情闭环
- 恢复规则正式生效语义
- 提升结果质量和前端一致性
- 做结构治理和文档收尾
只要坚持这个顺序，内部公文模块就能在不改业务逻辑的前提下，按当前项目规范稳妥完成迁移收口。