# 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` 的公開查詢/操作端點。