leaudit-platform-backend/docs/内部公文模块/内部公文模块实施进展与运行依赖说明.md

# 内部公文模块实施进展与运行依赖说明

## 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 / 旧上游
- 带登录态做完整联调验收