member-platform/docs/BACKEND_ARCHITECTURE.md

memberapi.ose.tw 後端架構（FastAPI）

1. 目標與邊界

• 網域：memberapi.ose.tw
• 角色：會員中心後端真相來源（Member + Organization + Permission）
• 範圍：
  • user/member 管理（以 authentik_sub 為跨系統主鍵）
  • organization 管理
  • member-organization 關聯管理
  • permission grant/revoke 與 snapshot
  • internal 查詢 API 提供其他系統
• 不在本服務處理：
  • 前端 UI/互動流程
  • Authentik hosted login page 本身

2. 技術棧

• Python 3.12
• FastAPI
• SQLAlchemy 2.0
• PostgreSQL（psycopg）
• Pydantic Settings

3. 後端目錄

• backend/app/main.py
• backend/app/api/
  • auth.py
  • me.py
  • admin.py（permission）
  • admin_entities.py（member/org）
  • internal.py
  • internal_entities.py
• backend/app/models/
  • user.py
  • permission.py
  • organization.py
  • member_organization.py
  • api_client.py
• backend/app/repositories/
  • users_repo.py
  • permissions_repo.py
  • organizations_repo.py
  • member_organizations_repo.py

4. 資料模型

• users
  • id, authentik_sub(unique), authentik_user_id, email, display_name, is_active, timestamps
• permissions
  • id, user_id, scope_type, scope_id, module, action, created_at
  • unique: (user_id, scope_type, scope_id, module, action)
• organizations
  • id, org_code(unique), name, tax_id, status, timestamps
• member_organizations
  • id, member_id, organization_id, created_at
  • unique: (member_id, organization_id)
• api_clients（由 docs/API_CLIENTS_SQL.sql 建立）
  • client_key, api_key_hash, status, allowlist, expires/rate-limit 欄位

5. API 設計

• 健康檢查
  • GET /healthz
• 登入
  • GET /auth/oidc/url
  • POST /auth/oidc/exchange
• 使用者路由（Bearer）
  • GET /me
  • GET /me/permissions/snapshot
• 管理路由（X-Client-Key + X-API-Key）
  • POST /admin/permissions/grant
  • POST /admin/permissions/revoke
  • GET|POST|PATCH /admin/organizations...
  • GET|POST|PATCH /admin/members...
  • GET|POST|DELETE /admin/members/{member_id}/organizations...
• 內部路由（X-Internal-Secret）
  • POST /internal/users/upsert-by-sub
  • GET /internal/permissions/{authentik_sub}/snapshot
  • POST /internal/authentik/users/ensure
  • GET /internal/members
  • GET /internal/members/by-sub/{authentik_sub}
  • GET /internal/organizations
  • GET /internal/organizations/by-code/{org_code}
  • GET /internal/members/{member_id}/organizations

6. 安全策略

• admin 路由：API client 驗證（status/過期/hash/allowlist）
• internal 路由：X-Internal-Secret
• me 路由：Auth token + JWKS 驗簽
• /me 補值：若 token 無 email/name，會呼叫 userinfo 補齊

7. 與其他系統資料流

1. 其他系統登入後，以 token sub 呼叫 /internal/users/upsert-by-sub
2. 需要組織/會員資料時，走 /internal/members*、/internal/organizations*
3. 權限查詢走 /internal/permissions/{sub}/snapshot
4. 後台人員調整權限走 /admin/permissions/grant|revoke

8. 下一階段建議

• 導入 Alembic migration
• 加 audit log（誰在何時做了 member/org/permission 變更）
• 補上整合測試與 rate-limit metrics