99 lines
4.3 KiB
Markdown
99 lines
4.3 KiB
Markdown
# 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)
|