# 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)