first commit

docs/MIGRATION_NOTE.md

@@ -0,0 +1,75 @@
+# Migration Note — 規格重置欄位相容說明
+
+## 適用版本
+
+規格重置：2026-03-22（詳見 `CURRENT_WORK_ITEMS.md` 第二節）
+
+---
+
+## 移除的欄位與相容策略
+
+### 1. `variants.is_control`
+
+**舊行為**：每個 Experiment 有一個 `is_control=true` 的變體代表控制組。
+
+**新行為**：建立 Experiment 時自動建立第一個 Variant（命名為「原始版本」），無任何特殊角色標記。所有 Variant 地位平等，由流量權重決定分配比例。
+
+**相容策略**：
+- Backend `domain/admin.py` `Variant` dataclass 已移除 `is_control` 欄位。
+- `schemas/admin.py` `VariantRead` / `VariantCreate` / `VariantUpdate` 均已移除。
+- `repositories/directus/variants.py` `default_fields` 已移除 `is_control`。
+- `application/runtime/assignment.py` 已移除所有 `is_control=variant.is_control` 引用。
+- **Directus 欄位本身**：可保留在 DB schema 中，不影響新流程；若需清除可在 Directus 後台刪除 `variants.is_control` 欄位。
+
+---
+
+### 2. `variants.status`
+
+**舊行為**：Variant 有獨立 `status`（draft / active / archived）。
+
+**新行為**：Variant 無 status。生命週期完全由上層 Experiment `status` 控制。使用者只編輯 `name` 與 `traffic_weight`。
+
+**相容策略**：
+- Backend `domain/admin.py` 已移除 `Variant.status`。
+- `repositories/directus/variants.py` `default_fields` 已移除 `status`。
+- Frontend `variant-view-model.js` 已移除 `status` / `buildVariantStatusTag`。
+- **Directus 欄位**：`variants.status` 欄位在 DB 中仍存在，可安全保留；不再被讀取或寫入。
+
+---
+
+### 3. `variant_changes.enabled`
+
+**舊行為**：每筆 VariantChange 有 `enabled` 布林值，`False` 表示該筆修改暫時停用，不進入 runtime payload。
+
+**新行為**：`enabled` 欄位移除。所有在 `PUT /api/editor/variants/{id}/changes` 的 changes 均視為有效；不需要的修改直接刪除即可。
+
+**相容策略**：
+- Backend `domain/editor_builder.py` 已移除 `enabled` 過濾邏輯。
+- `schemas/editor.py` `EditorChangeRead` / `EditorChangeWrite` 已移除 `enabled` 欄位。
+- Frontend `editor-workspace-model.js` 已移除所有 `enabled: true` 殘留。
+- **Directus 欄位**：`variant_changes.enabled` 欄位在 DB 中仍存在，可安全保留；不再被讀取或寫入。若 Directus repo 的 `default_fields` 仍包含 `enabled`，需確認已移除（已於 2026-03-22 修正）。
+
+---
+
+## 新增行為（對應舊欄位的補充）
+
+| 舊欄位 | 替代機制 |
+|--------|---------|
+| `variants.is_control` | 建立 Experiment 時自動建立原始 Variant，`name="原始版本"` |
+| `variants.status` | Experiment `status` 控制整體啟停，Variant 無獨立生命週期 |
+| `variant_changes.enabled` | `PUT /api/editor/variants/{id}/changes` 改為完整覆蓋語意（刪除不在 request 中的舊 change） |
+
+---
+
+## Directus DB 清理建議（選擇性）
+
+若需徹底清理 DB schema，可在 Directus 後台或 migration script 執行：
+
+```sql
+-- 可選，不影響系統運作
+ALTER TABLE variants DROP COLUMN IF EXISTS is_control;
+ALTER TABLE variants DROP COLUMN IF EXISTS status;
+ALTER TABLE variant_changes DROP COLUMN IF EXISTS enabled;
+```
+
+**注意**：執行前確認沒有其他服務或直接 SQL 查詢依賴這些欄位。