first commit

docs/backend/BACKEND_ARCHITECTURE_SPEC.md

@@ -0,0 +1,82 @@
+# 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)