leaudit-platform-backend/docs/内部公文模块/内部公文模块业务逻辑梳理.md

内部公文模块业务逻辑梳理

1. 文档目的

本文档用于明确当前 leaudit-platform 中 govdoc（内部公文模块）的业务定位、核心对象、标准流程、权限边界与结果语义。

这份文档的目标不是讲技术实现，而是先把“这个模块业务上到底是什么、用户怎么用、系统应该怎么理解”说清楚，作为后续前后端对接补齐和修复的业务基线。

---

2. 模块定位

govdoc 模块是当前平台中的一个一等业务模块，不是外挂独立系统。

它的核心业务目标是：

• 上传一份内部公文文件
• 按公文格式规范自动发起审查
• 输出结构化问题、规则检查结果、结构/大纲/实体识别结果
• 提供 HTML 报告、批注 DOCX、原文下载
• 全流程复用当前平台的账号、权限、地区、文档主档、OSS、异步任务体系

一句话概括：

内部公文模块本质上是平台里的“公文格式审查模块”。

---

3. 业务边界

3.1 本模块负责的事

• 公文文档上传
• 自动格式审查
• 审查结果展示
• 审查历史留痕
• 规则查看
• 报告下载

3.2 本模块不负责的事

• 公文流转审批
• 协同编辑
• 发文流程管理
• 独立规则平台
• 第二套独立文档系统
• 通用 RAG / 合同评审 / 交叉评查

因此，第一阶段不要把 govdoc 理解成“公文业务平台”，而应理解成“公文格式审查能力模块”。

---

4. 审查对象

从现有页面文案、规则展示和引擎能力看，govdoc 模块重点审查的是“公文格式规范”，而不是公文业务内容是否正确。

它重点关注的对象包括但不限于：

• 标题
• 发文字号
• 主送机关
• 正文层级
• 附件标记
• 附件标题
• 署名
• 成文日期
• 字体字号
• 行距
• 标点
• 禁用表述
• 易混词
• 文种合法性
• 层级编号规范
• 需要 AI/语义辅助判断的规则

因此，模块输出的“分数”和“问题”，本质上是：

公文格式规范符合度结果，不是业务内容质量结果。

---

5. 核心业务对象

本模块建议围绕以下 4 层业务对象展开。

5.1 文档

文档是平台主档中的一份公文文件。

业务语义：

• 用户上传的一份公文文件
• 是平台中的主对象
• 需要标记该文档属于 govdoc 模块

建议复用：

• leaudit_documents
• leaudit_document_files

同时在主档中补充模块标识，例如：

• engine_type = 'govdoc'

5.2 审查运行（Run）

Run 表示：

• 某份文档的一次审查执行记录
• 同一份文档可以有多次 run
• 新 run 不覆盖旧 run
• run 是执行留痕，不是业务主对象

5.3 规则结果

规则结果表示：

• 每条规则对当前文档检查后的结果

单条规则最终状态不是只有“通过/不通过”，而是：

• pass
• fail
• skipped

其中 skipped 表示：

• 条件不足，无法检查
• 或外部依赖能力异常，临时跳过

5.4 报告产物

审查完成后会产出一组可展示或可下载的结果文件，例如：

• HTML 报告
• 批注 DOCX
• 段落 HTML
• 原文下载
• 其他结构化中间结果

---

6. 主对象结论

结合当前业务确认，推荐正式拍板如下：

• 业务主对象是文档，不是 run
• run 是文档的一次审查执行留痕

原因：

• 列表页已经确定为文档列表
• 首页统计按文档最新结果计算
• 删除、下载原文、权限继承都天然是文档维度
• 用户面对的是“这份公文”，而不是技术上的 run

---

7. 详情页主键结论

推荐正式拍板如下：

• 详情页路由主键使用 documentId
• 页面默认展示该文档“最新一次 run”的结果
• 历史 run 在详情页内切换查看

推荐语义：

• 页面入口面向文档
• 页面内容展示 run 结果
• 最新 run 为默认视图

不建议直接把页面主键设计成 runId，否则会带来这些问题：

• 用户难以理解自己打开的是“哪份文档”
• 同一文档多次审查后页面入口不稳定
• 列表页与详情页的主对象不一致

---

8. 标准业务流程

8.1 进入模块

用户进入 govdoc 模块后，可以看到：

• 模块首页/概览
• 最近文档
• 统计数据

8.2 上传公文

用户上传一份公文文件。

第一阶段支持的文件类型应以现有前端为准，例如：

• doc
• docx
• wps

上传成功后：

• 创建平台文档主档
• 文档被标记为 govdoc

8.3 自动发起审查

已确认第一阶段默认行为为：

• 上传成功后自动发起审查

也就是：

• 上传成功
• 立即创建一条新的 run
• 投递异步任务处理

因此在业务上：

• 上传 ≠ 审查结果已经出来
• 上传 = 文档入库 + 自动创建 run

8.4 异步执行审查

Worker 异步执行完整审查链路，包括：

• 读取原文
• 解析段落与样式
• 识别段落角色
• 抽取实体
• 加载规则
• 执行规则评估
• 生成问题结果
• 生成报告产物
• 回写数据库与 OSS

8.5 查看详情

用户打开某份文档详情后，默认应看到：

• 该文档最新一次 run 的结果

包括：

• 问题列表
• 已通过规则
• 已跳过规则
• 结构面板
• 大纲面板
• 实体面板
• 报告下载

8.6 查看历史审查记录

同一份文档允许存在多个 run。

已确认需要保留历史 run，因此：

• 新 run 不覆盖旧 run
• 历史记录在详情页中查看
• 第一阶段前端不主动开放“重跑按钮”，但底层模型要支持

---

9. 列表页业务定义

已确认列表页应为：

• 文档列表

不是：

• run 列表

因此每一行表示的是：

• 一份公文文档

展示的是该文档当前/最近一次审查摘要，例如：

• 文档名称
• 文件类型
• 上传时间
• 当前状态
• 最新分数
• 最新问题数
• 最近一次审查时间

为什么不能做成 run 列表：

• 同一份文档多次重跑会出现多行重复记录
• 用户业务上关心的是“这份公文当前状态如何”
• 列表页会与文档权限、删除语义、首页统计口径冲突

---

10. Run 的业务定位

Run 是内部执行留痕，不是页面主对象，但它在业务上必须存在。

Run 的业务价值：

• 记录某次审查什么时候发起
• 记录谁触发了审查
• 记录本次状态、阶段、分数、错误信息
• 保留历史版本，支持追踪和回溯

当前业务确认：

• 需要支持重跑
• 但前端第一阶段不开放重跑按钮
• 处理方式与其他文档类型保持一致

因此应理解为：

• 能力层支持多 run
• 数据层必须保留历史 run
• 交互层是否开放重跑，可后续逐步释放

---

11. 结果页业务语义

结果页中几个核心对象的业务含义如下。

11.1 Findings

Findings 是最细粒度的问题明细。

其业务语义是：

• 某条规则在某一段落或某个结构位置上发现的问题

典型信息包括：

• 规则 ID
• 规则名称
• 严重级别
• 分类
• 位置
• 实际值
• 期望值
• 建议
• 证据文本

本质上是“段落级问题清单”。

11.2 Checked Rules

这是规则维度的检查结果。

每条规则的最终状态只有一个：

• pass
• fail
• skipped

这个列表用于回答：

• 哪些规则通过了
• 哪些规则失败了
• 哪些规则因为条件不足被跳过了

11.3 Structure

Structure 表示：

• 文档结构统计

它关注的是：

• 识别出了哪些结构角色
• 各角色出现了多少次
• 是否缺少预期结构
• 样式是否一致

11.4 Outline

Outline 表示：

• 文档大纲树

本质上是标题层级结构，用于帮助用户快速跳到对应段落。

11.5 Entities

Entities 表示：

• 从公文中识别出的关键实体

例如：

• 标题
• 发文字号
• 主送机关
• 附件
• 署名
• 日期
• 文种

---

12. 右侧结果面板的业务定义

当前详情右侧面板可归纳为 3 类结果：

12.1 问题

显示：

• 所有失败规则对应的问题明细

这是用户最主要的修正文档入口。

12.2 已通过

显示：

• 当前 run 中已通过的规则

作用：

• 帮助用户知道哪些规范项已经满足

12.3 已跳过

显示：

• 当前 run 中未被真正执行的规则

典型原因：

• 目标实体未识别到
• 检查条件不满足
• 外部智能检查服务不可用

业务上要明确：

• skipped 不算失败
• 但也不等于通过

---

13. 评分语义

已确认分数语义为：

• 格式审查分

它表示：

• 这份公文在格式规范层面的符合程度

不表示：

• 公文业务内容质量
• 法律风险程度
• 审批流转质量

因此用户看到的分数，本质上是格式规范扣分结果。

---

14. 首页统计口径

已确认首页统计应按：

• 文档最新结果

而不是：

• 所有历史 run 累加

因此统计时应遵循：

• 一份文档多次重跑，只按最新结果参与当前统计
• “本月评查文件数”按文档数，不按 run 数
• “问题数”“通过率”也按文档最新结果计算

如果按所有 run 统计，会导致：

• 文档数量虚高
• 问题数虚高
• 同一文档反复重跑导致指标失真

---

15. 权限模型

本模块应使用独立的 govdoc 权限命名空间，不与其他模块混用。

15.1 模块级权限

• govdoc:module:read

15.2 文档权限

• govdoc:document:create
• govdoc:document:read
• govdoc:document:update
• govdoc:document:delete

15.3 Run 权限

• govdoc:run:create
• govdoc:run:read
• govdoc:run:retry

15.4 结果与报告权限

• govdoc:result:read
• govdoc:report:read

15.5 规则权限

• govdoc:rule:read
• govdoc:rule:manage

---

16. 数据范围规则

当前业务确认如下。

16.1 普通用户（common）

• 只能看自己上传/自己触发的文档与结果
• 不能通过参数查看别人数据

16.2 地区管理员（admin）

• 只能看本地区数据
• 即使前端传入其他 region，后端也必须拦截

16.3 全局角色

• super_admin
• provincial_admin

可看更大范围或全量数据

---

17. 结果与报告权限继承原则

已确认以下资源不单独放宽：

• findings
• entities
• HTML 报告
• 批注 DOCX
• 原文下载

统一原则：

• 能否查看结果 = 能否查看该文档

也就是说：

• 不能看这份文档，就不能看它的任何结果和报告产物

---

18. 删除语义

已确认删除语义为：

• 软删除文档

业务含义：

• 删除的是文档在模块中的业务可见性/状态
• 不是立刻物理删除 OSS 文件
• 历史 run 和产物先保留

因此第一阶段不应把“删除文档”理解成“彻底清除所有数据”。

---

19. 文档修改权限

已确认普通用户默认不应具备较高的文档管理权限。

推荐权限语义：

• 普通用户可 create/read
• 普通用户默认不具备 update/delete

因此：

• govdoc:document:update
• govdoc:document:delete

应高于：

• govdoc:document:create
• govdoc:document:read
• govdoc:run:create

---

20. 规则模块关系

已确认规则模块口径为：

• 按照现有规则模块功能怎么做，内部公文模块就怎么接

这意味着：

• govdoc 不额外发明一套私有规则治理方式
• 规则版本、生效规则、规则选择逻辑，应尽量复用平台现有规则体系
• govdoc 只是作为一个业务模块接入既有规则治理框架

因此第一阶段不建议：

• 单独做一套 govdoc 私有规则选择交互
• 单独维护一套与平台脱节的规则管理入口

---

21. 第一阶段用户可见能力

第一阶段用户可见能力应聚焦在：

• 上传公文
• 自动格式审查
• 查看问题
• 查看结构/大纲/实体
• 下载报告

不作为第一阶段重点暴露的能力：

• 手动重跑按钮
• 高级规则版本选择
• 复杂模块配置页

其中：

• 重跑能力底层可以支持
• 规则版本能力可先遵循现有平台规则模块现状

---

22. 推荐正式拍板结论

为了保证后续前后端对接和修复方向稳定，推荐正式拍板以下两条：

22.1 主对象结论

• 主对象 = 文档

22.2 详情页结论

• 详情页路由 = documentId
• 页面默认展示该文档最新 run
• 历史 run 在详情页内部切换查看

这两条一旦定稿，以下模块都会更清晰：

• 列表页
• 详情聚合
• 权限继承
• 首页统计
• 历史记录展示
• 下载与删除语义

---

23. 一句话总结

govdoc 模块应被定义为：

以“公文文档”为主对象、以“审查 run”为执行留痕、以“规则结果 + 报告产物”为输出、复用平台统一底座的内部公文格式审查模块。