warrenchen/member_center
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
member_center/docs/OPENAPI.md
warrenchen 33102d536e feat: Implement email blacklist functionality and completed auth for subscription sending flow 
- Added EmailBlacklist service and controller for managing blacklisted emails.
- Created EmailBlacklistDto for data transfer and EmailBlacklistFormViewModel for form handling.
- Implemented views for listing and adding emails to the blacklist.
- Updated database schema with new EmailBlacklist entity and related migrations.
- Enhanced OAuthClientFormViewModel to include ClientId and ClientSecret properties.
- Added EmailBlacklistService to handle email blacklisting logic.
- Integrated email blacklist service into the application with necessary dependencies.
2026-02-10 18:05:03 +09:00

2.2 KiB
Raw Blame History

OpenAPI 草案（完整）

已補上完整端點與資料結構，並提供 docs/openapi.yaml 作為可直接擴充的版本。

版本

  • OpenAPI: 3.1.0
  • 檔案：docs/openapi.yaml

核心資源

  • OAuth2/OIDC：授權、token、discovery、JWKS
  • Auth：註冊、登入（password grant）、刷新、登出、忘記/重設密碼、Email 驗證
  • User：個人資料
  • Newsletter：訂閱/確認/退訂/偏好
  • Admin：Tenants/Lists/OAuth Clients（MVP CRUD）

Security Schemes

  • OAuth2 (Authorization Code + PKCE)
  • Bearer JWT（API 使用）

補充說明

  • /oauth/token、/auth/login、/auth/refresh 使用 application/x-www-form-urlencoded
  • /auth/email/verify 需要 token + email
  • /newsletter/subscribe 會回傳 confirm_token
  • /newsletter/unsubscribe-token 需要 list_id + email 才能申請 unsubscribe_token
  • /newsletter/preferences（GET/POST）需要 list_id + email，避免跨租戶資料讀取/更新

通用欄位

  • occurred_at：RFC3339（例：2026-02-10T09:30:00Z）
  • event_id、request_id：UUID

通用錯誤格式

{
  "error": "string_code",
  "message": "human readable message",
  "request_id": "uuid"
}

多租戶資料隔離原則

  • 與訂閱者資料（preferences、unsubscribe token）相關的查詢與寫入，一律必須帶 list_id + email 做租戶邊界約束。
  • 不提供僅靠 email 或單純 subscription_id 的公開查詢/操作端點。

待新增 API / Auth（規劃中）

API

  • GET /newsletter/subscriptions?list_id=...：回傳清單內所有訂閱（供發送引擎同步用）
  • POST /webhooks/subscriptions：Member Center → Send Engine 事件推送（Send Engine 端點，scope: newsletter:events.write）
  • POST /webhooks/lists/full-sync：Member Center → Send Engine 全量同步（Send Engine 端點，scope: newsletter:events.write）
  • POST /api/subscriptions/disable：Send Engine → Member Center 黑名單回寫（全租戶 email，scope: newsletter:events.write）

Auth / Scope

  • OAuth Client 需綁定 tenant_id
  • 新增 scope：
    • newsletter:list.read
    • newsletter:events.read
    • newsletter:events.write
  • 發送引擎僅能用上述 scope，禁止 admin 權限