# 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 查詢依賴這些欄位。