TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
leaudit-platform-backend/docs/内部公文模块/内部公文模块实施进展与运行依赖说明.md
T

14 KiB
Raw Permalink Blame History

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

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 / 旧上游
  • 带登录态做完整联调验收
Reference in New Issue View Git Blame Copy Permalink