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