yelan
fc22d22f85
用 VITE_MOCK_* 系列环境变量替换全局 VITE_USE_MOCK，各模块独立控制演示数据 启用，并新增 src/utils/mock-flags.ts 统一解析缺省值。文档库关闭演示库时 如实提示接口待接入，避免静默沿用本地数据或覆盖已保存内容。
94 lines
5.9 KiB
Markdown
94 lines
5.9 KiB
Markdown
# 文档权限页面接口接入说明
|
||
|
||
核验时间：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`，撤销继承权限被拒绝，审计日志记录批量操作。
|