83 lines
2.1 KiB
Markdown
83 lines
2.1 KiB
Markdown
# 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)
|