member_center/docs/FLOWS.md

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：回寫後由 Member Center 取消該 email 的所有訂閱（跨租戶）並加入黑名單
• [API] complaint：回寫後由 Member Center 僅取消該筆訂閱，不加入黑名單
• [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] hard_bounce / soft_bounce_threshold / suppression 才會寫入 email_blacklist；complaint 不寫黑名單

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

註記：此流程目前尚未在程式中落地（屬待辦）。