first commit

docs/backend/DATA_OWNERSHIP_MATRIX.md

@@ -0,0 +1,49 @@
+# Data Ownership Matrix
+
+## 目的
+
+這份文件用來固定「資料放哪裡、誰負責寫入、誰能直接讀取」，避免新模組把資料邊界混在一起。
+
+## 規則總結
+
+- 對外業務 API 只走 FastAPI。
+- 內容型資料可由 FastAPI 經 Directus repository 寫入 Directus（保留 revision）。
+- 高頻系統型資料由 FastAPI native repository 直接處理，不走 Directus revision。
+- Frontend/SDK 不直接做 Directus 新業務寫入。
+- 變更模型簡化：`Variant` 不使用 `is_control` / `status`，`VariantChange` 不使用 `enabled`。
+
+## 資料歸屬矩陣
+
+| Entity | 主儲存 | 寫入責任 | 讀取入口 | Revision | 頻率特性 |
+| --- | --- | --- | --- | --- | --- |
+| site | Directus | FastAPI -> Directus repo | Admin API | Yes | 低頻 |
+| experiment | Directus | FastAPI -> Directus repo | Admin API | Yes | 中頻 |
+| variant | Directus | FastAPI -> Directus repo | Admin/Editor API | Yes | 中頻 |
+| variant_change | Directus | FastAPI -> Directus repo | Editor API | Yes | 中頻 |
+| experiment_release | Directus | FastAPI -> Directus repo | Admin/Runtime API | Yes | 中頻 |
+| goal | Directus | FastAPI -> Directus repo | Admin API | Yes | 低頻 |
+| sdk_config | Directus | FastAPI -> Directus repo | Admin/Runtime API | Yes | 低頻 |
+| editor_session | Native DB | FastAPI native repo | Editor API | No | 中高頻 |
+| assignment | Native DB | FastAPI native repo | Runtime API | No | 高頻 |
+| runtime_event | Native DB | FastAPI native repo | Runtime API / analytics pipeline | No | 高頻 |
+| audit_log | Native DB | FastAPI native repo | Internal ops API | No | 中高頻 |
+
+## 新 Entity 判斷流程
+
+1. 是否需要 CMS/revision 與人工管理？
+- 是：優先 Directus（由 FastAPI 轉寫）
+- 否：走 FastAPI native
+
+2. 是否高頻（每請求或每曝光級）？
+- 是：禁止放 Directus revision 路徑
+- 否：可評估 Directus
+
+3. 是否要給 runtime 低延遲讀取？
+- 是：優先 native 或快取層
+- 否：可走內容層
+
+## 禁止事項
+
+- 新功能直接在 frontend 直寫 Directus。
+- 同一份資料同時承擔 CMS 欄位與 runtime payload 責任。
+- 把 runtime 高頻事件塞進 Directus revision 流。