ulthon_admin/.agents/skills/ulthon-permission-cli/SKILL.md

name, description

name	description
ulthon-permission-cli	解释并指导 RBAC 权限体系与相关 CLI 命令（admin:role:* / admin:user:role:* / admin:permission:*）。用于查看节点、管理角色权限、给用户分配角色、排查权限问题。

权限与角色管理（RBAC CLI）

何时调用

• 需要查看系统当前有哪些权限节点。
• 需要创建/查看/删除角色，或查看角色详情。
• 需要为角色分配/撤回权限节点。
• 需要给指定用户分配/撤回角色。
• 需要排查“有菜单但无权限 / 有权限但仍被拦截 / 节点名称不一致”等权限问题。

概念速览

• 权限节点：基于控制器/方法注解生成的权限标识（用于授权与鉴权）。
• 角色：权限节点的集合（SystemAuth）。
• 用户：后台用户（SystemAdmin），通过 auth_ids（逗号分隔）绑定角色 ID 列表。
• 角色-节点：SystemAuthNode 记录 auth_id + node 的多对多关系。
• 鉴权入口：后台请求进入后会根据“当前节点”进行权限检查（未授权则拦截）。
• 输出说明：权限相关命令默认以文本输出为主；如命令涉及交互确认，可使用 --force-force 或 -ff 跳过确认。

常用命令

1) 查看权限节点

php think admin:permission:nodes

常用参数（如需）：

• --module=<模块>：按模块过滤
• --level=1|2：按级别过滤（1=控制器，2=方法）

2) 角色管理

php think admin:role:list
php think admin:role:info --role-id=12
php think admin:role:create --title="测试角色" --remark="测试用"
php think admin:role:delete --role-id=12

要点：

• 删除角色会检查该角色是否仍被用户分配；若仍有用户绑定，则删除会失败。

3) 角色权限管理

php think admin:role:permission:list --role-id=12
php think admin:role:permission:assign --role-id=12 --nodes="system.admin/index,system.admin/add"
php think admin:role:permission:revoke --role-id=12 --nodes="system.admin/add"

要点：

• --nodes 支持逗号分隔批量操作。
• 建议先用 admin:permission:nodes 确认节点名称完全一致后再分配到角色。

4) 用户角色管理

php think admin:user:role:list --user-id=1
php think admin:user:role:assign --user-id=1 --role-ids="12,13"
php think admin:user:role:revoke --user-id=1 --role-ids="13"

5) 透视查询用户当前权限

php think admin:permission:user --user-id=1

典型工作流

工作流 A：新增/调整注解后，核对节点并授权

1. 在控制器/方法上新增或调整权限注解（节点名称、标题、模块等）。
2. 执行 admin:permission:nodes，确认节点列表中已出现新节点且名称符合预期。
3. 确定要使用的角色（可通过 admin:role:list / admin:role:info 查看；没有合适角色就用 admin:role:create 新建）。
4. 执行 admin:role:permission:assign 将新节点分配给角色。
5. 执行 admin:user:role:assign 将角色分配给用户。
6. 执行 admin:permission:user 透视确认该用户已拥有节点。

工作流 B：排查“明明有权限但仍被拦截”

1. 执行 admin:permission:user --user-id=<id>，确认用户是否真的拥有当前节点。
2. 执行 admin:permission:nodes，确认“当前被拦截节点名”是否存在、是否有大小写/分隔符差异。
3. 如果用户通过角色获得权限，执行 admin:role:permission:list --role-id=<roleId> 核对角色是否包含该节点。
4. 检查后台配置中是否存在免鉴权规则（例如 no_login/no_auth 的控制器/节点白名单）。

变更说明（重要）

• 旧命令 admin:permission:assign / admin:permission:revoke 已移除。
• “按用户直接增删节点”的需求，应通过“角色”承接：
  • 只影响单个用户：创建专用角色 → 给该角色分配节点 → 将角色分配给该用户。
  • 影响一批用户：维护共享角色 → 给该角色增删节点 → 所有拥有该角色的用户一起生效。

常见坑位

• 节点名不一致：注解里写的节点名与实际鉴权使用的当前节点不一致，导致分配了权限但无法命中。
• 只改了菜单没改权限：菜单能看到不代表有权限访问，权限检查以节点为准。
• 缓存/环境差异：在不同环境中节点生成来源不一致时，先以 admin:permission:nodes 的输出为准核对。
• 修改共享角色影响面过大：撤回/新增角色节点会影响所有拥有该角色的用户。
• 删除角色失败：仍有用户绑定该角色，先用 admin:user:role:revoke 撤回后再删除。