FR-049.1 問卷顯示條件（目標側重構）Implementation Plan

母案：FR-049（來源側 goto，四段已 commit 未部署——jedi-survey 4e9cd41 / FE 5d73876 / BE checkpoint 快照）。本案是資料模型翻轉：跳題規則從「來源選項宣告目的地（goto_*）」改為「目標題目/題組宣告顯示條件（display_condition）」。 設計真相：docs/features/FR-049.1-2607-survey-display-conditions/design.md（§2 六決策全拍板，不重開）。 狀態：plan 待 review（階段一）。核准後才進實作（階段二）。 For agentic workers: 逐 Task 做；jedi-survey 驗證邏輯 TDD 先測後碼；migration 寫好【先不套】，套用時機回報指揮官。

Goal: 把 FR-049 的來源側 goto 模型翻成目標側 display_condition：BE（jedi-survey）加 display_condition 欄位（刻意排除 translatable_fields，繞開 jedi-common 翻譯 bug）+ 驗證/清理改對象 → Designer 目標側「顯示條件」UI + 子題入口重構（決策 2/3）+ mapper 改鍵 → 填答端 computeVisibility 換輸入形狀 → 稽核檢視端快照換內容。FR-049 骨架（可見性引擎雙函數、快照機制全鏈、三消費點同源架構、子題 pid 接線）保留換輸入（design §5 delta 不 revert）。

Architecture: display_condition 是題目/題組級屬性（非選項級），落 SurveyQuestion / SurveyPage 本體各一個新 JSONB 欄位（需 migration）。填答端沿用單一純函數，語意翻轉為「掃全部目標的 display_condition，判斷每個目標當下該不該顯示」——比 goto 起訖區間演算法更簡單、無 OR 合併爭議。

Tech Stack: Python（jedi-survey path dependency dev loop，目前已是 path 狀態，symlink 已驗）/ Vue 3 + PrimeVue / pytest / Cucumber+Playwright（E2E 另派）。

逐項對 jedi-survey / jedi-common / FE / BE 原始碼 + DEV DB 實查。

a. display_condition 落欄位 + translatable_fields 家族檢查 ✅ 決定：新增專用欄位、刻意排除 translatable_fields

• 無現成雜項欄可掛：SurveyQuestion（jedi_survey/infra/models/survey_question.py）JSONB 欄位只有 options / tags / references，皆有既定語意，不可借掛。SurveyPage（.../survey_page.py）連 JSONB 欄位都沒有（只有 name / description / sort / no）。→ 兩表各需新增一個 display_condition JSONB 欄位（migration）。
• translatable_fields 家族檢查（design §3.2 硬性要求）：
  • SurveyQuestion 的可翻譯欄位 = ['question', 'description', 'options']（survey_question_repo_impl.py:36 _setup_translation + survey_question_mapper.py:12）。
  • SurveyPage 的可翻譯欄位 = ['name', 'description']（survey_page_repo_impl.py + survey_page_mapper.py:12）。
• 決定性查證 — 只要 display_condition 不進 translatable_fields，就完全繞開 jedi-common bug：直讀 jedi-common _get_failover_query()（base_repository_impl.py:642-690）——failover 讀取對非可翻譯欄位走 load_only（直接讀主表原值），只有可翻譯欄位才套 coalesce(trans.col, main.col)。而寫入端 bug（base_repository_impl.py:628-633 的 field not in self._translatable_fields 型別誤判）造成「所有欄位都被當非可翻譯、無條件寫回主表」——對一個本來就非可翻譯的欄位而言，「無條件寫回主表」正是我們要的正確行為。
  • 結論：display_condition 不加入 translatable_fields。讀（load_only 讀主表）、寫（主表）雙路徑都乾淨落主表，與 docs/issues/pending/2026-07-18-jedi-common-translation-exclude-never-works.md 的 bug 零耦合——不像 FR-049 的 goto（掛在可翻譯的 options 內、正確性依賴 bug 副作用）。這是目標側模型比來源側模型在工程上更乾淨的附帶收益。
  • 反面確認：若誤把 display_condition 塞進 options（沿用 FR-049 落點）就會重新踩進翻譯家族耦合——故 design §3.2「落 SurveyQuestion 本體」的裁決在此得到工程佐證，照辦。

b. FR-049 已 commit 的 goto 驗證/清理 hook/mapper 現況座標 ✅（退役/改造精確定位）

jedi-survey（commit 4e9cd41）： | 資產 | 座標 | FR-049.1 處置 | |------|------|--------------| | _validate_flow_rules 方法 | survey_question_domain_service.py:123-157 | 重做→ _validate_display_condition（驗對象換成 display_condition） | | 驗證呼叫點 | 同檔 :100（add_question）、:118（update_question） | 換呼叫新方法 | | _cleanup_goto_question_refs | 同檔 :173-186 | 重做→ 清理「引用被刪題的 display_condition」（含 page 表） | | delete_question 清理呼叫 | 同檔 :168 | 換呼叫新清理 | | _cleanup_goto_page_refs | survey_page_domain_service.py:291-311 | 退役（display_condition source 只會是 question，page 不當 source，刪 page 無「引用它的規則」要清） | | delete_page 清理呼叫 | 同檔 :285 | 刪除該行 | | error codes | common/enum/error_code.py:27-30（SURVEY_409010~013 FLOW_RULE 系列） | 重做→ DISPLAY_CONDITION 系列（沿用 409010~013 序號，改語意） | | goto 驗證/清理 14 測試 | tests/unittest/domain/service/test_survey_question_domain_service.py:533-668 + test_survey_page_domain_service.py:412 | 退役，改寫 display_condition 對應測試 |

FE（commit 5d73876）： | 資產 | 座標 | 處置 | |------|------|------| | options goto 鍵映射 | survey-mapper.js:122-123（from）:217-218（to） | 退役（改 question/page 級 displayCondition 映射） | | flow rules 編輯 UI | AddQuestionDialog.vue:418-463（step3 流程規則區） | 退役，換「顯示條件」區 | | 父題目下拉 | 同檔 :401-407 + parentQuestionOptions:166 + form.parentId | 退役（決策 3，改母題卡「+新增延伸題」入口） | | flowRules 組裝 | 同檔 onSubmit:223-246 addFlowRule:110 removeFlowRule:121 canSetFlowRules:80 | 退役 | | flow rules 卡片預覽 | SurveyDesigner.vue:811-821 | 重做→ 條件顯示 badge | | hydrateFlowRules | SurveyDesigner.vue（grep hydrateFlowRules 定位，含 :91 gotoPageUids 反查） | 退役（display_condition 直接掛題目/題組，無需 hydrate 重組 label） | | goto 透傳 | useSurveyApi.js createQuestion/updateQuestionApi options map（goto 鍵） | 退役，改 display_condition 透傳 | | extractRulesFromQuestions / extractRulesFromSnapshot | useSurveyVisibility.js:14-53 | 重做（換掃 display_condition） | | computeVisibilityFromRules 核心 | 同檔 :59-138（goto 起訖區間 + OR 合併） | 重做（目標側逐目標判斷，演算法簡化） |

BE checkpoint： _extract_flow_rules_snapshot（app/task_survey/service/question_answer_service.py:32-62）重做→ 抽 display_condition 快照。

c. computeVisibility / computeVisibilityFromSnapshot 現行輸入形狀 ✅

• computeVisibility(allQuestions, allPages, answers)（useSurveyVisibility.js:141）→ extractRulesFromQuestions 掃 question.options[].gotoQuestionUid/gotoPageUids。
• computeVisibilityFromSnapshot(flowRulesSnapshot, allQuestions, allPages, answers)（:152）→ extractRulesFromSnapshot 掃 [{source_question_uid, options:[{option_key, goto_question_uid, goto_page_uids}]}]。
• 兩者共用 computeVisibilityFromRules（:59）產出 {visibleQuestionIds, visiblePageIds, hiddenReasons}。
• 消費點（SurveyPreview.vue）全部只吃輸出的三個集合，未直接碰規則形狀：visibility（:570）/auditVisibility（:594）/totalRequired（:654）/answeredCount（:659）/progress/currentQuestions（:633）/allPagesFlat（:624）/progressItems（:674）/onSave 必填（:827）/hiddenReasons 文案（:611）。
• 改動面：只需改 useSurveyVisibility.js 兩個 extract 函式 + core 演算法；SurveyPreview.vue 消費點幾乎零改（輸出契約不變），唯一新增：allPages 需帶 displayCondition 欄位（目前 allPagesRaw 只 flatten，未帶 display_condition，Task 3-2 補）。

d. Designer 列表子題現況（design §4.1 稱「1-1-1 仍平級」）✅ 根因定位

• BE 讀取路徑巢狀正確：ORM SurveyPage.questions relationship primaryjoin 帶 SurveyQuestion.pid == None（只回根題），根題的 sub_questions relationship 自動載入子題；serializer SurveyPageResponse.questions（api/survey/serializers/survey_page.py:42）+ SurveyQuestionResponse.sub_questions（survey_question.py:58）巢狀 dump。DEV 實查有真實子題資料（survey_id=360 有 206 筆 pid≠null）。
• FE 讀取路徑巢狀正確：survey-mapper.js:106 subQuestions: (q.sub_questions||[]).map(...)；SurveyDesigner.vue:828-843 有子題嵌套 render（縮排 + 左邊框）。
• 根因：不是讀取漏視圖，是建立後本地狀態平推——onQuestionSubmit/onCopyQuestion 建立成功後直接 selectedPage.value.questions.push(q)（如 :530），把新題（含子題）平推進根層 questions 陣列，沒依 pid 掛回母題的 subQuestions，畫面立即出現一張平級卡片；要重整（重走巢狀讀取路徑）才會正確。決策 3 把子題入口改成「母題卡 +新增延伸題」後，建立成功的本地插入需改為 push 進母題的 subQuestions（而非根 questions），此 bug 一併修掉。
• 驗證方式：實作 Task 2-x 後，FE dev server 起 → Designer 母題卡「+新增延伸題」建子題 → 不重整即應嵌套顯示（非平級）；再重整確認一致。（需 FE runtime，服務 user 起。）

e. checkpoint / revert 快照抽取現況 ✅

• 抽取函式：_extract_flow_rules_snapshot(questions)（question_answer_service.py:32-62）——掃 question.options[].goto_*，產 [{source_question_uid, options:[{option_key, goto_question_uid, goto_page_uids}]}]。只吃 questions，不吃 pages（goto 掛在 option 上，pages 無 goto）。→ 重做：display_condition 掛在 question 與 page 本體，新抽取需同時掃兩者（checkpoint 目前只 get_questions()，需補載 pages，見 Task 4-1）。
• 落地：checkpoint 每筆 history 落 flow_rules_snapshot（:339）。
• 欄位：survey.question_answer_histories.flow_rules_snapshot（jsonb, nullable）——DEV 已存在（本 session psql 實查確認），migration scripts/sql/2026-07-18-fr049-flow-rules-snapshot.sql 已套 DEV。照 design §3.3 沿用不回滾、不改欄名，只換 JSONB 內容形狀。
• revert 繼承：question_answer_history_service.py:110 建 revert 複本時 flow_rules_snapshot=answer_history.flow_rules_snapshot 繼承目標快照——行為不變（機制與內容無關）。
• snapshot 消費：SurveyPreview.vue:586 讀 target.flow_rules_snapshot → computeVisibilityFromSnapshot。內容形狀改變後，extractRulesFromSnapshot 同步改（Task 4-2）。

1.1 依賴順序（四段鏈，沿母案形態；每段驗證後才進下一段）

段① jedi-survey BE（欄位+migration+驗證+清理）
        ↓  Designer 依賴 BE 能存 display_condition
段② Designer（顯示條件 UI + 子題入口重構 + mapper 改鍵）
        ↓  填答端依賴 Designer 能正確寫入 display_condition
段③ 填答端（computeVisibility 換輸入）
        ↓  稽核端依賴 checkpoint 落新形狀快照
段④ 稽核檢視端（snapshot 內容換 + computeVisibilityFromSnapshot 換輸入）

1.2 退役清單（退役 = 刪碼，不留死碼）

• jedi-survey：_validate_flow_rules 全 goto 邏輯、_cleanup_goto_page_refs 整個方法、goto 14 測試、FLOW_RULE error code 文案（序號沿用改語意）。
• FE：AddQuestionDialog 流程規則區 + 父題目下拉、SurveyDesigner flow rules 預覽 + hydrateFlowRules、mapper goto 鍵映射、useSurveyApi goto 透傳、useSurveyVisibility 舊 extract + goto 起訖演算法。
• BE：_extract_flow_rules_snapshot goto 抽取邏輯。

1.3 Not-in-scope（design §7 backlog + 本次界定）

• 跳題精靈（來源題快捷設定自動翻譯成中間題條件）——backlog。
• 多來源/複合條件（AND/OR 跨題）、非單選來源題型、跨問卷——BE 驗證直接擋。
• goto_* 舊鍵：不讀不寫（新引擎只認 display_condition）；DEV 上 FR-049 測試期可能殘留的 goto 鍵成為 inert 死鍵，不遷移不清理（design §3.1）。
• Excel 匯入（import_survey）不支援 display_condition，匯入問卷無條件、可後續 Designer 補設。
• E2E：舊 goto 場景止損（另派 session 重寫，本 plan 只列範圍 §7）。

環境：jedi-survey path dependency（已是 path 狀態、symlink 已驗，不需重切）。

Task 1-1: display_condition 欄位落地（model + entity + mapper，排除 translatable_fields）

Files（jedi-survey）:

• Modify: jedi_survey/infra/models/survey_question.py（加 display_condition JSONB 欄）
• Modify: jedi_survey/infra/models/survey_page.py（加 display_condition JSONB 欄）
• Modify: jedi_survey/domain/entities/survey_question_entity.py（__init__ 加 display_condition=None + self.display_condition）
• Modify: jedi_survey/domain/entities/survey_page_entity.py（同）
• Modify: jedi_survey/infra/mapper/survey_question_mapper.py（to_entity 加 display_condition=survey_question.display_condition；translatable_fields 不動）
• Modify: jedi_survey/infra/mapper/survey_page_mapper.py（同）

• Step 1: 兩個 model 各加：

display_condition: Mapped[Optional[Any]] = mapped_column(
    JSONB, nullable=True,
    comment="顯示條件（FR-049.1）：{source_question_uid, answers:[option_key]}；null=恆顯示"
)

• Step 2: 兩個 entity __init__ 加參數 display_condition=None 與 self.display_condition = display_condition。
• Step 3: 兩個 mapper to_entity 補 display_condition=...。確認 translatable_fields 未加入 display_condition（前提查證 a 的核心，繞開翻譯 bug）。
• Step 4: 反查 repo _setup_translation 的 translatable_fields 清單，確認未含 display_condition（question=['question','description','options']、page=['name','description'] 維持原樣）。

驗證方式：python3 -c "import jedi_survey; from jedi_survey.infra.models.survey_question import SurveyQuestion; print('display_condition' in SurveyQuestion.__table__.columns)" → True。

Task 1-2: Migration（2 新欄位，寫好先不套）

Files:

• Create: scripts/sql/2026-07-18-fr0491-display-condition.sql（主專案）

• Step 1: 照 sql-migration skill 鐵則寫（檔頭 -- Date:、每語句日期註解、additive nullable 欄不需 re-GRANT、INSERT public.schema_migrations、ON CONFLICT DO NOTHING）：

-- Date: 2026-07-18
-- FR-049.1 問卷顯示條件（目標側）—— 題目/題組各加 display_condition JSONB
-- 語意：{source_question_uid, answers:[option_key]}；null=恆顯示。刻意不列入 translatable_fields，
-- 讀寫走主表、與 jedi-common 翻譯 bug 零耦合（見 implementation-plan §0-a）。
-- Run with: psql --single-transaction -v ON_ERROR_STOP=1 -f <file>  (account: cmmgr)

ALTER TABLE survey.survey_questions
  ADD COLUMN IF NOT EXISTS display_condition JSONB NULL; -- 2026-07-18
COMMENT ON COLUMN survey.survey_questions.display_condition IS
  'FR-049.1 顯示條件：{source_question_uid, answers:[option_key]}；null=恆顯示'; -- 2026-07-18

ALTER TABLE survey.survey_pages
  ADD COLUMN IF NOT EXISTS display_condition JSONB NULL; -- 2026-07-18
COMMENT ON COLUMN survey.survey_pages.display_condition IS
  'FR-049.1 顯示條件：{source_question_uid, answers:[option_key]}；null=恆顯示'; -- 2026-07-18

INSERT INTO public.schema_migrations(filename, note) VALUES
  ('2026-07-18-fr0491-display-condition.sql',
   'FR-049.1 / add display_condition to survey.survey_questions + survey.survey_pages（目標側顯示條件）')
ON CONFLICT (filename) DO NOTHING; -- 2026-07-18

• Step 2: 不套用。寫好後回報指揮官套用時機（DEV 先套才能手測段①之後）。⚠️ 硬規則：任何 DB 寫入先報再動。

Task 1-3: display_condition 驗證邏輯（TDD 先測後碼）

Files:

• Modify: jedi_survey/domain/service/survey_question_domain_service.py（_validate_display_condition 取代 _validate_flow_rules）
• Modify: jedi_survey/domain/service/survey_page_domain_service.py（page 也要驗 display_condition）
• Modify: jedi_survey/common/enum/error_code.py（FLOW_RULE 系列改 DISPLAY_CONDITION）
• Test: tests/unittest/domain/service/test_survey_question_domain_service.py + test_survey_page_domain_service.py

驗證規則（design §3.1 v1 範圍）：

1. display_condition 存在 → 必含 source_question_uid（str）+ answers（非空 list），否則 malformed 擋。
2. source_question_uid 必須存在、同問卷、type=='radio'（單選來源限定）。
3. question 級：source 不可指向自己（禁自指）；page 級無自指問題（source 恆為 question）。

• Step 1（先寫失敗測試，退役舊 goto 測試）：刪 :533-668 goto 測試，新增：

def test_question_rejects_display_condition_non_radio_source(...):
    """source 指向非單選題 → SURVEY_DISPLAY_CONDITION_SOURCE_NOT_RADIO"""
def test_question_rejects_display_condition_self_reference(...):
    """source 指向自己 → SURVEY_DISPLAY_CONDITION_SELF_REFERENCE"""
def test_question_rejects_display_condition_source_not_found(...):
    """source uid 不存在 → SURVEY_DISPLAY_CONDITION_SOURCE_NOT_FOUND"""
def test_question_rejects_display_condition_cross_survey(...):
    """source 在別份問卷 → SURVEY_DISPLAY_CONDITION_CROSS_SURVEY"""
def test_question_rejects_display_condition_malformed(...):
    """缺 source_question_uid 或 answers 空 → SURVEY_DISPLAY_CONDITION_MALFORMED"""
def test_question_allows_valid_display_condition(...):
    """合法（radio source、同問卷、answers 非空）→ 通過"""
def test_question_no_display_condition_unaffected(...):
    """display_condition=None → 零影響（驗收情境對照 design §6-1 未作答全可見前置）"""
def test_page_rejects_display_condition_non_radio_source(...):  # page 版
def test_page_allows_valid_display_condition(...):              # page 版

• Step 2: 跑測試確認 FAIL（新方法未實作）。
• Step 3: error_code：FLOW_RULE 四碼改語意（沿 409010~013 序號）+ 補一碼：

SURVEY_DISPLAY_CONDITION_SOURCE_NOT_RADIO = ("顯示條件的來源題必須是單選題", "SURVEY_409010")
SURVEY_DISPLAY_CONDITION_SELF_REFERENCE = ("顯示條件的來源題不可是自己", "SURVEY_409011")
SURVEY_DISPLAY_CONDITION_SOURCE_NOT_FOUND = ("顯示條件的來源題不存在", "SURVEY_409012")
SURVEY_DISPLAY_CONDITION_CROSS_SURVEY = ("顯示條件的來源題必須與本題屬於同一份問卷", "SURVEY_409013")
SURVEY_DISPLAY_CONDITION_MALFORMED = ("顯示條件格式錯誤（缺來源題或答案清單為空）", "SURVEY_400001")  # 序號接既有 400 系列

• Step 4: 實作共用驗證（question domain service，page domain service 呼叫同語意但略過自指）：

def _validate_display_condition(self, entity, is_question: bool, locale: str = None):
    dc = entity.display_condition
    if not dc:
        return
    source_uid = dc.get("source_question_uid")
    answers = dc.get("answers")
    if not source_uid or not isinstance(answers, list) or len(answers) == 0:
        raise BadRequestError(ErrorCode.SURVEY_DISPLAY_CONDITION_MALFORMED)
    if is_question and source_uid == entity.uid:
        raise ConflictError(ErrorCode.SURVEY_DISPLAY_CONDITION_SELF_REFERENCE)
    source = self.survey_question_repo.get_by_uid(source_uid, locale)
    if source is None:
        raise ConflictError(ErrorCode.SURVEY_DISPLAY_CONDITION_SOURCE_NOT_FOUND)
    if source.survey_id != entity.survey_id:
        raise ConflictError(ErrorCode.SURVEY_DISPLAY_CONDITION_CROSS_SURVEY)
    if source.type != "radio":
        raise ConflictError(ErrorCode.SURVEY_DISPLAY_CONDITION_SOURCE_NOT_RADIO)

在 add_question/update_question（:100/:118 改呼叫）與 add_page/update_page 呼叫（page domain service 需能取 survey_question_repo——查證 _cleanup_goto_page_refs 已在用 self.survey_question_repo，代表已注入，可直接用）。

• Step 5: 跑測試確認 PASS。

Task 1-4: 刪來源題連動清理 display_condition（重做 §0-e 清理）

Files:

• Modify: jedi_survey/domain/service/survey_question_domain_service.py（_cleanup_goto_question_refs → _cleanup_display_condition_refs，掃 question 與 page 兩表）
• Modify: jedi_survey/domain/service/survey_page_domain_service.py（刪 _cleanup_goto_page_refs:291-311 + delete_page 呼叫 :285——page 非 source 無需清理）
• Test: 對應兩 test 檔

• Step 1（先寫失敗測試）：

def test_delete_question_clears_display_condition_on_questions_and_pages(...):
    """刪來源題 → 引用它的 question.display_condition 與 page.display_condition 皆被清空（限同問卷）"""
def test_delete_page_no_display_condition_cleanup_needed(...):
    """刪 page 不觸發 display_condition 清理（page 非 source）——回歸確認 _cleanup_goto_page_refs 已退役"""

• Step 2: 跑確認 FAIL。
• Step 3: 實作 delete_question 清理（:168 換呼叫）：

def _cleanup_display_condition_refs(self, deleted_uid, survey_id, locale=None):
    # 掃同問卷所有題目
    for q in self.survey_question_repo.get_all_by_fields(
            SurveyQuestionQueryEntity(survey_id=survey_id), locale):
        dc = q.display_condition
        if dc and dc.get("source_question_uid") == deleted_uid:
            q.display_condition = None
            self.survey_question_repo.update(q, locale)
    # 掃同問卷所有題組（需注入 survey_page_repo；查證已有 self.survey_page_repo）
    for p in self.survey_page_repo.get_all_by_fields(
            SurveyPageQueryEntity(survey_id=survey_id), locale):
        dc = p.display_condition
        if dc and dc.get("source_question_uid") == deleted_uid:
            p.display_condition = None
            self.survey_page_repo.update(p, locale)

• Step 4: 刪 survey_page_domain_service.py 的 _cleanup_goto_page_refs（:291-311）與 delete_page 的呼叫行（:285）。
• Step 5: 跑確認 PASS。
• Step 6（來源題改題型的清理，design §4.1「來源題改為其他題型 → 同樣清空」）：update_question 內若偵測 type 由 radio 改為非 radio，對「引用本題的 display_condition」做同款清理。查證 update_question 目前 verify_question_exist_by_uid 已載入 existing，可比對 existing.type == 'radio' and new.type != 'radio' 觸發 _cleanup_display_condition_refs(question_entity.uid, survey_id, locale)。補測試 test_change_source_type_from_radio_clears_referencing_conditions。

Task 1-5: BE serializer 透傳 display_condition

Files（主專案）:

• Modify: api/survey/serializers/survey_question.py（Create/Update Request + Response 加 display_condition = fields.Raw(allow_none=True, load_default=None)）
• Modify: api/survey/serializers/survey_page.py（同）

• Step 1: SurveyQuestionCreateRequest / SurveyQuestionUpdateRequest / SurveyQuestionResponse 各加 display_condition。
• Step 2: SurveyPageResponse + page 的 Create/Update Request 同加。
• Step 3: 確認全問卷整棵樹 PUT（api/survey/serializers/survey.py 的 pages = fields.List(fields.Dict()) + questions 開放 dict）passthrough——查證 FR-049 已驗開放 dict 原樣通過，display_condition 走整樹 PUT 不需改 survey.py。但 route 組 entity 時需確認 SurveyQuestionEntity(**question) / SurveyPageEntity(**page) 能吃 display_condition key（Task 1-1 已加 entity 參數，✅）。

Task 1-6: 段① 全測試 + commit（jedi-survey repo）

• Step 1: cd ~/Projects/Jedicogy/module/jedi-python-package/jedi-survey && pytest tests/unittest/domain/service/ -v → 全綠（新 display_condition 測試通過、既有非 goto 測試不受影響）。
• Step 2: 顯式 git add（列出檔案，不用 -am），commit（等指揮官驗收後才 commit——依紀律，本 plan 不預先 commit）。

⚠️ 段① 驗證需 DEV 套 migration + 重啟 BE：Task 1-2 migration 套用時機回報指揮官；BE 改套件後提醒 user 重啟。

Task 2-1: survey-mapper.js — 退役 goto 鍵、改 question/page 級 displayCondition 映射

Files（FE）: src/views/survey-v2/utils/survey-mapper.js

• Step 1: mapOptionFromApi/mapOptionToApi 移除 gotoQuestionUid/gotoPageUids（:122-123/:217-218）。
• Step 2: mapQuestionFromApi（:92）加 displayCondition: q.display_condition || null；mapQuestionToApi（:159）加 if (q.displayCondition) out.display_condition = q.displayCondition。
• Step 3: mapPageFromApi（:77）加 displayCondition: p.display_condition || null；page 的 toApi（mapPageToApi 若有，否則整樹 PUT 走 mapSurveyToApi）同補。

Task 2-2: AddQuestionDialog.vue — 退役流程規則/父題目、加「顯示條件」區

Files: src/views/survey-v2/components/AddQuestionDialog.vue

• Step 1: 退役 step3 流程規則區（:418-463）、父題目下拉（:401-407）、parentQuestionOptions（:166）、form.parentId、addFlowRule/removeFlowRule/canSetFlowRules、onSubmit 的 flowRules 組裝（:223-246）。
• Step 2: 加「顯示條件」區（題目 dialog，design §4.1）：
  • form.displayCondition = { sourceQuestionUid: null, answers: [] }（或 null）。
  • UI：「當 [單選題▼] 的答案是 [選項多選▼] 時顯示」+ 清除鈕。
  • 來源題下拉 radioQuestionOptions：allQuestionsFlat filter type==='radio' && id!==本題 && 非本題子題。
  • 答案多選 sourceAnswerOptions：選中來源題後，列該題 options 的 {label:opt.label, value:opt.id}（id=key||name，與填答值同源）。
• Step 3: onSubmit emit {...form, displayCondition}（sourceQuestionUid+answers 皆空時送 null）。
• Step 4: 「進階設定」步驟內容重整（決策：父題目 + 流程規則移除後，step3 只剩補充描述 + 顯示條件；步驟數/導覽視內容合併，實作時定）。
• Step 5: i18n 新增 display_condition / show_when / condition_source / condition_answers / clear_condition key（zh-tw + en）；移除 flow_rules/jump_to/jump_to_pages 等 goto 文案。

Task 2-3: 題組（SurveyPage）顯示條件 UI

Files: src/views/survey-v2/components/AddPageDialog.vue（或題組設定入口，grep 定位）

• Step 1: 題組設定 dialog 同加「顯示條件」區（與題目同形狀，design §4.1「題目/題組設定各加」）。來源題下拉列同問卷所有單選題。
• Step 2: page create/update payload（useSurveyApi.js createPage/updatePage）透傳 display_condition。

Task 2-4: SurveyDesigner.vue — 退役 hydrate/flow 預覽、加條件 badge + 子題入口重構

Files: src/views/survey-v2/SurveyDesigner.vue

• Step 1: 退役 hydrateFlowRules（grep 定位）、flow rules 卡片預覽（:811-821）。
• Step 2: 加「條件顯示 badge」：題目/題組卡片有 displayCondition 時顯示「條件顯示：依 <來源題編號>」（design §4.1 全局視圖）。來源題編號查 allQuestionsFlat by sourceQuestionUid。
• Step 3（決策 3 子題入口）：母題卡 footer 加「+新增延伸題」按鈕 → 開 AddQuestionDialog 並預設 parentDbId=母題._dbId（取代父題目下拉）。
• Step 4（修查證 d 平推 bug）：onQuestionSubmit 建立成功後，若是子題（有 parentDbId），本地插入改為 push 進母題的 subQuestions 陣列（而非根 questions），確保不重整即嵌套顯示。
• Step 5（決策 2 子題排序）：子題卡不提供獨立上移/下移（跟母題走）——確認子題卡 action bar 無獨立 reorder 控制。
• Step 6: onQuestionSubmit/useSurveyApi create/update payload 退役 goto 透傳、改帶 displayCondition。

Task 2-5: 段② 手測 + commit（FE repo）

• Step 1: FE dev server 起（user 起服務）。手測：
  1. 題目設顯示條件（選單選來源+答案）→ 存 → 重整 → badge 正確顯示。
  2. 題組設顯示條件 → 存 → 重整 → badge 正確。
  3. 母題卡「+新增延伸題」→ 建子題 → 不重整即嵌套顯示（查證 d 修復驗證）。
  4. 刪來源題 → 引用它的條件 badge 消失（段① 清理連動）。
• Step 2: 顯式 git add + commit（等指揮官驗收後）。

Task 3-1: useSurveyVisibility.js — 重做 extract + core 演算法（目標側）

Files: src/views/survey-v2/composables/useSurveyVisibility.js（重做，保留匯出函式名 computeVisibility/computeVisibilityFromSnapshot 讓 SurveyPreview 消費點零改）

目標側語意（design §3.1，比 goto 簡單）：

• 每個 target（question 或 page）看自己的 displayCondition：
  • 無 displayCondition → 恆可見。
  • 有 → source 未作答 → 可見（維持「答了才略過」）；source 已作答且答案 ∈ answers → 可見；已作答且答案 ∉ answers → 隱藏。
• page 隱藏 → 其下所有 question 隱藏。
• hiddenReasons：target → source_question_uid（供「依 X-N 略過」文案）。

• Step 1（TDD——本 FE repo 若有 Vitest 走單元測試，否則 §7 E2E 覆蓋 + 手測）：先寫 core 演算法測試（未作答全可見 / 命中顯示 / 未命中隱藏 / page 隱藏連帶 question / 無條件零變化）。
• Step 2: 重做 core：

function computeVisibilityFromConditions(questionConds, pageConds, allQuestions, allPages, answers) {
    const hiddenQ = new Set(), hiddenP = new Set(), hiddenReasons = new Map()
    const isHidden = (dc) => {
        if (!dc?.sourceQuestionUid || !dc.answers?.length) return false
        const ans = answers[dc.sourceQuestionUid]
        const v = ans && typeof ans === 'object' && 'answer' in ans ? ans.answer : ans
        if (v === undefined || v === null || v === '') return false  // 未作答=顯示
        return !dc.answers.includes(v)  // 已作答未命中=隱藏
    }
    for (const p of allPages) {
        if (isHidden(p.displayCondition)) { hiddenP.add(p.id); hiddenReasons.set(p.id, p.displayCondition.sourceQuestionUid) }
    }
    for (const q of allQuestions) {
        if (hiddenP.has(q._pageId)) { hiddenQ.add(q.id); if(!hiddenReasons.has(q.id)) hiddenReasons.set(q.id, allPages.find(p=>p.id===q._pageId)?.displayCondition?.sourceQuestionUid) ; continue }
        if (isHidden(q.displayCondition)) { hiddenQ.add(q.id); hiddenReasons.set(q.id, q.displayCondition.sourceQuestionUid) }
    }
    return {
        visibleQuestionIds: new Set(allQuestions.filter(q=>!hiddenQ.has(q.id)).map(q=>q.id)),
        visiblePageIds: new Set(allPages.filter(p=>!hiddenP.has(p.id)).map(p=>p.id)),
        hiddenReasons,
    }
}
export function computeVisibility(allQuestions, allPages, answers) {
    return computeVisibilityFromConditions(null, null, allQuestions, allPages, answers)
    // question/page 的 displayCondition 直接掛在物件上，無需另抽
}

• Step 3: computeVisibilityFromSnapshot 換新快照形狀（見 Task 4-2 快照格式 [{target_type, target_uid, source_question_uid, answers}]）：把快照的 target 條件覆寫回對應 question/page 的 displayCondition，再走同一 core（讓 view/history 讀「提交當下」條件而非即時結構）。

Task 3-2: SurveyPreview.vue — 補 allPages 帶 displayCondition，消費點沿用

Files: src/views/survey-v2/SurveyPreview.vue

• Step 1: allPagesRaw（:558）flatten 時帶上 displayCondition（目前只 flatten 結構，需保留 p.displayCondition）；collectAllQuestions（:538）已帶 _pageId，補帶 q.displayCondition（mapper 已映射，應已在物件上，確認即可）。
• Step 2: visibility computed（:570）呼叫 computeVisibility(allQuestions.value, allPagesRaw.value, answers.value)——簽章不變（allPages 現在帶 displayCondition）。三消費點（totalRequired/currentQuestions/onSave 必填 + progress + progressItems）零改（輸出契約不變，查證 c）。
• Step 3: hiddenReasons 文案（:611）沿用（source_question_uid → 編號）。
• Step 4: 手測：地端/雲端/混合三情境（design §6-1）；同題組跳題（§6-3，現在是對中間題各設 Q1≠2 條件）；改答重算、答案保留（§6-3）；必填同源（§6-4）。

Task 3-3: 段③ commit（FE repo，等指揮官驗收後）

Task 4-1: BE checkpoint — 重做快照抽取（掃 question + page 的 display_condition）

Files: app/task_survey/service/question_answer_service.py

• Step 1: _extract_flow_rules_snapshot 重做為 _extract_display_conditions_snapshot(questions, pages)：

def _extract_display_conditions_snapshot(questions, pages) -> list[dict]:
    snap = []
    for q in questions:
        dc = getattr(q, "display_condition", None)
        if dc and dc.get("source_question_uid"):
            snap.append({"target_type": "question", "target_uid": q.uid,
                         "source_question_uid": dc["source_question_uid"], "answers": dc.get("answers") or []})
    for p in pages:
        dc = getattr(p, "display_condition", None)
        if dc and dc.get("source_question_uid"):
            snap.append({"target_type": "page", "target_uid": p.uid,
                         "source_question_uid": dc["source_question_uid"], "answers": dc.get("answers") or []})
    return snap

• Step 2: checkpoint 三處寫 history（:110/:243/:339 區）需補載 pages——目前只 get_questions(survey_id=...)。查證是否有 survey_page_domain_service.get_by_survey_id(survey_id) 可用（jedi-survey 有此 method），載入 pages 傳進抽取函式。落地 flow_rules_snapshot=_extract_display_conditions_snapshot(questions, pages)（欄名沿用不改，design §3.3）。
• Step 3: revert 繼承（question_answer_history_service.py:110）行為不變（機制與內容無關，確認即可）。

Task 4-2: 稽核檢視端渲染（view/history 不適用標記）

Files: src/views/survey-v2/SurveyPreview.vue

• Step 1: extractRulesFromSnapshot（在 useSurveyVisibility）換讀新形狀 [{target_type, target_uid, source_question_uid, answers}]，覆寫回 target 的 displayCondition 後走 core（Task 3-1 Step 3）。
• Step 2: view/history 模式的「不適用 vs 漏答」渲染（:1351/:1645 區）沿用——auditVisibility 產出的 hiddenQuestionIds + hiddenReasons 邏輯不變，只是規則來源換成 display_condition 快照。
• Step 3: 手測（design §6-5）：提交後 Designer 改條件 → 稽核檢視按提交當下快照判定不適用、不漂移；revert 版本繼承目標快照。

Task 4-3: 段④ commit（BE + FE 分開，等指揮官驗收後）

7.1 jedi-survey pytest（段①）

• display_condition 驗證：non_radio_source / self_reference / source_not_found / cross_survey / malformed / valid / no_condition（question + page）
• 清理：delete_question 清 question+page 條件 / delete_page 不觸發清理（回歸）/ 改題型清理

cd ~/Projects/Jedicogy/module/jedi-python-package/jedi-survey && pytest tests/unittest/domain/service/ -v

7.2 E2E（test repo，另派 session）

• 退役：舊 goto designer/fill scenario（模型翻轉，止損重寫）。
• 新增（designer）：題目/題組設顯示條件 + badge、刪來源題連動清空、母題卡新增延伸題嵌套。
• 新增（fill）：部署環境三分流、新增選項無漏網、同組跳題進度分母、改答重算保留、必填同源。
• 回歸：survey-v2 無條件既有問卷零變化。

7.3 手測 checklist（段②③④，開發者過一輪）

• 題目/題組設顯示條件 → 存 → 重整 → badge 正確
• 部署環境三分流填答行為正確（含混合）
• 新增選項不動條件 → 答新選項 → 條件字面隱藏正確
• 同組跳題略過題不算進度分母
• 改答重算、先前已填答案保留
• 隱藏必填不擋提交 / 可見必填擋提交
• 母題卡新增延伸題 → 不重整即嵌套
• 刪來源題 → 引用它的條件 badge 消失
• 稽核檢視按提交快照判不適用、不漂移；revert 繼承
• 無條件既有問卷（任選 1-2 份）行為零變化

依 CLAUDE.md「收尾等命令」：完成所有段落 + 手測過關後，停下回報 status + checklist 結果，不主動做：

• jedi-survey 發版（path dependency 還原 pin）
• migration 套用 STG/POC（DEV 套用時機亦回報指揮官）
• docs/specs/ 頁面 spec 更新（writing-feature-specs skill）
• Notion / memory / SUMMARY

• jedi-common 翻譯 bug 耦合 → 本案零耦合（前提查證 a）：display_condition 為專用非可翻譯欄位，read（load_only 讀主表）+ write（主表）雙路徑乾淨，不像 FR-049 goto 依賴 bug 副作用。此為目標側模型的工程附帶收益。
• goto 舊鍵 inert：DEV 若殘留 FR-049 測試期 goto 鍵，新引擎不讀，成死鍵，不遷移（design §3.1）。
• snapshot 欄位沿用：question_answer_histories.flow_rules_snapshot 不回滾不改名，只換內容形狀（design §3.3）。
• checkpoint 需補載 pages（Task 4-1）：display_condition 掛 page 本體，抽快照需額外載入 pages（原 goto 只在 question option 上）。
• 查證 d 平推 bug：FR-049.1 子題入口重構順帶修「建立後平推根層」的既有 FE bug。