# API Contract Master

## 目標

固定 `v1` 對外契約，避免前後端與 SDK 在開發中漂移。

> 參數必填/可選與路由實際狀態，請優先看：
> [PYTHON_API_PARAMETER_GUIDE.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/backend/PYTHON_API_PARAMETER_GUIDE.md)

## 這輪契約調整（2026-03-22）

- `experiment_key` 改為系統生成（`EX+timestamp`），不接受使用者輸入。
- `variant_key` 改為系統生成（`VA+timestamp`），不接受使用者輸入。
- Variant 不再暴露 `status`、`is_control` 作為使用者可編輯欄位。
- `variant_changes` 移除 `enabled` 欄位（每筆 change 預設啟用）。
- 建立 Experiment API 成功時，需同步建立一個原始版本 Variant（系統管理）。
- Runtime 實驗匹配需基於 URL 規則與裝置限制。
- Release rollback 僅允許針對 `published` 版本，且操作後需維持「每個 experiment 僅一個 published」。

## 分區

- Admin API
- Editor API
- Runtime API

## Admin API（v1）

### Sites

- `GET /api/admin/sites`
- `GET /api/admin/sites/{site_id}`

### Experiments

- `GET /api/admin/experiments`
- `GET /api/admin/experiments/{experiment_id}`
- `POST /api/admin/experiments`
- `PATCH /api/admin/experiments/{experiment_id}`
- `GET /api/admin/experiments/{experiment_id}/activity`

`POST/PATCH /api/admin/experiments` 使用者輸入重點：

- `name`
- `module_type`
- `status`
- `targeting_config.url_rules`
- `targeting_config.device_targets`

使用者不輸入：

- `experiment_key`（系統生成）

### Variants

- `GET /api/admin/variants/{variant_id}`
- `GET /api/admin/variants?experiment_id=...`
- `POST /api/admin/variants`
- `PATCH /api/admin/variants/{variant_id}`

`POST/PATCH /api/admin/variants` 使用者輸入重點：

- `name`
- `traffic_weight`

使用者不輸入：

- `variant_key`（系統生成）
- `status`
- `is_control`

### Releases

- `GET /api/admin/releases?experiment_id=...`
- `GET /api/admin/releases/{release_id}`
- `POST /api/admin/releases/build`
- `POST /api/admin/releases/{release_id}/publish`
- `POST /api/admin/releases/{release_id}/rollback`
- `POST /api/admin/releases/{release_id}/archive`

### Goals / SDK Config

- `GET /api/admin/goals`
- `GET /api/admin/goals/{goal_id}`
- `GET /api/admin/sdk-configs`
- `GET /api/admin/sdk-configs/{sdk_config_id}`

## Editor API（v1）

- `POST /api/editor/sessions`
- `GET /api/editor/sessions/{session_id}`
- `PATCH /api/editor/sessions/{session_id}`
- `DELETE /api/editor/sessions/{session_id}`
- `GET /api/editor/variants/{variant_id}/changes`
- `PUT /api/editor/variants/{variant_id}/changes`
- `POST /api/editor/previews/build`

`PUT /api/editor/variants/{variant_id}/changes`：

- change 欄位不含 `enabled`
- change 是否生效由是否存在於 change set 決定

## Runtime API（v1）

- `POST /api/runtime/bootstrap`
- `POST /api/runtime/assign`
- `POST /api/runtime/payload`
- `POST /api/runtime/events/impression`
- `POST /api/runtime/events/conversion`

## 契約原則

- 所有 API 回傳統一 DTO，不回傳 Directus raw item
- editor 專用 DTO 與 runtime 專用 DTO 分離
- breaking change 需升 API 版本
- 對外 `C/U/D` 一律經 FastAPI，禁止 frontend 直接對 Directus 做新業務寫入