33102d536e
- 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.
58 lines
2.2 KiB
Markdown
58 lines
2.2 KiB
Markdown
# 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
|
||
|
||
## 通用錯誤格式
|
||
```json
|
||
{
|
||
"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 權限
|