Guidant AI v1.9.0 Release Note

1. 概述

v1.9.0 是功能版號，涵蓋三個獨立功能案與一個效能批：

1. FR-050 稽核輪次階段回退：稽核流程推進後首次支援「有條件返回上一步」——manager 專屬 + reason 必填 + closed 不可退 + 不刪資料只作廢標記（superseded）+ UI 可見階段歷程時間軸。解決過去「按錯/需求變更只能整輪作廢重開專案」的痛點。
2. FR-049 / FR-049.1 問卷跳題模型：問卷流程規則（跳題）從無到有補齊，中途因 user 手測發現來源側 goto_* 模型有四項瑕疵（隱式副作用、漏網坑、零全局視圖、心智模型錯位），翻轉為目標側 display_condition（業界主流做法，Qualtrics/Typeform 同款）。FR-049.1 是上線模型，FR-049 的可見性計算引擎與稽核快照機制保留、跳題資料模型由 FR-049.1 取代。
3. 效能批1：GRC 專案列表兩組 per-row 查詢改 batch，SQL 數 -29%、回應時間 -31%；連帶補 4 顆 flow-engine 缺失 FK index。
4. P0 安全修復：FR-050 rollback 權限守門在特定反查鏈（round 主 workflow 的 job 不落 task_assignees）下 100% 誤擋非 admin manager，E2E 抓到後當日修復（c5fcb16b）。

版本定位 1.9.0（功能版號）：三個功能案對 user 皆有感（新增可操作能力/UI），依版號定義應 bump 功能版號，不落入 1.8.2 的 BUG 版號範疇。

2. 新功能

FR-050 稽核輪次階段回退（Stage Rollback）

• 三個回退邊界全開：audit_planning→planning／auditing→audit_planning／remediation→auditing（僅相鄰上一步，非任意跳轉）。
• manager 專屬 + reason 必填（DB CHECK 強制非空）；closed 輪次無回退入口。
• 回退時 SSP/AP/POA&M 不刪資料，改標記 superseded（新表 round_rollback_supersessions，本專案側機制，不動 jedi-oscal-v2 套件列舉）。
• 新表 round_stage_transitions：advance + rollback 皆落表，UI「階段歷程」時間軸資料源。
• 新增 4 個 error code：GRC_412046（狀態不允許回退）／GRC_400096（reason 必填）／GRC_412047（邊界不允許）／GRC_400097（handler 未註冊）。
• FE：FlowPhaseBanner 回退入口按鈕 + 階段歷程時間軸元件。
• P0 修復（c5fcb16b）：rollback 權限守門走 v2 反查鏈（workflow→job→task_assignees）取得 project_id，但 round 主 workflow 的 job 不落 task_assignees → 反查恆 None → 非 admin manager 100% 誤擋 403（admin 有旁路，手測假綠，E2E 非 admin 帳號才抓到）。修法：assert_project_participant/revert_job 加 known_project_id 參數，StageRollbackService 傳入已解析的 project_id 直接查角色跳過反查；既有呼叫點零行為變更。
• BE pytest 31 全綠；DEV 手測 6 項全過；E2E 未派工（design §6 六驗收情境中情境 1/2/6 需完整 live 資料流驗證，目前只做過 API/單元測試層級）。

FR-049 / FR-049.1 問卷跳題模型（目標側顯示條件）

• 規則掛在目標題目/題組本體 display_condition JSONB（{source_question_uid, answers:[option_key]}），取代來源選項宣告 goto_* 的舊模型；null/缺省=恆顯示，未作答=顯示、已作答才比對 answers 集合。
• 來源題型支援 radio + dropdown；子題不吃自身條件、顯示跟隨母題。
• Designer：條件 badge 全文化、來源題選項尾端反向提示、母題卡「+新增延伸題」直建入口（題號自動衍生）。
• 填答端：改答即時重算，選項尾端「＋將增加 N 題」提示。
• 稽核檢視端：checkpoint 落地時保存規則快照（question_answer_histories.flow_rules_snapshot），重算不適用/漏答時讀快照而非即時拉當前規則，避免「規則被事後改過」造成歷史畫面漂移；舊 goto 快照與 null 皆有 fallback。
• 刻意不列入 translatable_fields——與既有 jedi-common 可翻譯欄位失效 bug（docs/issues/pending/2026-07-18-jedi-common-translation-exclude-never-works.md）零耦合。
• jedi-survey 0.0.26 → 0.0.27 → 0.0.28（P0 snapshot 缺陷修復）→ 0.0.29（add_page @transaction 迴歸修復，0.0.28 即廢）。
• 測試：jedi-survey pytest 82 passed；BE 快照抽取 7 案；FE 引擎 15 案；E2E 已收案（test repo 902709c，designer 22/22、fill 27/27 全綠）。
• 已知子缺口（Notion 3a2346da-4cd0-8193-ab09-cb0df3c2c813，修正待驗證）：子題編輯 dialog 無顯示條件區與跳題精靈區，根因子題嵌套預覽區未掛點擊事件；已修（FE e424020d + c668c1d），待 STG 部署後隨 @known-bug 回歸轉綠。

3. 效能改善

• GRC 專案列表 N+1 消除批1（2302fe59）：participants 整頁 project_ids 一次 IN 查詢 + joinedload，消除二層 N+1；_inscope_counts 改 batch（SSP get_by_id_list 整批 + import_profile_id resolve 記憶體 cache）。
• 實測（DEV 真實端點）：SQL 238→169（-29%），回應 2.55s→1.77s（-31%），response JSON 零差異；get_projects_for_dashboard 同路徑自動受惠。
• 新增 4 顆 flow-engine 缺失 FK index（workflow_executions.template_id / job_executions.workflow_execution_id+main_workflow_execution_id / project_extensions.living_ssp_id）。
• 屬 follow-up 效能調查（600+ 專案量級劣化）的第一批，root cause 完整調查另案批2。

4. 其他

• 新增 GET /api/1.0/version endpoint（免認證，回 pyproject.toml 版本號，供部署驗證/監控使用）。
• FR-050 spec 勘誤：flow-phase-banner spec「狀態不在白名單」錯誤碼由 GRC_412046 更正為實際 GRC_412047（E2E worker 對碼發現）。

5. Breaking Changes / 契約變更

無。

6. DB Migration

4 支，皆 additive / nullable，非破壞性：

DEV / STG 皆已套（2026-07-19，指揮官執行，對帳綠）；POC 未套（累計缺 4 支，隨 POC 部署日補）。

7. 相依套件版本

已發布 Nexus。

8. 部署順序

1. BE：拉 code → poetry update（裝上 jedi-survey 0.0.29）→ 重啟（無 hot reload）
2. FE：部署對應版本（FlowPhaseBanner 回退入口 + 問卷 Designer/填答端 display_condition 引擎）
3. Migration：4 支依檔頭日期序執行（見 §6），cmmgr 帳號 --single-transaction
4. 部署後驗證：
   • FR-050：非 admin manager 執行三個回退邊界皆應成功（P0 修復重點，勿用 admin 帳號驗證會假綠）；closed 輪次無回退入口；reason 空應 400
   • FR-049.1：問卷 Designer 顯示條件區 + 跳題精靈雙入口；填答端改答即時重算；子題編輯 dialog 可開啟顯示條件區（@known-bug 收尾項）
   • site-regression 移除對應 @known-bug tag 回歸

9. 已知 follow-up

• FR-050 design §6 情境 1/2/6 需完整 live 端到端驗證（推進→回退→重推整輪資料流）
• FR-050 E2E 場景尚未派工（test repo 無對應 feature/step）
• FR-049.1 子題編輯入口缺口修正待 STG 部署後回歸轉綠
• POC migration 缺 4 支（隨 POC 部署日）
• 效能批2（root cause 完整調查：疑 N+1/缺 index/eventlet 序列化）
• jedi-common 可翻譯欄位排除邏輯 bug 修復（跳題模型已避開耦合，但 bug 本身待修）
• §4.4 superseded 標記表選項 A（動 jedi-oscal-v2 PublishStatus 列舉）暫無觸發跡象，目前維持選項 B

10. 相關文件索引

• FR-050：docs/features/FR-050-2607-stage-rollback/（design.md / implementation-plan.md / handoff SUMMARY）
• FR-049：docs/features/FR-049-2607-survey-flow-rules/
• FR-049.1：docs/features/FR-049.1-2607-survey-display-conditions/（design.md / implementation-plan.md / handoff SUMMARY）
• Spec 同步：docs/specs/v1.8.0/shared-components/flow-phase-banner.md（FR-050 回退功能全章節）
• FR 登記表：docs/features/README.md