diff --git a/ROADMAP.md b/ROADMAP.md index a49e168..1908898 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,7 +2,7 @@ ## 現在位置 -➡️ **Phase A–E 主線完成（2026-03-23）。** 系統已通過 Staging 真實環境驗證並可運作，尚有少量 hardening（rollback 邊界條件、自動化測試）持續補強。 +➡️ **Phase A–E 主線完成（2026-03-23）。** 系統已通過 Staging 真實環境驗證並可運作，尚有少量 hardening（自動化測試、驗證流程一致化）持續補強。 ## 本輪規格重置 diff --git a/backend/app/application/admin/releases.py b/backend/app/application/admin/releases.py index 7eeeb01..ff9918b 100644 --- a/backend/app/application/admin/releases.py +++ b/backend/app/application/admin/releases.py @@ -3,6 +3,8 @@ from __future__ import annotations from dataclasses import asdict from typing import Any +from fastapi import HTTPException + from app.domain.editor import VariantChange from app.domain.editor_builder import build_runtime_payload_from_changes from app.domain.mappers import to_release @@ -25,6 +27,24 @@ class ReleaseService: self.variant_repository = variant_repository or VariantRepository() self.change_repository = change_repository or VariantChangeRepository() + async def _enforce_single_published( + self, + experiment_id: str, + keep_release_id: str, + access_token: str | None = None, + ) -> None: + published_items = await self.repository.list( + params={ + "filter[experiment_id][_eq]": experiment_id, + "filter[status][_eq]": "published", + }, + access_token=access_token, + ) + for item in published_items: + item_id = str(item["id"]) + if item_id != keep_release_id: + await self.repository.update(item_id, {"status": "draft"}, access_token=access_token) + async def list_releases( self, experiment_id: str | None = None, @@ -118,21 +138,14 @@ class ReleaseService: experiment_id = str(target["experiment_id"]) - # Demote any currently published release in this experiment to draft - currently_published = await self.repository.list( - params={ - "filter[experiment_id][_eq]": experiment_id, - "filter[status][_eq]": "published", - }, - access_token=access_token, - ) - for other in currently_published: - if str(other["id"]) != release_id: - await self.repository.update(str(other["id"]), {"status": "draft"}, access_token=access_token) - item = await self.repository.update(release_id, {"status": "published"}, access_token=access_token) if not item: return None + await self._enforce_single_published( + experiment_id=experiment_id, + keep_release_id=release_id, + access_token=access_token, + ) return ReleaseLifecycleResponse( id=str(item["id"]), status=str(item["status"]), @@ -150,44 +163,56 @@ class ReleaseService: return None experiment_id = str(target["experiment_id"]) + target_status = str(target.get("status", "")) + if target_status != "published": + raise HTTPException( + status_code=409, + detail=f"Release '{release_id}' is not published; rollback is only allowed for published releases.", + ) + current_version_no = int(target["version_no"]) - # Demote the current release back to draft - await self.repository.update(release_id, {"status": "draft"}, access_token=access_token) - - # Find the most recent draft release with an earlier version_no to restore + # Find the most recent non-archived release with an earlier version_no to restore. previous_candidates = await self.repository.list( params={ "filter[experiment_id][_eq]": experiment_id, - "filter[status][_eq]": "draft", "filter[version_no][_lt]": str(current_version_no), + "filter[status][_neq]": "archived", "sort": "-version_no", "limit": "1", }, access_token=access_token, ) - if previous_candidates: - restored = await self.repository.update( - str(previous_candidates[0]["id"]), - {"status": "published"}, - access_token=access_token, + if not previous_candidates: + raise HTTPException( + status_code=409, + detail=f"Release '{release_id}' cannot rollback because no earlier non-archived release exists.", ) - if restored: - return ReleaseLifecycleResponse( - id=str(restored["id"]), - status=str(restored["status"]), - version_no=int(restored["version_no"]), - ) - # No previous release to restore — return the now-drafted current release - updated = await self.repository.get(release_id, access_token=access_token) - if not updated: - return None + # Demote current published release, then promote previous release. + await self.repository.update(release_id, {"status": "draft"}, access_token=access_token) + restored_id = str(previous_candidates[0]["id"]) + restored = await self.repository.update( + restored_id, + {"status": "published"}, + access_token=access_token, + ) + if not restored: + raise HTTPException( + status_code=500, + detail="Rollback failed while promoting the target previous release.", + ) + + await self._enforce_single_published( + experiment_id=experiment_id, + keep_release_id=restored_id, + access_token=access_token, + ) return ReleaseLifecycleResponse( - id=str(updated["id"]), - status=str(updated["status"]), - version_no=int(updated["version_no"]), + id=str(restored["id"]), + status=str(restored["status"]), + version_no=int(restored["version_no"]), ) async def archive_release( diff --git a/docs/CURRENT_WORK_ITEMS.md b/docs/CURRENT_WORK_ITEMS.md index e880732..afc9a9e 100644 --- a/docs/CURRENT_WORK_ITEMS.md +++ b/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 完成後可進一步提高一致性與可回歸性。 diff --git a/docs/backend/API_CONTRACT_MASTER.md b/docs/backend/API_CONTRACT_MASTER.md index 0549b79..1d8056c 100644 --- a/docs/backend/API_CONTRACT_MASTER.md +++ b/docs/backend/API_CONTRACT_MASTER.md @@ -15,6 +15,7 @@ - `variant_changes` 移除 `enabled` 欄位（每筆 change 預設啟用）。 - 建立 Experiment API 成功時，需同步建立一個原始版本 Variant（系統管理）。 - Runtime 實驗匹配需基於 URL 規則與裝置限制。 +- Release rollback 僅允許針對 `published` 版本，且操作後需維持「每個 experiment 僅一個 published」。 ## 分區 diff --git a/docs/backend/PYTHON_API_PARAMETER_GUIDE.md b/docs/backend/PYTHON_API_PARAMETER_GUIDE.md index f6ed170..9979700 100644 --- a/docs/backend/PYTHON_API_PARAMETER_GUIDE.md +++ b/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 刪掉。