159 lines
9.2 KiB
Markdown
159 lines
9.2 KiB
Markdown
# Flows
|
||
|
||
流程以「API 自建 UI」與「會員中心統一 UI」兩種模式描述。
|
||
|
||
## F-01 註冊會員
|
||
- [API] 站點送出 `POST /auth/register`
|
||
- [API] 會員中心建立 user、寄送驗證信
|
||
- [UI] 導向會員中心註冊頁完成註冊
|
||
- [UI] 會員中心寄送驗證信
|
||
|
||
## F-02 登入（OAuth2 + OIDC）
|
||
- [UI] 使用 `usage=web_login` OAuth client，導向 `/oauth/authorize` 完成 Authorization Code + PKCE
|
||
- [UI] 若未登入，會員中心會導向 Web login，登入後回到原 authorize request
|
||
- [UI] 站點用 code + code_verifier 換 token
|
||
- [UI] `web_login` 可使用 public client，不要求 client secret；必須設定 redirect URI
|
||
- [UI] 若 Web 與 API 不同 origin，需設定 `Auth:WebLoginUrl`，且 Web 端需允許導回 `Auth:Issuer` 或 `Auth:AllowedLoginReturnUrlPrefixes`
|
||
- [UI] 若 Web 與 API 位於不同子網域，需設定 `Auth:CookieDomain`，讓 authorize endpoint 可讀取 Web login cookie
|
||
- [Auth] 不支援 password grant 或未註冊 client；refresh token 統一送至 `/oauth/token`
|
||
- [Auth] 新簽發 token 套用後台安全設定：access token `5–1440` 分鐘、refresh token `1–365` 天
|
||
|
||
## F-02a 登出（外站 direct logout）
|
||
- [UI] 外站將瀏覽器導向 Member Center Web `/account/logout`
|
||
- [UI] Member Center 清除 Web login cookie / session
|
||
- [UI] 若帶 `returnUrl`，Member Center 僅允許導回本站 local URL 或 allowlist 內的外站 URL
|
||
- [Auth] Login 與 Logout 使用各自 allowlist，並結構化比對 scheme、host、port 與 path segment，禁止單純字串 prefix
|
||
- [UI] 登出完成後導回外站 callback
|
||
- [UI] 外站 callback 清除本站 session / 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-02c 檔案上傳（A service -> File Space）
|
||
- [API] `A service` 以 `client_credentials` 向 Member Center 取得 access token
|
||
- [API] token 需包含 `files:upload.write`
|
||
- [API] token 必須包含有效 `tenant_id`，並以 `aud=file_access_api` 為目標資源；缺少或不符時拒絕
|
||
- [API] `A service` 帶 token 呼叫 access agent / file space 上傳檔案
|
||
- [API] access agent 以 JWKS 驗簽 JWT，並驗 `iss/aud/exp/scope/tenant_id`
|
||
|
||
## F-02d 檔案下載（A service -> client -> File Space）
|
||
- [API] client 向 `A service` 請求下載檔案
|
||
- [API] `A service` 以自己的商業邏輯驗證該 user 是否可讀取指定檔案
|
||
- [API] `A service` 以 `files:download.delegate` 呼叫 Member Center `POST /file-access/download-tokens` 取得短效 download token
|
||
- [API] download token 由 Member Center 簽發，至少綁定 `tenant_id + user_id + file_id/object_key + method=GET + exp`
|
||
- [UI/API] `A service` 將帶短效 token 的下載 URL 回給 client
|
||
- [UI/API] client 直接向 access agent / file space 請求檔案
|
||
- [API] access agent 以 `files:download.read` 呼叫 Member Center `POST /file-access/download-tokens/validate`，確認 token 與實際 GET request 邊界一致後放行
|
||
- [API] issuing 與 validation 都採 tenant fail-closed；Bearer token 缺少或帶錯 `tenant_id` 時不得簽發或驗證成功
|
||
|
||
註記：下載流程不直接暴露一般 S2S token 給 client。
|
||
|
||
## F-03 忘記密碼 / 重設密碼
|
||
- [API] 站點送出 `POST /auth/password/forgot`
|
||
- [UI] 會員中心頁提交 email 並發送重設信
|
||
- [API/UI] 使用 token 進入重設密碼頁
|
||
|
||
註記：目前 Web UI 已實作 forgot/reset 流程，但尚未串接 email 發送；開發階段會直接顯示 reset token 與 reset 連結。
|
||
|
||
## F-03b 已登入修改密碼
|
||
- [UI] 使用者登入後進入 `/account/changepassword`
|
||
- [UI] 輸入目前密碼與新密碼
|
||
- [UI] 會員中心驗證目前密碼後更新密碼
|
||
- [UI] 更新成功後刷新登入狀態
|
||
|
||
## F-04 訂閱電子報（未登入）
|
||
- [API] 站點以 `tenant_api` client credentials 取得含 `newsletter:subscriptions.write` 的 token
|
||
- [API] 站點帶 Bearer token 送出 `POST /newsletter/subscribe`；token tenant 必須擁有指定清單
|
||
- [API] 會員中心建立 pending 訂閱並發送驗證信
|
||
- [UI] 使用者點擊驗證信連結 `/newsletter/confirm?token=...`
|
||
- [UI] 訂閱改為 active，發出 event `subscription.activated`
|
||
|
||
## F-05 取消訂閱（單一清單）
|
||
- [API] 站點以 tenant Bearer token 與 `list_id + email` 呼叫 `POST /newsletter/unsubscribe-token` 取得 token；需 `newsletter:subscriptions.write`
|
||
- [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 訂閱偏好管理（租戶站台 S2S）
|
||
- [API] 站點以 tenant Bearer token 與 `list_id + email` 讀取 `/newsletter/preferences`；需 `newsletter:subscriptions.read`
|
||
- [API] 站點以 tenant Bearer token 與 `list_id + email` 更新 `/newsletter/preferences`；需 `newsletter:subscriptions.write`
|
||
- [API] Member Center 驗證 token tenant 擁有指定清單，缺少或不符時拒絕
|
||
- [UI] 會員中心提供偏好頁（可選）
|
||
|
||
## F-06b 我的電子報訂閱管理（登入後）
|
||
- [UI] 使用者登入後進入 `/profile/subscriptions`
|
||
- [API/UI] 會員中心依目前登入 user 查出其已綁定的訂閱清單
|
||
- [UI] 顯示各租戶 / 清單 / 狀態 / 訂閱時間
|
||
- [UI] 使用者可直接按下取消訂閱
|
||
- [API/UI] 系統驗證該訂閱屬於目前登入 user 後直接退訂
|
||
- [API/UI] 不需再次 email token 驗證
|
||
- [API] 發出 event `subscription.unsubscribed`
|
||
|
||
## 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-10b 訂閱名單讀取（Send Engine → Member Center）
|
||
- [API] tenant client 以 `newsletter:list.read` 呼叫 `GET /newsletter/subscriptions?list_id=...`
|
||
- [API] Member Center 驗證 token `tenant_id` 與清單 tenant 一致；claim 缺少、格式錯誤或不符時拒絕
|
||
- [API] 平台級跨 tenant 同步必須使用獨立的 `newsletter:list.read.global`
|
||
|
||
## 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`
|
||
- [API] `/user/profile`、`/user/addresses`、`/user/subscriptions` 僅能存取 access token subject 對應的會員資料
|
||
- [API] Email 不是公開識別資料，不提供 by-email 跨會員查詢端點
|
||
- [UI] 會員中心提供個人資料頁
|
||
|
||
## F-07b 會員資料維護
|
||
- [UI] 使用者登入後進入 `/profile`
|
||
- [UI] 維護電話、公司、統編等基本資料
|
||
- [API/UI] 儲存會員基本資料
|
||
|
||
## F-07c 地址簿管理
|
||
- [UI] 使用者登入後進入 `/profile/addresses`
|
||
- [UI] 新增、編輯、刪除收貨地址
|
||
- [UI] 可設定預設地址
|
||
- [API/UI] 地址簿資料綁定目前登入 user
|
||
- [API/UI] 若只剩最後一筆地址，不允許刪除
|
||
|
||
## F-07d 其他服務讀取會員資料
|
||
- [API] 其他服務以 access token 呼叫會員中心 profile API
|
||
- [API] token 需帶對應 profile scopes
|
||
- [API] 會員中心依 scope 決定可讀取基本資料、地址簿或訂閱資料
|
||
- [API] service API 為主要模式，只要 client 具對應 scope 即可存取對應資料
|
||
|
||
## F-08 管理者管理租戶/清單/Client
|
||
- [UI] 會員中心管理後台進行 CRUD
|
||
|
||
## F-09 訂閱與會員綁定
|
||
- [API] 使用者完成註冊後，會員中心將訂閱資料與 user_id 綁定
|
||
- [API] 發送事件 `subscription.linked_to_user`
|