# Backend Architecture Spec

## 目標

定義 `mktapi.ose.tw` 的後端分層、責任邊界與核心資料模型，讓 FastAPI 成為穩定產品 API 層。

## 分層架構

### Domain Layer

- 核心概念與聚合邊界
- 不直接依賴 Directus 原始 schema

### Application Layer

- use case / command / query
- 權限驗證、狀態流轉、流程編排

### Repository Layer

- Directus-backed repositories（內容型資料）
- Native repositories（系統型高頻資料）

### API Layer

- Admin API
- Editor API
- Runtime API

## Directus / FastAPI 邊界

### Directus 保留

- Identity / Access
- CMS / schema / content
- revision/audit 能力（內容層版本追蹤）

### FastAPI 接手

- 實驗與發布業務規則
- editor 協作流程
- runtime assignment 與 payload
- 事件收集與整合

## 寫入責任（CUD）

- Frontend/SDK 的業務寫入一律先進 FastAPI。
- 內容型 `C/U/D`：FastAPI 驗證後透過 Directus repository 寫入 Directus（保留 revision）。
- 高頻系統型寫入：FastAPI 直接寫 native repository（不依賴 Directus revision）。
- 禁止在前端直接對 Directus 做新業務寫入。

## 核心資料模型（DATA_MODEL）

- Site
- Experiment
- Variant
- VariantChange
- ExperimentRelease
- Goal
- SdkConfig
- Assignment
- AuditLog
- SystemLog

### 模型欄位約束（這輪）

- `Experiment.experiment_key`：系統生成（`EX+timestamp`）
- `Variant.variant_key`：系統生成（`VA+timestamp`）
- `Variant` 不含使用者可編輯 `status` 與 `is_control`
- `VariantChange` 不含 `enabled`

## 設計原則

- API DTO、Domain Model、Persistence Schema 分開管理
- 不將 Directus raw item 直接當對外契約
- 嚴格限制跨層耦合

## 參照文件

- [API_CONTRACT_MASTER.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/backend/API_CONTRACT_MASTER.md)
- [DATA_OWNERSHIP_MATRIX.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/backend/DATA_OWNERSHIP_MATRIX.md)
- [RUNTIME_SDK_SPEC.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/backend/RUNTIME_SDK_SPEC.md)