# 文档权限页面接口接入说明

核验时间：2026-09-03。依据后端提交 `b2f9a48` 部署后的 `http://127.0.0.1:18080/v3/api-docs`，文档权限页面已按“文档模板”维度接入新权限配置目录、跨模板矩阵和批量保存接口。页面保留原型的三部分，并补充单用户直接授权：

1. **文档库权限矩阵**：说明可见、可用、可维护和继承规则。
2. **按角色授权**：选择一个文档模板，调整角色的 VIEW、USE、MAINTAIN。
3. **按科室授权**：沿用当前模板，调整科室的 VIEW、USE、MAINTAIN。
4. **模板权限明细与直接授权**：可选择角色、科室或用户新增/删除直接绑定，并选择用户预览继承结果。

## 已接入接口

| 用途               | 方法   | 路径                                                      |
| ------------------ | ------ | --------------------------------------------------------- |
| 查询权限配置模板   | GET    | /api/v1/templates/permission-config                       |
| 查询角色及人数     | GET    | /api/v1/roles/summary                                     |
| 查询科室           | GET    | /api/v1/departments                                       |
| 查询用户           | GET    | /api/v1/users                                             |
| 查询跨模板权限矩阵 | GET    | /api/v1/templates/permissions/matrix                      |
| 批量新增或撤销权限 | POST   | /api/v1/templates/permissions/batch                       |
| 查询用户继承结果   | GET    | /api/v1/templates/{templateId}/permissions                |
| 旧版单模板新增权限 | POST   | /api/v1/templates/{templateId}/permissions                |
| 旧版单模板撤销权限 | DELETE | /api/v1/templates/{templateId}/permissions/{permissionId} |

单条权限绑定请求使用 OpenAPI 中的 PermissionBindingRequest：

```json
{
  "subjectType": "ROLE",
  "subjectId": "<role-or-department-uuid>",
  "permissionLevel": "USE",
  "effect": "ALLOW"
}
```

批量保存请求使用 `TemplatePermissionBatchRequest`：

```json
{
  "operations": [
    {
      "templateId": "<template-uuid>",
      "action": "ADD",
      "subjectType": "ROLE",
      "subjectId": "<role-uuid>",
      "permissionLevel": "USE",
      "effect": "ALLOW"
    },
    {
      "templateId": "<template-uuid>",
      "action": "REVOKE",
      "permissionId": "<direct-permission-uuid>"
    }
  ]
}
```

成功响应的 `data.results` 与 `operations` 下标对应，ADD 的 `result` 为 `CREATED` 或 `EXISTING`，REVOKE 的 `result` 为 `REVOKED`。

权限等级映射：

- VIEW：可浏览模板
- USE：可发起签署
- MAINTAIN：可维护模板

权限配置目录、权限矩阵、科室和用户接口都是分页接口，页面按后端返回的 `total` 自动补齐后续页，不会因为接口单页上限 200 而漏掉配置模板或授权对象。权限配置目录遵守操作者数据范围；管理员可以查询范围内全部模板，但不能绕过院区、科室和数据范围。角色优先使用 `/roles/summary` 获取人数；该接口失败时回退 `/roles`，人数按已加载用户的角色关系估算。

权限矩阵按当前选择的模板调用 `templateId` 查询，并自动读取所有矩阵分页。矩阵支持 `templateId/templateIds`（最多 100 个）、`roleId`、`subjectDepartmentId`、`userId`、`subjectType`、`campusId` 和 `templateDepartmentId` 筛选；数组参数按重复 query 参数发送。页面使用旧的单模板 GET 接口补充指定用户的有效继承预览，因为矩阵接口中的 `userId` 是授权主体筛选条件，不是继承预览参数。接口返回的直接绑定和继承结果统一展示；继承项的 `permissionId`、`subjectId`、`createdAt` 和 `createdBy` 可为空，页面将其标记为系统默认继承规则且不可删除。

## 页面保存行为

页面开关和明细表单统一使用 `/templates/permissions/batch` 保存，后端保证整批预校验、事务回滚和幂等：

- 开启：批量 REVOKE 同主体、同等级的直接 DENY；没有有效允许权限时 ADD ALLOW。
- 关闭：批量 REVOKE 直接 ALLOW；如果仍有继承的 ALLOW，ADD 直接 DENY 覆盖继承。
- 明细新增发送单项 ADD，明细删除发送单项 REVOKE；REVOKE 只携带直接权限绑定 ID。
- ADD 返回 `CREATED` 或 `EXISTING` 均视为成功；继承权限不参与撤销。
- 继承 DENY 没有持久化绑定 ID，且契约约定拒绝优先，页面将其显示为不可直接覆盖。

页面不会把继承结果当成可删除的直接绑定，也不会伪造权限数据。权限矩阵查询失败时会显示错误态并禁用新增、删除和矩阵调整，避免把空响应误当成“无权限”。真实环境接口没有数据时会显示空态。

## 当前核验结论

文档权限页面仅在显式设置 `VITE_MOCK_DOCUMENT_PERMISSIONS=true` 时使用演示数据；未设置该变量或设为 `false` 时，页面调用真实权限接口。该开关缺省关闭。修改环境变量后需要重启 Vite。

本轮新增接口已覆盖当前文档权限页面的后端缺口，暂无阻断前端接入的缺失接口。跨模板矩阵查询最多支持 100 个模板，批量保存最多支持 200 项；页面当前采用“模板选择 + 当前模板矩阵”的交互，没有臆造跨模板对比表。

联调验收至少包括：

- 权限管理员能看到数据范围内、但普通模板 ACL 不可见的配置模板；越过院区、科室或数据范围时返回 403。
- Network 中模板目录使用 `/api/v1/templates/permission-config`，矩阵使用 `/api/v1/templates/permissions/matrix` 并正确发送 `page/size/templateId`。
- 页面能跨矩阵分页读取直接权限和继承权限；继承空字段显示为默认规则且不提供删除。
- 开关操作使用一次批量请求；同时撤销旧绑定并新增覆盖规则时整批成功或整批回滚。
- 重复新增返回 `EXISTING`，撤销继承权限被拒绝，审计日志记录批量操作。