mass_mail_engine/docs/DESIGN.md

Design

本文件描述 Send Engine 的核心模組、資料流、模組邊界與 Auth/Scope 設計。 本引擎只負責事件控制與執行，不提供 UI。 ESP 介接暫定為 Amazon SES。

核心模組

• Event Ingest
• List Store（多租戶）
• Campaign / Send Job
• Sender Adapter
• Delivery & Bounce Handling

信任邊界與 Auth 模型

外部角色

• Member Center：事件來源與名單權威來源（authority）
• 各租戶網站：內容來源（campaign/content producer）
• Send Engine：執行與狀態記錄（executor）

信任邊界

• Send Engine 不自行發放 tenant 身分；一律以 Member Center 代表的 tenant scope 為準
• 所有 API 必須攜帶 tenant_id，且在驗證後固定於 request context

驗證方式（建議）

1. Member Center → Send Engine
   • 使用簽名 Webhook（主推），或 OAuth2 Client Credentials
   • token 內含 tenant_id 與 scopes（例如 newsletter:events.write）
2. 租戶網站 → Send Engine
   • 使用 OAuth2 Client Credentials 或 JWT（由 Member Center 簽發）
   • token 內含 tenant_id 與 scopes（例如 newsletter:send.write）
3. Send Engine → Member Center
   • 使用 OAuth2 Client Credentials（Send Engine 作為 client）
   • scopes 只允許 newsletter:list.read / newsletter:events.read / newsletter:events.write

Tenant Scope 取得與約束

• 事件 ingest：以 token 中的 tenant_id 為唯一來源，不接受 body 覆寫
• Send Job 建立：tenant_id 從 token 取得；list_id 必須屬於該 tenant
• 名單同步：由 Member Center 主動推送（全量/增量），Send Engine 不主動拉取名單
• 回寫事件：回寫時攜帶同一 tenant_id，Member Center 做二次驗證

防護與審計

• 所有跨服務呼叫需記錄 tenant_id、client_id、scope、request_id
• API 層進行 scope 檢查與 tenant 一致性檢查
• Event Ingest 與 Webhook 需具備重放防護（timestamp + nonce）

名單外流風險控制

• Send Engine 不提供「名單查詢 API」
• 全量同步由 Member Center 發動並推送
• 如需測試/診斷，僅回傳計數與版本資訊，不回傳名單內容

資料模型原則

• 事件為 append-only，快照表僅反映最新狀態
• 任何狀態變更必須可追溯（含來源與租戶）