TanWenyan/leaudit-platform-backend

Fork 0

Files

T

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

2026-05-13 14:37:12 +08:00

12 KiB

Raw Blame History

内部公文模块接口与权限设计

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:*:*
数据范围统一走当前地区隔离逻辑
结果下载权限继承文档可见范围
公文模块不单独再造第二套用户、权限、地区模型

这样才能保证：

模块边界清晰
前后端联动简单
后续统计和审计一致
长期维护成本最低

12 KiB Raw Blame History

内部公文模块接口与权限设计

1. 目标

2. 设计原则

2.1 平台统一原则

2.2 接口职责边界

2.3 全异步执行原则

3. 模块路由建议

4. 权限键设计

4.1 模块级权限键

4.2 文档权限键

4.3 审查运行权限键

4.4 报告与结果权限键

4.5 规则权限键

4.6 配置权限键（可选）

5. 角色建议与默认授权

5.1 super_admin

5.2 provincial_admin

5.3 admin

5.4 common

6. 数据范围隔离规则

6.1 全局角色

6.2 地区管理角色

6.3 普通用户

6.4 结果与报告的权限继承

7. 接口设计建议

8. 文档接口

8.1 上传公文

8.2 获取公文列表

8.3 获取公文详情

8.4 更新文档信息

8.5 删除文档

9. 审查运行接口

9.1 发起审查

9.2 获取 run 状态

9.3 重试 run

10. 结果与报告接口

10.1 获取审查结果摘要

10.2 获取 findings 明细

10.3 获取 entities 明细

10.4 获取段落 HTML

10.5 下载 HTML 报告

10.6 下载批注 DOCX

10.7 下载原文

11. 规则接口

11.1 获取规则清单

11.2 获取规则详情

11.3 发布规则版本（后续）

12. 配置接口（可选）

12.1 获取模块配置

12.2 更新模块配置

13. 前后端联动约定

13.1 前端菜单显示

13.2 页面按钮显示

13.3 数据不可仅靠前端隐藏

14. 错误码与返回建议

15. SQL 与初始化建议

16. 最终建议

12 KiB

Raw Blame History

5.1 `super_admin`

5.2 `provincial_admin`

5.3 `admin`

5.4 `common`