From 67afbf6c5d43b5eee8146688ffeda2d291f377e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E6=80=A7=E9=A9=8A?= Date: Tue, 19 May 2026 21:56:59 +0800 Subject: [PATCH] add member design --- README.md | 1 + docs/identity-member-design.md | 1262 ++++++++++++++++++++++++++++++++ 2 files changed, 1263 insertions(+) create mode 100644 docs/identity-member-design.md diff --git a/README.md b/README.md index 7025e58..b20e435 100644 --- a/README.md +++ b/README.md @@ -160,6 +160,7 @@ HTTP Request - [internal/library/errors/README.md](internal/library/errors/README.md) — 錯誤碼與 HTTP 對照 - [internal/library/mongo/README.md](internal/library/mongo/README.md) — MongoDB / Redis cache 流程與用法 - [docs/model.md](docs/model.md) — `internal/model/{module}` 分層（entity / repository / usecase） +- [docs/identity-member-design.md](docs/identity-member-design.md) — **Draft** Identity / Member / Permission 模組架構（ZITADEL、LDAP、SCIM、B2B 自定義權限） ## 開發約定 diff --git a/docs/identity-member-design.md b/docs/identity-member-design.md new file mode 100644 index 0000000..e9e8024 --- /dev/null +++ b/docs/identity-member-design.md @@ -0,0 +1,1262 @@ +# 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 |