lijiaoqiao/docs/multi_role_permission_design_v1_2026-04-02.md

# 多角色权限设计方案（P1）

- 版本：v1.0
- 日期：2026-04-02
- 状态：设计稿（已修复）
- 依赖：
  - `docs/token_runtime_minimal_spec_v1.md`（TOK-001）
  - `docs/token_auth_middleware_design_v1_2026-03-29.md`（TOK-002）
  - `docs/llm_gateway_prd_v1_2026-03-25.md`
- 目标：实现 PRD P1 "多角色权限"需求

---

## 1. 背景与目标

### 1.1 业务背景

LLM Gateway 平台需要支持多类用户角色，满足不同的使用场景：

1. **平台管理员** - 负责组织级策略、预算、权限管理
2. **AI 应用开发者** - 负责接入模型与业务落地
3. **财务/运营负责人** - 负责成本追踪、对账与预算控制
4. **供应方** - 拥有多余LLM配额的个人或企业（平台用户）
5. **需求方** - 需要LLM调用能力的企业/开发者

### 1.2 设计目标

1. **角色扩展**：在现有 `owner/viewer/admin` 三角色基础上扩展，支持更多业务场景
2. **权限细分**：支持细粒度的 scope 权限控制
3. **层级清晰**：建立的角色继承/层级关系
4. **API兼容**：保持与现有 SUP-004~SUP-008 链路一致
5. **可扩展**：支持未来新增角色和权限

---

## 2. 现有权限模型分析

### 2.1 现有角色体系（TOK-001）

| 角色 | 等级 | 能力 | 约束 |
|------|------|------|------|
| admin | 3 | 风控与审计管理 | 仅平台内部可用 |
| owner | 2 | 管理供应侧账号、套餐、结算 | 不可读取上游凭证明文 |
| viewer | 1 | 只读查询 | 不可执行写操作 |

### 2.2 现有 JWT Token Claims 结构

```go
type TokenClaims struct {
    jwt.RegisteredClaims
    SubjectID string   `json:"subject_id"`  // 用户主体ID
    Role      string   `json:"role"`        // 角色: admin/owner/viewer
    Scope     []string `json:"scope"`        // 授权范围列表
    TenantID  int64    `json:"tenant_id"`   // 租户ID
}
```

### 2.3 现有中间件链路（TOK-002）

```
RequestIdMiddleware
    ↓
QueryKeyRejectMiddleware
    ↓
BearerExtractMiddleware
    ↓
TokenVerifyMiddleware
    ↓
TokenStatusCheckMiddleware
    ↓
ScopeRoleAuthzMiddleware     ← 权限校验
    ↓
AuditEmitMiddleware
```

---

## 3. 多角色权限设计方案

### 3.1 角色定义

#### 3.1.1 平台侧角色（Platform Roles）

| 角色 | 代码 | 层级 | 说明 | 继承关系 |
|------|------|------|------|----------|
| 超级管理员 | `super_admin` | 100 | 平台最高权限，仅平台运营方可用 | - |
| 组织管理员 | `org_admin` | 50 | 组织级管理，管理本组织所有资源 | 显式配置（拥有operator+finops+developer+viewer所有scope） |
| 运维人员 | `operator` | 30 | 系统运维与配置 | 显式配置（拥有viewer所有scope + platform:write等） |
| 开发者 | `developer` | 20 | AI应用开发者，接入模型与业务落地 | 继承 viewer |
| 财务人员 | `finops` | 20 | 成本追踪、对账与预算控制 | 继承 viewer |
| 查看者 | `viewer` | 10 | 只读查询 | - |

**说明**：
1. 继承关系仅用于权限聚合，代表"子角色拥有父角色所有scope + 自身额外scope"
2. `org_admin` 显式配置拥有 `operator` + `finops` + `developer` + `viewer` 的所有scope
3. `operator` 显式配置拥有 `viewer` 所有scope + `platform:write` 等权限
4. 层级数值仅用于权限优先级判断，不影响继承关系

#### 3.1.2 供应侧角色（Supply Roles）

| 角色 | 代码 | 层级 | 说明 | 继承关系 |
|------|------|------|------|----------|
| 供应方管理员 | `supply_admin` | 40 | 供应侧全面管理 | 显式配置（拥有supply_operator+supply_finops所有scope） |
| 供应方运维 | `supply_operator` | 30 | 套餐管理、额度配置 | 显式配置（拥有supply_viewer所有scope + supply:package:write等） |
| 供应方财务 | `supply_finops` | 20 | 收益结算、对账 | 继承 supply_viewer |
| 供应方查看者 | `supply_viewer` | 10 | 只读查询 | - |

#### 3.1.3 需求侧角色（Consumer Roles）

| 角色 | 代码 | 层级 | 说明 | 继承关系 |
|------|------|------|------|----------|
| 需求方管理员 | `consumer_admin` | 40 | 需求侧全面管理 | 显式配置（拥有consumer_operator所有scope） |
| 需求方运维 | `consumer_operator` | 30 | API Key管理、调用配置 | 显式配置（拥有consumer_viewer所有scope + consumer:apikey:*等） |
| 需求方查看者 | `consumer_viewer` | 10 | 只读查询 | - |

### 3.2 角色层级关系图

```
                    ┌─────────────┐
                    │ super_admin │  (层级100)
                    └──────┬──────┘
                           │ 权限聚合
                           ▼
                    ┌─────────────┐
                    │  org_admin  │  (层级50)
                    └──────┬──────┘
                           │ 显式配置（聚合operator+developer+finops+viewer scope）
              ┌────────────┼────────────┐
              ▼            ▼            ▼
       ┌──────────┐  ┌──────────┐  ┌──────────┐
       │ operator │  │developer │  │  finops  │  (层级20-30)
       └────┬─────┘  └────┬─────┘  └────┬─────┘
            │             │             │
            │ 显式配置     │ 继承        │ 继承
            │ (+viewer)   │ (+viewer)   │ (+viewer)
            ▼             ▼             ▼
       ┌──────────┐  ┌──────────┐  ┌──────────┐
       │  viewer  │  │  viewer  │  │  viewer  │  (层级10)
       └──────────┘  └──────────┘  └──────────┘

    ─────────────────────────────────────────

       ┌──────────┐     ┌──────────────┐
       │supply_ad │────│consumer_adm │
       │   min    │    │   in        │  (层级40)
       └────┬─────┘    └──────┬───────┘
            │ 显式配置         │ 显式配置
            │ (+operator      │ (+operator
            │  +finops)       │  +viewer)
            ▼                  ▼
       ┌──────────┐     ┌──────────────┐
       │supply_op │     │consumer_op  │
       │  erator  │     │  erator     │  (层级30)
       └────┬─────┘     └──────┬───────┘
            │ 显式配置          │ 显式配置
            │ (+viewer)        │ (+viewer)
            ▼                   ▼
       ┌──────────┐     ┌──────────────┐
       │supply_vi │     │consumer_vi  │
       │  ewer    │     │  ewer       │  (层级10)
       └──────────┘     └──────────────┘
```

**继承关系说明**：
- 继承 = 子角色拥有父角色所有 scope + 自身额外 scope
- 显式配置 = 直接授予特定 scope 列表（等效于显式继承但更清晰）
- supply_admin/consumer_admin = 拥有该类别下所有子角色 scope
- operator/developer/finops = 拥有 viewer 所有 scope + 各自额外 scope

### 3.3 Scope 权限定义

#### 3.3.1 Platform Scope

| Scope | 说明 | 授予角色 |
|-------|------|----------|
| `platform:read` | 读取平台配置 | viewer+ |
| `platform:write` | 修改平台配置 | operator+ |
| `platform:admin` | 平台级管理 | org_admin+ |
| `platform:audit:read` | 读取审计日志 | operator+ |
| `platform:audit:export` | 导出审计日志 | org_admin+ |

#### 3.3.2 Tenant Scope

| Scope | 说明 | 授予角色 | 备注 |
|-------|------|----------|------|
| `tenant:read` | 读取租户信息 | viewer+ | |
| `tenant:write` | 修改租户配置 | operator+ | |
| `tenant:member:manage` | 管理租户成员 | org_admin | |
| `tenant:billing:write` | 修改账单设置 | org_admin | |

#### 3.3.3 Supply Scope

| Scope | 说明 | 授予角色 | 备注 |
|-------|------|----------|------|
| `supply:account:read` | 读取供应账号 | supply_viewer+ | |
| `supply:account:write` | 管理供应账号 | supply_operator+ | |
| `supply:package:read` | 读取套餐信息 | supply_viewer+ | |
| `supply:package:write` | 管理套餐 | supply_operator+ | |
| `supply:package:publish` | 发布套餐 | supply_operator+ | |
| `supply:package:offline` | 下架套餐 | supply_operator+ | |
| `supply:settlement:withdraw` | 提现 | supply_admin | |
| `supply:credential:manage` | 管理凭证 | supply_admin | |

#### 3.3.4 Consumer Scope

| Scope | 说明 | 授予角色 | 备注 |
|-------|------|----------|------|
| `consumer:account:read` | 读取账户信息 | consumer_viewer+ | |
| `consumer:account:write` | 管理账户 | consumer_operator+ | |
| `consumer:apikey:create` | 创建API Key | consumer_operator+ | |
| `consumer:apikey:read` | 读取API Key | consumer_viewer+ | |
| `consumer:apikey:revoke` | 吊销API Key | consumer_operator+ | |
| `consumer:usage:read` | 读取使用量 | consumer_viewer+ | |

#### 3.3.5 Billing Scope（统一）

| Scope | 说明 | 授予角色 | user_type限定 |
|-------|------|----------|---------------|
| `billing:read` | 读取账单 | finops+, supply_finops+, consumer_viewer+ | 通过user_type区分数据范围 |
| `billing:write` | 修改账单设置 | org_admin | |

**说明**：
- 原有 `tenant:billing:read`、`supply:settlement:read`、`consumer:billing:read` 统一为 `billing:read`
- 通过 TokenClaims.user_type 字段限定数据范围：platform用户看租户账单，supply用户看供应结算，consumer用户看需求账单
- 原 scope 名称保留作为 deprecated alias

#### 3.3.6 Router Scope（网关转发）

| Scope | 说明 | 授予角色 |
|-------|------|----------|
| `router:invoke` | 调用模型 | 所有认证用户 |
| `router:model:list` | 列出可用模型 | viewer+ |
| `router:model:config` | 配置路由策略 | operator+ |

---

## 4. API 路由权限映射

### 4.1 Platform API

| API路径 | 方法 | 所需Scope | 所需角色 |
|---------|------|-----------|----------|
| `/api/v1/platform/info` | GET | `platform:read` | viewer+ |
| `/api/v1/platform/config` | GET | `platform:read` | viewer+ |
| `/api/v1/platform/config` | PUT | `platform:write` | operator+ |
| `/api/v1/platform/tenants` | GET | `tenant:read` | viewer+ |
| `/api/v1/platform/tenants` | POST | `tenant:write` | operator+ |
| `/api/v1/platform/audit/events` | GET | `platform:audit:read` | operator+ |
| `/api/v1/platform/audit/events/export` | POST | `platform:audit:export` | org_admin+ |

### 4.2 Supply API（与 SUP-004~SUP-008 保持一致）

| API路径 | 方法 | 所需Scope | 所需角色 |
|---------|------|-----------|----------|
| `/api/v1/supply/accounts` | GET | `supply:account:read` | supply_viewer+ |
| `/api/v1/supply/accounts` | POST | `supply:account:write` | supply_operator+ |
| `/api/v1/supply/accounts/:id` | PUT | `supply:account:write` | supply_operator+ |
| `/api/v1/supply/accounts/:id/verify` | POST | `supply:account:write` | supply_operator+ |
| `/api/v1/supply/packages` | GET | `supply:package:read` | supply_viewer+ |
| `/api/v1/supply/packages` | POST | `supply:package:write` | supply_operator+ |
| `/api/v1/supply/packages/:id/publish` | POST | `supply:package:publish` | supply_operator+ |
| `/api/v1/supply/packages/:id/offline` | POST | `supply:package:offline` | supply_operator+ |
| `/api/v1/supply/settlements` | GET | `billing:read` | supply_finops+ |
| `/api/v1/supply/settlements/withdraw` | POST | `supply:settlement:withdraw` | supply_admin |
| `/api/v1/supply/billing` | GET | `billing:read` | supply_finops+ |

**Deprecated Alias 说明**：
- `/api/v1/supplier/*` 路径仅作为历史兼容别名保留
- 新接口禁止使用 `/supplier` 前缀
- deprecated alias 响应体应包含 `deprecation_notice` 字段提示迁移
- S2 阶段评估 alias 下线时间

### 4.3 Consumer API

| API路径 | 方法 | 所需Scope | 所需角色 |
|---------|------|-----------|----------|
| `/api/v1/consumer/account` | GET | `consumer:account:read` | consumer_viewer+ |
| `/api/v1/consumer/account` | PUT | `consumer:account:write` | consumer_operator+ |
| `/api/v1/consumer/apikeys` | GET | `consumer:apikey:read` | consumer_viewer+ |
| `/api/v1/consumer/apikeys` | POST | `consumer:apikey:create` | consumer_operator+ |
| `/api/v1/consumer/apikeys/:id/revoke` | POST | `consumer:apikey:revoke` | consumer_operator+ |
| `/api/v1/consumer/usage` | GET | `consumer:usage:read` | consumer_viewer+ |
| `/api/v1/consumer/billing` | GET | `billing:read` | consumer_viewer+ |

### 4.4 Router API（网关调用）

| API路径 | 方法 | 所需Scope | 所需角色 |
|---------|------|-----------|----------|
| `/v1/chat/completions` | POST | `router:invoke` | 所有认证用户 |
| `/v1/completions` | POST | `router:invoke` | 所有认证用户 |
| `/v1/embeddings` | POST | `router:invoke` | 所有认证用户 |
| `/v1/models` | GET | `router:model:list` | viewer+ |
| `/api/v1/router/models` | GET | `router:model:list` | viewer+ |
| `/api/v1/router/policies` | GET | `router:model:config` | operator+ |
| `/api/v1/router/policies` | PUT | `router:model:config` | operator+ |

---

## 5. 数据模型扩展

### 5.1 Role 定义表（iam_roles）

```sql
CREATE TABLE iam_roles (
    id BIGSERIAL PRIMARY KEY,
    role_code VARCHAR(50) NOT NULL UNIQUE,  -- super_admin, org_admin, operator, developer, finops, viewer
    role_name VARCHAR(100) NOT NULL,
    role_type VARCHAR(20) NOT NULL,          -- platform, supply, consumer
    parent_role_id BIGINT REFERENCES iam_roles(id),  -- 继承关系
    level INT NOT NULL DEFAULT 0,            -- 权限层级
    description TEXT,
    is_active BOOLEAN DEFAULT TRUE,

    -- 审计字段（符合 database_domain_model_and_governance v1 规范）
    request_id VARCHAR(64),                  -- 请求追踪ID
    created_ip INET,                         -- 创建者IP
    updated_ip INET,                          -- 更新者IP
    version INT DEFAULT 1,                   -- 乐观锁版本号

    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_iam_roles_code ON iam_roles(role_code);
CREATE INDEX idx_iam_roles_type ON iam_roles(role_type);
CREATE INDEX idx_iam_roles_request_id ON iam_roles(request_id);
```

### 5.2 Scope 定义表（iam_scopes）

```sql
CREATE TABLE iam_scopes (
    id BIGSERIAL PRIMARY KEY,
    scope_code VARCHAR(100) NOT NULL UNIQUE,  -- platform:read, supply:account:write
    scope_name VARCHAR(100) NOT NULL,
    scope_type VARCHAR(50) NOT NULL,          -- platform, supply, consumer, router
    description TEXT,
    is_active BOOLEAN DEFAULT TRUE,

    -- 审计字段（符合 database_domain_model_and_governance v1 规范）
    request_id VARCHAR(64),                  -- 请求追踪ID
    created_ip INET,                         -- 创建者IP
    updated_ip INET,                          -- 更新者IP
    version INT DEFAULT 1,                   -- 乐观锁版本号

    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_iam_scopes_code ON iam_scopes(scope_code);
CREATE INDEX idx_iam_scopes_request_id ON iam_scopes(request_id);
```

### 5.3 角色-Scope 关联表（iam_role_scopes）

```sql
CREATE TABLE iam_role_scopes (
    id BIGSERIAL PRIMARY KEY,
    role_id BIGINT NOT NULL REFERENCES iam_roles(id),
    scope_id BIGINT NOT NULL REFERENCES iam_scopes(id),

    -- 审计字段（符合 database_domain_model_and_governance v1 规范）
    request_id VARCHAR(64),                  -- 请求追踪ID
    created_ip INET,                         -- 创建者IP
    version INT DEFAULT 1,                   -- 乐观锁版本号

    created_at TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE(role_id, scope_id)
);

CREATE INDEX idx_iam_role_scopes_role ON iam_role_scopes(role_id);
CREATE INDEX idx_iam_role_scopes_scope ON iam_role_scopes(scope_id);
CREATE INDEX idx_iam_role_scopes_request_id ON iam_role_scopes(request_id);
```

### 5.4 用户-角色关联表（iam_user_roles）

```sql
CREATE TABLE iam_user_roles (
    id BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL,
    role_id BIGINT NOT NULL REFERENCES iam_roles(id),
    tenant_id BIGINT,                         -- 租户范围（NULL表示全局）
    granted_by BIGINT,
    granted_at TIMESTAMPTZ DEFAULT NOW(),
    expires_at TIMESTAMPTZ,                   -- 角色过期时间

    -- 审计字段（符合 database_domain_model_and_governance v1 规范）
    request_id VARCHAR(64),                  -- 请求追踪ID
    created_ip INET,                         -- 创建者IP
    updated_ip INET,                          -- 更新者IP
    version INT DEFAULT 1,                   -- 乐观锁版本号

    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_iam_user_roles_user ON iam_user_roles(user_id);
CREATE INDEX idx_iam_user_roles_tenant ON iam_user_roles(tenant_id);
CREATE INDEX idx_iam_user_roles_request_id ON iam_user_roles(request_id);
CREATE UNIQUE INDEX idx_iam_user_roles_unique ON iam_user_roles(user_id, role_id, tenant_id);
```

### 5.5 扩展 Token Claims

```go
type TokenClaims struct {
    jwt.RegisteredClaims
    SubjectID   string   `json:"subject_id"`    // 用户主体ID
    Role        string   `json:"role"`          // 主角色
    Scope       []string `json:"scope"`          // 授权范围列表
    TenantID    int64    `json:"tenant_id"`     // 租户ID
    UserType    string   `json:"user_type"`     // 用户类型: platform/supply/consumer
    Permissions []string `json:"permissions"`    // 细粒度权限列表
}
```

---

## 6. 中间件设计

### 6.1 扩展 ScopeRoleAuthzMiddleware

```go
// 扩展后的权限校验逻辑
type AuthzConfig struct {
    // 路由-角色映射
    RouteRolePolicies map[string]RolePolicy
    // 路由-Scope映射
    RouteScopePolicies map[string][]string
    // 角色层级
    RoleHierarchy map[string]int
}

type RolePolicy struct {
    RequiredLevel int
    RequiredRole string
    RequiredScope []string
}

// 权限校验逻辑
func (m *AuthMiddleware) ScopeRoleAuthzMiddleware(requiredScope string) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            claims, ok := r.Context().Value(tokenClaimsKey).(*TokenClaims)
            if !ok {
                writeAuthError(w, http.StatusUnauthorized, "AUTH_CONTEXT_MISSING", "")
                return
            }

            // 1. Scope 校验
            if requiredScope != "" && !containsScope(claims.Scope, requiredScope) {
                m.emitAuditAndReject(r, w, "AUTH_SCOPE_DENIED", requiredScope, claims)
                return
            }

            // 2. 角色层级校验（如果配置了角色要求）
            if policy, exists := getRoutePolicy(r.URL.Path); exists {
                if !checkRolePolicy(claims, policy) {
                    m.emitAuditAndReject(r, w, "AUTH_ROLE_DENIED", "", claims)
                    return
                }
            }

            next.ServeHTTP(w, r)
        })
    }
}
```

### 6.2 新增角色层级中间件

```go
// RoleHierarchyMiddleware 角色层级校验中间件
// 用于需要特定角色层级的操作
func RoleHierarchyMiddleware(minLevel int) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            claims := GetTokenClaims(r.Context())
            if claims == nil {
                writeAuthError(w, http.StatusUnauthorized, "AUTH_CONTEXT_MISSING", "")
                return
            }

            if getRoleLevel(claims.Role) < minLevel {
                writeAuthError(w, http.StatusForbidden, "AUTH_ROLE_LEVEL_DENIED",
                    fmt.Sprintf("required role level %d", minLevel))
                return
            }

            next.ServeHTTP(w, r)
        })
    }
}
```

### 6.3 新增跨类型校验中间件

```go
// UserTypeMiddleware 用户类型校验中间件
// 用于区分 platform/supply/consumer 用户
func UserTypeMiddleware(allowedTypes ...string) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            claims := GetTokenClaims(r.Context())
            if claims == nil {
                writeAuthError(w, http.StatusUnauthorized, "AUTH_CONTEXT_MISSING", "")
                return
            }

            if !containsString(allowedTypes, claims.UserType) {
                writeAuthError(w, http.StatusForbidden, "AUTH_USER_TYPE_DENIED",
                    fmt.Sprintf("allowed user types: %v", allowedTypes))
                return
            }

            next.ServeHTTP(w, r)
        })
    }
}
```

---

## 7. 错误码扩展

| 错误码 | HTTP状态 | 说明 |
|--------|----------|------|
| `AUTH_SCOPE_DENIED` | 403 | Scope权限不足 |
| `AUTH_ROLE_DENIED` | 403 | 角色权限不足 |
| `AUTH_ROLE_LEVEL_DENIED` | 403 | 角色层级不足 |
| `AUTH_USER_TYPE_DENIED` | 403 | 用户类型不允许 |
| `AUTH_TENANT_MISMATCH` | 403 | 租户上下文不匹配 |
| `AUTH_RESOURCE_OWNER_DENIED` | 403 | 资源所有权校验失败 |

---

## 8. 审计事件扩展

| 事件名 | 说明 | 触发场景 |
|--------|------|----------|
| `role.assign` | 角色分配 | 给用户分配角色 |
| `role.revoke` | 角色吊销 | 吊销用户角色 |
| `role.scope.denied` | Scope权限拒绝 | Scope校验失败 |
| `role.hierarchy.denied` | 角色层级拒绝 | 角色层级校验失败 |
| `usertype.denied` | 用户类型拒绝 | 用户类型校验失败 |

---

## 9. API 契约更新

### 9.1 新增角色管理 API

#### GET /api/v1/iam/roles

获取角色列表

**响应：**
```json
{
  "roles": [
    {
      "role_code": "org_admin",
      "role_name": "组织管理员",
      "role_type": "platform",
      "level": 50,
      "scopes": ["platform:read", "tenant:read", "tenant:write"]
    }
  ]
}
```

#### POST /api/v1/iam/users/:userId/roles

分配角色给用户

**请求：**
```json
{
  "role_code": "developer",
  "tenant_id": 123,
  "expires_at": "2026-12-31T23:59:59Z"
}
```

#### DELETE /api/v1/iam/users/:userId/roles/:roleCode

吊销用户角色

### 9.2 新增 Scope 查询 API

#### GET /api/v1/iam/scopes

获取所有可用Scope

---

## 10. 向后兼容方案

### 10.1 新旧层级映射表（与TOK-001对齐）

| TOK-001旧层级 | 旧角色代码 | 新角色代码 | 新层级 | 权限变化说明 |
|---------------|------------|------------|--------|--------------|
| 3 | admin | `super_admin` | 100 | 完全对应，平台最高权限 |
| 2 | owner | `supply_admin` | 40 | 权限范围明确为供应侧管理，不含平台运营权限 |
| 1 | viewer | `viewer` | 10 | 完全对应 |

**说明**：
- TOK-001 新角色体系（super_admin/org_admin/operator）专属于平台侧管理
- 原 owner 角色对应 supply_admin（供应侧管理员），职责边界清晰
- 层级数值用于优先级判断，新旧体系独立运作

### 10.2 现有角色映射

| 旧角色 | 新角色 | 说明 |
|--------|--------|------|
| `admin` | `super_admin` | 完全对应，层级100 |
| `owner` | `supply_admin` | 权限范围重新定义为供应侧，不含平台运营权限 |
| `viewer` | `viewer` | 完全对应，层级10 |

**权限边界变化说明**：
- 原 owner 可管理供应侧账号、套餐、结算（对应 supply_admin）
- 原 owner 不可执行平台级操作（由 org_admin/super_admin 专属）
- supply_admin(40) < org_admin(50) 是合理设计，因为 org_admin 管理范围更广

### 10.3 Token 兼容处理

```go
// RoleMapping 旧角色到新角色的映射
var RoleMapping = map[string]string{
    "admin": "super_admin",
    "owner": "supply_admin",
    // viewer 保持不变
}

// 在Token验证时自动转换
func normalizeRole(role string) string {
    if newRole, exists := RoleMapping[role]; exists {
        return newRole
    }
    return role
}
```

---

## 11. 实施计划

### 11.1 Phase 1: 数据模型扩展

1. 创建 `iam_roles`, `iam_scopes`, `iam_role_scopes`, `iam_user_roles` 表
2. 初始化预定义角色和Scope数据
3. 提供数据迁移脚本

### 11.2 Phase 2: 中间件扩展

1. 扩展 `ScopeRoleAuthzMiddleware` 支持新角色层级
2. 新增 `RoleHierarchyMiddleware`
3. 新增 `UserTypeMiddleware`
4. 更新 Token Claims 结构

### 11.3 Phase 3: API 实现

1. 实现角色管理 API
2. 实现 Scope 查询 API
3. 更新现有 API 的权限校验

### 11.4 Phase 4: 向后兼容

1. 实现角色映射逻辑
2. 提供迁移指导文档

---

## 12. 验收标准

1. [ ] 角色层级清晰：super_admin > org_admin > operator/developer/finops > viewer
2. [ ] Scope权限校验正确：精确匹配路由与所需Scope
3. [ ] 继承关系正确：子角色自动继承父角色Scope
4. [ ] 向后兼容：现有 owner/viewer/admin 角色正常工作
5. [ ] 审计完整：角色变更和权限拒绝事件全量记录
6. [ ] API契约更新：新增角色管理API符合RESTful规范

---

## 13. 关联文档

- `docs/token_runtime_minimal_spec_v1.md`（TOK-001）
- `docs/token_auth_middleware_design_v1_2026-03-29.md`（TOK-002）
- `docs/llm_gateway_prd_v1_2026-03-25.md`
- `docs/database_domain_model_and_governance_v1_2026-03-27.md`
- `docs/api_naming_strategy_supply_vs_supplier_v1_2026-03-27.md`

---

**文档状态**：设计稿（待评审）
**下一步**：提交评审，根据反馈修订后进入实施阶段