xh-medical-sign-web/clinical-web/docs/document-permissions-api.md

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

核验时间：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：

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

批量保存请求使用 TemplatePermissionBatchRequest：

{
  "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，撤销继承权限被拒绝，审计日志记录批量操作。