# Permission Module

> 本模組提供 Gateway 多租戶 **B2B 自定義 RBAC**：平台級 Permission Catalog + 租戶級 Role / RolePermission / UserRole / RoleMapping，搭配 Casbin enforcer 進行 HTTP path/method 授權。設計參考 `docs/identity-member-design.md` §6 / §7.3 / §13。

---

## 0. TL;DR

```mermaid
flowchart LR
    subgraph Platform["平台層 (Platform-wide)"]
      Catalog[Permission Catalog]
    end
    subgraph Tenant["租戶層 (per-tenant)"]
      Role[Role]
      RP[RolePermission]
      UR[UserRole]
      RM[RoleMapping]
    end
    Catalog -- 勾選 --> RP --> Role
    Role -- 指派 --> UR
    Role -- 對應 --> RM

    Tenant -- LoadPolicy --> Casbin[(Casbin Enforcer<br/>Redis adapter)]
    Casbin -- Check --> Middleware[CasbinRBAC Middleware]
```

- Permission **平台 seed 全局**（`cmd/permission-seed`），租戶不可新增；只能勾選。
- Role / RolePermission / UserRole **租戶獨立**；同名 role 可在不同租戶共存。
- Role.Key 一旦建立 **不可改**；外部 IdP（ZITADEL / LDAP / SCIM）以 Key 作對應。
- 多 pod 同步：**Redis Pub/Sub 即時通知 + 5min cron 兜底**。

---

## 1. 核心概念

| 概念 | 簡述 | 關鍵欄位 |
|------|------|----------|
| **Permission** | 平台級權限節點（樹狀，dot notation） | `name` 唯一、`http_methods` + `http_path` 命中 Casbin policy |
| **Role** | 租戶內的角色 | `tenant_id + key` unique；`is_system=true` 不可刪 |
| **RolePermission** | Role 勾選了哪些 Permission | 自動補齊 parent permission ID |
| **UserRole** | 使用者被指派的角色（多角色） | `source` 區分 manual / zitadel / ldap / scim |
| **RoleMapping** | 外部 group/role → 內部 Role.Key | SyncFromX 用來翻譯 IdP claims |
| **Casbin Policy** | 物化後的授權規則（Redis Set） | `(tenant, role, path, methods, name)` |

### 1.1 Permission Tree 範例

```
member.info.management            ← 分類（無 HTTP）
├── member.basic.info             ← 二級分類
│   ├── member.info.select        GET   /api/v1/members/me
│   └── member.info.update        PATCH /api/v1/members/me
├── member.admin.list             GET   /api/v1/members
└── member.admin.read             GET   /api/v1/members/:uid

permission.role.management        ← 分類
├── permission.role.read          GET    /api/v1/permissions/roles
├── permission.role.write         POST/PUT/DELETE /api/v1/permissions/roles*
└── permission.assign.write       POST/DELETE /api/v1/permissions/users/*/roles*
```

> 分類節點（無 `http_path`）**不會**寫入 Casbin policy；它們只是 UI 樹狀渲染與 parent closure 用。

---

## 2. 目錄結構

```
internal/model/permission/
├── README.md                       # 本文件
├── config/
│   └── config.go                   # CasbinConfig / CacheConfig / ReloadConfig
├── domain/
│   ├── const.go                    # BSON 欄位 / Casbin / Role.Key 規則
│   ├── errors.go                   # 模組共用 sentinel errors
│   ├── redis.go                    # Redis key helpers (casbin / user_roles / role_perms)
│   ├── entity/
│   │   ├── permission.go           # Permission catalog node
│   │   ├── role.go
│   │   ├── role_permission.go
│   │   ├── user_role.go
│   │   └── role_mapping.go
│   ├── enum/
│   │   ├── status.go               # open / close + Permissions map
│   │   ├── permission_type.go      # backend_user / frontend_user
│   │   └── role_source.go          # manual / zitadel / ldap / scim
│   ├── repository/                 # 介面（+ Casbin adapter port）
│   │   ├── permission.go
│   │   ├── role.go
│   │   ├── role_permission.go
│   │   ├── user_role.go
│   │   ├── role_mapping.go
│   │   └── casbin_adapter.go
│   └── usecase/                    # 介面 + DTO
│       ├── permission.go
│       ├── role.go
│       ├── role_permission.go
│       ├── user_role.go
│       ├── role_mapping.go
│       ├── rbac.go
│       └── authorization_query.go
├── repository/                     # Mongo + Redis 實作
│   ├── index.go                    # EnsureMongoIndexes + bsonOpSet
│   ├── permission_mongo.go
│   ├── role_mongo.go
│   ├── role_permission_mongo.go
│   ├── user_role_mongo.go
│   ├── role_mapping_mongo.go
│   └── casbin_redis.go             # tenant-scoped policy Redis Set
├── usecase/                        # atomic primitives (7)
│   ├── module.go                   # NewModuleFromParam
│   ├── errors.go                   # wrapRepoErr → errs.For(code.Permission)
│   ├── permission_tree.go          # buildTree / filterOpenNodes / parent closure
│   ├── permission_usecase.go
│   ├── role_usecase.go
│   ├── role_permission_usecase.go
│   ├── user_role_usecase.go
│   ├── role_mapping_usecase.go
│   ├── authorization_query_usecase.go
│   └── rbac_usecase.go             # Casbin enforcer + LoadPolicy + Pub/Sub reload
└── seed/
    ├── catalog.go                  # embed + Apply + DefaultSystemRoles
    └── catalog.json                # 平台 seed 資料
```

---

## 3. 模組依賴

```mermaid
flowchart TD
    Logic[logic/permission] --> SVC[svc.ServiceContext]
    SVC --> AuthQ[AuthorizationQueryUseCase]
    SVC --> Perm[PermissionUseCase]
    SVC --> Role[RoleUseCase]
    SVC --> RolePerm[RolePermissionUseCase]
    SVC --> UserRole[UserRoleUseCase]
    SVC --> Mapping[RoleMappingUseCase]
    SVC --> RBAC[RBACUseCase]

    AuthQ --> RoleR[(roles)]
    AuthQ --> PermR[(permissions)]
    AuthQ --> RPR[(role_permissions)]
    AuthQ --> URR[(user_roles)]

    Perm --> PermR
    Role --> RoleR
    Role --> URR
    RolePerm --> RPR
    RolePerm --> RoleR
    RolePerm --> PermR
    UserRole --> URR
    UserRole --> RoleR
    Mapping --> RMR[(role_mappings)]
    Mapping --> RoleR

    RBAC --> RoleR
    RBAC --> PermR
    RBAC --> RPR
    RBAC --> URR
    RBAC --> Adapter[Casbin Redis Adapter]
    Adapter --> Redis[(Redis)]
    RBAC --> Pub[Redis Pub/Sub]
```

---

## 4. UseCase 介面（7 個）

| UseCase | 主要方法 | 注入 |
|---------|----------|------|
| `PermissionUseCase` | `GetCatalogTree` / `List` / `UpsertCatalog` / `UpdateStatus` | PermissionRepository |
| `RoleUseCase` | `Create` / `Get` / `List` / `Update` / `Delete` | Role + RolePermission + UserRole |
| `RolePermissionUseCase` | `List` / `Replace` | Role + Permission + RolePermission + Reloader |
| `UserRoleUseCase` | `Assign` / `Revoke` / `List` / `ReplaceForSource` | Role + UserRole + Reloader |
| `RoleMappingUseCase` | `Upsert` / `Delete` / `GetByExternal` / `List` | Role + RoleMapping |
| `AuthorizationQueryUseCase` | `Me` | Role + Permission + RolePermission + UserRole |
| `RBACUseCase` | `Check` / `LoadPolicy` / `LoadAllPolicies` / `BroadcastReload` / `Start/StopReloadSubscriber` | All repos + Redis |

---

## 5. 資料儲存

### 5.1 MongoDB

| Collection | 索引 | 用途 |
|------------|------|------|
| `permissions` | `name`(uniq) / `parent` / `status` / `type` | 平台 Permission Catalog（樹狀） |
| `roles` | `(tenant_id, key)`(uniq) / `(tenant_id, is_system)` | 租戶角色 |
| `role_permissions` | `(tenant_id, role_id, permission_id)`(uniq) / `(tenant_id, permission_id)` | Role↔Permission 多對多 |
| `user_roles` | `(tenant_id, uid, role_id)`(uniq) / `(tenant_id, role_id)` / `(tenant_id, uid, source)` | User↔Role 多對多 |
| `role_mappings` | `(tenant_id, external_source, external_key)`(uniq) / `(tenant_id, internal_role_id)` | 外部 group → 內部 Role |

啟動時呼叫 `permrepo.EnsureMongoIndexes(ctx, &c.Mongo)`（已掛在 `cmd/mongo-index`）。

### 5.2 Redis Key

| Key | 內容 | TTL | 由誰寫 |
|-----|------|-----|--------|
| `permission:casbin:rules:{tenant_id}` | Set of JSON-encoded `[]string` rules | 永久 | `RBACUseCase.LoadPolicy` / `BroadcastReload` |
| `perm:user_roles:{tenant_id}:{uid}` | List of role keys（讀取快取，預留） | `Cache.UserRolesTTLSeconds` | 預留 |
| `perm:role_perms:{tenant_id}:{role_id}` | List of permission names（預留） | `Cache.RolePermsTTLSeconds` | 預留 |
| `permission:tree:open` | 序列化的全局 open tree（預留） | `Cache.CatalogTTLSeconds` | 預留 |
| (channel) `casbin:reload` | Pub/Sub payload `{tenant_id, ts}` | — | `RBACUseCase.BroadcastReload` |

> Redis Set + JSON 編碼是為了讓 SaveAll 用 pipelined `DEL + SADD` 一致性更新；Pub/Sub 走獨立 go-redis client（go-zero 沒有 Subscribe），詳見 `internal/library/redis/pubsub.go`。

---

## 6. 核心流程時序圖

### 6.1 NewModuleFromParam — 模組組裝

```mermaid
sequenceDiagram
    participant Boot as svc.NewServiceContext
    participant Mod as permission.NewModuleFromParam
    participant Cfg as config.Defaults()
    participant Repo as Mongo Repos (5)
    participant Casbin as RBACUseCase
    participant Redis as PolicyAdapter

    Boot->>Mod: FactoryParam{MongoConf, Redis, Config}
    Mod->>Cfg: cfg = Config.Defaults()
    Mod->>Repo: NewPermission/Role/.../RoleMapping Repository
    Note over Mod: 若已注入 repo（測試）跳過
    alt cfg.Casbin.Enabled && Redis 有
        Mod->>Casbin: NewRBACUseCase(repos+Redis)
        Casbin-->>Mod: rbacUC
        Mod->>Redis: RedisAdapterFactory = NewCasbinRedisAdapter
        Mod->>Mod: reloader = rbacUC.BroadcastReload
    else 無 Redis 或 Disabled
        Mod->>Mod: rbacUC = nil（Check 永遠 deny）
    end
    Mod->>Mod: New {Permission, Role, RolePermission, UserRole, RoleMapping, AuthorizationQuery}
    Mod-->>Boot: *Module（7 usecases + 5 repos）
```

### 6.2 Permission Catalog Seed

```mermaid
sequenceDiagram
    participant CLI as cmd/permission-seed
    participant Cfg as config.Mongo
    participant Idx as permrepo.EnsureMongoIndexes
    participant Seed as seed.Apply
    participant Cat as Permissions
    participant Roles as Roles + RolePermissions

    CLI->>Cfg: load -f etc/gateway.dev.yaml
    CLI->>Idx: 建立 5 collections 索引
    CLI->>Seed: Apply(perms, roles, rolePerms, opts)
    alt SkipCatalog == false
        Seed->>Cat: 第一輪 UpsertByName（不含 parent）
        Seed->>Cat: GetAll → 建 name→ID index
        Seed->>Cat: 第二輪 UpsertByName（補 parent ID）
    end
    loop opts.TenantIDs
        Seed->>Roles: GetByKey or Insert is_system role
        Seed->>Roles: SetForRole(roleID, [permIDs])  ← 全量取代
    end
    Seed-->>CLI: Report{ catalog, roles, role_perms }
    CLI-->>CLI: stdout summary
```

> 預設 5 個 system role：`tenant_owner` / `tenant_admin` / `member_manager` / `member` / `viewer`，定義於 `seed/catalog.go::DefaultSystemRoles`。

### 6.3 Role 建立 / 更新 / 刪除

```mermaid
sequenceDiagram
    participant API as POST/PATCH/DELETE /permissions/roles
    participant Logic as logic.permission.*
    participant UC as RoleUseCase
    participant Repo as RoleRepository
    participant URR as UserRoleRepository

    API->>Logic: req + actor (tenant_id, uid)
    Logic->>UC: Create / Update / Delete
    alt Create
        UC->>UC: validateRoleKey（^[a-z][a-z0-9._-]+$、不可 system./platform_）
        UC->>Repo: Insert(role) ← unique (tenant_id, key)
    else Update
        UC->>Repo: GetByID
        UC->>UC: 阻擋 is_system 改 status
        UC->>Repo: FindOneAndUpdate
    else Delete
        UC->>Repo: GetByID
        UC->>UC: 阻擋 is_system
        UC->>URR: ListByRole（仍有指派 → 拒絕）
        UC->>Repo: DeleteByRole(role_perms)
        UC->>Repo: Delete(role)
    end
    UC-->>Logic: role
    Logic-->>API: types.RoleData
```

### 6.4 RolePermission 全量取代（PUT /roles/:id/permissions）

```mermaid
sequenceDiagram
    participant API as PUT /permissions/roles/:id/permissions
    participant Logic as logic.replaceRolePermissions
    participant UC as RolePermissionUseCase
    participant Roles as RoleRepository
    participant Perms as PermissionRepository
    participant RP as RolePermissionRepository
    participant RBAC as RBACUseCase

    API->>Logic: req{ID, PermissionIDs}
    Logic->>UC: Replace(tenantID, roleID, ids)
    UC->>Roles: GetByID（驗證 tenant 一致）
    UC->>Perms: GetAll（拿到 catalog 全表）
    UC->>UC: 檢查 ids ⊆ catalog
    UC->>UC: getFullParentPermissionIDs(ids, all)
    UC->>RP: SetForRole(tenantID, roleID, closure)
    Note over RP: DeleteMany + InsertMany 原子化
    UC->>RBAC: BroadcastReload(tenantID)
    RBAC-->>UC: ok（fire-and-forget）
    UC-->>Logic: nil
    Logic-->>API: 200 OK
```

### 6.5 UserRole 指派 / 撤銷

```mermaid
sequenceDiagram
    participant API as POST /permissions/users/:uid/roles
    participant UC as UserRoleUseCase
    participant Roles as RoleRepository
    participant URR as UserRoleRepository
    participant RBAC as RBACUseCase

    API->>UC: Assign{tenant, uid, role_id, source=manual}
    UC->>Roles: GetByID (tenant scope check)
    UC->>URR: Insert(unique tenant+uid+role)
    UC->>RBAC: BroadcastReload(tenant)
    UC-->>API: UserRole
```

### 6.6 SyncFromX 流程（外部 IdP 來源同步）

```mermaid
sequenceDiagram
    participant Sync as auth/provisioning
    participant UC as UserRoleUseCase
    participant Map as RoleMappingUseCase
    participant Roles as RoleRepository
    participant URR as UserRoleRepository
    participant RBAC as RBACUseCase

    Sync->>Map: GetByExternal(tenant, source=zitadel, externalKey)
    Map-->>Sync: RoleMapping(internal_role_key)
    Note over Sync: 收齊 IdP 端所有 roles → keys
    Sync->>UC: ReplaceForSource(tenant, uid, source=zitadel, [roleKeys])
    UC->>UC: 阻擋 source==manual（防誤洗）
    loop key in roleKeys
        UC->>Roles: GetByKey (skip 不存在的)
    end
    UC->>URR: ReplaceForSource(tenant, uid, source, [roleIDs])
    Note over URR: DeleteMany source=zitadel + BulkInsert<br/>※ source=manual 紀錄不動
    UC->>RBAC: BroadcastReload(tenant)
```

### 6.7 LoadPolicy（Casbin 規則載入）

```mermaid
sequenceDiagram
    participant Trigger as Replace / Reload / Boot
    participant RBAC as RBACUseCase
    participant Roles as RoleRepository
    participant RP as RolePermissionRepository
    participant Perms as PermissionRepository
    participant Enf as casbin.SyncedEnforcer
    participant Adp as Redis Adapter

    Trigger->>RBAC: LoadPolicy(tenantID)
    RBAC->>Roles: ListByTenant
    RBAC->>RP: ListByRoles(roleIDs)
    RBAC->>Perms: GetByIDs(unique perm ids)
    RBAC->>RBAC: 過濾 IsLeaf() && Status=open
    RBAC->>RBAC: rules = [tenant, role.key, http_path, http_methods, perm.name]
    RBAC->>Enf: ClearPolicy + AddPolicies
    RBAC->>Adp: SaveAll(tenant, rules)  ← Redis pipelined DEL+SADD
    RBAC-->>Trigger: nil
```

### 6.8 Check（授權檢查）

```mermaid
sequenceDiagram
    participant MW as middleware.CasbinRBAC
    participant Logic as ActorFromContext
    participant RBAC as RBACUseCase
    participant URR as UserRoleRepository
    participant Roles as RoleRepository
    participant Enf as casbin.SyncedEnforcer

    MW->>Logic: actor (tenant, uid)
    MW->>RBAC: Check{tenant, uid, path, method}
    RBAC->>RBAC: enforcerFor(tenant)（lazy clone model + AddPolicies）
    RBAC->>URR: ListByUser(tenant, uid)
    RBAC->>Roles: ListByTenantAndIDs（過濾 status=open）
    loop role in roles（any-allow）
        RBAC->>Enf: EnforceEx(tenant, role.key, path, method)
        alt allow
            RBAC-->>MW: CheckResult{Allow=true, MatchedRoleKey, MatchedPolicyRow}
        end
    end
    MW->>MW: result.Allow ? next : 403 (errs.AuthForbidden)
```

### 6.9 Pub/Sub 多 Pod Reload

```mermaid
sequenceDiagram
    participant PodA as Pod A (Replace)
    participant Redis
    participant PodB as Pod B (Subscribe)
    participant PodC as Pod C (Subscribe)

    PodA->>PodA: RolePermission.Replace + LoadPolicy（本地）
    PodA->>Redis: PUBLISH casbin:reload {tenant, ts}
    Redis-->>PodB: 推 message
    Redis-->>PodC: 推 message
    PodB->>PodB: handleReload → LoadPolicy(tenant)
    PodC->>PodC: handleReload → LoadPolicy(tenant)
    Note over PodB,PodC: 2-3ms 內三個 pod 同步
```

> 兜底：每個 pod 可定時跑 `LoadAllPolicies`（5min cron，未在本模組內排程；建議 svc 層或 cron-worker 觸發）。掃 Redis `permission:casbin:rules:*` key 推導 tenant 列表。

### 6.10 GET /permissions/me（前端選單渲染）

```mermaid
sequenceDiagram
    participant Front as Frontend
    participant API as GET /permissions/me
    participant UC as AuthorizationQueryUseCase
    participant URR as UserRoleRepository
    participant Roles as RoleRepository
    participant RP as RolePermissionRepository
    participant Perms as PermissionRepository

    Front->>API: Bearer JWT
    API->>UC: Me(tenant, uid, includeTree)
    UC->>URR: ListByUser
    UC->>Roles: ListByTenantAndIDs（過濾 status=open）
    UC->>RP: ListByRoles(roleIDs)
    UC->>Perms: GetByIDs(unique perm ids)
    UC->>UC: permission map = name→status
    alt includeTree
        UC->>UC: buildPermissionTree + filterOpenNodes
    end
    UC-->>API: { uid, tenant_id, roles, permissions, tree? }
    API-->>Front: 200 OK
```

---

## 7. Casbin 模型（`etc/rbac.conf`）

```ini
[request_definition]
r = tenant, role, path, method

[policy_definition]
p = tenant, role, path, methods, name

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = r.tenant == p.tenant && r.role == p.role && keyMatch2(r.path, p.path) && regexMatch(r.method, p.methods)
```

- `keyMatch2`：支援 `/api/v1/members/*` 萬用 path
- `regexMatch`：`GET|POST|PATCH` 多 method 同一 policy
- 平台 Admin bypass 不寫進 matcher，由 middleware 預檢（保留 audit）

---

## 8. ServiceContext 注入

```go
sc.PermissionCatalog        // Permission catalog reader (tree / list / status)
sc.PermissionRole           // Role CRUD（含 system role 防呆）
sc.PermissionRolePermission // Replace（含 parent closure）
sc.PermissionUserRole       // Assign / Revoke / ReplaceForSource
sc.PermissionRoleMapping    // 外部 group → Role.Key
sc.PermissionAuthQuery      // GET /me 用
sc.PermissionRBAC           // Casbin enforcer（Mongo+Redis 全到位才有）
sc.PermissionRoleRepo       // 給 SCIM / SyncFromX 等下游使用
```

未啟用 Casbin 時 `PermissionRBAC == nil`，`Check()` 永遠 deny；middleware 會拒絕所有請求（除非 `AllowMissingActor=true`）。

---

## 9. HTTP API（前綴 `/api/v1/permissions`）

| Method | Path | Handler | 說明 |
|--------|------|---------|------|
| GET    | `/catalog` | `getPermissionCatalog` | 全局 Catalog（tree=true 取樹狀） |
| GET    | `/me` | `getMePermissions` | 當前 user 的 role / permission map |
| GET    | `/roles` | `listRoles` | 租戶角色清單 |
| POST   | `/roles` | `createRole` | 建立角色（key 不可改） |
| PATCH  | `/roles/:id` | `updateRole` | 更新 display_name / status（system role 限制） |
| DELETE | `/roles/:id` | `deleteRole` | 刪角色（system / 仍有指派 → 拒絕） |
| GET    | `/roles/:id/permissions` | `getRolePermissions` | 角色目前的 permission 集合 |
| PUT    | `/roles/:id/permissions` | `replaceRolePermissions` | 全量取代 + 補 parent + Pub/Sub reload |
| GET    | `/users/:uid/roles` | `listUserRoles` | 使用者目前指派的 role |
| POST   | `/users/:uid/roles` | `assignUserRole` | 指派角色（source 預設 manual） |
| DELETE | `/users/:uid/roles/:role_id` | `revokeUserRole` | 撤銷單一角色 |
| GET    | `/role-mappings` | `listRoleMappings` | 外部映射列表（分頁） |
| PUT    | `/role-mappings` | `upsertRoleMapping` | Upsert 外部 group → Role.Key |
| DELETE | `/role-mappings` | `deleteRoleMapping` | 刪除外部映射 |
| POST   | `/policy/reload` | `reloadPolicy` | 強制重載（單租戶或 `*`） |

完整錯誤碼註解參見 `generate/api/permission.api`，由 `make gen-doc` 出 OpenAPI。

---

## 10. 設定範例（`etc/gateway.dev.example.yaml`）

```yaml
Permission:
  Casbin:
    Enabled: false                 # 預設關閉，啟用後 RBAC enforcement 生效
    ModelPath: etc/rbac.conf
    PolicyAdapter: auto             # auto / redis / mongo
  Cache:
    UserRolesTTLSeconds: 300
    RolePermsTTLSeconds: 300
    CatalogTTLSeconds: 600
  Reload:
    Channel: casbin:reload
    DebounceMilliseconds: 200
    HeartbeatSeconds: 60
```

---

## 11. CLI / 操作指南

```bash
# 1) 建索引
make mongo-index

# 2) 撰寫 / 修改 catalog
$EDITOR internal/model/permission/seed/catalog.json

# 3) 全平台 seed catalog（不為任何 tenant 建 role）
go run ./cmd/permission-seed -f etc/gateway.dev.yaml

# 4) 同時為 dev tenant seed 5 個 system role
go run ./cmd/permission-seed -f etc/gateway.dev.yaml -tenant TEN-100001

# 5) 多租戶
go run ./cmd/permission-seed -f etc/gateway.dev.yaml -tenant TEN-100001,TEN-100002

# 6) 只 reseed tenant role（catalog 已存在）
go run ./cmd/permission-seed -f etc/gateway.dev.yaml -tenant TEN-100001 -skip-catalog

# 7) 強制全部 pod 重載 policy（HTTP）
curl -X POST http://localhost:8888/api/v1/permissions/policy/reload \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: TEN-100001" -H "X-UID: TEN-100001-OWNER" \
  -d '{"tenant_id": "*"}'
```

---

## 12. 中介層（middleware/casbin_rbac.go）

**現況：** middleware 已寫好，但 **尚未掛入 routes.go**（避免影響現有 dev 模式）。要啟用：

```go
import perm "gateway/internal/middleware"

server.AddRoutes(routes,
    rest.WithMiddlewares(
        []rest.Middleware{
            middleware.CloudEPJWT(serverCtx.AuthToken),  // 已存在
            middleware.CasbinRBAC(serverCtx.PermissionRBAC, middleware.CasbinRBACOptions{
                AllowMissingActor: false,
                SkipPaths: map[string]struct{}{
                    "/api/v1/health": {},
                },
            }),
        }...,
    ),
    rest.WithPrefix("/api/v1/members"),
)
```

要先：
1. 跑 seed CLI 把 catalog + system role 建好
2. 為平台 admin tenant 建 `platform_super_admin` role + bypass allowlist
3. 開啟 `Permission.Casbin.Enabled = true`
4. 設好 `Permission.Reload.Channel`（多 pod 才需要）

---

## 13. 測試

```bash
# 全模組 unit test
go test ./internal/model/permission/...

# 含整合（需要 Mongo + Redis 在 docker compose 起著）
make deps-up
go test -tags=integration ./internal/model/permission/...
```

---

## 14. 設計權衡 / 注意事項

| 議題 | 決策 | 原因 |
|------|------|------|
| Permission `name` 改名 | **禁止** | 被 RolePermission、UI i18n、Casbin policy.name 引用；廢棄走 `status=close` 然後新建 |
| Role `key` 改名 | **禁止** | 外部 IdP mapping 直接綁 key；改名會切斷映射 |
| `is_system` role 刪除 | 拒絕 | 平台預設角色保留 |
| `is_system` role 改 status | 拒絕 | 維持平台預期行為 |
| `manual` source ReplaceForSource | 拒絕 | 防 SyncFromX 誤洗手動指派 |
| Permission 有 `*` 萬用 path | 不建議裸 `*`；至少帶資源根 | 防 keyMatch2 貪婪命中跨資源 |
| Casbin 多 enforcer | 一 tenant 一個 enforcer，lazy 建 | 比一個 enforcer + filtered policy 簡單，且記憶體可預測 |
| 多 pod 同步 | Pub/Sub 即時 + 5min cron 兜底 | 即時通知 + reboot 不漏 |
| Pub/Sub client | 獨立 go-redis，不走 go-zero pool | go-zero 沒包 Subscribe，且 Subscribe 會佔住 conn |
| Permission Catalog 改動 | seed CLI 即可（idempotent） | UI 端不直接改 catalog；seed JSON 是 SoT |

---

## 15. 後續工作

| 項目 | 預估 |
|------|------|
| Platform admin allowlist + audit log | 後續 |
| RoleMapping 用 SyncFromX 落地（Zitadel / LDAP / SCIM）| 隨對應 SyncFromX usecase 推進 |
| Policy reload cron worker（5 min） | 取自 svc 啟動 ticker |
| Role permission 編輯 UI（不在 Gateway 內，由前端取資） | 前端 |
| 細粒度欄位過濾（`.plain_code` 變體） | logic 層額外查 sub-permission |