chris/mkt.ose.tw

Files

Chris 74d612aca1 first commit

2026-03-23 20:23:58 +08:00

4.3 KiB

Raw Blame History

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）

Editor 主幹穩定

穩定選取與可視回饋
即時編輯文字/連結/圖片/樣式
結構操作與 undo/redo 可回復

管理流可跑通

Experiment / Variant / Release 建立與更新
Publish / Rollback

Runtime 可運行

Bootstrap / Assign / Payload / Events 主流程

驗證與營運

validation、readiness、go/no-go、rollback 文件可執行

模組邊界

Frontend 規格：見 FRONTEND_ARCHITECTURE_SPEC.md
Visual Editor：見 VISUAL_EDITOR_SPEC.md
Backend 架構：見 BACKEND_ARCHITECTURE_SPEC.md
實驗系統：見 EXPERIMENT_SYSTEM_SPEC.md
API 契約：見 API_CONTRACT_MASTER.md
Runtime/SDK：見 RUNTIME_SDK_SPEC.md
安全與環境：見 ENV_SECURITY_SPEC.md
資料歸屬矩陣：見 DATA_OWNERSHIP_MATRIX.md

新模組開發治理

新模組開發流程： MODULE_DEVELOPMENT_PLAYBOOK.md
模組規格模板： MODULE_SPEC_TEMPLATE.md
所有新模組都必須先完成 data ownership 判斷，再開 API 與 UI 開發。

執行節奏

任務主控： EXECUTION_PLAN.md
目前細項： CURRENT_WORK_ITEMS.md
延後細修： DEFERRED_POLISH_BACKLOG.md