125 lines
4.7 KiB
Markdown
125 lines
4.7 KiB
Markdown
# 系統設計草案（Member Center）
|
||
|
||
日期：2026-01-30
|
||
|
||
## 1. 需求摘要（已確認）
|
||
1) 多個網站共用的會員登入中心（SSO）
|
||
2) 電子報訂閱管理（發送另建）
|
||
3) 未註冊會員可訂閱；註冊後沿用訂閱資料
|
||
4) 未註冊會員可取消訂閱（單一清單退訂）
|
||
5) 登入需支援 API 與 Redirect 兩種方式（OAuth2 + OIDC）
|
||
|
||
## 2. 架構原則
|
||
- OAuth2 + OIDC（Authorization Code + PKCE）
|
||
- 會員中心只管理 Email 與訂閱狀態
|
||
- Double Opt-in
|
||
- 各站自行設計 UI，主要走 API；少數狀況使用 redirect
|
||
- 多租戶為邏輯隔離，但會員資料跨站共享
|
||
- 訂閱狀態同步採 event/queue
|
||
- PostgreSQL
|
||
- 實作：C# .NET Core + MVC + OpenIddict
|
||
|
||
## 3. 使用者故事（精簡）
|
||
- 訪客：在任一站點未登入狀態下輸入 Email 訂閱電子報
|
||
- 訪客：在信件中點擊連結完成 double opt-in
|
||
- 訪客：點擊取消訂閱連結即可退訂（單一清單）
|
||
- 會員：在任一站點登入後，其他站點可無痛登入（SSO）
|
||
- 站點後台：可管理站點資訊、訂閱清單、會員基本資料
|
||
|
||
## 4. 核心模組
|
||
- Identity Service：註冊、登入、密碼重設、Email 驗證
|
||
- OAuth2/OIDC Service：授權流程、token 發放、ID Token
|
||
- Subscription Service：訂閱/退訂/偏好管理
|
||
- Admin Console：租戶與清單管理
|
||
- Mailer Integration：驗證信/退訂信/確認信的發送介面（外部系統）
|
||
- Event Publisher：訂閱事件發佈（供發信系統或數據系統消費）
|
||
|
||
## 5. 資料模型（概念）
|
||
- tenants
|
||
- id, name, domains, status, created_at
|
||
- users
|
||
- id, email, password_hash, email_verified_at, status, created_at
|
||
- oauth_clients
|
||
- id, tenant_id, name, redirect_uris, client_type, created_at
|
||
- oauth_codes
|
||
- id, client_id, user_id, code_hash, code_challenge, expires_at, consumed_at
|
||
- oauth_tokens
|
||
- id, user_id, client_id, access_token_hash, refresh_token_hash, expires_at, revoked_at
|
||
- oidc_id_tokens
|
||
- id, user_id, client_id, id_token_hash, expires_at
|
||
- newsletter_lists
|
||
- id, tenant_id, name, status, created_at
|
||
- newsletter_subscriptions
|
||
- id, list_id, tenant_id, email, user_id (nullable), status, preferences, created_at
|
||
- email_verifications
|
||
- id, email, tenant_id, token_hash, purpose, expires_at, consumed_at
|
||
- unsubscribe_tokens
|
||
- id, subscription_id, token_hash, expires_at, consumed_at
|
||
- audit_logs
|
||
- id, actor_type, actor_id, action, payload, created_at
|
||
|
||
關聯說明：
|
||
- newsletter_subscriptions.email 與 users.email 維持唯一性關聯
|
||
- 使用者註冊時，如 email 存在訂閱紀錄，補上 user_id
|
||
- 單一清單退訂：unsubscribe token 綁定 subscription_id
|
||
|
||
## 6. 核心流程
|
||
|
||
### 6.1 OAuth2/OIDC Redirect 登入（Authorization Code + PKCE）
|
||
1) 站點導向 `/oauth/authorize`，帶 `client_id`, `redirect_uri`, `code_challenge`, `scope=openid email`
|
||
2) 使用者於會員中心登入
|
||
3) 成功後導回 `redirect_uri` 並附 `code`
|
||
4) 站點以 `code` + `code_verifier` 向 `/oauth/token` 換取 token + `id_token`
|
||
|
||
### 6.2 OAuth2 API 使用（站點自行 UI）
|
||
1) 站點以 API 驗證使用者登入（會員中心提供 login API）
|
||
2) 成功後取得 token（含 ID Token 可選）
|
||
3) 站點以 access_token 呼叫其他會員中心 API
|
||
|
||
### 6.3 未登入狀態的訂閱流程（在獨立平台）
|
||
1) 使用者在各站點輸入 Email 並選擇訂閱清單
|
||
2) 站點呼叫 `POST /newsletter/subscribe`
|
||
3) 會員中心建立 `pending` 訂閱並發送驗證信（透過外部發信系統）
|
||
4) 使用者點擊信件連結 `/newsletter/confirm?token=...`
|
||
5) 訂閱狀態改為 `active`
|
||
6) 會員中心發出事件 `subscription.activated` 到 event/queue
|
||
|
||
### 6.4 未登入退訂（單一清單）
|
||
1) 信件提供「一鍵退訂」連結 `/newsletter/unsubscribe?token=...`
|
||
2) 驗證 token 後將該訂閱標記為 `unsubscribed`
|
||
3) 會員中心發出事件 `subscription.unsubscribed` 到 event/queue
|
||
|
||
### 6.5 註冊後銜接
|
||
1) 使用者完成註冊
|
||
2) 系統搜尋 `newsletter_subscriptions.email`
|
||
3) 將 `user_id` 補上並保留偏好
|
||
4) 可選：發出事件 `subscription.linked_to_user`
|
||
|
||
## 7. API 介面（草案）
|
||
- GET `/oauth/authorize`
|
||
- POST `/oauth/token`
|
||
- GET `/.well-known/openid-configuration`
|
||
- POST `/auth/login` (API-only login)
|
||
- POST `/auth/refresh`
|
||
- POST `/newsletter/subscribe`
|
||
- GET `/newsletter/confirm`
|
||
- POST `/newsletter/unsubscribe`
|
||
- GET `/newsletter/preferences`
|
||
- POST `/newsletter/preferences`
|
||
|
||
## 8. 安全與合規
|
||
- 密碼強度與防暴力破解（rate limit + lockout）
|
||
- Token rotation + refresh token revoke
|
||
- Redirect URI 白名單 + PKCE
|
||
- Double opt-in（可配置）
|
||
- Audit log
|
||
- GDPR/CCPA：資料匯出與刪除（規劃中）
|
||
|
||
## 9. 其他文件
|
||
- `docs/UI.md`
|
||
- `docs/USE_CASES.md`
|
||
- `docs/FLOWS.md`
|
||
- `docs/OPENAPI.md`
|
||
- `docs/SCHEMA.sql`
|
||
- `docs/TECH_STACK.md`
|