# 实施边界锁定后的补齐修复计划 ## 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. 做结构治理和文档收尾 只要坚持这个顺序，内部公文模块就能在不改业务逻辑的前提下，按当前项目规范稳妥完成迁移收口。