warrenchen/member_center
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
member_center/docs/FLOWS.md
warrenchen 4fbf2e5497 feat: Enhance OAuth client management and add one-click unsubscribe functionality 
- Updated OpenAPI documentation to include new OAuth2 usage types: `send_api`.
- Added endpoints for issuing one-click unsubscribe tokens in both single and batch requests.
- Modified OAuth client creation and management to enforce new usage types and redirect URI requirements.
- Implemented logic in the Newsletter service to handle one-click unsubscribe token issuance.
- Updated UI to reflect changes in OAuth client usage options and redirect URI handling.
- Enhanced token generation logic to support new scopes and audience settings for Send Engine.
2026-02-25 14:29:26 +09:00

4.1 KiB
Raw Blame History

Flows

流程以「API 自建 UI」與「會員中心統一 UI」兩種模式描述。

F-01 註冊會員

  • [API] 站點送出 POST /auth/register
  • [API] 會員中心建立 user、寄送驗證信
  • [UI] 導向會員中心註冊頁完成註冊
  • [UI] 會員中心寄送驗證信

F-02 登入（OAuth2 + OIDC）

  • [API] 站點送出 POST /auth/login 取得 access_token + id_token
  • [API] 站點建立自身 session
  • [UI] 導向 /oauth/authorize 完成授權碼流程
  • [UI] 站點用 code 換 token + id_token

F-02b 內容站台呼叫 Send Engine（Client Credentials + JWT 驗簽）

  • [API] 內容站台以 client_credentials 呼叫 POST /oauth/token 取得 access_token（usage=send_api）
  • [API] 內容站台帶 Bearer token 呼叫 Send Engine 建立發送任務
  • [API] Send Engine 以 Member Center JWKS 驗簽 token
  • [API] 驗證 scope/tenant_id/exp 通過後才受理任務

F-03 忘記密碼 / 重設密碼

  • [API] 站點送出 POST /auth/password/forgot
  • [UI] 會員中心頁提交 email 並發送重設信
  • [API/UI] 使用 token 進入重設密碼頁

F-04 訂閱電子報（未登入）

  • [API] 站點送出 POST /newsletter/subscribe
  • [API] 會員中心建立 pending 訂閱並發送驗證信
  • [UI] 使用者點擊驗證信連結 /newsletter/confirm?token=...
  • [UI] 訂閱改為 active，發出 event subscription.activated

F-05 取消訂閱（單一清單）

  • [API] 站點以 list_id + email 呼叫 POST /newsletter/unsubscribe-token 取得 token
  • [UI] 使用者點擊退訂連結 /newsletter/unsubscribe?token=...
  • [UI] 訂閱狀態改為 unsubscribed
  • [API] 發出 event subscription.unsubscribed

F-05b One-Click 退訂 Token（Send Engine 發信前）

  • [API] Send Engine 以 tenant_id + list_id + subscriber_id 呼叫 POST /newsletter/one-click-unsubscribe-token
  • [API] 或以 tenant_id + list_id + subscriber_ids[] 呼叫 POST /newsletter/one-click-unsubscribe-tokens 批次取得
  • [API] Member Center 回傳 one-click unsubscribe_token
  • [API] Send Engine 將 token 置入信件 List-Unsubscribe URL

F-06 訂閱偏好管理（登入後）

  • [API] 站點以 list_id + email 讀取 /newsletter/preferences
  • [API] 站點以 list_id + email 更新 /newsletter/preferences
  • [UI] 會員中心提供偏好頁（可選）

F-10 Send Engine 事件同步（Member Center → Send Engine）

  • [API] Member Center 以 webhook 推送 subscription.activated/unsubscribed/preferences.updated（scope: newsletter:events.write）
  • [API] Header 使用 X-Signature / X-Timestamp / X-Nonce / X-Client-Id
  • [API] X-Client-Id 對應 Send Engine auth_clients.id（UUID）
  • [API] Member Center 從 DB 的 tenant 設定讀取對應 webhook client id
  • [API] Send Engine 驗證簽章 + timestamp + nonce（重放防護）後入庫
  • [API] Send Engine 更新名單快照

F-11 黑名單回寫（Send Engine → Member Center）

  • [API] Send Engine 依事件規則處理：
  • [API] hard_bounce / soft_bounce_threshold / suppression：設黑名單後回寫
  • [API] complaint：先在 Send Engine 取消訂閱，再回寫黑名單
  • [API] 呼叫 POST /subscriptions/disable：
  • [API] tenant client 用 newsletter:events.write
  • [API] 平台 client（SES 聚合事件）用 newsletter:events.write.global
  • [API] body 需含 tenant_id + subscriber_id + list_id + reason + disabled_by + occurred_at
  • [API] Member Center 將 email 寫入 email_blacklist，停用寄送並停止事件推送

F-12 Webhook Client Mapping 回填（Send Engine → Member Center）

  • [API] Send Engine 建立/更新 tenant 對應的 webhook client（auth_clients.id）
  • [API] 呼叫 POST /integrations/send-engine/webhook-clients/upsert（scope: newsletter:events.write.global）
  • [API] Member Center 更新 tenant 設定（DB）

F-07 會員資料查看

  • [API] 站點讀取 /user/profile
  • [UI] 會員中心提供個人資料頁

F-08 管理者管理租戶/清單/Client

  • [UI] 會員中心管理後台進行 CRUD

F-09 訂閱與會員綁定

  • [API] 使用者完成註冊後，會員中心將訂閱資料與 user_id 綁定
  • [API] 發送事件 subscription.linked_to_user