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

Identity / Member / Permission 模組設計草稿

狀態：Draft（待 Review）
適用專案：Portal API Gateway（PGW）
參考實作：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。

---

目錄

1. 設計目標與原則
2. 模組全景
3. 外部系統分工
4. auth 模組
5. member 模組
6. permission 模組（B2B 自定義）
7. API 規劃
8. Middleware 鏈
9. 核心流程
10. LDAP 與 SCIM
11. 可讀 UID 設計
12. 資料模型與索引
13. Redis Key 命名
14. 規模與性能（100 萬+ / 單租戶 50 萬）
15. 目錄結構
16. 設定檔
17. 實施順序
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）

   • 平台 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 介面

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

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）

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

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

.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 介面

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 已驗證的設計：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。

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 租戶自定義）

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

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）

[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）

// 輸入：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 介面

// --- 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 映射

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

// 伪代码
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）

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 主要索引

// 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 擴充草案：

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 組裝草案

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：怎麼寫（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