/permission-model-change-guide

name: permission-model-change-guide
description: 修改 BK-CI IAM RBAC 权限模型时使用，例如新增资源类型、设计操作列表、配置 IAM 资源、补迁移数据和验证回调链路。当用户要变更权限模型而不是普通权限调用时优先使用。

权限模型变更指南

适用场景

• 新增一种 IAM 资源类型
• 为资源类型设计或调整操作列表
• 修改 IAM RBAC 配置、实例选择器或回调数据
• 补权限迁移、初始化脚本或线上变更流程
• 排查资源类型接入不完整的问题

不适用场景

• 只是调用现有权限校验接口
• 只是处理用户授权、加成员、移成员
• 只是修改 Auth 模块普通业务逻辑
• 只是做 OAuth2 或登录认证

快速指导

1. 这个 skill 关注的是“权限模型本身如何变更”，不是“现有权限怎么调用”。 2. 一次变更通常至少覆盖四层：资源定义、操作定义、数据初始化、校验验证。 3. 先按问题类型进入对应参考文档：

• 资源类型与操作设计：`reference/1-resource-action-design.md`
• IAM 配置、迁移与初始化：`reference/2-iam-config-migration.md`
• 回调、验证与常见坑：`reference/3-callback-validation.md`

4. `create` 一类动作往往是权限模型里最容易配错的特殊项，要先确认关联资源是否还是父级资源。 5. 任何模型变更都要同步考虑国际化、初始化脚本、历史数据兼容和线上落地方式。 6. 如果你改的是 Auth 模块内部 RBAC 服务实现，而不是资源模型本身，切到 `auth-module-architecture`。

高信号规则

• 权限模型变更本质上是契约变更，不只是加几个枚举或 JSON
• 资源类型、操作列表、实例选择器、回调链路必须一起看
• 线上接入时要优先考虑初始化与兼容，而不是只让本地跑通
• API 方式和脚本方式都要明确边界，避免重复写入或状态不一致

关键陷阱

• 只加资源枚举，不补 IAM 配置和初始化链路
• `create`、`list`、`manage` 等动作的关联资源设计错误
• 只改配置，不做国际化、回调和验证
• 把权限模型问题误判成普通 Auth 业务问题

延伸阅读

• 资源类型与操作设计：`reference/1-resource-action-design.md`
• IAM 配置、迁移与初始化：`reference/2-iam-config-migration.md`
• 回调、验证与常见坑：`reference/3-callback-validation.md`
• 如果你在改 Auth 内部实现：再看 `auth-module-architecture`