first commit

docs/backend/EXPERIMENT_SYSTEM_SPEC.md

@@ -0,0 +1,77 @@
+# Experiment System Spec
+
+## 目標
+
+定義銷售實驗主線的最小可上線系統範圍（MVP）：
+
+- Experiment
+- Variant
+- Change Set
+- Release
+- Runtime delivery
+
+## 這輪規格調整（2026-03-22）
+
+1. 實驗匹配規則必須同時支援：
+- URL 規則（contains / equals / starts_with / regex）
+- 裝置限制（mobile / tablet / desktop）
+
+2. 建立 Experiment 時，自動建立一個「原始版本 Variant」：
+- 系統自動建立，不讓使用者手動調整該原始版本內容
+
+3. 移除 `is_control`：
+- 不再讓使用者手動指定對照組
+
+4. 移除 `variant_changes.enabled`：
+- 每筆 change 預設生效，不提供啟用/停用欄位
+
+5. key 全改為系統生成：
+- `experiment_key`：`EX+timestamp`
+- `variant_key`：`VA+timestamp`
+- 使用者不輸入 key
+
+6. Variant 簡化：
+- 不再有 `status`
+- 使用者建立/編輯 variant 只可調整 `name` 與 `traffic_weight`
+
+## 核心流程
+
+1. 建立 Experiment
+2. 系統自動建立原始版本 Variant（不可編輯內容）
+3. 建立其他 Variant（只編輯 name / traffic_weight）
+4. 在 Editor 編輯 Variant changes
+5. Build Release（產生 runtime payload）
+6. Publish / Rollback
+7. Runtime assign + payload 套用 + event 回傳
+
+## Experiment 管理
+
+- 列表、建立、編輯、狀態流轉（schedule / pause / resume / archive）
+- 支援 module_type 與 targeting_config
+- targeting_config 最少要包含 `url_rules` 與 `device_targets`
+
+## Variant 管理
+
+- 列表、建立、編輯、刪除
+- 使用者可調整：`name`、`traffic_weight`
+- 系統管理欄位：`variant_key`
+- 不提供 `status`、`is_control`
+- change set 可讀可寫（不含 enabled 開關）
+
+## Release 管理
+
+- build：由 variant_changes 聚合 payload
+- publish：將 release 生效
+- rollback：回到前一可用 release
+
+## Assignment 規則
+
+- 以 stable seed 決定 bucket
+- bucket 對映 variant weight
+- assignment 結果需可追蹤
+
+## 第一版成功標準
+
+- 後台可完成「建立實驗 -> 建立變體 -> 編輯 -> build -> publish」
+- runtime 可正確回傳 assignment 與 payload
+- rollback 可恢復上一版本