fix release rollback guards and sync api docs

docs/CURRENT_WORK_ITEMS.md

@@ -95,20 +95,20 @@
 
 ### G. Code Review 待修（✅ 完成，2026-03-23）
 
-- [x] `P0` Release lifecycle 修正：`publish()` 先 unpublish 同實驗其他 published release，`rollback()` 設自身為 draft 並自動升版前一個 draft release。
+- [x] `P0` Release lifecycle 修正：`publish()` 先 unpublish 同實驗其他 published release，`rollback()` 會回退到較早版本。
 - [x] `P0` Editor preview API 契約對齊：前端 `buildPreview()` 改送 `items`（原為 `changes`），與 `BuildPreviewRequest.items` 一致。
 - [x] `P0` `save_changes()` 改為完整覆蓋語意：先刪除 DB 中不在 request items 的舊 change，再 upsert。
 - [x] `P1` 移除 `variant_changes.enabled`：`EditorChangeRead` / `EditorChangeWrite` schema 刪除欄位；frontend `editor-workspace-model.js` 同步清除。
 - [x] `P1` 建立 Experiment 時前端不再送 `experiment_key`（`ExperimentFormDialog` 移除 `autoFillKey`、`_auto_key`、`_generated_key`）。
 - [x] `P1` Runtime bootstrap 改為從 release snapshot 讀取 `traffic_weight` / `variant_key`，避免即時 variant 異動造成分流不一致。
 - [x] `P1` Editor bridge snippet `handleMessage` 加 `event.source === window.parent` 驗證；`EditorCanvasFrame` 捕捉 `event.origin` 並存入 `canvasOrigin`，postMessage 改用具體 targetOrigin（fallback `"*"`）。
-- [ ] `P1` Release rollback 邊界條件補強：限制只能 rollback `published` release，並在 rollback 流程最後再次保證同一 experiment 僅有一個 `published`。
+- [x] `P1` Release rollback 邊界條件補強：只允許 rollback `published` release，並在 publish/rollback 後保證同一 experiment 僅有一個 `published`。
 - [ ] `P2` 補自動化測試：Backend API 契約、Editor flow、Runtime targeting/assignment、Release lifecycle 回歸。
 - [ ] `P2` 文件狀態一致化：`ROADMAP`、`CURRENT_WORK_ITEMS`、`VALIDATION_EXECUTION_LOG` 的完成狀態同步。
 
 ## 系統狀態
 
-**Phase A–G 主線已完成（2026-03-23），目前剩餘：1 項 P1 邊界條件 + 2 項 P2 強化。**
+**Phase A–G 主線已完成（2026-03-23），目前剩餘：2 項 P2 強化。**
 
 目前系統可運作；P1/P2 完成後可進一步提高一致性與可回歸性。
 

docs/backend/API_CONTRACT_MASTER.md

@@ -15,6 +15,7 @@
 - `variant_changes` 移除 `enabled` 欄位（每筆 change 預設啟用）。
 - 建立 Experiment API 成功時，需同步建立一個原始版本 Variant（系統管理）。
 - Runtime 實驗匹配需基於 URL 規則與裝置限制。
+- Release rollback 僅允許針對 `published` 版本，且操作後需維持「每個 experiment 僅一個 published」。
 
 ## 分區
 

docs/backend/PYTHON_API_PARAMETER_GUIDE.md

@@ -201,8 +201,9 @@
 
 - Path 必填：`release_id`
 - 業務行為：
-  - 目標 release 先降為 `draft`
-  - 嘗試把同 experiment、版本號較小、最新的一筆 `draft` 升為 `published`
+  - 只允許 rollback 目前 `published` 的 release（否則 `409`）
+  - 會找同 experiment 中「版本號較小且非 archived」的最新 release 升為 `published`
+  - rollback 完成後，會強制同 experiment 僅保留一個 `published`
 
 ### `POST /api/admin/releases/{release_id}/archive`
 
@@ -379,6 +380,11 @@
 
 1. 同一 experiment 下，所有 variant 的 `traffic_weight` 加總不等於 `100`。
 
+### `rollback` 回 `409` 常見原因
+
+1. 你指定的 release 目前不是 `published`。
+2. 該 release 沒有更早的非 archived 版本可回退。
+
 ### `editor PUT changes` 看起來「少資料」的常見原因
 
 1. 你沒有把舊 change id 一起送回去，會被 full-replace 刪掉。