62 lines
3.8 KiB
Markdown
62 lines
3.8 KiB
Markdown
# 文档权限页面接口接入说明
|
||
|
||
依据本机后端 `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`，不需要新增专用用户权限接口。
|