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

依据本机后端 `http://127.0.0.1:18080/v3/api-docs`，文档权限页面当前按“文档模板”维度接入权限。页面保留原型的三部分，并补充单用户直接授权：

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

## 已接入接口

| 用途                   | 方法   | 路径                                                      |
| ---------------------- | ------ | --------------------------------------------------------- |
| 查询可配置模板         | GET    | /api/v1/templates                                         |
| 查询角色及人数         | GET    | /api/v1/roles/summary                                     |
| 查询科室               | GET    | /api/v1/departments                                       |
| 查询用户               | GET    | /api/v1/users                                             |
| 查询模板权限及继承结果 | 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"
}
```

权限等级映射：

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

模板、科室和用户接口都是分页接口，页面按后端返回的 `total` 自动补齐后续页，不会因为接口单页上限 200 而漏掉授权对象。角色优先使用 `/roles/summary` 获取人数；该接口失败时回退 `/roles`，人数按已加载用户的角色关系估算。

查询模板权限时不传 `userId` 表示查看当前登录用户的继承结果；页面也支持选择用户，将其 UUID 作为 `userId` 重新查询，用于预览该用户的科室签署员默认 `USE` 继承。接口返回的直接绑定和继承结果统一展示，但只有直接绑定带有可删除的 `id`。

## 页面保存行为

当前契约没有更新权限绑定的 PUT 接口，因此开关按以下规则保存：

- 开启：删除同主体、同等级的直接 DENY；没有有效允许权限时 POST ALLOW。
- 关闭：撤销直接 ALLOW；如果仍有继承的 ALLOW，POST 直接 DENY 覆盖继承。
- 继承 DENY 没有持久化绑定 ID，且契约约定拒绝优先，页面将其显示为不可直接覆盖。

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

## 当前 OpenAPI 未提供的能力

如果产品要求“跨全部文档模板”的全局角色/科室权限矩阵，后端还需要提供以下能力之一：

- 全局角色权限查询与批量保存接口；
- 全局科室权限查询与批量保存接口；
- 或提供带模板维度的批量权限查询/保存接口，避免前端逐个模板请求。

另外，当前 GET /api/v1/templates 的语义是查询当前用户有权限查看的模板。若权限管理员需要配置自己当前不可见的模板，请后端提供管理员可见的模板列表语义或专用接口。用户直接授权已使用 `subjectType=USER`，不需要新增专用用户权限接口。