feat: 接入文档权限批量接口
This commit is contained in:
xy
@@ -1,6 +1,6 @@
|
||||
# 文档权限页面接口接入说明
|
||||
|
||||
依据本机后端 `http://127.0.0.1:18080/v3/api-docs`，文档权限页面当前按“文档模板”维度接入权限。页面保留原型的三部分，并补充单用户直接授权：
|
||||
核验时间：2026-09-03。依据后端提交 `b2f9a48` 部署后的 `http://127.0.0.1:18080/v3/api-docs`，文档权限页面已按“文档模板”维度接入新权限配置目录、跨模板矩阵和批量保存接口。页面保留原型的三部分，并补充单用户直接授权：
|
||||
|
||||
1. **文档库权限矩阵**：说明可见、可用、可维护和继承规则。
|
||||
2. **按角色授权**：选择一个文档模板，调整角色的 VIEW、USE、MAINTAIN。
|
||||
@@ -9,17 +9,19 @@
|
||||
|
||||
## 已接入接口
|
||||
|
||||
| 用途 | 方法 | 路径 |
|
||||
| ---------------------- | ------ | --------------------------------------------------------- |
|
||||
| 查询可配置模板 | 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} |
|
||||
| 用途 | 方法 | 路径 |
|
||||
| ------------------ | ------ | --------------------------------------------------------- |
|
||||
| 查询权限配置模板 | 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：
|
||||
单条权限绑定请求使用 OpenAPI 中的 PermissionBindingRequest：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -30,32 +32,60 @@
|
||||
}
|
||||
```
|
||||
|
||||
批量保存请求使用 `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`，人数按已加载用户的角色关系估算。
|
||||
权限配置目录、权限矩阵、科室和用户接口都是分页接口，页面按后端返回的 `total` 自动补齐后续页，不会因为接口单页上限 200 而漏掉配置模板或授权对象。权限配置目录遵守操作者数据范围；管理员可以查询范围内全部模板，但不能绕过院区、科室和数据范围。角色优先使用 `/roles/summary` 获取人数；该接口失败时回退 `/roles`，人数按已加载用户的角色关系估算。
|
||||
|
||||
查询模板权限时不传 `userId` 表示查看当前登录用户的继承结果；页面也支持选择用户，将其 UUID 作为 `userId` 重新查询，用于预览该用户的科室签署员默认 `USE` 继承。接口返回的直接绑定和继承结果统一展示，但只有直接绑定带有可删除的 `id`。
|
||||
权限矩阵按当前选择的模板调用 `templateId` 查询，并自动读取所有矩阵分页。矩阵支持 `templateId/templateIds`（最多 100 个）、`roleId`、`subjectDepartmentId`、`userId`、`subjectType`、`campusId` 和 `templateDepartmentId` 筛选；数组参数按重复 query 参数发送。页面使用旧的单模板 GET 接口补充指定用户的有效继承预览，因为矩阵接口中的 `userId` 是授权主体筛选条件，不是继承预览参数。接口返回的直接绑定和继承结果统一展示；继承项的 `permissionId`、`subjectId`、`createdAt` 和 `createdBy` 可为空，页面将其标记为系统默认继承规则且不可删除。
|
||||
|
||||
## 页面保存行为
|
||||
|
||||
当前契约没有更新权限绑定的 PUT 接口，因此开关按以下规则保存：
|
||||
页面开关和明细表单统一使用 `/templates/permissions/batch` 保存，后端保证整批预校验、事务回滚和幂等：
|
||||
|
||||
- 开启：删除同主体、同等级的直接 DENY；没有有效允许权限时 POST ALLOW。
|
||||
- 关闭：撤销直接 ALLOW；如果仍有继承的 ALLOW，POST 直接 DENY 覆盖继承。
|
||||
- 开启：批量 REVOKE 同主体、同等级的直接 DENY；没有有效允许权限时 ADD ALLOW。
|
||||
- 关闭：批量 REVOKE 直接 ALLOW；如果仍有继承的 ALLOW，ADD 直接 DENY 覆盖继承。
|
||||
- 明细新增发送单项 ADD，明细删除发送单项 REVOKE；REVOKE 只携带直接权限绑定 ID。
|
||||
- ADD 返回 `CREATED` 或 `EXISTING` 均视为成功；继承权限不参与撤销。
|
||||
- 继承 DENY 没有持久化绑定 ID，且契约约定拒绝优先，页面将其显示为不可直接覆盖。
|
||||
|
||||
页面不会把继承结果当成可删除的直接绑定，也不会伪造全局权限矩阵数据。权限查询失败时会显示错误态并禁用新增、删除和矩阵调整，避免把空响应误当成“无权限”。真实环境接口没有数据时会显示空态。
|
||||
页面不会把继承结果当成可删除的直接绑定，也不会伪造权限数据。权限矩阵查询失败时会显示错误态并禁用新增、删除和矩阵调整，避免把空响应误当成“无权限”。真实环境接口没有数据时会显示空态。
|
||||
|
||||
## 当前 OpenAPI 未提供的能力
|
||||
## 当前核验结论
|
||||
|
||||
如果产品要求“跨全部文档模板”的全局角色/科室权限矩阵，后端还需要提供以下能力之一：
|
||||
本轮新增接口已覆盖当前文档权限页面的后端缺口，暂无阻断前端接入的缺失接口。跨模板矩阵查询最多支持 100 个模板，批量保存最多支持 200 项；页面当前采用“模板选择 + 当前模板矩阵”的交互，没有臆造跨模板对比表。
|
||||
|
||||
- 全局角色权限查询与批量保存接口；
|
||||
- 全局科室权限查询与批量保存接口；
|
||||
- 或提供带模板维度的批量权限查询/保存接口，避免前端逐个模板请求。
|
||||
联调验收至少包括：
|
||||
|
||||
另外，当前 GET /api/v1/templates 的语义是查询当前用户有权限查看的模板。若权限管理员需要配置自己当前不可见的模板，请后端提供管理员可见的模板列表语义或专用接口。用户直接授权已使用 `subjectType=USER`，不需要新增专用用户权限接口。
|
||||
- 权限管理员能看到数据范围内、但普通模板 ACL 不可见的配置模板；越过院区、科室或数据范围时返回 403。
|
||||
- Network 中模板目录使用 `/api/v1/templates/permission-config`，矩阵使用 `/api/v1/templates/permissions/matrix` 并正确发送 `page/size/templateId`。
|
||||
- 页面能跨矩阵分页读取直接权限和继承权限；继承空字段显示为默认规则且不提供删除。
|
||||
- 开关操作使用一次批量请求；同时撤销旧绑定并新增覆盖规则时整批成功或整批回滚。
|
||||
- 重复新增返回 `EXISTING`，撤销继承权限被拒绝，审计日志记录批量操作。
|
||||
|
||||
Reference in New Issue
Block a user