# 系統設計草案（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
- 多租戶為邏輯隔離，但會員資料跨站共享
- 公開訂閱端點必須使用 `list_id + email` 做資料邊界，禁止僅以 `email` 查詢或操作
- 訂閱狀態同步目前採 webhook（event payload）；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 (ASP.NET Core Identity)
  - id, user_name, email, password_hash, email_confirmed, lockout, is_blacklisted, blacklisted_at, blacklisted_by, created_at
- roles / user_roles (Identity)
  - id, name, created_at
- OpenIddictApplications
  - id, client_id, client_secret, display_name, permissions, redirect_uris, properties（含 `tenant_id`, `usage=tenant_api|send_api|webhook_outbound|platform_service`）
- OpenIddictAuthorizations
  - id, application_id, status, subject, type, scopes
- OpenIddictTokens
  - id, application_id, authorization_id, subject, type, status, expiration_date
- OpenIddictScopes
  - id, name, display_name, resources
- newsletter_lists
  - id, tenant_id, name, status, created_at
- newsletter_subscriptions
  - id, list_id, email, user_id (nullable), status, preferences, created_at
- email_blacklist
  - id, email, reason, blacklisted_at, blacklisted_by
- 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
- system_flags
  - id, key, value, updated_at

關聯說明：
- newsletter_subscriptions.email 與 users.email 維持唯一性關聯
- 使用者註冊時，如 email 存在訂閱紀錄，補上 user_id
- 單一清單退訂：unsubscribe token 綁定 subscription_id
- blacklist 記錄於 email_blacklist（全租戶共用）

## 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.4b Send Engine 發信前申請 One-Click Token
1) Send Engine 依收件者呼叫 `POST /newsletter/one-click-unsubscribe-token`，或批次呼叫 `POST /newsletter/one-click-unsubscribe-tokens`
2) body 帶 `tenant_id + list_id + subscriber_id`（批次版為 `subscriber_ids[]`）
3) 會員中心簽發 token（與手動退訂 token 分離 purpose）
4) Send Engine 將 token 寫入 `List-Unsubscribe` 連結

### 6.6 Send Engine 事件同步（Member Center → Send Engine）
1) Member Center 發出事件（`subscription.activated` / `subscription.unsubscribed` / `preferences.updated`）
2) 以 webhook 推送至 Send Engine（簽章與重放防護）
3) `X-Client-Id` 使用 Send Engine `auth_clients.id`（可按 tenant 做設定覆蓋）
4) Send Engine 驗證 tenant scope，更新本地名單快照

### 6.7 Send Engine 退信/黑名單回寫（選用）
1) Send Engine 依事件類型決定回寫時機與原因碼：
2) `hard_bounce` / `soft_bounce_threshold` / `suppression`：Member Center 取消該 email 所有訂閱（跨租戶）並加入黑名單
3) `complaint`：Member Center 僅取消該筆訂閱，不加入黑名單
4) 回寫請求需帶 `tenant_id + subscriber_id + list_id`，Member Center 端做租戶邊界驗證
5) 回寫授權可用：
   - tenant client scope：`newsletter:events.write`
   - platform client scope：`newsletter:events.write.global`（SES 聚合事件）

### 6.5 註冊後銜接
1) 使用者完成註冊
2) 系統搜尋 `newsletter_subscriptions.email`
3) 將 `user_id` 補上並保留偏好
4) 可選：發出事件 `subscription.linked_to_user`

### 6.8 已登入修改密碼
1) 使用者登入會員中心
2) 進入 change password 頁面
3) 提交 `current_password + new_password`
4) 系統驗證目前密碼正確後更新 password hash
5) 更新成功後刷新目前 session

## 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`
- POST `/newsletter/unsubscribe-token`
- POST `/newsletter/one-click-unsubscribe-token`
- POST `/newsletter/one-click-unsubscribe-tokens`
- GET `/newsletter/preferences`
- POST `/newsletter/preferences`
- POST `/webhooks/subscriptions`（Send Engine 端點，Member Center 呼叫）
- POST `/webhooks/lists/full-sync`（Send Engine 端點，Member Center 呼叫）
- POST `/subscriptions/disable`（Member Center 端點，Send Engine 呼叫）
- POST `/integrations/send-engine/webhook-clients/upsert`（Member Center 端點，Send Engine 呼叫）

## 7.1 進度狀態（2026-02）
### API
- `GET /newsletter/subscriptions?list_id=...`：已實作
- `POST /webhooks/subscriptions`：已實作（Member Center 發送）
- `POST /subscriptions/disable`：已實作
- `POST /integrations/send-engine/webhook-clients/upsert`：已實作
- `POST /webhooks/lists/full-sync`：尚未實作（保留規格）

### Auth / Scope
- `tenant_api` / `send_api` / `webhook_outbound` OAuth Client 綁定 `tenant_id`，所有清單/事件 API 需驗證租戶邊界
- OAuth Client 需區分用途：`tenant_api` / `send_api` / `webhook_outbound` / `platform_service`（禁止混用）
- 新增 scope：`newsletter:list.read`、`newsletter:send.write`、`newsletter:send.read`、`newsletter:events.read`
- 新增 scope：`newsletter:events.write`
- 新增 scope：`newsletter:events.write.global`
- JWT Access Token 已改為 JWS（`DisableAccessTokenEncryption`），供 Send Engine 以 JWKS 驗簽

### 租戶端取 Token（Client Credentials）
- 租戶使用 OAuth Client Credentials 向 Member Center 取得 access token
- token 內含 `tenant_id` 與 scope
- Send Engine 收到租戶請求後以 JWKS 驗簽 JWT（JWS）
- 驗簽通過後將 `tenant_id` 固定在 request context，不接受 body 覆寫

## 7.2 尚未完成（待辦）
- `POST /webhooks/lists/full-sync`：Member Center 端尚未發送此事件（僅保留契約）
- 註冊後訂閱綁定（`newsletter_subscriptions.user_id` 補值）已在註冊 / external login 流程落地
- `subscription.linked_to_user` 事件已發送
- 安全設定頁（access/refresh 時效）目前僅存值，尚未實際套用到 OpenIddict token lifetime
- Audit Logs 目前以查詢為主，關鍵操作的寫入覆蓋率仍不足

## 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`
