# 内部公文模块现状偏差与对接补齐计划 ## 1. 文档目的 本文档基于当前仓库代码、已有迁移设计文档，以及已确认的业务口径，回答 3 个问题： - 当前 `govdoc` 模块业务上到底应该怎么跑 - 当前代码实际上跑成了什么状态 - 后续应该按什么顺序补齐，才能低风险落地 这份文档是后续前后端对接、数据库补齐、权限修复、页面改造的执行基线。 --- ## 2. 已确认的业务结论 结合现有页面语义、引擎能力和你已确认的口径，当前正式业务结论如下。 ### 2.1 模块定位 `govdoc` 不是公文流转系统，也不是审批系统。 它的第一阶段定位是： - **内部公文格式审查模块** 核心能力是： - 上传公文 - 自动发起格式审查 - 输出问题、规则结果、结构结果、报告产物 - 保留历史审查记录 ### 2.2 业务主对象 当前应正式拍板： - **主对象是文档** - `run` 只是某份文档的一次审查执行记录 原因： - 列表页已经确定是文档列表 - 删除、权限、原文下载天然属于文档 - 首页统计按文档最新结果算 - 用户认知对象是“这份公文”，不是“某次 run” ### 2.3 页面入口结论 详情页建议固定为： - **按 `documentId` 进入详情** 详情页默认行为： - 默认展示该文档最新一次审查结果 - 页面内可切换历史 run 因此正确语义是： - 列表展示文档 - 详情入口指向文档 - 结果展示某个 run ### 2.4 审查流程结论 当前业务流程应为： 1. 用户上传公文 2. 创建平台文档主档，标记 `engine_type='govdoc'` 3. 自动创建一条新的 `run` 4. 投递异步任务 5. Worker 执行格式审查 6. 产出规则结果、结构结果、报告产物 7. 详情页默认展示最新 run，保留历史 run ### 2.5 权限与可见范围结论 - `common` 只能看自己上传的文档及结果 - `admin` 只能看本地区 - 报告、原文、findings、history 都必须继承文档可见性 - 删除是软删除 - 普通用户默认不开放文档更新/删除 - 需要保留重跑能力，但前端暂不开放按钮 ### 2.6 指标与结果语义结论 - 分数是**公文格式规范符合度** - 不是内容质量分 - 首页统计要按**每份文档的最新 run** 计算 - 不是把所有 run 累加 --- ## 3. 当前实现的总体判断 结论先说： - 当前仓库已经把 `govdoc` 的目录、接口骨架、前端页面壳、SQL 草案、Worker 编排骨架都铺出来了 - 但它还没有形成一个真正闭环的“可用模块” 当前状态更准确地说是： - **已经完成模块迁移骨架** - **但业务主模型、接口契约、运行链路、权限落地还没有完全收口** 这不是一个“修几个接口”的问题，而是一个“已经搭了半套系统，但业务模型还没完全统一”的问题。 --- ## 4. 现状偏差分析 以下按 4 层来看：业务模型、前后端契约、运行链路、权限与统计。 ### 4.1 业务模型偏差 #### 偏差 1：后端设计想走文档模型，前端详情仍然是 run 模型 后端控制器已经提供： - `/govdoc/documents` - `/govdoc/documents/{documentId}` - `/govdoc/runs` - `/govdoc/runs/{runId}/...` 说明后端设计方向其实已经倾向： - 文档是主对象 - run 是子对象 但前端详情页实际还是： - `/govdoc/[id]` 且页面直接把 `id` 当作 `auditId` 传给旧组件。 这意味着当前前端仍在延续旧的“run 即详情页主键”思路。 直接影响： - 文档列表跳详情时主键语义不稳定 - 同一文档多次运行后，入口对象变成“当前 run” - 后续历史 run 展示很难自然补进去 #### 偏差 2：列表页名义上是文档列表，数据上仍在混用文档 ID 和 run ID 当前前端列表适配时把： - `audit_id = currentRunId ?? documentId` 这其实是在用一个字段混装两种对象： - 有最新 run 时，这个 ID 代表 run - 没有 run 时，这个 ID 代表 document 这会直接带来： - 详情页路由语义漂移 - 删除、下载原文、查看结果时对象类型不确定 - 前端组件后续越来越难维护 #### 偏差 3：上传与发起审查的业务闭环还没有真正做完 业务上已经确认： - 上传后应自动发起审查 但当前后端 `UploadDocument()` 只是占位返回； `CreateRun()` 也是占位返回； 前端 `uploadAudit()` 虽然按“先上传、再建 run”的思路写了，但后端并没有真正完成这两个动作。 因此现在只是： - 前端以为自己在走业务闭环 - 后端实际上还没有落地 ### 4.2 前后端接口与路由契约偏差 #### 偏差 4：前端代理路径与实际代理实现不一致 当前前端 API 客户端里大量请求走的是： - `/api/govdoc/...` 但仓库里实际存在的代理路由是： - `/api/govdoc-audit/[...path]` 这代表至少在当前仓库状态下： - 代码意图已经切到新模块路径 - 代理实现仍停留在旧路径 运行时风险很直接： - 前端请求可能 404 - 或必须依赖外部额外 rewrite 才能工作 #### 偏差 5：前端页面路由已经叫 `govdoc`，但菜单和别名体系仍残留大量 `govdoc-audit` 当前仓库同时存在两套路由语义： - 新路由：`/govdoc` - 旧路由：`/govdoc-audit` 遗留点包括： - 菜单映射 - 最小权限白名单 - breadcrumb - 角色权限页面提示文案 - route alias 配置 - 某些入口页跳转目标 这意味着当前前端不是“已经迁完”，而是处于： - 新旧路径并存 - 新路径只接了一半 直接后果： - 菜单权限和真实页面可能不一致 - 用户访问入口与页面跳转链路可能绕回旧路径 - 后续排障会出现“接口没问题但入口不对”的假象 #### 偏差 6：SQL 菜单种子与前端真实详情路由不一致 当前 SQL 种子注册的是： - `/govdoc/detail` 但前端真实详情页现在是： - `/govdoc/[id]` 而业务推荐最终应为： - `/govdoc/detail/:documentId` 这说明目前菜单/RBAC 路由、Next 页面路由、业务路由设计三者还没有统一。 ### 4.3 后端服务实现偏差 #### 偏差 7：`GovdocServiceImpl` 大部分接口仍是占位实现 当前真正有一定查询逻辑的主要只有： - `GetRunResult()` 其余关键接口基本仍是骨架： - `UploadDocument()` - `ListDocuments()` - `GetDocumentDetail()` - `UpdateDocument()` - `DeleteDocument()` - `CreateRun()` - `GetRunStatus()` - `GetRunFindings()` - `GetRunEntities()` - `GetRunParagraphs()` - `GetRunStructure()` - `GetRunOutline()` - `GetReportHtml()` - `GetReportDocx()` - `DownloadOriginal()` 这意味着： - 控制器接口已经暴露出来 - 但绝大部分业务服务还没有真正接平台主档、结果表、OSS、权限范围 #### 偏差 8：`GetRunResult()` 所依赖字段与当前建表 SQL 不一致 代码查询了： - `govdoc_runs.rules_path` - `govdoc_rule_results.skip_reason` 但当前建表 SQL 中并没有这两个字段。 这属于很典型的： - 服务代码和 DDL 没同步 直接后果： - 查询会报 SQL 字段不存在 - 或部署后不同环境表现不一致 #### 偏差 9：结果接口仍是 run 视角，缺少“文档详情聚合接口” 业务上真正需要的详情能力是： - 输入 `documentId` - 返回文档基础信息 - 返回最新 run 摘要 - 返回历史 run 列表 - 默认选中最新 run 的 findings / structure / outline / artifacts 当前后端虽然有： - `GetDocumentDetail(documentId)` 但只是占位返回 `{"documentId": ...}`。 这意味着真正业务需要的“文档详情聚合接口”还没做。 ### 4.4 Worker / Bridge / 运行时偏差 #### 偏差 10：Worker 调用 `GovdocRunner.Execute()` 时缺少必填 `RulesPath` `GovdocRunner.Execute()` 的签名要求： - `RulesPath: str` 但 Celery 任务调用时没有传这个参数。 这意味着当前一旦任务真正执行到这里，运行时就会直接报错。 #### 偏差 11：状态更新参数名不一致，`phase` 很可能写不进去 `StorageAdapter.UpdateRunStatus()` 定义的是： - `Phase` 但调用时传的是： - `phase=...` 由于这里大小写不一致，`Phase` 不会接收到值。 直接后果： - `govdoc_runs.phase` 可能一直不更新 - 前端状态页看到的阶段信息不可信 #### 偏差 12：结果持久化只写了规则结果和产物，没有把文档维度聚合真正打通 当前 Bridge 更像是在做： - run 生命周期管理 - 规则结果入库 - 报告产物索引入库 但还没有完全补齐： - 文档最新 run 的选择逻辑 - 文档级状态汇总 - 文档级最新分数/最新结果统计口径 - 首页统计查询口径 所以底层虽然开始有 run 表，但“平台层文档视角”还没有真正建立。 ### 4.5 权限、可见范围、删除语义偏差 #### 偏差 13：控制器做了登录校验，但还没真正落细粒度数据范围 当前控制器统一用了： - `verify_access_token` 说明登录态有了。 但真正业务要求的是： - `common` 仅本人 - `admin` 仅本地区 - 报告/原文/结果/历史全部继承文档范围 而这些逻辑目前还没有在 `GovdocServiceImpl` 中真正实现。 所以当前状态更接近： - 只有“是否登录” - 还没有“能看谁的数据” #### 偏差 14：删除语义业务上要求软删除，但当前服务只是占位返回 业务上已经确认删除必须是： - 软删除 当前 `DeleteDocument()` 只是返回： - `{"documentId": ..., "deleted": True}` 没有真正处理： - 文档主档软删 - 文件记录是否保留 - run 是否跟随隐藏 - 报告产物是否继续留存但不可见 #### 偏差 15：普通用户不应默认拥有更新/删除，但当前接口已开放，权限键还没真正落表 接口层已经有： - `PATCH /documents/{documentId}` - `DELETE /documents/{documentId}` 这本身没错，因为管理员要用。 但当前问题是： - 角色默认能力 - 权限键 - 按角色/地区/本人范围控制 这些还没真正打通。 所以现在属于“接口先开出来了，但权限收口还没跟上”。 --- ## 5. 当前代码实际反映出的真实业务状态 从代码现状反推，当前模块实际上处于下面这个阶段： ### 5.1 已经确定的部分 - 决定把 `govdoc-audit` 收口进主平台 - 决定复用主平台账号、权限、文档主档、OSS、Celery - 决定新建 `govdoc_runs / govdoc_rule_results / govdoc_report_artifacts` - 决定后端 API 挂到 `/govdoc` - 决定前端页面也逐步迁到 `/govdoc` 这部分方向是对的。 ### 5.2 还没有完全拍平的部分 - 详情页到底按 `documentId` 还是 `runId` - 列表项到底代表文档还是运行 - 前端入口到底以 `govdoc` 还是 `govdoc-audit` 为准 - 路由种子、前端页面、菜单权限是否统一 - 文档级详情聚合接口长什么样 - 统计到底按 run 还是按文档最新结果 ### 5.3 因此当前模块不是“坏了”，而是“未收口” 更准确地说： - 架构方向基本正确 - 但业务主模型尚未完全统一 - 结果导致前端、后端、SQL、任务链各自朝着相近但不完全一致的方向在写 这就是当前所有错位问题的根因。 --- ## 6. 建议的正式收口方案 为了后面少返工，建议现在先正式拍板以下模型，不再来回摇摆。 ### 6.1 正式主模型 - 主对象：`document` - 执行对象：`run` - 结果对象：`rule_result` - 产物对象：`artifact` ### 6.2 正式页面路由 - `/govdoc` - `/govdoc/home` - `/govdoc/upload` - `/govdoc/audits` 或 `/govdoc/list` - `/govdoc/detail/[documentId]` - `/govdoc/rules` 建议最终二选一： - 要么统一保留 `/govdoc/audits` - 要么统一收敛为 `/govdoc/list` 不要两个同时长期并存。 从当前业务文案看，我更建议统一为： - `/govdoc/list` - `/govdoc/detail/[documentId]` 因为它更贴近“文档列表 / 文档详情”的业务语义。 ### 6.3 正式接口模型 建议稳定成两层接口。 第一层：文档接口 - `POST /govdoc/documents` - `GET /govdoc/documents` - `GET /govdoc/documents/{documentId}` - `PATCH /govdoc/documents/{documentId}` - `DELETE /govdoc/documents/{documentId}` - `GET /govdoc/documents/{documentId}/original` - `GET /govdoc/documents/{documentId}/runs` 第二层：run 结果接口 - `POST /govdoc/runs` - `GET /govdoc/runs/{runId}` - `GET /govdoc/runs/{runId}/result` - `GET /govdoc/runs/{runId}/findings` - `GET /govdoc/runs/{runId}/entities` - `GET /govdoc/runs/{runId}/structure` - `GET /govdoc/runs/{runId}/outline` - `GET /govdoc/runs/{runId}/paragraphs` - `GET /govdoc/runs/{runId}/report/html` - `GET /govdoc/runs/{runId}/report/docx` 其中： - 页面入口以 `documentId` 为准 - 结果读取以 `runId` 为准 ### 6.4 正式详情页返回模型 建议把 `GET /govdoc/documents/{documentId}` 做成真正的聚合详情： - 文档基本信息 - 当前状态 - 当前最新 run 摘要 - 历史 run 列表 - 当前默认 runId - 当前可用报告产物摘要 页面进入后： - 先拿文档聚合详情 - 再按默认 runId 拉 findings / structure / outline / entities 这样前端会非常稳定。 --- ## 7. 分阶段补齐计划 以下是建议执行顺序。顺序不能乱，因为前一层不收口，后一层会反复返工。 ### Phase 1：先把业务主模型收口 目标： - 明确 `document` 是主对象 - 统一详情入口为 `documentId` - 统一列表项表达的是文档 具体动作： - 前端详情路由改为 `/govdoc/detail/[documentId]` - 列表接口返回文档维度 DTO，不再混用 `documentId/runId` - 列表项保留 `latestRunId` 字段，但不能拿它充当主键 - SQL 路由种子、前端菜单、页面跳转统一成同一套路由 产出结果： - 页面导航语义稳定 - 历史 run 可自然挂入详情页 - 后续删除、下载、权限继承都有明确主语 ### Phase 2：补齐后端文档主链路 目标： - 真正打通“上传文档 -> 创建主档 -> 标记为 govdoc -> 自动建 run” 具体动作： - `UploadDocument()` 接入平台文档主档服务 - 文档主档写入 `engine_type='govdoc'` - 上传后默认自动触发 `CreateRun()` - `CreateRun()` 真正写入 `govdoc_runs` - 投递 Celery 任务 - 回写 `leaudit_documents.processing_status/current_run_id` 产出结果： - 用户上传后能真正看到一条 govdoc 文档 - 文档状态从上传到处理中可追踪 ### Phase 3：修复 Worker 运行闭环 目标： - 让异步任务真正可跑完 具体动作： - 修复 `RulesPath` 来源与传参 - 修复 `UpdateRunStatus()` 的 `Phase/phase` 参数不一致 - 明确默认规则文件解析策略 - 补 run 开始时间、结束时间、失败信息 - 补结果持久化后的文档最新状态回写 产出结果： - Celery worker 可以稳定完成一次 run - 失败时数据库里有清晰可读的错误和状态 ### Phase 4：补齐结果查询与详情聚合 目标： - 让详情页真正能按业务方式展示 具体动作： - `GetDocumentDetail()` 改为聚合查询 - 增加 `GET /documents/{documentId}/runs` - `GetRunFindings()` / `GetRunEntities()` / `GetRunStructure()` / `GetRunOutline()` / `GetReportHtml()` / `GetReportDocx()` / `DownloadOriginal()` 全部接真实数据 - HTML/DOCX/original 下载统一继承文档权限 产出结果： - 详情页默认展示最新结果 - 用户可切换历史 run - 报告与原文下载链路完整 ### Phase 5：补齐权限、数据范围、软删除 目标： - 让模块真正符合平台权限模型 具体动作： - 落 `govdoc:*:*` 权限键 - `common` 按本人过滤 - `admin` 按地区过滤 - `provincial_admin/super_admin` 按更大范围过滤 - 删除改为主档软删 - 结果/报告/历史查询全部继承文档范围 产出结果： - 模块可以上线到真实账号体系 - 不会出现越权查看他人公文结果 ### Phase 6：清理前端旧壳与统计口径 目标： - 把遗留的 `govdoc-audit` 痕迹真正收口 具体动作： - 统一 `/govdoc` 与 `/govdoc-audit` 路由 - 菜单、breadcrumb、minimal-scope、route alias 统一 - 首页统计改为按文档最新 run 聚合 - 前端隐藏重跑按钮，但保留后端能力 产出结果： - 前端不再混用新旧模块名 - 用户看到的是完整一致的一套业务入口 --- ## 8. 优先级建议 如果要按最小可用闭环来排，我建议优先级如下： ### P0：不修就跑不起来 - 统一详情主模型为 `documentId` - 修复 `/api/govdoc` 与实际代理不一致 - 实现 `UploadDocument()` / `CreateRun()` - 修复 `RulesPath` 缺失 - 修复 `phase` 状态写回失败 - 修复 DDL 与服务代码字段不一致 ### P1：能跑但还不能交付 - 实现文档聚合详情 - 实现历史 run 查询 - 实现 findings / structure / outline / artifacts 真实读取 - 实现原文/HTML/DOCX 下载 ### P2：上线前必须补齐 - 权限键 - 数据范围 - 软删除 - 首页统计口径 - 新旧路由与菜单彻底收口 --- ## 9. 最终建议 当前最重要的不是马上补某一个接口，而是先统一下面这句话： - **内部公文模块是“文档为主、run 为辅、详情按 documentId 进入、结果按 runId 展示”的业务模型。** 只要这个模型拍板，后面所有实现都可以顺下来： - 列表怎么查 - 详情怎么开 - 历史怎么挂 - 统计怎么算 - 权限怎么继承 - 删除怎么定义 如果这句话不拍板，后面无论先修前端还是后端，都会反复返工。 --- ## 10. 审核结论 基于当前业务确认和代码现状，我给出的正式判断是： - 当前模块方向是对的 - 当前实现还未闭环 - 最大问题不是单点 bug，而是“主业务模型尚未完全统一” 建议正式以本文方案收口后，再进入代码补齐阶段。 这样改一次，后面才不会反复拆。