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”为执行留痕、以“规则结果 + 报告产物”为输出、复用平台统一底座的内部公文格式审查模块。**