template-monorepo/docs/identity-member-design.md

# Identity / Member / Permission 模組設計草稿

> **狀態**：Draft（待 Review）  
> **適用專案**：Portal API Gateway（PGW）  
> **參考實作**：[app-cloudep-permission-server](https://code.30cm.net/digimon/app-cloudep-permission-server)（Casbin RBAC、Permission Tree、Role/RolePermission）  
> **最後更新**：2026-05-19  
> **前提**：全新 Gateway module，不考慮舊版 member-server 遷移。

本文件描述 Gateway 內 **auth**、**member**、**permission** 三個業務模組的目標架構，整合 **ZITADEL**（身份）、**LDAP**（企業目錄）、**SCIM 2.0**（企業 provisioning），支援 **多租戶** 與 **百萬級會員**（含單租戶 50 萬）。

模組分層與程式碼撰寫規範見 [model.md](./model.md)。

---

## 目錄

1. [設計目標與原則](#1-設計目標與原則)
2. [模組全景](#2-模組全景)
3. [外部系統分工](#3-外部系統分工)
4. [auth 模組](#4-auth-模組)
5. [member 模組](#5-member-模組)
6. [permission 模組（B2B 自定義）](#6-permission-模組b2b-自定義)
7. [API 規劃](#7-api-規劃)
8. [Middleware 鏈](#8-middleware-鏈)
9. [核心流程](#9-核心流程)
10. [LDAP 與 SCIM](#10-ldap-與-scim)
11. [可讀 UID 設計](#11-可讀-uid-設計)
12. [資料模型與索引](#12-資料模型與索引)
13. [Redis Key 命名](#13-redis-key-命名)
14. [規模與性能（100 萬+ / 單租戶 50 萬）](#14-規模與性能100-萬--單租戶-50-萬)
15. [目錄結構](#15-目錄結構)
16. [設定檔](#16-設定檔)
17. [實施順序](#17-實施順序)
18. [待決策事項](#18-待決策事項)

---

## 1. 設計目標與原則

### 1.1 目標

| 目標 | 說明 |
|------|------|
| 統一身份 | ZITADEL 作為 IdP（含 LDAP IdP、Social Login） |
| 業務會員 | Gateway `member` 模組管理 tenant-scoped profile |
| 細粒度授權 | Gateway `permission` 模組（**Casbin RBAC + Permission Tree**）；**每個 B2B 租戶可自定義 Role 並勾選 Permission** |
| Token | go-zero JWT 驗證 + Redis 黑名單（只黑名單 JWT） |
| 企業整合 | SCIM 2.0 + LDAP Directory Sync（AD + OpenLDAP） |
| 規模 | 全平台 100 萬+ 會員；單租戶可達 50 萬 |
| UID | 人類可讀、可口述，非 UUID / 亂碼 |

### 1.2 核心原則

1. **職責分離**
   - `auth`：你是誰（Authentication）
   - `member`：你的業務資料是什麼（Profile）
   - `permission`：你能做什麼（Authorization）

2. **LDAP 不做登入 bind**
   - 登入驗證由 ZITADEL LDAP IdP 處理
   - Gateway 的 LDAP client 僅供 Directory Sync（read-only）

3. **Token Exchange**
   - 對外 API 只接受 Gateway 簽發的 CloudEP JWT
   - ZITADEL OIDC token 僅在 `/auth/token/exchange` 使用一次

4. **租戶隔離**
   - 所有持久化資料以 `tenant_id` 為邊界
   - JWT `tenant_id` 與請求資源必須一致

5. **B2B 權限自定義**（參考 [app-cloudep-permission-server](https://code.30cm.net/digimon/app-cloudep-permission-server)）
   - 平台 seed 全局 Permission Tree（含 `http_path` / `http_method`）
   - 租戶建立自訂 Role，從 Tree **勾選** Permission（`RolePermission` + 自動補 parent）
   - API 授權由 **Casbin** 比對 `(role.Name, path, method)`
   - B2C 租戶仅用 seed 模板

---

## 2. 模組全景

```
┌─────────────────────────────────────────────────────────────────┐
│                     Portal API Gateway (go-zero)                   │
├─────────────────────────────────────────────────────────────────┤
│  generate/api/                                                   │
│    auth.api · member.api · permission.api · tenant.api · scim.api│
├─────────────────────────────────────────────────────────────────┤
│  internal/middleware/                                            │
│    jwt_revoke · casbin_rbac · scim_auth · tenant_context           │
├─────────────────────────────────────────────────────────────────┤
│  internal/model/                                                 │
│    auth/        → Token 簽發、換票、登出、黑名單、auth_gen         │
│    member/      → Profile、Identity、Tenant、UID、Directory Sync │
│    permission/  → Casbin RBAC、Permission Tree、Role（B2B 自定義）│
├─────────────────────────────────────────────────────────────────┤
│  internal/library/                                               │
│    zitadel/ · ldap/ · uid/ · casbin/（RBAC enforcer 封裝）        │
├─────────────────────────────────────────────────────────────────┤
│  internal/worker/                                                │
│    directory_sync/                                               │
└─────────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
     MongoDB               Redis              ZITADEL
   (profile/role)      (cache/blacklist)    (identity/LDAP IdP)
```

### 2.1 模組依賴方向

```
handler → logic → model/{auth|member|permission}/usecase（interface）
                      ↓
                repository → MongoDB / Redis

logic 不 import entity / repository（見 model.md）

auth      → member（EnsureMember）
auth      → permission（SyncRolesFromClaims）
member    → auth（停權時 RevokeAllForUser）
permission → member（可選：驗證 uid 存在）
```

---

## 3. 外部系統分工

| 能力 | ZITADEL | Gateway auth | Gateway member | Gateway permission |
|------|---------|--------------|----------------|-------------------|
| 註冊 / 登入 | ✅ | 換票 | EnsureMember | SyncRoles |
| 密碼 / MFA / 忘記密碼 | ✅ | — | — | — |
| Google / LINE / Apple | ✅ IdP | — | — | — |
| LDAP 登入 | ✅ LDAP IdP | — | — | Group→Role 映射 |
| Access / Refresh Token（對外） | — | ✅ CloudEP JWT | — | — |
| JWT 黑名單 | — | ✅ Redis | — | — |
| 業務 UID | — | — | ✅ | — |
| Profile | — | — | ✅ | — |
| 會員列表 / 狀態 | — | — | ✅ | 需授權 |
| API 細粒度權限 | 粗粒度 Role | — | — | **Casbin RBAC**（path + method） |
| SCIM Users/Groups | 可同步 | — | ✅ 業務寫入 | ✅ Group→Role |
| LDAP Directory Sync | — | — | ✅ Worker | ✅ Group→Role |

### 3.1 多租戶對應

```
1 CloudEP Tenant  =  1 ZITADEL Organization  =  1 資料隔離邊界
```

| 欄位 | 來源 | 用途 |
|------|------|------|
| `tenant_id` | ZITADEL `org_id` | 分片鍵、授權邊界 |
| `identity_id` | ZITADEL `sub` | 身份映射 |
| `uid` | Member 模組產生 | 業務會員 ID（如 `ACME-ODWXGYBK`） |

### 3.2 租戶類型

| 類型 | 登入 | LDAP | 權限 |
|------|------|------|------|
| **B2C** | Email / Social | 無 | 系統預設 Role（不可或不常自定義） |
| **B2B** | ZITADEL → LDAP IdP | 有 | **完全自定義 Role + Permission** |
| **Hybrid** | Social + LDAP | 有 | B2B 自定義 + 外部客戶用預設 Role |

---

## 4. auth 模組

路徑：`internal/model/auth/`

### 4.1 職責

- 驗證 ZITADEL OIDC token（id_token / authorization_code + PKCE）
- 編排 `member.EnsureMember` 與 `permission.SyncRolesFromClaims`
- 簽發 CloudEP JWT（access + refresh）
- 登出：jti 黑名單
- 批量失效：`auth_gen`（停權 / 改密碼 / 權限強制刷新）

### 4.2 UseCase 介面

```go
type TokenUseCase interface {
    Exchange(ctx context.Context, req *ExchangeRequest) (*TokenPair, error)
    Refresh(ctx context.Context, req *RefreshRequest) (*TokenPair, error)
    Logout(ctx context.Context, req *LogoutRequest) error
    RevokeAllForUser(ctx context.Context, tenantID, uid string) error
}
```

### 4.3 CloudEP JWT Claims

```go
type Claims struct {
    jwt.RegisteredClaims          // 含 jti, exp, iat
    TenantID string `json:"tenant_id"`
    UID      string `json:"uid"`
    Roles    string `json:"roles"`     // 逗號分隔 Role.Name，Casbin enforce 用
    Typ      string `json:"typ"`       // access | refresh
    AuthGen  int64  `json:"auth_gen"`  // 批量失效代號
}
```

### 4.4 JWT 設定（go-zero）

```yaml
Auth:
  AccessSecret: ${JWT_ACCESS_SECRET}
  AccessExpire: 900          # 15 分鐘

RefreshAuth:
  AccessSecret: ${JWT_REFRESH_SECRET}
  AccessExpire: 604800       # 7 天
```

`.api` 受保護路由：

```api
@server(jwt: Auth, middleware: JwtRevokeMiddleware)
```

### 4.5 黑名單策略（只黑名單 JWT）

#### 單 Token 撤銷（登出）

```
Key:   auth:jwt:bl:{jti}
Value: 1
TTL:   token 剩餘有效時間（exp - now）
```

登出時同時黑名單 access + refresh 的 jti。

#### 批量失效（停權 / 改密碼 / SCIM deactivate / 角色強刷）

```
Key:   auth:gen:{tenant_id}:{uid}
Value: 整數，預設 1；事件發生時 INCR
```

Middleware 檢查：`token.auth_gen >= redis.auth_gen`，否則 401。

> JWT 內不放全部 permission（避免 token 過大）；批量失效用 `auth_gen`，單次登出用 jti 黑名單。

### 4.6 Middleware 檢查順序

```
1. go-zero JWT 驗簽 + exp
2. typ == "access"（受保護 API）
3. NOT EXISTS auth:jwt:bl:{jti}
4. claims.auth_gen >= redis auth:gen:{tenant}:{uid}
5. 注入 context：tenant_id, uid, roles
```

---

## 5. member 模組

路徑：`internal/model/member/`

### 5.1 職責

- 會員 Profile CRUD（tenant-scoped）
- Identity 映射（`zitadel_sub` ↔ `uid`）
- Tenant  metadata 與 LDAP 同步設定
- UID 產生（可讀格式）
- SCIM 業務寫入（User + externalId = uid）
- Directory Sync Worker（AD + OpenLDAP）
- 會員狀態（active / suspended）→ 通知 auth 撤銷 token

### 5.2 UseCase 介面

```go
type ProvisioningUseCase interface {
    EnsureMember(ctx context.Context, req *EnsureMemberRequest) (*MemberDTO, error)
}

type ProfileUseCase interface {
    GetByUID(ctx context.Context, req *GetMemberRequest) (*MemberDTO, error)
    Update(ctx context.Context, req *UpdateMemberRequest) (*MemberDTO, error)
    List(ctx context.Context, req *ListMembersRequest) (*ListMembersResponse, error)
}

type AdminUseCase interface {
    UpdateStatus(ctx context.Context, req *UpdateStatusRequest) error
}

type TenantUseCase interface {
    Create(ctx context.Context, req *CreateTenantRequest) (*TenantDTO, error)
    ResolveBySlug(ctx context.Context, slug string) (*TenantDTO, error)
    ConfigureLDAP(ctx context.Context, req *ConfigureLDAPRequest) error
}

type ScimUseCase interface {
    CreateUser(ctx context.Context, req *ScimCreateUserRequest) (*ScimUserDTO, error)
    GetUser(ctx context.Context, req *ScimGetUserRequest) (*ScimUserDTO, error)
    PatchUser(ctx context.Context, req *ScimPatchUserRequest) (*ScimUserDTO, error)
    DeleteUser(ctx context.Context, req *ScimDeleteUserRequest) error
    // Groups（供 SCIM Group → Role 映射）
    PatchGroup(ctx context.Context, req *ScimPatchGroupRequest) error
}

type DirectorySyncUseCase interface {
    SyncTenant(ctx context.Context, tenantID string) (*SyncResult, error)
}
```

### 5.3 會員狀態

| 狀態 | 語意 | 副作用 |
|------|------|--------|
| `unverified` | 尚未完成業務驗證 | — |
| `active` | 正常使用 | — |
| `suspended` | 停權 | `auth.RevokeAllForUser` |

---

## 6. permission 模組（B2B 自定義，參考 permission-server）

路徑：`internal/model/permission/`

> 本節吸收 [app-cloudep-permission-server](https://code.30cm.net/digimon/app-cloudep-permission-server) 已驗證的設計：**Casbin + Redis RBAC**、**Permission Tree（父子繼承）**、**HTTP Path/Method 綁定**。  
> **與舊 permission-server 的差異**：Token 簽發/驗證/黑名單移至 Gateway `auth` 模組；`ClientID` 改為 `tenant_id`；支援多租戶 B2B 各自定義 Role。

### 6.1 設計目標

| 能力 | 說明 |
|------|------|
| **Permission Tree** | 全局權限樹（平台 seed），父子節點繼承；父節點關閉則子節點不可用 |
| **Casbin RBAC** | 以 `(role, http_path, http_method)` 做 API 授權；path 支援 `keyMatch2` 萬用字元 |
| **B2B 自定義 Role** | 每個租戶建立自訂 Role，從全局 Catalog **勾選** Permission（不可自創 Permission 字串） |
| **UserRole** | 租戶 + uid + role；支援多角色（JWT 帶 role names，Casbin 逐一檢查） |
| **RolePermission** | 勾選子權限時自動補齊父權限 ID（沿用 permission-server 的 `getFullParentPermissionIDs`） |
| **Policy 同步** | MongoDB → Casbin Policy → Redis；定時 `LoadPolicy` + 變更時觸發 reload |
| **外部映射** | ZITADEL Role / LDAP Group / SCIM Group → 租戶內部 Role |
| **細粒度擴展** | 同一 API 可掛 `.plain_code` 子權限（如明碼查詢），沿用舊設計 |

### 6.2 與 app-cloudep-permission-server 對照

| permission-server | Gateway permission 模組 | 備註 |
|-------------------|---------------------------|------|
| `TokenService` | **`auth` 模組** | JWT 不再放 permission-server |
| `PermissionService`（空） | 完整 HTTP API | 直接在 Gateway 暴露 |
| `entity.Permission` | 沿用 + `tenant_id` 不適用（全局 Catalog） | Permission 為平台級 |
| `entity.Role.ClientID` | `Role.TenantID` | 租戶隔離 |
| `entity.Role.UID` | `Role.CreatorUID` | 建立者，可選 |
| `entity.Role.Name` | `Role.Name` | **Casbin policy 的 role 欄位** |
| `Casbin Enforcer` | `RBACUseCase` + Redis Adapter | 沿用 |
| `PermissionTree` | `usecase/permission_tree.go` | 沿用 |
| `AdminRoleUID` / `GodDog` | `PlatformSuperAdminUID` | 平台超級管理員 bypass |
| `permission.Type` | `enum.PermissionType` | `BackendUser` / `FrontendUser` |

### 6.3 核心概念

```
Permission（全局樹）  平台定義，含 name / http_path / http_method / parent / status / type
Role（租戶自定義）    租戶建立的命名角色，如 sales_supervisor、tenant_admin
RolePermission       Role ↔ Permission ID 多對多；勾選時自動補父節點
UserRole             uid ↔ Role；一 user 可多 role
RoleMapping          外部 Group/Role → 內部 Role.Name
Casbin Policy        p, {role.Name}, {http_path}, {http_method}, {permission.Name}
```

### 6.4 Permission Entity（全局 Catalog）

沿用 permission-server 的 `entity.Permission` 結構，MongoDB collection：`permission`。

```go
type Permission struct {
    ID         primitive.ObjectID
    Parent     string             // 父權限 ID（ObjectID hex）；空 = 掛 root
    Name       string             // 唯一語意名，dot notation，如 member.info.select
    HTTPMethod string             // GET / POST / PATCH / DELETE / PUT；分類節點可為空
    HTTPPath   string             // 如 /api/v1/members/*；分類節點可為空
    Status     enum.Status        // open | close
    Type       enum.PermissionType // backend_user | frontend_user（後台 / 前台菜單）
    CreateAt   int64
    UpdateAt   int64
}
```

#### 命名規則（dot notation，與 permission-server 一致）

```
{domain}.{module}.{action}
{domain}.{module}.{action}.{variant}   # 如 .plain_code
```

#### Permission Tree 範例（seed 草案）

```
member.info.management          # 一級：會員資訊管理（分類，無 HTTP）
├── member.basic.info           # 二級：基礎資訊
│   ├── member.info.select      # GET  /api/v1/members/me
│   ├── member.info.update      # PATCH /api/v1/members/me
│   └── member.info.select.plain_code  # GET /api/v1/members（明碼欄位）
├── member.admin.list           # GET  /api/v1/members
├── member.admin.read           # GET  /api/v1/members/:uid
├── member.admin.update         # PATCH /api/v1/members/:uid
└── member.admin.status         # PATCH /api/v1/members/:uid/status

permission.role.management      # 一級：角色權限管理
├── permission.role.read        # GET  /api/v1/permissions/roles
├── permission.role.write       # POST/PUT/DELETE roles
├── permission.assign.write     # POST/DELETE user roles
└── permission.catalog.read     # GET  /api/v1/permissions/catalog

tenant.management
├── tenant.read
├── tenant.ldap.write
└── tenant.sync.trigger

scim.management
├── scim.users.write
└── scim.groups.write

system.management               # 平台級
└── system.tenant.create
```

> **分類節點**（無 `http_path`）供 UI 樹狀勾選；**葉節點**才寫入 Casbin Policy。  
> 新增 Permission 走平台 seed migration；租戶**不可**自行新增 Permission 名稱。

#### Permission Tree 行為（沿用 permission-server）

1. **`filterOpenNodes`**：父節點 `status=close` → 整棵子樹不可用
2. **`getFullParentPermissionIDs`**：勾選子權限 → 自動加入所有父節點 ID
3. **`getFullParentPermission`**：查 Role 權限 → 回傳含父節點的完整 permission name → status map（供前端 UI）

### 6.5 Role Entity（B2B 租戶自定義）

```go
type Role struct {
    ID         primitive.ObjectID
    TenantID   string             // 租戶 ID（= 舊 ClientID）
    Name       string             // 角色名稱，租戶內唯一；Casbin enforce 用此值
    CreatorUID string             // 建立者 uid（= 舊 Role.UID，可選）
    Status     enum.Status        // open | close
    IsSystem   bool               // 系統 seed 的預設角色，B2B 可改 Permission 但不可刪除 Owner
    CreateAt   int64
    UpdateAt   int64
}
// Index: { tenant_id, name } unique
```

#### B2B 自定義規則

1. 租戶可 **CRUD** 自訂 Role（`is_system=false`）
2. 系統 seed 的預設 Role（`is_system=true`）可修改 Permission 集合，**tenant_owner 不可刪**
3. Role 綁定的 Permission 必須是全局 Catalog 中 `status=open` 的節點
4. 租戶**不可**勾選 `system.*` 權限（除非平台另行開啟）
5. 至少保留一個 Role 含 `permission.role.write`，避免租戶自鎖

#### 預設 Role 模板（建立 B2B tenant 時 seed）

| Name | 說明 | 預設勾選（Permission Name） |
|------|------|----------------------------|
| `tenant_owner` | 租戶擁有者 | 除 `system.*` 外全部 open 節點 |
| `tenant_admin` | 租戶管理員 | member.*, permission.*, tenant.*, scim.* |
| `member_manager` | 會員管理 | member.admin.list, member.admin.read, member.admin.status |
| `member` | 一般會員 | member.info.select, member.info.update |
| `viewer` | 唯讀 | member.info.select |

B2B 管理員範例：

```
建立 Role：sales_supervisor
勾選：member.admin.list, member.admin.read
指派：POST /permissions/users/{uid}/roles { "role_name": "sales_supervisor" }
→ RolePermission.Create → getFullParentPermissionIDs 自動補 parent
→ LoadPolicy 刷新 Casbin
```

### 6.6 UserRole / RolePermission

```go
type UserRole struct {
    TenantID string
    UID      string
    RoleID   string   // Role._id hex
    Source   enum.RoleSource  // manual | zitadel | ldap | scim
    CreateAt int64
    UpdateAt int64
}
// Index: { tenant_id, uid, role_id } unique
// Index: { tenant_id, uid }

type RolePermission struct {
    RoleID       string
    PermissionID string
    CreateAt     int64
    UpdateAt     int64
}
// Index: { role_id, permission_id } unique
```

> 舊 permission-server 的 UserRole 為一 user 一 role（Update 覆蓋）；新設計**支援多角色**，Middleware 對每個 role name 做 Casbin enforce，任一 allow 即通過。

### 6.7 Casbin RBAC（核心授權引擎）

#### 模型檔 `etc/rbac.conf`（沿用 permission-server）

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

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

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

[role_definition]
g = _, _

[matchers]
m = g(r.role, p.role) && keyMatch2(r.path, p.path) && regexMatch(r.method, p.methods) \
    || r.role == "${PlatformSuperAdminUID}"
```

- **`keyMatch2`**：支援 `/api/v1/members/*` 萬用 path
- **`regexMatch`**：支援 `GET|POST` 多 method 寫在同一 policy
- **SuperAdmin bypass**：平台維運 uid 全放行（對應舊 `GodDog`）

#### Policy 載入（`RBACUseCase.LoadPolicy`）

```
1. permissionRepo.GetAll → GeneratePermissionTree → filterOpenNodes
2. roleRepo.All(tenant_id) → 每個 role 取 rolePermissionRepo.Get
3. 對每個 (role, permission) 若 http_path + http_method 非空：
     enforcer.AddPolicy(role.Name, permission.HTTPPath, permission.HTTPMethod, permission.Name)
4. adapter.SavePolicy → Redis List（casbin rules）
5. enforcer.LoadPolicy()
```

#### 授權檢查（`RBACUseCase.Check`）

```go
// 輸入：roleName, requestPath, requestMethod
ok, policy, err := enforcer.EnforceEx(roleName, path, method)

// 回傳 CheckRolePermissionStatus：
//   Allow: bool
//   PermissionName: string   // 命中的 permission.Name
//   PlainCode: bool           // 是否有 .plain_code 子權限（GET 時額外查）
```

#### Policy 同步策略

| 觸發 | 動作 |
|------|------|
| RolePermission 變更 | 該 tenant `LoadPolicy` |
| Permission status 變更（平台） | 全局 `LoadPolicy` |
| 定時 cron（如 5min） | `SyncPolicy` 兜底 |
| Gateway 啟動 | 初始 `LoadPolicy` |

Redis 儲存 Casbin rules：`permission:casbin:rules`（List of JSON `rbac.Rule`）

### 6.8 UseCase 介面

```go
// --- Casbin 授權（核心）---
type RBACUseCase interface {
    Check(ctx context.Context, req *CheckRequest) (*CheckResult, error)
    LoadPolicy(ctx context.Context, tenantID string) error
    LoadAllPolicies(ctx context.Context) error
    SyncPolicy(ctx context.Context, interval time.Duration)
}

type CheckRequest struct {
    TenantID string
    UID      string
    Path     string   // 實際請求 path
    Method   string   // 實際 HTTP method
}

type CheckResult struct {
    Allow          bool
    PermissionName string
    PlainCode      bool
    MatchedRole    string
}

// --- Permission Catalog（平台級）---
type PermissionUseCase interface {
    All(ctx context.Context, status *enum.Status) ([]PermissionDTO, error)
    FilterAll(ctx context.Context) ([]PermissionDTO, error)  // 樹狀過濾 open 節點
    Insert(ctx context.Context, req *CreatePermissionRequest) error  // 平台 Admin
    Update(ctx context.Context, id string, req *UpdatePermissionRequest) error
}

// --- Role（租戶級，B2B 自定義）---
type RoleUseCase interface {
    List(ctx context.Context, req *ListRolesRequest) ([]RoleDTO, int64, error)
    All(ctx context.Context, tenantID string) ([]RoleDTO, error)
    GetByID(ctx context.Context, tenantID, id string) (*RoleDTO, error)
    Create(ctx context.Context, req *CreateRoleRequest) error
    Update(ctx context.Context, id string, req *UpdateRoleRequest) error
    Delete(ctx context.Context, tenantID, id string) error
}

// --- RolePermission ---
type RolePermissionUseCase interface {
    Get(ctx context.Context, roleID string) (enum.Permissions, error)  // name → open/close
    Create(ctx context.Context, roleID string, perms enum.Permissions) error
    Delete(ctx context.Context, roleID string, perms enum.Permissions) error
}

// --- UserRole ---
type UserRoleUseCase interface {
    GetByUID(ctx context.Context, tenantID, uid string) ([]UserRoleDTO, error)
    Assign(ctx context.Context, tenantID, uid, roleID string) error
    Revoke(ctx context.Context, tenantID, uid, roleID string) error
    Replace(ctx context.Context, tenantID, uid string, roleIDs []string) error
}

// --- 外部映射 ---
type RoleMappingUseCase interface {
    List(ctx context.Context, tenantID string) ([]RoleMappingDTO, error)
    Upsert(ctx context.Context, req *UpsertRoleMappingRequest) error
    Delete(ctx context.Context, tenantID, id string) error
    SyncFromZitadelClaims(ctx context.Context, req *SyncFromZitadelRequest) error
    SyncFromScimGroup(ctx context.Context, req *SyncFromScimGroupRequest) error
    SyncFromLDAPGroups(ctx context.Context, req *SyncFromLDAPGroupsRequest) error
}

// --- 聚合查詢（前端菜单）---
type AuthorizationQueryUseCase interface {
    GetMyPermissions(ctx context.Context, tenantID, uid string) (enum.Permissions, error)
    GetMyRoles(ctx context.Context, tenantID, uid string) ([]string, error)
}
```

### 6.9 Middleware 授權流程

```
Request（JWT 已驗證）
  1. 取 ctx.tenant_id, ctx.uid
  2. userRoleUC.GetByUID → []Role.Name
  3. 對每個 roleName：
       rbacUC.Check(tenantID, uid, roleName, r.URL.Path, r.Method)
  4. 任一 Allow=true → 通過，注入 ctx.permission_name, ctx.plain_code
  5. 全否 → 403 Forbidden
  6. SuperAdmin uid → 直接通過
```

Logic 層可讀 `ctx.plain_code` 決定是否回傳明碼欄位（沿用 permission-server 的 `PlainCode` 模式）。

### 6.10 外部 Group / Role 映射

```go
type RoleMapping struct {
    TenantID       string
    ExternalSource enum.RoleSource  // zitadel | ldap | scim
    ExternalKey    string           // ZITADEL role / LDAP group DN / SCIM group id
    InternalRole   string           // 租戶 Role.Name
}
// Index: { tenant_id, external_source, external_key } unique
```

| 來源 | ExternalKey 範例 | 映射到 |
|------|------------------|--------|
| ZITADEL | `org_admin` | `tenant_admin` |
| LDAP (AD) | `CN=CloudEP-Admins,OU=Groups,DC=acme,DC=com` | 租戶自訂 Role.Name |
| LDAP (OpenLDAP) | `cn=admins,ou=groups,dc=acme,dc=com` | 租戶自訂 Role.Name |
| SCIM Group | `group-uuid-xxx` | 租戶自訂 Role.Name |

由 B2B 租戶管理員在後台設定（需命中 `permission.role.write` 對應 API）。

### 6.11 權限變更生效

| 事件 | 動作 |
|------|------|
| RolePermission Create/Delete | `LoadPolicy(tenant_id)` |
| Role Create/Update/Delete | `LoadPolicy(tenant_id)` |
| UserRole Assign/Revoke | 可選 `INCR auth:gen`（立即踢下线） |
| SCIM / LDAP Group 變更 | 更新 user_roles → `LoadPolicy` + `INCR auth_gen` |
| Permission status 變更（平台） | `LoadAllPolicies()` |

### 6.12 B2C vs B2B 權限策略

| 租戶類型 | Role 自定義 | Permission 勾選 |
|----------|-------------|-----------------|
| **B2C** | 不可（只用 seed 模板） | 固定 |
| **B2B** | **完全自定義** | 從全局 Catalog 自由勾選 |
| **Hybrid** | B2B 部分可自定義 | 依 tenant 設定 |

---

## 7. API 規劃

檔案：`generate/api/`

### 7.1 auth.api（公開）

| Method | Path | 說明 |
|--------|------|------|
| POST | `/api/v1/auth/token/exchange` | ZITADEL token → CloudEP JWT |
| POST | `/api/v1/auth/token/refresh` | 刷新 JWT |
| POST | `/api/v1/auth/logout` | 登出（jti 黑名單） |

### 7.2 member.api（需 JWT + Casbin）

| Method | Path | Casbin 命中 Permission（示例） |
|--------|------|-------------------------------|
| GET | `/api/v1/members/me` | `member.info.select` |
| PATCH | `/api/v1/members/me` | `member.info.update` |
| GET | `/api/v1/members` | `member.admin.list` |
| GET | `/api/v1/members/:uid` | `member.admin.read` |
| PATCH | `/api/v1/members/:uid` | `member.admin.update` |
| PATCH | `/api/v1/members/:uid/status` | `member.admin.status` |

> 授權由 **Casbin 比對實際 path + method** 決定，非硬編碼 permission 字串。

### 7.3 permission.api（需 JWT + Casbin）

| Method | Path | 說明 |
|--------|------|------|
| GET | `/api/v1/permissions/catalog` | 全局 Permission Tree（open 節點） |
| GET | `/api/v1/permissions/me` | 當前用户的 permission name → status map |
| GET | `/api/v1/permissions/roles` | 列出租戶 Role |
| POST | `/api/v1/permissions/roles` | 建立 Role（B2B） |
| PUT | `/api/v1/permissions/roles/:id` | 更新 Role |
| DELETE | `/api/v1/permissions/roles/:id` | 刪除 Role |
| GET | `/api/v1/permissions/roles/:id/permissions` | 取得 Role 勾選的 Permission |
| PUT | `/api/v1/permissions/roles/:id/permissions` | 更新 Role 勾選（PermissionTree 驗證 + 補 parent） |
| GET | `/api/v1/permissions/users/:uid/roles` | 查用户角色 |
| POST | `/api/v1/permissions/users/:uid/roles` | 指派 Role `{ "role_id": "..." }` |
| DELETE | `/api/v1/permissions/users/:uid/roles/:role_id` | 撤銷 Role |
| GET | `/api/v1/permissions/role-mappings` | 外部 Group 映射列表 |
| PUT | `/api/v1/permissions/role-mappings` | 新增/更新映射 |
| POST | `/api/v1/permissions/policy/reload` | 手動觸發 LoadPolicy（平台 Admin） |

### 7.4 tenant.api（平台 / 租戶 Admin）

| Method | Path | Casbin 命中 Permission（示例） |
|--------|------|-------------------------------|
| POST | `/api/v1/admin/tenants` | `system.tenant.create` |
| GET | `/api/v1/admin/tenants/:tenant_id` | `tenant.read` |
| PUT | `/api/v1/admin/tenants/:tenant_id/ldap` | `tenant.ldap.write` |
| POST | `/api/v1/admin/tenants/:tenant_id/directory-sync` | `tenant.sync.trigger` |

### 7.5 scim.api（SCIM Bearer Token，非 JWT）

```
/scim/v2/tenants/{tenant_id}/Users
/scim/v2/tenants/{tenant_id}/Groups
```

認證：`Authorization: Bearer {tenant_scim_token}`（hash 存於 tenant 設定）

SCIM 請求授權可透過 tenant 級 token 隱含 `scim:*`，或細分 scim users/groups permission。

---

## 8. Middleware 鏈

### 8.1 一般受保護 API

```
Request
  → go-zero JWT 驗簽
  → JwtRevokeMiddleware（jti 黑名單 + auth_gen）
  → TenantContextMiddleware（校驗 tenant_id 一致）
  → CasbinRBACMiddleware（role names × path × method → Allow）
  → handler → logic → usecase
```

### 8.2 CasbinRBACMiddleware

```go
// 伪代码
roles := userRoleUC.GetRoleNames(ctx, tenantID, uid)
for _, roleName := range roles {
    result, _ := rbacUC.Check(ctx, &CheckRequest{
        TenantID: tenantID, UID: uid,
        RoleName: roleName, Path: r.URL.Path, Method: r.Method,
    })
    if result.Allow {
        ctx = withPermissionName(ctx, result.PermissionName)
        ctx = withPlainCode(ctx, result.PlainCode)
        next(w, r)
        return
    }
}
// SuperAdmin bypass
if uid == cfg.PlatformSuperAdminUID { next(w, r); return }
httpx.Error(w, forbidden)
```

### 8.3 SCIM API

```
Request
  → ScimAuthMiddleware（tenant_scim_token）
  → TenantContextMiddleware
  → handler
```

### 8.4 Logic 層補充授權

Casbin 處理 **API 級** 授權。Logic 內可追加 **資源級** 判斷：

- `member.info.select` vs 查他人：若 path 含 `:uid` 且 uid ≠ caller，需命中 `member.admin.read`
- `PlainCode`：Logic 讀 `ctx.plain_code`，決定是否回傳明碼欄位

---

## 9. 核心流程

### 9.1 登入 / 換票

```
Client → ZITADEL OIDC Login（含 LDAP IdP）
Client → POST /auth/token/exchange { tenant_slug, id_token }
  1. zitadel.VerifyIDToken
  2. tenant.ResolveBySlug → 校驗 org_id
  3. member.EnsureMember → uid（如 ACME-ODWXGYBK）
  4. permission.SyncFromZitadelClaims → user_roles
  5. auth.IssueTokenPair（role names 逗號分隔, auth_gen）
Client ← { access_token, refresh_token, uid }
```

### 9.2 受保護 API

```
Client → GET /api/v1/members/me (Bearer access_jwt)
  1. JWT + 黑名單 + auth_gen
  2. CasbinRBACMiddleware → Check(role, "/api/v1/members/me", "GET")
  3. member.GetByUID
```

### 9.3 B2B 自定義 Role + 勾選 Permission

```
Tenant Admin → PUT /permissions/roles/{id}/permissions
  { "member.admin.list": "open", "member.admin.read": "open" }
  → RolePermissionUC.Create
  → PermissionTree.getFullParentPermissionIDs（自動補 parent）
  → RBACUC.LoadPolicy(tenant_id)

Tenant Admin → POST /permissions/users/{uid}/roles
  { "role_id": "..." }
  → UserRoleUC.Assign
```

### 9.4 停權

```
Admin → PATCH /members/:uid/status { status: "suspended" }
  → member.UpdateStatus
  → auth.RevokeAllForUser（INCR auth_gen）
```

---

## 10. LDAP 與 SCIM

### 10.1 三條 Provisioning 路徑

| 路徑 | 適用 | 說明 |
|------|------|------|
| **SCIM → ZITADEL → Gateway** | 有 HR / Entra ID / Okta | 企業推送用户 |
| **ZITADEL LDAP IdP** | 用戶登入時 JIT | 首次登入建立 member |
| **Directory Sync Worker** | 無 SCIM 的 AD / OpenLDAP | 定時同步 + 離職偵測 |

### 10.2 LDAP 設定（AD + OpenLDAP）

```go
type TenantLDAPConfig struct {
    TenantID     string
    Type         string   // "ad" | "openldap"
    Host         string
    Port         int
    UseTLS       bool
    BaseDN       string
    BindDN       string   // encrypted
    BindPassword string   // encrypted
    UserFilter   string
    GroupFilter  string
    AttrMap      LDAPAttrMap
}

type LDAPAttrMap struct {
    Username    string // AD: sAMAccountName / LDAP: uid
    Email       string // mail
    DisplayName string // displayName / cn
    Phone       string // telephoneNumber
    ExternalID  string // objectGUID / entryUUID
    Groups      string // memberOf
}
```

### 10.3 SCIM

- `externalId` = Member UID（`ACME-ODWXGYBK`）
- SCIM Groups PATCH → `permission.SyncFromScimGroup`
- SCIM deactivate → `member.suspended` + `auth.RevokeAllForUser`

---

## 11. 可讀 UID 設計

### 11.1 格式

```
{TenantPrefix}-{Body}

範例：ACME-ODWXGYBK
```

- `TenantPrefix`：2~4 位大寫（來自 tenant.UIDPrefix / slug 縮寫）
- `Body`：6~8 位大寫字母（自訂字母表，排除易混淆字元）
- **不要** UUID、不要純數字、不要 base64 亂碼

### 11.2 字母表（沿用 invited_code 風格）

```
O D W X Y G B C H E F A Q I J L M N Z K P V R S T
（25 字符，無 0/O/1/I 混淆問題）
```

### 11.3 產生（Bucket 取號，支援單租戶 50 萬）

```
Redis: member:seq:{tenant_id}
每次 INCRBY 500 取一個 bucket
bucket 內 sequential 編碼 → Body
```

唯一索引：`{ tenant_id, uid }` unique

---

## 12. 資料模型與索引

### 12.1 Collections

| Collection | 模組 | 說明 |
|------------|------|------|
| `members` | member | Profile |
| `identities` | member | zitadel_sub ↔ uid |
| `tenants` | member | 租戶 metadata |
| `tenant_ldap_configs` | member | LDAP 同步設定（加密） |
| `permissions` | permission | 全局 Permission Tree（平台 seed） |
| `roles` | permission | 租戶 Role（`tenant_id` + `name`） |
| `role_permissions` | permission | Role ↔ Permission ID |
| `user_roles` | permission | uid ↔ Role（支援多角色） |
| `role_mappings` | permission | 外部 Group ↔ Role.Name |

### 12.2 主要索引

```javascript
// members
{ tenant_id: 1, uid: 1 }                          // unique
{ tenant_id: 1, zitadel_user_id: 1 }              // unique
{ tenant_id: 1, member_status: 1, create_at: -1 }

// identities
{ tenant_id: 1, zitadel_user_id: 1 }              // unique
{ tenant_id: 1, uid: 1 }
{ tenant_id: 1, external_id: 1 }

// permissions（全局）
{ name: 1 }                                       // unique
{ parent: 1, status: 1 }
{ http_path: 1, http_method: 1 }                  // sparse

// roles
{ tenant_id: 1, name: 1 }                       // unique
{ tenant_id: 1, status: 1 }

// role_permissions
{ role_id: 1, permission_id: 1 }                // unique

// user_roles
{ tenant_id: 1, uid: 1, role_id: 1 }            // unique
{ tenant_id: 1, uid: 1 }

// role_mappings
{ tenant_id: 1, external_source: 1, external_key: 1 }  // unique
```

### 12.3 分片鍵（100 萬+）

```
Shard Key: { tenant_id: 1, uid: 1 }
```

單租戶 50 萬會集中在同一 chunk，MongoDB 仍可承受；若預期單租戶千萬級再評估 hash 二次分片。

---

## 13. Redis Key 命名

### auth（`internal/model/auth/redis.go`）

```
auth:jwt:bl:{jti}                  # 單 token 黑名單，TTL = 剩餘壽命
auth:gen:{tenant_id}:{uid}         # 批量失效代號
```

### member（`internal/model/member/redis.go`）

```
member:profile:{tenant_id}:{uid}   # profile cache，TTL 5~15min
member:sub:{tenant_id}:{sub}       # zitadel_sub → uid，TTL 1h
member:seq:{tenant_id}             # UID bucket counter
```

### permission（`internal/model/permission/redis.go`）

```
permission:casbin:rules              # Casbin policy rules（List of JSON）
permission:tree:open                 # 可選：open 節點 cache
perm:role_perms:{tenant_id}:{role_id}  # role → permission names，TTL 30min
perm:user_roles:{tenant_id}:{uid}      # uid → role names，TTL 5min
```

---

## 14. 規模與性能（100 萬+ / 單租戶 50 萬）

| 項目 | 策略 |
|------|------|
| Gateway | 無狀態，水平擴展 |
| MongoDB | Sharding + Replica Set，讀走 secondary |
| ListMembers | Cursor 分頁，禁止 deep offset |
| Authorize | Casbin EnforceEx（内存 + Redis policy） |
| LoadPolicy | 变更时增量；cron 5min 全量兜底 |
| JWT → UID | Redis cache 1h |
| Directory Sync | 500 users / batch，rate limit ZITADEL API |
| Access Token TTL | 15min（降低撤銷窗口） |

### 容量粗估

```
100 萬 members × ~2KB  ≈ 2GB（不含 index）
indexes               ≈ 1~2GB
→ 單集群可承受，建議 3 node replica set 起跳
```

---

## 15. 目錄結構

```
gateway/
├── generate/api/
│   ├── auth.api
│   ├── member.api
│   ├── permission.api
│   ├── tenant.api
│   └── scim.api
│
├── internal/
│   ├── middleware/
│   │   ├── jwt_revoke.go
│   │   ├── tenant_context.go
│   │   ├── require_permission.go
│   │   └── scim_auth.go
│   │
│   ├── library/
│   │   ├── zitadel/
│   │   │   ├── oidc.go
│   │   │   └── management.go
│   │   ├── ldap/
│   │   │   ├── client.go
│   │   │   └── attrmap.go
│   │   ├── casbin/                 # Enforcer 初始化 helper
│   │   └── uid/
│   │       ├── encode.go
│   │       └── generator.go
│   │
│   ├── model/
│   │   ├── auth/
│   │   │   └── ...
│   │   ├── member/
│   │   │   └── ...
│   │   └── permission/
│   │       ├── entity/
│   │       │   ├── permission.go
│   │       │   ├── role.go
│   │       │   ├── user_role.go
│   │       │   ├── role_permission.go
│   │       │   └── role_mapping.go
│   │       ├── enum/
│   │       │   ├── status.go
│   │       │   └── permission_type.go
│   │       ├── repository/
│   │       │   ├── permission.go
│   │       │   ├── role.go
│   │       │   ├── user_role.go
│   │       │   ├── role_permission.go
│   │       │   ├── role_mapping.go
│   │       │   └── casbin_redis_adapter.go   # 沿用 permission-server
│   │       ├── usecase/
│   │       │   ├── permission_tree.go        # 沿用 permission-server
│   │       │   ├── rbac.go                   # Casbin LoadPolicy / Check
│   │       │   ├── permission.go
│   │       │   ├── role.go
│   │       │   ├── role_permission.go
│   │       │   ├── user_role.go
│   │       │   ├── role_mapping.go
│   │       │   └── authorization_query.go
│   │       ├── rbac/
│   │       │   └── rule.go                   # Casbin Rule struct
│   │       ├── config/
│   │       ├── errors.go
│   │       ├── redis.go
│   │       └── mock/
│   │
│   └── worker/
│       ├── directory_sync/
│       └── policy_sync/            # 可選：定時 LoadPolicy
│
├── etc/
│   ├── gateway.yaml
│   └── rbac.conf                   # Casbin 模型（沿用 permission-server）
│
└── docs/
    ├── model.md
    └── identity-member-design.md   # 本文件
```

---

## 16. 設定檔

`etc/gateway.yaml` 擴充草案：

```yaml
Name: gateway
Host: 0.0.0.0
Port: 8888

Auth:
  AccessSecret: ${JWT_ACCESS_SECRET}
  AccessExpire: 900

RefreshAuth:
  AccessSecret: ${JWT_REFRESH_SECRET}
  AccessExpire: 604800

Zitadel:
  Issuer: https://id.example.com
  ClientID: ${ZITADEL_CLIENT_ID}
  JWKSUrl: https://id.example.com/oauth/v2/keys
  MgmtURL: https://id.example.com/management/v1
  MgmtToken: ${ZITADEL_MGMT_TOKEN}

Mongo:
  # 見 internal/library/mongo 設定

Redis:
  Host: 127.0.0.1:6379
  Type: node

Member:
  DefaultLanguage: zh-tw
  DefaultCurrency: TWD

Permission:
  RBACModelPath: etc/rbac.conf
  PolicySyncInterval: 5m
  PlatformSuperAdminUID: ${PLATFORM_SUPER_ADMIN_UID}  # 對應舊 GodDog bypass
  CacheTTLSeconds: 300
```

---

## 17. 實施順序

| 階段 | 內容 | 產出 |
|------|------|------|
| **P0** | 目錄骨架、entity、redis key、config | 可啟動、可連 Mongo/Redis |
| **P1** | UID generator + EnsureMember + token exchange | 可登入取得 JWT + 可讀 UID |
| **P2** | JWT middleware + jti 黑名單 + auth_gen + logout/refresh | 完整 Token 生命週期 |
| **P3** | Permission seed + PermissionTree + Casbin RBAC + Redis Adapter | 可 LoadPolicy / Check |
| **P4** | member profile API + 預設 Role seed + CasbinRBACMiddleware | `/members/me` + API 授權生效 |
| **P5** | RolePermission + UserRole + B2B Role CRUD + Permission 勾選 API | 租戶完全自定義 |
| **P6** | Tenant 建立 + ZITADEL CreateOrg + LDAP 設定 | 多租戶 |
| **P7** | Directory Sync Worker（AD + OpenLDAP） | 企業目錄同步 |
| **P8** | SCIM 2.0 endpoint + Group 映射 | 企業 provisioning |
| **P9** | 壓測（100 萬 seed）、sharding、調優 | 上線準備 |

---

## 18. 待決策事項

| # | 議題 | 選項 | 備註 |
|---|------|------|------|
| 1 | UID 格式 | `ACME-ODWXGYBK` vs 純 `ODWXGYBK` | 建議带前缀 |
| 2 | SCIM 路由 | `/scim/v2/tenants/{id}` vs 獨立子域名 | |
| 3 | ZITADEL 部署 | Self-hosted vs Cloud | 影響 LDAP 網路 |
| 4 | 權限變更生效 | 仅清 cache vs 强制 INCR auth_gen | 建议重要變更 INCR |
| 5 | B2C 租戶 | 是否允許自定義 Role | 建议 B2C 只用 seed 模板，B2B 完全自定義 |
| 6 | Refresh Token | 是否輪換 + 舊 jti 黑名單 | 建议輪換 |
| 7 | UserRole | 一 user 多 role vs 單 role | 建议多 role（Casbin 逐一 Check） |
| 8 | PlatformSuperAdminUID | 固定 uid vs 平台 Role | 建议保留 bypass uid + 后续可移除 |

---

## 附錄 A：ServiceContext 組裝草案

```go
type ServiceContext struct {
    Config config.Config
    Validator validate.Validate

    // library clients
    Zitadel *zitadel.Client

    // usecases
    AuthUC           authusecase.TokenUseCase
    MemberProvUC     memberusecase.ProvisioningUseCase
    MemberProfileUC  memberusecase.ProfileUseCase
    MemberAdminUC    memberusecase.AdminUseCase
    TenantUC         memberusecase.TenantUseCase
    ScimUC           memberusecase.ScimUseCase

    // permission usecases（對齊 permission-server 拆分）
    PermRBACUC       permusecase.RBACUseCase
    PermUC           permusecase.PermissionUseCase
    RoleUC           permusecase.RoleUseCase
    RolePermUC       permusecase.RolePermissionUseCase
    UserRoleUC       permusecase.UserRoleUseCase
    RoleMappingUC    permusecase.RoleMappingUseCase
    AuthQueryUC      permusecase.AuthorizationQueryUseCase
}
```

---

## 附錄 C：permission-server 遷移對照（程式碼級）

| permission-server 檔案 | Gateway 目標 | 遷移方式 |
|------------------------|--------------|----------|
| `pkg/usecase/permission_tree.go` | `model/permission/usecase/permission_tree.go` | 幾乎原樣搬移 |
| `pkg/usecase/casbin_redis_rbac.go` | `model/permission/usecase/rbac.go` | 加 `tenant_id` 過濾 |
| `pkg/repository/casbin_redis_adapter.go` | `model/permission/repository/casbin_redis_adapter.go` | 原樣搬移 |
| `pkg/domain/rbac/rule.go` | `model/permission/rbac/rule.go` | 原樣搬移 |
| `etc/rbac.conf` | `etc/rbac.conf` | 原樣搬移 |
| `pkg/usecase/role.go` | `model/permission/usecase/role.go` | `ClientID`→`TenantID` |
| `pkg/usecase/role_permission.go` | `model/permission/usecase/role_permission.go` | 原樣搬移 |
| `pkg/usecase/user_role.go` | `model/permission/usecase/user_role.go` | 改支援多角色 |
| `pkg/usecase/token.go` | **`model/auth/usecase/token.go`** | 不在 permission 模組 |
| `generate/database/seeders/*_permission*` | `generate/database/seeders/` 或 Mongo seed | 改為 Gateway seed job |

---

## 附錄 B：與 model.md 的關係

- 本文件：**做什麼**（架構、流程、API、權限模型）
- [model.md](./model.md)：**怎麼寫**（entity / repository / usecase 程式碼規範）

實作時兩份文件搭配使用。

---

## 修訂紀錄

| 日期 | 版本 | 說明 |
|------|------|------|
| 2026-05-19 | 0.1.0 | 初稿：auth + member + permission（B2B 自定義）+ ZITADEL/LDAP/SCIM |
| 2026-05-19 | 0.2.0 | 對齊 app-cloudep-permission-server：Casbin RBAC、Permission Tree、Role/RolePermission |