TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(govdoc): 新增内部公文模块全链路（后端58+前端11文件）

Browse Source
This commit is contained in:
wren
2026-05-13 14:37:12 +08:00
parent 99699e20e1
commit 5d777599bf
63 changed files with 7608 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/内部公文模块/内部公文模块接口与权限设计.md
+731
View File
@@ -0,0 +1,731 @@
# 内部公文模块接口与权限设计
## 1. 目标
本文档定义 `govdoc` 模块接入当前 `leaudit-platform` 后端后的：
- 接口边界
- 路由设计
- 权限键设计
- 角色可见范围
- 数据隔离规则
- 前后端联动约定
该模块的正式中文名建议为：
- `内部公文处理`
模块编码建议为：
- `govdoc`
---
## 2. 设计原则
### 2.1 平台统一原则
`govdoc` 不作为独立系统存在，而是当前平台中的一个业务模块，因此必须统一复用：
- JWT 鉴权
- RBAC 权限模型
- 地区隔离
- 文档主档与文件版本体系
- OSS/MinIO
- Celery 异步任务
- Result 统一响应格式
### 2.2 接口职责边界
接口层只负责：
- 收参
- 鉴权
- 权限校验
- 数据范围校验
- 调 service
- 返回 DTO
接口层不负责：
- 文档解析
- 规则执行
- 本地落盘
- 同步长耗时审查
### 2.3 全异步执行原则
公文审查必须走异步任务，不能在 HTTP 请求内同步完成整条处理链。
即：
- 上传文档 ≠ 立即完成审查
- 发起审查 = 创建 run + 投递 worker
- 结果查询 = 前端轮询或详情页进入后查询
---
## 3. 模块路由建议
建议前端页面路由：
- `/govdoc`
- `/govdoc/upload`
- `/govdoc/list`
- `/govdoc/detail/:documentId`
- `/govdoc/rules`
- `/govdoc/settings`（可选）
说明：
- 前端实际详情页建议使用 `/govdoc/detail/:documentId`
- `sys_routes` 中可注册隐藏详情模板路由 `/govdoc/detail`，供菜单/RBAC 使用
建议在 `sys_routes` 中注册为一组完整模块菜单。
---
## 4. 权限键设计
建议单独定义 `govdoc` 模块权限，不与 `rag:*`、`cross_review:*`、`document:*` 混用。
### 4.1 模块级权限键
- `govdoc:module:read`
语义：
- 是否可见内部公文处理模块菜单
- 是否可进入 `/govdoc` 相关页面
### 4.2 文档权限键
- `govdoc:document:create`
- `govdoc:document:read`
- `govdoc:document:update`
- `govdoc:document:delete`
语义：
- 上传公文
- 查看公文文档列表与详情
- 更新文档基础信息
- 删除公文文档
### 4.3 审查运行权限键
- `govdoc:run:create`
- `govdoc:run:read`
- `govdoc:run:retry`
- `govdoc:run:cancel`（若后续支持）
语义：
- 发起公文审查
- 查看 run 状态
- 失败后重试
- 取消执行中的任务
### 4.4 报告与结果权限键
- `govdoc:report:read`
- `govdoc:result:read`
语义：
- 下载 HTML 报告 / 批注 DOCX / 原文
- 查看 findings / entities / summary 等结果
### 4.5 规则权限键
- `govdoc:rule:read`
- `govdoc:rule:manage`
语义：
- 查看规则清单与规则详情
- 发布/更新/切换规则版本
### 4.6 配置权限键（可选）
- `govdoc:settings:read`
- `govdoc:settings:update`
语义：
- 查看模块配置
- 修改模块配置，例如默认规则版本、模型开关、执行策略等
---
## 5. 角色建议与默认授权
当前平台已收口角色：
- `provincial_admin`
- `admin`
- `common`
- `super_admin`（可选，仅系统级）
建议 `govdoc` 默认授权如下。
### 5.1 `super_admin`
建议权限：
- 全部 `govdoc:*:*`
数据范围：
- 全量
### 5.2 `provincial_admin`
建议权限：
- `govdoc:module:read`
- `govdoc:document:create`
- `govdoc:document:read`
- `govdoc:document:update`
- `govdoc:document:delete`
- `govdoc:run:create`
- `govdoc:run:read`
- `govdoc:run:retry`
- `govdoc:report:read`
- `govdoc:result:read`
- `govdoc:rule:read`
- `govdoc:rule:manage`
- `govdoc:settings:read`
- `govdoc:settings:update`
数据范围：
- 全省
### 5.3 `admin`
建议权限：
- `govdoc:module:read`
- `govdoc:document:create`
- `govdoc:document:read`
- `govdoc:document:update`
- `govdoc:document:delete`
- `govdoc:run:create`
- `govdoc:run:read`
- `govdoc:run:retry`
- `govdoc:report:read`
- `govdoc:result:read`
- `govdoc:rule:read`
是否授予：
- `govdoc:rule:manage`
- `govdoc:settings:update`
取决于业务是否允许地区管理员维护本地区规则版本。
数据范围：
- 本地区
### 5.4 `common`
建议权限：
- `govdoc:module:read`
- `govdoc:document:create`
- `govdoc:document:read`
- `govdoc:run:create`
- `govdoc:run:read`
- `govdoc:report:read`
- `govdoc:result:read`
- `govdoc:rule:read`
不建议授予：
- `govdoc:document:delete`
- `govdoc:document:update`
- `govdoc:run:retry`
- `govdoc:rule:manage`
- `govdoc:settings:update`
数据范围：
- 本人
---
## 6. 数据范围隔离规则
`govdoc` 模块的数据范围必须严格复用当前平台模型，不单独搞第二套。
建议规则：
### 6.1 全局角色
角色：
- `super_admin`
- `provincial_admin`
规则：
- 可看全量数据
- 若请求中带 `region` 筛选，则按筛选值缩小范围
### 6.2 地区管理角色
角色：
- `admin`
规则：
- 只能看 `region = 当前用户 area`
- 即便前端传入其他地区，也必须后端拦截为 0 结果或直接拒绝
### 6.3 普通用户
角色：
- `common`
规则：
- 只能看本人上传 / 本人创建 / 本人触发的文档与 run
- 不能通过 `userId` 参数查看他人数据
### 6.4 结果与报告的权限继承
以下资源不单独放宽：
- findings
- entities
- HTML 报告
- annotated DOCX
- 原文下载
这些资源的查看权限必须继承文档主档可见范围。
即：
- 能否查看结果 = 能否查看该文档
---
## 7. 接口设计建议
建议全部放在 `/api/v3/govdoc/` 命名空间下。
---
## 8. 文档接口
### 8.1 上传公文
`POST /api/v3/govdoc/documents`
功能：
- 上传一份公文文档
- 创建 `leaudit_documents` / `leaudit_document_files` 主记录
- `engine_type` 标记为 `govdoc`
- 可选自动触发审查
请求建议：
- `file`: 主文件
- `typeId` / `typeCode`
- `region`（最终以后端数据范围校正为准）
- `autoRun`
- `speed`
- `ruleVersionId`（可选）
所需权限：
- `govdoc:document:create`
返回建议：
- `documentId`
- `fileId`
- `region`
- `engineType`
- `autoRunTriggered`
- `run`（若自动触发）
### 8.2 获取公文列表
`GET /api/v3/govdoc/documents`
功能：
- 获取公文模块的文档列表
查询参数建议：
- `page`
- `pageSize`
- `keyword`
- `region`
- `status`
- `resultStatus`
- `createdBy`
- `dateFrom`
- `dateTo`
后端必须附加固定过滤：
- `engine_type = 'govdoc'`
所需权限：
- `govdoc:document:read`
### 8.3 获取公文详情
`GET /api/v3/govdoc/documents/{DocumentId}`
功能：
- 获取文档基础信息
- 获取当前最新 run 摘要
- 获取报告资源引用
所需权限：
- `govdoc:document:read`
### 8.4 更新文档信息
`PATCH /api/v3/govdoc/documents/{DocumentId}`
功能：
- 修改公文标题、文号、备注、类型等基础信息
所需权限：
- `govdoc:document:update`
### 8.5 删除文档
`DELETE /api/v3/govdoc/documents/{DocumentId}`
功能：
- 软删除文档
- 默认只删模块侧展示，不立即物理删除 OSS 产物
所需权限：
- `govdoc:document:delete`
---
## 9. 审查运行接口
### 9.1 发起审查
`POST /api/v3/govdoc/runs`
功能：
- 对已存在文档发起一次公文审查 run
- 创建 `govdoc_runs`
- 投递 Celery worker
请求建议：
- `documentId`
- `ruleVersionId`（可选）
- `speed`
- `force`
所需权限：
- `govdoc:run:create`
返回建议：
- `runId`
- `documentId`
- `status=queued`
- `phase=dispatch`
### 9.2 获取 run 状态
`GET /api/v3/govdoc/runs/{RunId}`
功能：
- 查询当前 run 的状态、阶段、耗时、错误摘要
所需权限：
- `govdoc:run:read`
### 9.3 重试 run
`POST /api/v3/govdoc/runs/{RunId}/retry`
功能：
- 对失败或已完成的 run 重新发起一次新 run
- 原 run 不覆盖
所需权限：
- `govdoc:run:retry`
---
## 10. 结果与报告接口
### 10.1 获取审查结果摘要
`GET /api/v3/govdoc/runs/{RunId}/result`
功能：
- 返回 summary
- 返回 checked rules
- 返回 findings 统计
- 返回 entities 摘要
所需权限：
- `govdoc:result:read`
### 10.2 获取 findings 明细
`GET /api/v3/govdoc/runs/{RunId}/findings`
功能：
- 返回段落级问题列表
所需权限：
- `govdoc:result:read`
### 10.3 获取 entities 明细
`GET /api/v3/govdoc/runs/{RunId}/entities`
功能：
- 返回识别出的标题、文号、收文机关、署名、文种、附件等实体
所需权限：
- `govdoc:result:read`
### 10.4 获取段落 HTML
`GET /api/v3/govdoc/runs/{RunId}/paragraphs`
功能：
- 返回前端文档联动视图所需的段落 HTML
所需权限：
- `govdoc:report:read`
### 10.5 下载 HTML 报告
`GET /api/v3/govdoc/runs/{RunId}/report/html`
功能：
- 获取 HTML 报告内容或下载地址
所需权限：
- `govdoc:report:read`
### 10.6 下载批注 DOCX
`GET /api/v3/govdoc/runs/{RunId}/report/docx`
功能：
- 下载带批注的 DOCX
所需权限：
- `govdoc:report:read`
### 10.7 下载原文
`GET /api/v3/govdoc/documents/{DocumentId}/original`
功能：
- 下载原始上传文档
所需权限：
- `govdoc:report:read`
- 同时必须满足文档数据范围校验
---
## 11. 规则接口
### 11.1 获取规则清单
`GET /api/v3/govdoc/rules`
功能：
- 查看当前生效规则集摘要
- 查看总规则数、group、severity、category
所需权限：
- `govdoc:rule:read`
### 11.2 获取规则详情
`GET /api/v3/govdoc/rules/{RuleId}`
功能：
- 查看单条规则详情，包括 stages、messages、target / applies_to 等
所需权限：
- `govdoc:rule:read`
### 11.3 发布规则版本（后续）
`POST /api/v3/govdoc/rule-versions/publish`
功能：
- 发布新的规则版本
所需权限：
- `govdoc:rule:manage`
---
## 12. 配置接口（可选）
### 12.1 获取模块配置
`GET /api/v3/govdoc/settings`
所需权限：
- `govdoc:settings:read`
### 12.2 更新模块配置
`PATCH /api/v3/govdoc/settings`
所需权限：
- `govdoc:settings:update`
配置项示例：
- 默认规则版本
- 是否允许自动审查
- 是否启用外部 LLM
- 最大文件大小
- 最大排队任务数
---
## 13. 前后端联动约定
### 13.1 前端菜单显示
前端展示 `govdoc` 模块菜单的条件建议为：
- 路由可见
- 且拥有 `govdoc:module:read`
### 13.2 页面按钮显示
建议按动作权限键控制：
- 上传按钮：`govdoc:document:create`
- 删除按钮：`govdoc:document:delete`
- 重新发起审查：`govdoc:run:create`
- 重试按钮：`govdoc:run:retry`
- 规则管理入口：`govdoc:rule:manage`
### 13.3 数据不可仅靠前端隐藏
即使按钮被隐藏，后端仍必须做：
- 权限校验
- 数据范围校验
- 文档归属校验
前端永远不是安全边界。
---
## 14. 错误码与返回建议
建议继续复用当前平台 Result 风格，错误语义明确：
常见错误建议：
- `401`：未登录 / token 无效
- `403`：无权限
- `404`：文档 / run / 规则不存在
- `409`：已有运行中任务，不允许重复发起
- `422`：文件类型不支持 / 参数非法
- `500`：执行失败
建议返回可读 message，例如：
- `您没有查看内部公文处理模块的权限`
- `您没有查看该公文的权限`
- `当前文档已有执行中的审查任务`
- `当前规则版本不可用，请联系管理员`
---
## 15. SQL 与初始化建议
建议至少补以下脚本：
- `scripts/创建sql/schema_add_govdoc_module.sql`
- `scripts/创建sql/seed_govdoc_permissions.sql`
- `scripts/创建sql/seed_govdoc_entry_module.sql`
- `scripts/创建sql/seed_govdoc_routes.sql`
建议初始化内容：
- `permissions` 中加入 `govdoc:*`
- `sys_routes` 中加入 `/govdoc*`
- `role_permissions` 中给 `provincial_admin/admin/common` 分配默认权限
- `role_route` 中分配菜单可见性
---
## 16. 最终建议
`govdoc` 模块的接口和权限设计，应严格遵守当前平台边界：
- 接口统一走 `/api/v3/govdoc/*`
- 权限统一走 `govdoc:*:*`
- 数据范围统一走当前地区隔离逻辑
- 结果下载权限继承文档可见范围
- 公文模块不单独再造第二套用户、权限、地区模型
这样才能保证：
- 模块边界清晰
- 前后端联动简单
- 后续统计和审计一致
- 长期维护成本最低
docs/内部公文模块/内部公文模块数据表复用与新增建议.md
+368
View File
@@ -0,0 +1,368 @@
# 内部公文模块数据表复用与新增建议
## 1. 结论
数据表不需要“全部重新建”，但也不建议“全部硬复用当前项目现有表”。
最合理的方式是：
- 复用当前项目已有的“平台公共表”
- 新建 `govdoc` 自己的“结果域表”
- 不要把公文模块的运行和结果强塞进现有 `leaudit` 专属结果表
一句话：
- 主档能复用
- 结果别乱复用
---
## 2. 建议直接复用的表
以下属于平台级公共能力，建议直接复用：
### 2.1 用户与权限相关
- `sso_users`
- `roles`
- `user_role`
- `permissions`
- `role_permissions`
- `sys_routes`
- `role_route`
这些负责：
- 用户身份
- JWT 登录态
- RBAC 授权
- 菜单显示
- 接口动作权限
### 2.2 文档主档相关
- `leaudit_documents`
- `leaudit_document_files`
这些负责：
- 文档主记录
- 文件版本
- 文件角色
- 所属地区
- 创建人
- OSS 路径关联
### 2.3 存储与任务基础设施
虽然不是数据表，但这些平台能力也必须复用：
- OSS / MinIO
- Celery
- 当前统一配置体系
---
## 3. 为什么文档主档可以复用
从平台视角看，公文本质上也是文档。
当前 `DocumentServiceImpl` 已经处理了很多平台公共问题：
- 上传
- 文档类型归属
- 地区归属
- 文件版本
- OSS 存储
- 创建人
- 列表查询
- 数据隔离
这说明：
- `leaudit_documents` 更像平台级文档主表
- 不只是某一个引擎专属表
所以公文模块完全可以这样接：
- 公文先入 `leaudit_documents`
- 文件入 `leaudit_document_files`
- 再通过模块标识或引擎标识决定后续执行链
---
## 4. 建议补充的主档字段
建议在 `leaudit_documents` 增加一个模块或引擎标识字段，例如：
- `engine_type`
可选值例如：
- `leaudit`
- `govdoc`
- `rag`
或者使用：
- `biz_module`
作用是让平台明确知道：
- 这份文档属于哪个处理模块
- 应走哪条执行链
- 应展示哪套结果详情页面
这个字段非常关键。
---
## 5. 不建议直接复用的现有结果表
不建议直接复用的主要是“运行结果型表”，例如：
- `leaudit_audit_runs`
- `leaudit_rule_results`
- 以及现有 `leaudit` 引擎专属的 metrics / extraction / rescue 一类结果表
原因如下。
### 5.1 字段语义会越来越脏
当前 `leaudit` 的运行结果表，天然围绕现有审查引擎设计，可能包含：
- phase
- OCR / extract / rescue 阶段
- ruleSetId / ruleVersionId
- resultStatus
- rescueApplied
- 当前引擎专属 timing / metrics
而 `govdoc` 运行时更关注：
- 公文结构解析
- 标题 / 发文字号 / 文种 / 附件识别
- 段落级 findings
- HTML / annotated docx / paragraph html 报告
表面上都叫 run，但含义并不完全相同。
### 5.2 结果明细模型不完全兼容
`govdoc-audit` 的单条 finding 更像：
- `rule_id`
- `rule_name`
- `severity`
- `category`
- `location.paragraph_index`
- `message`
- `suggestion`
- `actual`
- `expected`
- `evidence`
它非常强调：
- 段落定位
- 文档结构位置
- 格式问题
而当前 `leaudit_rule_results` 更可能偏：
- 评查点
- 提取字段
- 风险
- rescue 翻转
- 审核结果
两者不是一个结果语义世界。
### 5.3 后续统计口径容易混乱
如果共用结果表，后面做统计时会不断出现问题：
- 这个 `passed_count` 是公文规则通过数，还是合同规则通过数？
- 这个 `failed_count` 是格式错误项数，还是评查点失败数？
- 这个 `score` 的计算口径是否一致？
最终会逼着所有查询都加一层 `engine_type` 判断。
### 5.4 迁移与回滚成本更高
架构上：
- 从专属表改回公共表，容易
- 从硬复用公共表再拆出来，很痛苦
所以结果域隔离更稳。
---
## 6. 最推荐的折中方案
最佳折中不是“全新建”，也不是“全复用”，而是：
- 1 套平台主档
- 1 个模块标识字段
- 1 套 `govdoc` 结果域表
### 6.1 第一层：复用公共文档主档
继续使用：
- `leaudit_documents`
- `leaudit_document_files`
负责：
- 上传文档主记录
- 保存文件版本
- 地区归属
- 创建人
- OSS 路径
### 6.2 第二层：补充模块标识
在 `leaudit_documents` 增：
- `engine_type = 'govdoc'`
这样主档表知道：
- 这是一份由公文模块消费的文档
### 6.3 第三层：新增公文结果域表
建议新增：
- `govdoc_runs`
- `govdoc_rule_results`
- `govdoc_entities`
- `govdoc_report_artifacts`
好处：
- 上传、权限、地区、OSS 全复用
- 结果和运行态不污染原系统
- 前端查询和统计都清晰
---
## 7. 如果想极限少建表，最少也要新建哪几张
如果希望第一阶段尽量少建表，建议最少也要新建 3 张：
- `govdoc_runs`
- `govdoc_rule_results`
- `govdoc_report_artifacts`
可选第 4 张：
- `govdoc_entities`
如果想更快推进，`entities` 也可以先临时塞进 `govdoc_runs.result_json` 之类字段里，但长期仍建议拆表。
---
## 8. 什么情况下可以复用当前 `leaudit_audit_runs`
只有一种情况可以考虑：
先把 `leaudit_audit_runs` 正式重构为“平台通用引擎运行表”，明确它不再是 `leaudit` 私有运行表。
此时至少要补齐类似字段：
- `engine_type`
- `biz_module`
- `result_summary_json`
- `artifact_manifest_json`
然后让：
- `leaudit`
- `govdoc`
都成为这张“通用运行表”的消费者。
但要注意，这已经不是“直接复用原表”，而是：
- 先重构当前表
- 再让它变成通用表
这条路能走，但复杂度明显高于“新建 `govdoc_runs`”。
当前阶段，更推荐后者。
---
## 9. 明确建议
我的明确建议是：
- 不用全部重建
- 但也不要零成本硬复用全部现有结果表
最佳实践：
- 复用 `用户 / 权限 / 地区 / 文档主档 / 文件主档 / OSS / 任务系统`
- 新建 `govdoc` 的 `run + result + artifact` 结果域表
即：
**复用公共底座，新建领域结果。**
---
## 10. 推荐最终表划分
### 10.1 复用
- `sso_users`
- `roles`
- `user_role`
- `permissions`
- `role_permissions`
- `sys_routes`
- `role_route`
- `leaudit_documents`
- `leaudit_document_files`
### 10.2 建议补字段
- `leaudit_documents.engine_type`
- 或 `leaudit_documents.biz_module`
### 10.3 新增
- `govdoc_runs`
- `govdoc_rule_results`
- `govdoc_entities`
- `govdoc_report_artifacts`
后续规则平台化时再补：
- `govdoc_rule_sets`
- `govdoc_rule_versions`
---
## 11. 最终落地建议
如果现在立刻开始实施，建议按下面这版定：
1. `leaudit_documents` / `leaudit_document_files` 继续复用
2. 在 `leaudit_documents` 增加 `engine_type='govdoc'`
3. 新建 `govdoc_runs`
4. 新建 `govdoc_rule_results`
5. 新建 `govdoc_report_artifacts`
6. 后续视情况补 `govdoc_entities`
这是一版：
- 改动面适中
- 风险最小
- 迁移成本可控
- 长期仍可扩展
非常适合当前项目阶段。
docs/内部公文模块/内部公文模块目录结构与代码落点清单.md
+617
View File
@@ -0,0 +1,617 @@
# 内部公文模块目录结构与代码落点清单
## 1. 目标
本文档用于把 `govdoc-audit` 迁入当前 `leaudit-platform` 时，明确：
- 模块目录应该放在哪里
- 哪些旧代码要迁
- 哪些当前项目代码要扩展
- 每一层应该承担什么职责
- 第一阶段到第五阶段分别落哪些文件
这份文档不是讲业务方案，而是讲“代码最终应该落到仓库哪里”。
---
## 2. 总体落点原则
迁移后的 `govdoc` 不应再是一个独立系统，而应成为当前仓库中的一个标准业务模块。
总体原则：
- 内核代码进 `fastapi_modules/fastapi_leaudit/govdoc_engine/`
- 平台适配代码进 `fastapi_modules/fastapi_leaudit/govdoc_bridge/`
- 接口代码进 `controllers/`
- 业务编排代码进 `services/impl/`
- ORM 模型进 `models/`
- SQL 进 `scripts/创建sql/`
- 文档进 `docs/内部公文模块/`
- 前端模块进 `legal-platform-frontend/`
---
## 3. 后端目录结构建议
建议最终目录结构如下：
```text
fastapi_modules/fastapi_leaudit/
controllers/
govdocController.py
services/
govdocService.py
impl/
govdocServiceImpl.py
govdoc_bridge/
__init__.py
tasks.py
runner.py
input_resolver.py
rules_resolver.py
storage_adapter.py
result_adapter.py
report_adapter.py
context_builder.py
security_guard.py
govdoc_engine/
__init__.py
models.py
pipeline.py
parser/
dsl/
engine/
reporter/
llm/
models/
govdocRun.py
govdocRuleResult.py
govdocEntity.py
govdocReportArtifact.py
govdocRuleSet.py
govdocRuleVersion.py
```
---
## 4. 旧项目代码迁移落点
旧项目路径：
- `/home/wren-dev/Porject/govdoc-audit/`
### 4.1 建议直接迁入 `govdoc_engine/` 的内容
建议从旧项目迁入这些目录/文件：
```text
src/govdoc_audit/models.py
src/govdoc_audit/pipeline.py
src/govdoc_audit/parser/
src/govdoc_audit/dsl/
src/govdoc_audit/engine/
src/govdoc_audit/reporter/
src/govdoc_audit/llm/
```
迁入后落到：
```text
fastapi_modules/fastapi_leaudit/govdoc_engine/
```
### 4.2 不建议迁入的旧项目内容
这些不要直接迁：
```text
src/govdoc_audit/api/
src/govdoc_audit/storage/
src/govdoc_audit/services/storage_service.py
web/
```
原因：
- API 已由当前平台统一承接
- 存储必须改走当前数据库 + OSS
- 前端要融入当前平台，而不是保留一套独立页面
### 4.3 旧规则文件建议落点
旧规则文件：
```text
rules/govdoc_general/rules.yaml
```
短期建议：
- 先迁到当前仓库本地规则目录，例如：
```text
rules/govdoc/govdoc_general/rules.yaml
```
中期建议：
- 纳入规则版本管理体系
- 上传到 OSS
- 使用 `govdoc_rule_sets` / `govdoc_rule_versions` 控制生效版本
---
## 5. 新增后端文件清单
下面是建议新增的后端文件。
### 5.1 控制器层
新增：
- `fastapi_modules/fastapi_leaudit/controllers/govdocController.py`
职责：
- 上传公文
- 查询公文列表
- 查询文档详情
- 发起审查
- 查询 run 状态
- 查询 findings / entities / reports
- 下载 HTML / DOCX / 原文
- 查询规则清单
同时需要：
- 在 `fastapi_admin/bootstrap_parts/controllers.py` 中注册 `govdocController`
### 5.2 服务接口层
新增：
- `fastapi_modules/fastapi_leaudit/services/govdocService.py`
职责：
- 定义 `IGovdocService` 抽象接口
### 5.3 服务实现层
新增：
- `fastapi_modules/fastapi_leaudit/services/impl/govdocServiceImpl.py`
职责：
- 调用文档主档服务
- 创建 `govdoc_runs`
- 编排 worker 执行
- 聚合详情返回前端
- 权限/地区作用域后的结果查询
### 5.4 bridge 层
新增目录：
- `fastapi_modules/fastapi_leaudit/govdoc_bridge/`
建议文件职责如下。
#### `tasks.py`
职责：
- Celery 任务入口
- 抢占 run
- 加载执行上下文
- 调用 `runner.py`
参考现有：
- `fastapi_modules/fastapi_leaudit/leaudit_bridge/tasks.py`
#### `runner.py`
职责：
- 调用 `govdoc_engine.pipeline` 执行完整审查
- 组织执行顺序
- 统一异常转换
#### `input_resolver.py`
职责：
- 从 `leaudit_documents` / `leaudit_document_files` 中定位输入文件
- 从 OSS 下载到本地临时路径
- 附加必要的文件元信息
#### `rules_resolver.py`
职责：
- 解析当前应使用的公文规则版本
- 读取本地规则或从 OSS 下载规则文件
- 校验规则版本可用性
#### `storage_adapter.py`
职责：
- 把 run 状态、结果摘要、规则结果、实体、报告路径写回数据库
- 更新文档处理状态
#### `result_adapter.py`
职责：
- 将 `govdoc_engine` 的原始结果对象映射成数据库模型和前端 VO
#### `report_adapter.py`
职责：
- 处理 HTML、annotated docx、paragraph html、json 结果等产物上传 OSS
- 返回 artifact 清单
#### `context_builder.py`
职责：
- 统一构造一次 run 的执行上下文
- 避免在多个文件中反复拼上下文
#### `security_guard.py`
职责：
- 文件扩展名 / MIME / 大小 / 页数 / 压缩体积 / 临时路径安全校验
- 调用前的执行保护
---
## 6. 建议新增的 ORM 模型文件
建议新增：
- `fastapi_modules/fastapi_leaudit/models/govdocRun.py`
- `fastapi_modules/fastapi_leaudit/models/govdocRuleResult.py`
- `fastapi_modules/fastapi_leaudit/models/govdocEntity.py`
- `fastapi_modules/fastapi_leaudit/models/govdocReportArtifact.py`
- `fastapi_modules/fastapi_leaudit/models/govdocRuleSet.py`
- `fastapi_modules/fastapi_leaudit/models/govdocRuleVersion.py`
还需要：
- 更新 `fastapi_modules/fastapi_leaudit/models/__init__.py`
职责建议如下。
### 6.1 `govdocRun.py`
负责：
- 一次公文审查运行记录
- 记录文档、触发人、状态、阶段、得分、摘要、错误信息
### 6.2 `govdocRuleResult.py`
负责：
- 单条规则执行结果
- 记录 rule_id / severity / category / message / location / pass/fail/skipped
### 6.3 `govdocEntity.py`
负责：
- 标题、发文字号、文种、署名、附件、发文机关等实体结果
### 6.4 `govdocReportArtifact.py`
负责：
- HTML 报告、批注 DOCX、段落 HTML、JSON 报告等 OSS 产物索引
### 6.5 `govdocRuleSet.py`
负责：
- 公文规则集定义
### 6.6 `govdocRuleVersion.py`
负责：
- 规则版本与 OSS 路径、sha256、发布态等
---
## 7. 建议扩展的现有后端文件
除了新增文件，还建议扩展这些现有文件。
### 7.1 `fastapi_modules/fastapi_leaudit/models/leauditDocument.py`
建议增加：
- `engineType` / `engine_type`
用途：
- 标识该文档属于 `govdoc` 还是 `leaudit`
### 7.2 `fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py`
建议扩展：
- 上传时支持传入 `engine_type='govdoc'`
- 查询列表时支持按 `engine_type` 过滤
- 详情页聚合时能分发到 `govdoc` 详情构建逻辑
如果不想动太多，也可先由 `govdocServiceImpl` 单独包一层调用文档主档逻辑。
### 7.3 `fastapi_admin/bootstrap_parts/controllers.py`
建议扩展：
- 注册 `govdocController`
### 7.4 `fastapi_modules/fastapi_leaudit/services/impl/rbacAdminServiceImpl.py`
建议扩展：
- 加入 `govdoc:*` 权限种子定义
- 加入 `/govdoc` 路由绑定定义
### 7.5 `fastapi_modules/fastapi_leaudit/services/impl/rbacServiceImpl.py`
建议扩展：
- 为 `/govdoc` 前端入口提供兼容 route blueprint（如果当前系统仍依赖该机制）
---
## 8. SQL 文件落点建议
建议新增以下 SQL 草案文件：
- `scripts/创建sql/schema_add_govdoc_module.sql`
- `scripts/创建sql/seed_govdoc_permissions.sql`
- `scripts/创建sql/seed_govdoc_entry_module.sql`
- `scripts/创建sql/seed_govdoc_routes.sql`
职责建议：
### 8.1 `schema_add_govdoc_module.sql`
负责：
- 新增 `govdoc_runs`
- 新增 `govdoc_rule_results`
- 新增 `govdoc_entities`
- 新增 `govdoc_report_artifacts`
- 给 `leaudit_documents` 增加 `engine_type`
### 8.2 `seed_govdoc_permissions.sql`
负责：
- 插入 `govdoc:*:*` 权限点
### 8.3 `seed_govdoc_entry_module.sql`
负责：
- 在入口模块配置中加入 `govdoc`
### 8.4 `seed_govdoc_routes.sql`
负责：
- 加入 `/govdoc` 模块菜单与页面路由绑定
---
## 9. 文档目录落点建议
建议所有迁移文档统一放在：
```text
docs/内部公文模块/
```
建议至少保留：
- `内部公文模块迁移方案.md`
- `内部公文模块数据表复用与新增建议.md`
- `内部公文模块接口与权限设计.md`
- `内部公文模块目录结构与代码落点清单.md`
后续还可以继续补：
- `内部公文模块前端页面设计.md`
- `内部公文模块执行链与安全控制点.md`
- `内部公文模块测试清单.md`
---
## 10. 前端目录结构建议
前端项目在：
- `legal-platform-frontend/`
建议新增目录结构类似：
```text
legal-platform-frontend/
app/(audit)/govdoc/
page.tsx
upload/page.tsx
list/page.tsx
detail/[documentId]/page.tsx
components/govdoc/
upload-form.tsx
govdoc-list.tsx
govdoc-detail.tsx
findings-panel.tsx
entity-panel.tsx
report-toolbar.tsx
hooks/govdoc/
useGovdocList.ts
useGovdocDetail.ts
useGovdocRun.ts
lib/api/govdoc/
client.ts
types.ts
```
职责建议：
### 10.1 页面层
- 上传页
- 列表页
- 详情页
### 10.2 组件层
- 列表组件
- 详情组件
- findings 面板
- entities 面板
- 报告下载工具栏
### 10.3 hooks 层
- 列表请求
- 详情请求
- run 状态轮询
### 10.4 API 层
- 对接 `/api/v3/govdoc/*`
---
## 11. 第一阶段最小落地文件集
如果先只做一个最小可运行版本，建议第一批先落这些文件：
### 后端
- `controllers/govdocController.py`
- `services/govdocService.py`
- `services/impl/govdocServiceImpl.py`
- `govdoc_bridge/tasks.py`
- `govdoc_bridge/runner.py`
- `govdoc_bridge/input_resolver.py`
- `govdoc_bridge/storage_adapter.py`
- `govdoc_bridge/result_adapter.py`
- `govdoc_engine/`（裁剪内核）
- `models/govdocRun.py`
- `models/govdocRuleResult.py`
- `models/govdocReportArtifact.py`
### SQL
- `schema_add_govdoc_module.sql`
- `seed_govdoc_permissions.sql`
### 前端
- 上传页
- 列表页
- 详情页
- `lib/api/govdoc/client.ts`
这样就可以先跑通：
- 上传
- 发起审查
- 查询 run
- 看结果
- 下载报告
---
## 12. 第二阶段建议补充文件
第二阶段再补：
### 后端
- `models/govdocEntity.py`
- `models/govdocRuleSet.py`
- `models/govdocRuleVersion.py`
- `govdoc_bridge/rules_resolver.py`
- `govdoc_bridge/report_adapter.py`
- `govdoc_bridge/security_guard.py`
### SQL
- `seed_govdoc_entry_module.sql`
- `seed_govdoc_routes.sql`
### 前端
- 规则查看页
- 模块配置页
- 规则版本管理页（如果做）
---
## 13. 与现有 `leaudit_bridge` 的关系
`govdoc_bridge` 不应替换 `leaudit_bridge`，而应与之并行存在。
建议关系：
- `leaudit_bridge` 处理现有评查引擎
- `govdoc_bridge` 处理公文格式审查引擎
共同复用：
- Celery
- OSS
- JWT/RBAC
- 文档主档
- 地区隔离
这样当前平台最终就形成多引擎结构：
- `leaudit`
- `govdoc`
- `rag`（知识库/对话是另一类模块，不完全同构）
---
## 14. 最终建议
如果目标是把 `govdoc-audit` 真正“变成当前项目里的一个模块”，那代码落点必须明确：
- 内核进 `govdoc_engine`
- 平台适配进 `govdoc_bridge`
- 业务编排进 `govdocServiceImpl`
- 对外接口进 `govdocController`
- 运行与结果落 `govdoc_*` 表
- 页面落当前前端 `govdoc` 目录
不要保留成：
- 一个独立 API 项目
- 一个独立前端项目
- 一套独立 SQLite 持久化
那样不叫模块化迁移，只叫外挂系统代理。
当前最稳的落法，就是按本文档这套目录与代码边界执行。
docs/内部公文模块/内部公文模块迁移方案.md
+503
View File
@@ -0,0 +1,503 @@
# 内部公文模块迁移方案
## 1. 目标定位
`govdoc-audit` 不应作为独立系统继续外挂，而应正式收口为当前 `leaudit-platform` 中的一个一等业务模块。
建议模块名：
- `govdoc`
- 中文显示名：`内部公文处理`
它在当前项目中的定位应为：
- 一个“公文处理与格式审查模块”
- 共享当前平台的用户、权限、文档、OSS、任务系统
- 拥有自己独立的规则、运行、结果、报告模型
---
## 2. 总体迁移原则
一句话原则：
- 迁“引擎”
- 不迁“壳子”
应迁入当前项目的内容：
- 公文解析器
- 段落角色识别
- 语义实体提取
- YAML DSL
- 规则执行器
- HTML / DOCX / JSON 报告生成
不建议直接迁入的内容：
- 原 `FastAPI` API 层
- 原 `SQLite` 存储层
- 原 `web` 前端
- 原本地 `var/documents` 落盘模式
原因是当前平台已经具备更成熟的基础设施：
- 统一 FastAPI 应用
- JWT / RBAC
- 地区隔离
- 文档主档与文件版本
- MinIO / OSS
- Celery 异步任务
- bridge 执行链
因此正确方案不是再造第二个平台，而是把 `govdoc-audit` 变成当前平台中的一个能力模块。
---
## 3. 模块化后的目标形态
### 3.1 后端模块职责
该模块应负责：
- 公文上传
- 公文格式审查
- 审查结果查询
- 规则查看
- 报告下载
- 审查过程留痕
不负责：
- 通用 RAG
- 合同评审
- 交叉评查
### 3.2 前端模块职责
前端中应新增一个独立入口模块，页面建议包括：
- 公文上传页
- 审查列表页
- 审查详情页
- 规则查看页
- 报告下载入口
- 模块配置页（可选）
路由建议：
- `/govdoc`
- `/govdoc/upload`
- `/govdoc/list`
- `/govdoc/detail/:documentId`
---
## 4. 推荐架构分层
建议按 6 层拆分：
1. 接口层
2. 服务层
3. 执行桥接层
4. 引擎内核层
5. 持久化层
6. 展示层
### 4.1 接口层
建议新增：
- `fastapi_modules/fastapi_leaudit/controllers/govdocController.py`
职责：
- 上传公文
- 查询公文列表
- 发起审查
- 查询运行状态
- 查询结果详情
- 下载 HTML / DOCX / 原文
- 查询规则清单
控制器只做：
- JWT 鉴权
- DTO 收参
- 调 service
- 统一返回 Result
### 4.2 服务层
建议新增：
- `fastapi_modules/fastapi_leaudit/services/govdocService.py`
- `fastapi_modules/fastapi_leaudit/services/impl/govdocServiceImpl.py`
职责：
- 复用当前文档服务做上传与元数据管理
- 创建公文审查 run
- 调度异步任务
- 聚合查询结果
- 组织前端详情数据
### 4.3 执行桥接层
建议新增目录：
```text
fastapi_modules/fastapi_leaudit/govdoc_bridge/
__init__.py
tasks.py
runner.py
input_resolver.py
rules_resolver.py
storage_adapter.py
result_adapter.py
report_adapter.py
context_builder.py
security_guard.py
```
职责：
- 从当前平台读取文档与文件元数据
- 从 OSS 下载文档到本地临时文件
- 解析规则版本并准备本地规则文件
- 调用 `govdoc` 引擎执行
- 将结果适配回当前平台数据库和 OSS
这是整个模块接入的关键层。
### 4.4 引擎内核层
建议把 `govdoc-audit` 裁剪后并入当前仓库：
```text
fastapi_modules/fastapi_leaudit/govdoc_engine/
__init__.py
models.py
pipeline.py
parser/
dsl/
engine/
reporter/
llm/
```
建议迁入：
- `parser/`
- `dsl/`
- `engine/`
- `reporter/`
- `llm/`
- `models.py`
- `pipeline.py`
明确不迁：
- 原 `api/`
- 原 `storage/`
- 原 `services/storage_service.py`
- 原 `web/`
### 4.5 持久化层
不建议继续使用原项目自己的 `SQLite + var/documents` 模式。
应基于当前平台数据库新增公文模块结果域表。
### 4.6 展示层
不迁原 `govdoc-audit/web`。
应直接在当前前端项目中新增 `govdoc` 模块页面，复用现有：
- 登录态
- 权限体系
- 侧边栏菜单
- UI 样式体系
---
## 5. 数据模型建议
### 5.1 应复用的平台公共表
建议直接复用：
- `sso_users`
- `roles`
- `user_role`
- `permissions`
- `role_permissions`
- `sys_routes`
- `role_route`
- `leaudit_documents`
- `leaudit_document_files`
这些表负责：
- 用户身份
- 权限控制
- 地区隔离
- 文档主档
- 文件版本
- OSS 关联
### 5.2 建议补充的主档字段
建议在 `leaudit_documents` 增加一个模块标识字段，例如：
- `engine_type`
可选值：
- `leaudit`
- `govdoc`
- `rag`
这样平台可以明确知道某份文档应走哪条处理链。
### 5.3 建议新增的公文模块结果域表
第一阶段建议至少新增：
- `govdoc_runs`
- `govdoc_rule_results`
- `govdoc_report_artifacts`
后续可补：
- `govdoc_entities`
- `govdoc_rule_sets`
- `govdoc_rule_versions`
推荐理解方式：
- 公共主档复用
- 领域结果隔离
不要把公文模块结果硬塞进现有 `leaudit_audit_runs` / `leaudit_rule_results`。
原因：
- 语义不完全一致
- 结果模型不完全兼容
- 统计口径会混乱
- 后期拆分成本更高
---
## 6. 模块权限设计建议
建议一开始就单独定义 `govdoc` 模块权限键：
- `govdoc:module:read`
- `govdoc:document:create`
- `govdoc:document:read`
- `govdoc:document:update`
- `govdoc:document:delete`
- `govdoc:run:create`
- `govdoc:run:read`
- `govdoc:report:read`
- `govdoc:rule:read`
- `govdoc:rule:manage`
权限层继续复用当前平台：
- JWT 鉴权
- RBAC
- 地区隔离
数据范围继续遵守当前平台规则：
- 省级管理员：全量
- 地区管理员：本地区
- 普通用户：本人数据
---
## 7. 迁移实施步骤
建议分 5 期推进。
### 第一期：内核迁入
目标：
- 把 `govdoc-audit` 裁成当前项目内可调用的纯引擎内核
动作：
- 新建 `govdoc_engine/`
- 迁入 `parser / dsl / engine / reporter / llm`
- 去掉原 `api / storage / web` 依赖
- 改成本项目统一 import 结构
- 规则文件暂放本地规则目录
产出：
- 当前项目内可以本地调用一份 `.docx` 执行公文审查
### 第二期：bridge 接入
目标：
- 接入当前 worker 执行链
动作：
- 新建 `govdoc_bridge/tasks.py`
- 新建 `govdoc_bridge/storage_adapter.py`
- 新建 `govdoc_bridge/result_adapter.py`
- 复用 OSS 下载到本地临时文件
- 复用 Celery 异步执行
- 结果回写 DB + 上传 OSS
产出：
- 当前项目可异步跑公文审查任务
### 第三期：服务与接口接入
目标：
- 正式形成后端模块 API
动作：
- 新增 `govdocController.py`
- 新增 `govdocServiceImpl.py`
- 接入 JWT
- 接入地区隔离
- 接入上传、列表、详情、运行状态、报告下载
产出：
- 前端可以通过当前后端 API 正式使用公文模块
### 第四期：前端模块接入
目标：
- 当前平台页面可用
动作：
- 新增侧边栏模块
- 新增上传页、列表页、详情页
- 详情页展示：
- 分数
- findings
- entities
- 原文段落联动
- HTML / DOCX 报告下载
- 接入权限控制
产出：
- 用户可在当前平台直接使用“内部公文处理”
### 第五期：平台化收口
目标：
- 进入长期可维护状态
动作：
- 规则版本化
- 报告产物统一 OSS
- 文件转换 / 解析隔离执行
- LLM / OCR 白名单与审计
- 指标监控
- 错误告警
- 运行留痕
产出：
- 模块正式生产可用
---
## 8. 推荐目录结构
```text
fastapi_modules/fastapi_leaudit/
controllers/
govdocController.py
services/
govdocService.py
impl/
govdocServiceImpl.py
govdoc_bridge/
__init__.py
tasks.py
runner.py
input_resolver.py
rules_resolver.py
storage_adapter.py
result_adapter.py
report_adapter.py
security_guard.py
govdoc_engine/
__init__.py
models.py
pipeline.py
parser/
dsl/
engine/
reporter/
llm/
models/
govdocRun.py
govdocRuleResult.py
govdocEntity.py
govdocReportArtifact.py
govdocRuleSet.py
govdocRuleVersion.py
```
文档与 SQL：
```text
docs/内部公文模块/
内部公文模块迁移方案.md
内部公文模块数据表复用与新增建议.md
scripts/创建sql/
schema_add_govdoc_module.sql
seed_govdoc_permissions.sql
seed_govdoc_entry_module.sql
```
---
## 9. 最终建议
最优方案不是：
- 保留 `govdoc-audit` 为独立服务
- 当前平台只做代理壳
而应该是：
- 把 `govdoc-audit` 裁成 `govdoc_engine`
- 通过 `govdoc_bridge + Celery + OSS + RBAC + 地区隔离`
- 正式并入 `leaudit-platform`
最终形成：
- 平台共享底座
- 模块独立结果域
- 前后端统一接入
- 规则、报告、运行态统一纳入当前项目
这是最稳、最适合长期维护的一条路。