member_center/docs/OPENAPI.md

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，避免跨租戶資料讀取/更新

多租戶資料隔離原則

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