leaudit-platform-backend/docs/内部公文模块/内部公文模块接口与权限设计.md

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

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

这样才能保证：

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