docs: add govdoc migration analysis and implementation notes

2026-05-17 19:24:00 +08:00
parent adc1e0b8dc
commit cb13e61d3d
9 changed files with 4462 additions and 0 deletions
@@ -0,0 +1,396 @@
+# 内部公文模块实施进展与运行依赖说明
+
+## 1. 文档目的
+
+本文档只回答 3 个问题：
+
+- 当前 `govdoc` 模块代码已经接到了哪一步
+- 现在还缺哪些实现与运行依赖
+- 当前为什么仍不能视为“可正式运行”
+
+本文档基于 2026-05-17 当前仓库实际代码状态整理，不讨论理想方案，只描述现状。
+
+---
+
+## 2. 当前实施进展
+
+### 2.0 2026-05-17 运行面最新结论
+
+本次联调补充确认了一个非常关键的事实：
+
+- `govdoc` 前后端链路现在已经接到了当前 `leaudit-platform`
+- `GET /api/govdoc/documents` 不再是之前的 `404`
+- 当前未登录访问时，接口返回 `401 Unauthorized`
+- 当前未登录访问 `http://172.16.0.59:5173/govdoc/audits?entryModuleId=3` 时，会被正常重定向到 `/login`
+
+这说明：
+
+- “文档列表没有接到 1 后端”这个问题，按 2026-05-17 当前代码与运行验证结果看，**已经不是接口未接通问题**
+- 当前更真实的阻塞已经变成：
+  - 运行进程是否真的按当前仓库拉起
+  - 浏览器是否带了有效登录态
+  - 正式部署是否还混用了旧项目或错误上游
+
+本次实测时，以下链路已确认成立：
+
+- `legal-platform-frontend` 的 `/api/govdoc/*` 代理会转发到当前后端 `http://127.0.0.1:8096/api/govdoc/*`
+- 后端 `8096` 确认加载的是当前仓库 `fastapi_admin.app:app`
+- `GET /api/govdoc/documents?page=1&pageSize=1` 已到达当前后端，并返回认证失败而非路由不存在
+
+结论：
+
+- **当前剩余主阻塞不是“列表接口没接上”，而是“运行部署链路混乱 + 登录态/正式进程不稳定”。**
+
+### 2.1 业务基线已明确
+
+当前业务口径已经明确：
+
+- `govdoc` 是“内部公文格式审查模块”
+- 主对象是“文档”，不是 `run`
+- 上传后可自动触发审查
+- 历史 `run` 需要保留
+- 详情应以 `documentId` 为主，默认展示最新一次 `run`
+
+这部分结论已在已有业务文档中明确，不再重复展开。
+
+### 2.2 后端基础骨架已形成
+
+当前后端已具备以下基础结构：
+
+- `controller` 层已有 `govdoc` 路由入口
+- `service` 层已有 `GovdocServiceImpl`
+- `bridge` 层已有 `tasks / runner / storage_adapter / input_resolver / result_adapter`
+- `engine` 层已有 `govdoc_engine` 解析、规则执行、结构/大纲、报告相关代码
+- `model` 与 `DDL` 已具备 `govdoc_runs / govdoc_rule_results / govdoc_report_artifacts` 基础定义
+
+说明：
+
+- 这代表模块已经不是“纯占位”，而是已经具备一条从文档到运行结果的后端主链路雏形。
+
+### 2.3 文档与运行主链路已有实际实现
+
+当前 `GovdocServiceImpl` 已经实现了以下能力：
+
+- 文档上传
+- 文档列表
+- 文档详情
+- 创建运行 `CreateRun`
+- 运行状态查询
+- 运行结果读取
+- findings / entities / structure / outline 读取
+- 原文下载
+- HTML / DOCX 报告地址读取
+- 规则列表 / 规则详情读取
+
+说明：
+
+- 这意味着服务层已经不是之前那种“多数方法占位返回空壳”的阶段。
+- 当前更准确的判断应是：**后端主链路基本接通，但仍存在关键运行依赖缺口和若干结果完整性缺口。**
+
+### 2.4 worker / bridge / DDL 的 P0 已完成一轮修复
+
+截至当前代码状态，以下确定性断点已完成修复：
+
+- `dispatch_govdoc_task` 已支持透传 `rulesPath`
+- `govdoc_execute_task` 已支持接收 `rulesPath`
+- `GovdocRunner.Execute()` 已显式校验 `rulesPath`
+- `UpdateRunStatus()` 已兼容 `phase / Phase`
+- `govdoc_runs.rules_path` 已补入 model / DDL
+- `govdoc_rule_results.skip_reason` 已补入 model / DDL
+
+这部分修复的意义是：
+
+- 任务链不再因为参数签名不一致、字段缺列这类低级错位直接报错
+- 但“能跑到哪一步”仍取决于上游运行依赖是否齐全
+
+---
+
+## 3. 当前已完成项
+
+从“能不能形成后端最小闭环”角度看，当前已完成项如下。
+
+### 3.1 文档主档复用已接上
+
+- 上传公文时，已复用 `leaudit_documents`
+- 原始文件已复用 `leaudit_document_files`
+- 上传后会把 `engine_type` 标记为 `govdoc`
+
+### 3.2 运行记录域已接上
+
+- 已创建 `govdoc_runs`
+- 已支持记录 `status / phase / total_score / result_status`
+- 已支持写入 `task_id / started_at / finished_at`
+
+### 3.3 规则结果域已接上
+
+- 已支持写入 `govdoc_rule_results`
+- 已支持读取 `result / severity / category / message`
+- 已支持读取 `skip_reason`
+
+### 3.4 异步任务链已接上
+
+- 已支持 `CreateRun -> dispatch_govdoc_task -> govdoc_execute_task -> GovdocRunner.Execute`
+- 已支持 worker 中更新 run/document 状态
+
+### 3.5 结果读取链已接上
+
+- 已支持从 `govdoc_runs + govdoc_rule_results` 读取结果摘要
+- 已支持组装 `checkedRules / findings / structure / outline`
+- 已支持详情页所需的最新运行与历史运行信息
+
+---
+
+## 4. 当前待完成项
+
+以下内容属于“主链路已经搭上，但还没有真正闭环”。
+
+### 4.1 规则文件已落位，但规则来源策略仍是临时写法
+
+当前实现里，`GovdocServiceImpl._resolve_rules_path()` 仍只尝试两个固定候选路径：
+
+- `/home/wren-dev/Porject/leaudit-platform/rules/govdoc/govdoc_general/rules.yaml`
+- `/home/wren-dev/Porject/leaudit-platform/rules/govdoc_general/rules.yaml`
+
+按 2026-05-17 当前仓库实际状态看：
+
+- 第一条路径对应的规则文件已经存在
+- 当前真实运行也已经证明 `govdoc` 审查链路可以成功加载该规则并完成一次完整审查
+
+因此：
+
+- 现在的问题已经不是“规则文件本体不存在”
+- 而是**规则来源策略仍然是硬编码单规则集**
+
+当前仍待补的问题是：
+
+- 不支持按文种/类型切换不同规则集
+- 不支持按地区/版本切换规则集
+- 不支持平台化规则绑定与管理
+
+这不是当前链路跑不通的主阻塞，但它是后续正式化接入前必须收口的技术债。
+
+### 4.2 govdoc 专用规则资产已入库，但尚未平台化
+
+当前仓库已存在明确的 `govdoc` 规则目录：
+
+- `rules/govdoc/govdoc_general/rules.yaml`
+
+这说明：
+
+- `govdoc` 已经不再处于“只有代码骨架，没有规则资产”的阶段
+- 后端规则读取、规则列表、规则详情的最小语义已经有了真实落点
+
+但当前仍只能视为“单规则集可运行”：
+
+- 规则目录结构尚未接入统一规则管理策略
+- `rules_path` 仍主要服务于当前单套内部公文规则
+- 规则版本、切换与配置来源还没有平台化闭环
+
+### 4.3 报告产物主闭环已打通，但历史运行仍需补跑
+
+当前代码已补齐正式报告产物生成与写库：
+
+- 审查完成后会生成 `annotated_docx`
+- 审查完成后会生成 `html_report`
+- 审查完成后会生成 `paragraph_html`
+- 产物会落入 `govdoc_report_artifacts`
+
+并且已做过真实运行验证。
+
+但仍有两个现实问题没有自动消失：
+
+- 历史上在修复前跑成功的 run，并不会自动补出产物
+- 这类历史 run 需要重新触发一次审查，才能补齐正式报告文件
+
+### 4.4 页面接入已通，但真实登录态联调尚未完成
+
+虽然本文档不展开前端全部细节，但从当前代码与运行态核对结果看，前端接入边界已经比较明确：
+
+- `/govdoc/audits` 已接到当前 `legal-platform-frontend`
+- 页面真实数据请求走的是 `/api/govdoc/* -> 8096/api/govdoc/*`
+- 未登录访问时，`app/(audit)/layout.tsx -> requireAuth()` 会先基于 `user_info` cookie 重定向到 `/login`
+- `/api/*` 请求上的 `Authorization` 由 `middleware.ts` 从 `access_token` cookie 注入
+
+因此当前状态更适合描述为：
+
+- 前端页面和代理链路已经接通
+- 当前仍缺“带真实登录态”的完整回归验收
+- 当前若页面跳 `/login` 或接口 `401`，不能再直接判断为“govdoc 没接后端”
+
+---
+
+## 5. 当前已知运行阻塞
+
+以下是“现在就会影响模块能否真实跑通”的已知阻塞。
+
+### 5.1 阻塞一：正式运行进程与旧链路混用
+
+这是当前最关键、最真实的运行阻塞。
+
+现状：
+
+- 当前仓库后端标准端口应为 `8096`
+- 当前仓库 worker 应从 `leaudit-platform/scripts/start_worker.sh` 启动
+- 实机上曾长期存在旧 worker：
+  - `python start_worker_with_routing.py --config-port 8096`
+  - `cwd=/home/wren-dev/Porject/docauditai`
+- 实机联调过程中还出现过：
+  - `5173` 前端入口存在
+  - 但 `8096` 没有当前仓库后端在监听
+  - 因此页面表现为 `502 / 404 / 500` 来回切换
+
+结果：
+
+- 浏览器打开页面，不代表当前仓库后端已经真正生效
+- 即使代码已经修好，只要正式进程仍混用旧项目，上层依然会报错
+
+结论：
+
+- **当前 `govdoc` 最大阻塞已经不是接口代码未接通，而是部署运行链路未彻底切回当前仓库。**
+
+### 5.2 阻塞二：旧 `docauditai` worker 仍长期存活
+
+当前机器上已确认存在旧进程：
+
+- `python start_worker_with_routing.py --config-port 8096`
+- `cwd=/home/wren-dev/Porject/docauditai`
+- `PPID=1`
+- 标准输出与错误输出落在 `/tmp/worker_8096.log`
+
+这说明它更像是：
+
+- 历史上人工或脚本后台拉起后长期遗留的旧 worker
+
+它与当前仓库的主要冲突点不是抢占 `8096` HTTP 端口，而是：
+
+- 它仍可能消费旧 `docauditai` 任务链路
+- 它会制造“页面是新的，执行链还是旧的”的混合运行态
+- 它会严重干扰“问题究竟在当前仓库还是旧仓库”的判断
+
+在没有确认任务投递、结果写回、旧队列消费都已切到当前仓库前，不宜只凭主观感觉直接停掉该进程。
+
+### 5.3 阻塞三：规则来源策略仍是临时写法
+
+当前 `_resolve_rules_path()` 只使用硬编码候选路径。
+
+这意味着即便后续补了规则文件，也仍然存在以下待补问题：
+
+- 不支持按文档类型选择不同规则
+- 不支持按地区 / 版本 / 规则集切换
+- 不支持平台化规则管理
+
+这个问题不一定导致“立刻报错”，但会阻碍后续正式上线。
+
+### 5.4 阻塞四：当前终端启动方式不等于正式部署方式
+
+本次排障中还发现一个容易误判的问题：
+
+- 在当前 Codex 执行环境里，普通“后台启动后退出命令”的方式，子进程可能随会话一起被回收
+- 因此会出现：
+  - 日志显示 `startup complete`
+  - 但随后端口马上消失
+
+这个现象说明：
+
+- 不能把当前临时终端会话，等同于正式 supervisor / systemd / PM2 / nginx upstream 部署环境
+- 正式部署必须由稳定守护方式接管
+- 不能仅凭一次临时 shell `start` 成功，就判断运行问题已经彻底解决
+
+这属于运行验证边界，不属于 govdoc 业务逻辑问题。
+
+---
+
+## 6. 当前运行依赖清单
+
+从“要让 `govdoc` 至少完成一次真实审查”角度，当前最小运行依赖如下。
+
+### 6.1 数据库依赖
+
+- `leaudit_documents`
+- `leaudit_document_files`
+- `govdoc_runs`
+- `govdoc_rule_results`
+- `govdoc_report_artifacts`
+
+并且需执行当前 `schema_add_govdoc_module.sql`，保证以下列存在：
+
+- `govdoc_runs.rules_path`
+- `govdoc_rule_results.skip_reason`
+- `leaudit_documents.engine_type`
+
+### 6.2 文件与存储依赖
+
+- 上传文档需能写入 OSS / MinIO
+- worker 执行时需能下载原始文档到本地临时目录
+
+### 6.3 异步任务依赖
+
+- Celery worker 需可消费当前 `leaudit-platform` 队列
+- 当前实际队列为 `leaudit.normal` / `leaudit.urgent`
+- worker 进程需可访问数据库、OSS、本地临时目录
+
+### 6.4 规则引擎依赖
+
+- 必须存在可用的 `govdoc rules.yaml`
+- `rulesPath` 必须能被 service 层解析出来
+- worker 所在运行环境必须能读取该规则文件
+
+### 6.5 解析与报告依赖
+
+- `python-docx` 相关解析依赖需正常
+- 段落解析、规则执行、结构/大纲构建需可正常运行
+- 审查完成后需能生成并上传正式报告产物
+
+---
+
+## 7. 当前剩余细节清单
+
+从“业务语义已经基本对齐”往“可稳定交付”推进，当前剩余细节主要有这些：
+
+### 7.1 运行部署侧
+
+- 正式 `8096` 后端进程要固定切到当前 `leaudit-platform`
+- 正式 worker 要确认只消费当前 `leaudit-platform` 队列
+- 旧 `docauditai` 的 `start_worker_with_routing.py` 需要在确认安全前置条件后退出正式链路
+- `5173` 对应的 nginx / 前端上游要固定指向当前前端服务
+- 需要一份正式重启与巡检手册，避免以后又混回旧进程
+
+### 7.2 数据与历史运行侧
+
+- 修复前的历史成功 run 需要补跑一次，才能产出正式报告文件
+- 需要确认 `leaudit_documents.current_run_id` 是否都正确指向最新成功 run
+
+### 7.3 产品细节侧
+
+- `canonical.docx` 与 `result.json` 还没有作为显式产物沉淀
+- 前端某些展示位仍以 `run completed` 为主判断，而不是严格以产物存在性判断
+- 按钮开放策略还需要继续保持“和其他文档类型一致，但不额外放出不该开放的按钮”
+
+### 7.4 验收侧
+
+- 需要带真实登录态回归验证：
+  - 列表页
+  - 详情页
+  - HTML 报告
+  - DOCX 报告
+  - 段落联动视图
+  - 重跑与历史 run 切换
+
+---
+
+## 8. 当前结论
+
+截至 2026-05-17，`govdoc` 当前真实状态应表述为：
+
+- 业务语义基线已经明确
+- 后端主链路已经接通
+- 正式报告产物主闭环已经补齐
+- 前端列表/详情接口已接到当前后端契约
+- 当前 `rules/govdoc/govdoc_general/rules.yaml` 已存在且已被真实运行验证过
+- 当前最主要问题已经转为运行部署链路不稳定，而不是业务逻辑未实现
+
+因此后续工作重点不应再回到“列表接口有没有接上”，而应转向：
+
+- 固化正式运行方式
+- 清理旧 worker / 旧上游
+- 带登录态做完整联调验收