操作许可与展示契约¶
状态：已批准技术设计，需求依据为正式 admin-spec-001 §4；不新增业务能力。
许可目录¶
| 许可 | 需求含义 | core 返回的 Refine resource/action |
|---|---|---|
| admin:enter | 进入管理区 | admin / enter |
| users:read | 查看用户 | users / list、show |
| users:enable | 启用账户 | users / enable |
| users:disable | 禁用账户 | users / disable |
| users:assign-role | 分配角色 | users / assign-role |
| users:reset-password | 重置密码 | users / reset-password |
| roles:read | 查看角色 | roles / list、show |
| roles:create | 创建角色 | roles / create |
| roles:rename | 修改角色名称 | roles / edit |
| roles:configure | 配置已有权限 | roles / configure |
| roles:delete | 删除未使用自定义角色 | roles / delete |
| permissions:read | 查看权限目录 | permissions / list |
| menus:read | 查看菜单目录 | menus / list |
| menus:edit | 编辑菜单展示 | menus / edit |
/sessions/current 返回 permissions 和由 core 从同一目录派生的 access。web 的 accessControlProvider 只查询 access[resource] 是否包含 action，不维护角色映射。没有 admin:enter 时，core 不返回可用管理操作，即使角色配置含资源项；所有管理 API 也同时核实进入许可。
permission 字符串是持久化和业务授权的目录键，access 是展示适配结果，不能作为第二个可编辑目录。菜单、资源声明、客户端提交的 permissions/access 一律不构成授权来源。
恢复集合与内置角色¶
- 内置 admin 初始具有全部上述许可；不可移除的恢复集合为 admin:enter、users:read、users:enable、users:assign-role、users:reset-password、roles:read、roles:configure、permissions:read。
- 内置 student/teacher 的管理许可集合为空且受保护；本人身份/改密/退出由认证与本人归属保证，不可通过删除角色许可移除。
- 自定义角色初始许可集合由创建请求明确给出，可以为空；没有任何隐含“管理员”放行。只读用户管理员为 admin:enter + users:read。
- actor 可授予集合为其当前拥有的管理许可；配置/分配需要各自操作许可。完整目标角色许可超范围即拒绝，不默默丢弃。
- 技术方案补充防间接提权：改变目标账户访问能力的启用/禁用/改角色/密码重置，同时核实其当前角色管理许可未超出 actor 的范围；分配新角色还核实新集合。该策略随本轮技术方案评审，不借密码重置夺取更高权限账户。
编辑上下文与导航¶
- 分配角色控件调用
/assignable-roles，仅返回 actor 可授予范围内的角色，不要求另授予全部角色查看许可；服务端提交时再次校验，查询结果不构成授权票据。 - 权限编辑控件调用
/roles/{id}/permission-edit-context，要求 roles:configure，返回当前目标与可授予目录、影响账户数；目标本身超范围则拒绝。它是该操作的最小编辑上下文，不开放全库角色信息。 - 一般权限目录
/permissions仍要求 permissions:read，角色列表与详情要求 roles:read；写操作所需上下文不隐含授予全部读取能力。 /navigation-menus返回启用且拥有目标许可的导航；管理目录/menus另要求 menus:read。本人身份/退出为固定界面，不受菜单开关影响。- 已有页面键固定为 users、roles、permissions、menus。菜单编辑只接受名称、同级顺序和开关，不接受任意 URL、页面键或 permission 参数。
HTTP 与错误¶
机器可读路径与结构只在 openapi.json 定义；本文不维护第二份接口表。状态码：未登录/失效 401，无权/CSRF/范围外赋权 403，非法输入 400，目标不存在 404，重复/过期版本/恢复约束冲突 409，失败暂停 429。无查看许可的请求先拒绝，不能由错误细节泄漏目标存在与否。
对敏感写入不自动重放；权限和身份变化后清理全部 Refine 资源缓存。自改角色/权限成功可能撤销本人会话，成功结果可以先显示，但后续受保护访问必须重新登录。