first commit

docs/SYSTEM_SPEC_MASTER.md

@@ -0,0 +1,98 @@
+# System Spec Master
+
+## 目的
+
+這份是 `mkt.ose.tw` 的系統主規格單一入口，統一以下內容：
+
+- 系統整體架構與模組責任
+- Frontend / Backend / Runtime 的邊界
+- 開發與上線主線（MVP 優先）
+- 重要文件與驗收標準的定位
+
+## 系統組成
+
+### 1. Frontend（mkt.ose.tw）
+
+- 商家後台入口
+- 實驗管理與發布流程
+- 同頁 Visual Editor
+
+### 2. FastAPI（mktapi.ose.tw）
+
+- 產品業務 API 入口
+- 實驗編排、發布、runtime payload 組裝
+- editor / runtime 對外服務
+
+### 3. Directus（mktcms.ose.tw）
+
+- 帳號、權限、內容與 schema 底座
+- CMS 型資料管理
+
+### 4. Runtime SDK / Snippet
+
+- 網站端載入
+- 分流 assignment
+- payload 套用與事件上報
+
+## 核心原則
+
+- Frontend 正式業務資料以 `FastAPI` 為主入口，不直接以 Directus 當主要 API。
+- `Directus schema`、`Domain model`、`API DTO`、`runtime payload` 不混用。
+- Visual Editor 以「頁面為主角、控制最小化」為產品原則。
+- 先完成可上線 MVP，再做大型 UI polish 與 legacy 深重構。
+
+## API 與資料寫入策略（明確版）
+
+- `FastAPI` 是對外唯一產品 API 入口（Admin / Editor / Runtime）。
+- Frontend 與 SDK 不直接呼叫 Directus 作為業務 API。
+- 內容型資料的 `C/U/D` 由 FastAPI 編排，透過 Directus adapter 寫入 Directus。
+- Directus 負責 CMS 資料底座與 revision/audit 追蹤能力。
+- 高頻系統型資料（如 assignment、runtime event、system log）由 FastAPI 直接處理與儲存，不走 Directus revision 流。
+
+## 實驗模型簡化規則（這輪）
+
+- 實驗匹配必須以 `URL 規則 + 裝置限制` 共同決定。
+- 建立實驗時由系統自動建立「原始版本 Variant」。
+- 使用者不手動輸入 `experiment_key` / `variant_key`（系統生成 `EX+timestamp` / `VA+timestamp`）。
+- Variant 僅給使用者調整 `name` 與 `traffic_weight`。
+- 移除 `is_control` 與 `variant_changes.enabled` 這兩個使用者認知成本高的欄位。
+
+## 主線交付範圍（MVP）
+
+1. Editor 主幹穩定
+- 穩定選取與可視回饋
+- 即時編輯文字/連結/圖片/樣式
+- 結構操作與 undo/redo 可回復
+
+2. 管理流可跑通
+- Experiment / Variant / Release 建立與更新
+- Publish / Rollback
+
+3. Runtime 可運行
+- Bootstrap / Assign / Payload / Events 主流程
+
+4. 驗證與營運
+- validation、readiness、go/no-go、rollback 文件可執行
+
+## 模組邊界
+
+- Frontend 規格：見 [FRONTEND_ARCHITECTURE_SPEC.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/frontend/FRONTEND_ARCHITECTURE_SPEC.md)
+- Visual Editor：見 [VISUAL_EDITOR_SPEC.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/frontend/VISUAL_EDITOR_SPEC.md)
+- Backend 架構：見 [BACKEND_ARCHITECTURE_SPEC.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/backend/BACKEND_ARCHITECTURE_SPEC.md)
+- 實驗系統：見 [EXPERIMENT_SYSTEM_SPEC.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/backend/EXPERIMENT_SYSTEM_SPEC.md)
+- API 契約：見 [API_CONTRACT_MASTER.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/backend/API_CONTRACT_MASTER.md)
+- Runtime/SDK：見 [RUNTIME_SDK_SPEC.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/backend/RUNTIME_SDK_SPEC.md)
+- 安全與環境：見 [ENV_SECURITY_SPEC.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/backend/ENV_SECURITY_SPEC.md)
+- 資料歸屬矩陣：見 [DATA_OWNERSHIP_MATRIX.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/backend/DATA_OWNERSHIP_MATRIX.md)
+
+## 新模組開發治理
+
+- 新模組開發流程： [MODULE_DEVELOPMENT_PLAYBOOK.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/MODULE_DEVELOPMENT_PLAYBOOK.md)
+- 模組規格模板： [MODULE_SPEC_TEMPLATE.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/templates/MODULE_SPEC_TEMPLATE.md)
+- 所有新模組都必須先完成 data ownership 判斷，再開 API 與 UI 開發。
+
+## 執行節奏
+
+- 任務主控： [EXECUTION_PLAN.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/EXECUTION_PLAN.md)
+- 目前細項： [CURRENT_WORK_ITEMS.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/CURRENT_WORK_ITEMS.md)
+- 延後細修： [DEFERRED_POLISH_BACKLOG.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/DEFERRED_POLISH_BACKLOG.md)