2.1 KiB
2.1 KiB
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_controlVariantChange不含enabled
設計原則
- API DTO、Domain Model、Persistence Schema 分開管理
- 不將 Directus raw item 直接當對外契約
- 嚴格限制跨層耦合