"""
commands/ 批次 B 硬編碼字串集中化模組

本模組集中化 Batch 2 命令檔案中的硬編碼字串常數，包括：
- track_query.py
- track_board.py
- track_batch.py
- track_acceptance.py
- track_audit.py
- track_relations.py
- track.py
- migrate.py
- generate.py

統一管理所有使用者可見的訊息字串，避免重複定義和提高可維護性。
"""

from ticket_system.constants import (
    APPEND_LOG_EXTRA_SECTIONS,
    CANONICAL_BODY_SECTIONS,
)


# ============================================================================
# TrackQueryMessages - track_query.py 相關訊息
# ============================================================================

class TrackQueryMessages:
    """track_query.py 相關訊息常數"""

    # execute_summary 中的標題格式
    SUMMARY_TITLE = "[Summary] {version} ({completed}/{total} 完成)"

    # execute_version 中的標題格式
    VERSION_TITLE = "[Summary] {display_version} ({completed}/{total} 完成)"

    # execute_list 中的標題格式
    LIST_TITLE = "[List] {version} ({completed}/{total} 完成)"

    # execute_list 中截斷顯示時的標題格式（0.38.0-W1-006：統計為全量，清單為截斷後）
    LIST_TITLE_TRUNCATED = "[List] {version} ({completed}/{total} 完成, 顯示前 {shown})"

    # execute_summary 中找不到 Tickets 的標題
    SUMMARY_NO_TICKETS_TITLE = "[Summary] {version} (0/0 完成)"

    # execute_version 中找不到 Tickets 的標題
    VERSION_NO_TICKETS_TITLE = "[Summary] {display_version} (0/0 完成)"

    # execute_list 中找不到 Tickets 的標題
    LIST_NO_TICKETS_TITLE = "[Summary] {version} (0/0 完成)"

    # execute_chain 中找不到 root 時的警告
    CHAIN_ROOT_NOT_FOUND_HINT = "   嘗試將本身視為 root 展開"

    # 無 Tickets 時的提示訊息
    NO_TICKETS_MESSAGE = "   沒有 Tickets"

    # YAML 格式錯誤訊息格式
    YAML_ERROR_FORMAT = "Ticket {ticket_id} 的 YAML 格式錯誤：{error}"

    # 跨版本未完成任務警告
    CROSS_VERSION_WARNING_HEADER = "[WARNING] 其他版本有未完成的 Ticket："
    CROSS_VERSION_WARNING_ITEM = "   v{version}: {pending} 個 pending, {in_progress} 個 in_progress"
    CROSS_VERSION_WARNING_HINT = "   使用 --version <version> 查看詳情"

    # 版本全完成偵測 warning
    VERSION_ALL_COMPLETED_WARNING = (
        "[WARNING] 版本 {version} 所有 ticket 已完成"
    )
    VERSION_ALL_COMPLETED_NEXT = (
        "   下一個 active 版本: {next_version}"
    )
    VERSION_ALL_COMPLETED_HINT = (
        "   建議執行 version-release 或手動推進 todolist status"
    )


# ============================================================================
# TrackBoardMessages - track_board.py 相關訊息
# ============================================================================

class TrackBoardMessages:
    """track_board.py 相關訊息常數"""

    # render_board_tree 中的標題格式
    TREE_TITLE_ALL = "TICKET TREE - v{version} (所有任務)"
    TREE_TITLE_INCOMPLETE = "TICKET TREE - v{version} (未完成任務)"

    # render_board_tree 中無任務時的文字
    NO_TASKS_TEXT = "(無任務)"

    # render_tree_node 中的 Wave 標題格式
    WAVE_TITLE_FORMAT = "{wave} ({count} tasks)"

    # render_board_unicode 中的標題（動態版本號）
    UNICODE_BOARD_TITLE = "TICKET BOARD - v{version}"

    # render_board_unicode 中的統計行標籤
    UNICODE_STATS_PENDING = "[待處理]"
    UNICODE_STATS_IN_PROGRESS = "[進行中]"
    UNICODE_STATS_COMPLETED = "[已完成]"
    UNICODE_STATS_BLOCKED = "[被阻塞]"
    UNICODE_STATS_TASKS_SUFFIX = "tasks"

    # render_board_unicode 中的欄標題
    UNICODE_HEADERS = ["PENDING", "IN_PROGRESS", "COMPLETED", "BLOCKED"]

    # render_board_unicode 中的圖例
    UNICODE_LEGEND_TITLE = "Legend:"
    UNICODE_LEGEND_PRIORITY_HIGH = "[P0] - Priority 0 (Urgent)    [P1] - Priority 1 (High)"
    UNICODE_LEGEND_PRIORITY_LOW = "[P2] - Priority 2 (Medium)    [P3] - Priority 3 (Low)"

    # render_board_ascii 中的標題
    ASCII_BOARD_TITLE = "TICKET BOARD"

    # render_board_ascii 中的欄標題
    ASCII_HEADER_ROW = "Status    | Count | Tickets"

    # execute_board 中的錯誤訊息前綴
    ERROR_RENDERING_BOARD_PREFIX = "Error rendering board:"


# ============================================================================
# TrackBatchMessages - track_batch.py 相關訊息
# ============================================================================

class TrackBatchMessages:
    """track_batch.py 相關訊息常數"""

    # _execute_batch_operation 中的操作頭訊息格式
    BATCH_OPERATION_HEADER = "[Batch {operation_name}] 處理 {count} 個 Ticket"

    # _process_batch_claim 中的成功訊息格式
    CLAIM_SUCCESS_FORMAT = "{ticket_id} 已接手"

    # _process_batch_complete 中的成功訊息格式
    COMPLETE_SUCCESS_FORMAT = "{ticket_id} 已完成"

    # _process_batch_complete 中的已完成訊息格式
    ALREADY_COMPLETE_FORMAT = "{ticket_id} 已完成"

    # _process_batch_complete 中的驗收條件錯誤格式
    ACCEPTANCE_INCOMPLETE_FORMAT = "{ticket_id} 有未完成的驗收條件 ({count} 項)"

    # _execute_batch_operation 中的成功訊息前綴
    OK_PREFIX = "[OK]"

    # 批量操作的優先操作類型
    VALID_OPERATION_CLAIM = "claim"
    VALID_OPERATION_COMPLETE = "complete"

    # YAML 解析錯誤訊息格式
    YAML_ERROR_FORMAT = "Ticket {ticket_id} 的 YAML 格式錯誤：{error}"


# ============================================================================
# TrackAcceptanceMessages - track_acceptance.py 相關訊息
# ============================================================================

class TrackAcceptanceMessages:
    """track_acceptance.py 相關訊息常數"""

    # execute_check_acceptance 中的狀態訊息（勾選時）
    ALREADY_CHECKED_INFO = "[Info] index {index} 已是勾選狀態"

    # execute_check_acceptance 中的狀態訊息（取消勾選時）
    ALREADY_UNCHECKED_INFO = "[Info] index {index} 已是未勾選狀態"

    # execute_check_acceptance 中的新狀態標籤前綴
    NEW_STATUS_PREFIX = "   新狀態:"

    # execute_check_acceptance 中的狀態文字
    STATUS_TEXT_CHECKED = "勾選"
    STATUS_TEXT_UNCHECKED = "取消勾選"

    # execute_append_log 中有效的區段清單
    # 白名單自 constants.CANONICAL_BODY_SECTIONS 衍生（單一序列來源），
    # 加上 H1 容器 Execution Log；不再獨立維護清單，消除與
    # ticket_builder SCHEMA_H2_SECTIONS 的雙清單漂移。
    VALID_SECTIONS = [*CANONICAL_BODY_SECTIONS, *APPEND_LOG_EXTRA_SECTIONS]

    # execute_append_log 中的有效值提示前綴
    VALID_VALUES_PREFIX = "   有效值:"

    # execute_append_log 中缺失 Schema 章節自動建立的提示
    # W1-025: 白名單合法但 body 缺失的 Schema 章節（如 IMP 模板未含 Context Bundle）
    # 於 canonical 順序位置自動補建，消除「章節不存在 → 被迫繞道 Edit」的摩擦
    SECTION_AUTO_CREATED_FORMAT = "[OK] 章節 ## {section} 原不存在，已於 schema 順序位置自動建立"

    # execute_append_log 中的時間戳標籤
    TIMESTAMP_PREFIX = "   時間戳:"

    # execute_append_log 中的內容標籤
    CONTENT_PREFIX = "   內容:"

    # execute_append_log 中執行日誌的時間戳格式
    LOG_TIMESTAMP_FORMAT = "- [{timestamp}] {content}"

    # execute_check_acceptance 中的批量勾選摘要格式
    BATCH_CHECK_SUMMARY_FORMAT = "[OK] {ticket_id} 已勾選 {checked_count}/{total_count} 項"

    # execute_check_acceptance 中的批量取消勾選摘要格式
    BATCH_UNCHECK_SUMMARY_FORMAT = "[OK] {ticket_id} 已取消勾選 {unchecked_count}/{total_count} 項"

    # execute_accept_creation 中的成功訊息格式
    ACCEPT_CREATION_SUCCESS_FORMAT = "[OK] {ticket_id} 建立後驗收已通過"

    # execute_accept_creation 中的已通過訊息格式
    ACCEPT_CREATION_ALREADY_ACCEPTED_FORMAT = "[Info] {ticket_id} 已通過建立後驗收"


# ============================================================================
# TrackAuditMessages - track_audit.py 相關訊息
# ============================================================================

class TrackAuditMessages:
    """track_audit.py 相關訊息常數"""

    # _format_audit_report 中的標題
    AUDIT_REPORT_TITLE = "[Acceptance Audit Report]"

    # _format_audit_report 中的基本資訊標籤
    AUDIT_TICKET_PREFIX = "Ticket:"
    AUDIT_TIME_PREFIX = "時間:"
    AUDIT_AUDITOR_NAME = "acceptance-auditor"
    AUDIT_AUDITOR_PREFIX = "驗收者:"

    # _format_audit_report 中的檢查結果標籤
    AUDIT_RESULTS_TITLE = "檢查結果:"

    # _format_audit_report 中的表格標題
    AUDIT_TABLE_HEADER_STEP = "| 檢查步驟 | 結果 | 說明 |"
    AUDIT_TABLE_SEPARATOR = "|---------|------|------|"

    # _format_audit_report 中的描述文字
    AUDIT_DESCRIPTION_SKIPPED = "跳過（無子任務）"
    AUDIT_DESCRIPTION_PASSED = "[Y] 通過"
    AUDIT_DESCRIPTION_PASSED_WITH_WARNINGS = "[WARN] 通過（有 {count} 項警告）"
    AUDIT_DESCRIPTION_FAILED = "[N] {issue}"

    # _format_audit_report 中的結論標籤
    AUDIT_CONCLUSION_TITLE = "結論:"
    AUDIT_RESULT_PREFIX = "驗收結果:"

    # _format_audit_report 中的失敗項標籤
    AUDIT_FAILED_TITLE = "失敗項:"

    # _format_audit_report 中的失敗項格式
    AUDIT_FAILED_ITEM_FORMAT = "  - {step}:{issue}"

    # _format_audit_report 中的警告項標籤
    AUDIT_WARNINGS_TITLE = "警告項:"

    # _format_audit_report 中的警告項格式
    AUDIT_WARNING_ITEM_FORMAT = "  - {step}:{warning}"

    # execute_audit 中的驗收檢查失敗訊息前綴
    AUDIT_CHECK_FAILED_PREFIX = "驗收檢查失敗："

    # execute_audit 中的驗收過程錯誤訊息前綴
    AUDIT_PROCESS_ERROR_PREFIX = "驗收過程出錯："


# ============================================================================
# AuditVersionMessages - audit_version.py 相關訊息
# ============================================================================

class AuditVersionMessages:
    """audit_version.py 相關訊息常數"""

    # 報告標題
    AUDIT_REPORT_TITLE = "[版本歸屬審計報告]"

    # 掃描進度訊息
    SCANNING_TICKETS = "[掃描中] 掃描所有 Ticket 版本資訊..."

    # 過濾訊息
    FILTERED_VERSION = "[篩選] 從 {total} 個 Ticket 中篩選版本 v{version}：{filtered} 個"

    # 報告統計標題
    SECTION_MISMATCHES = "[版本不一致] 發現以下 Ticket 版本號與所在目錄不一致："
    SECTION_DUPLICATES = "[重複 Ticket] 發現以下 Ticket 出現在多個版本目錄："

    # 不一致項目格式
    MISMATCH_ITEM = "[不一致] {ticket_id}"
    MISMATCH_ID_VERSION = "  ID 版本: {version}"
    MISMATCH_DIR_VERSION = "  目錄版本: {version}（source of truth）"
    MISMATCH_FRONTMATTER_VERSION = "  Frontmatter 版本: {version}"

    # 修復建議
    FIX_SUGGESTION_MOVE = "  建議: 將檔案從 v{old_version} 搬移到 v{new_version}"
    FIX_SUGGESTION_FRONTMATTER = "  建議: 修正 frontmatter 中的 version 欄位為 {version}"

    # 重複項目格式
    DUPLICATE_ITEM = "[重複] {ticket_id}"
    DUPLICATE_SUGGESTION = "  建議: 保留版本 v{recommended_version} 中的檔案，刪除其他版本的副本"

    # 審計結果
    AUDIT_PASSED = "[通過] 審計成功，{total} 個 Ticket 版本一致"
    AUDIT_FOUND_ISSUES = "[發現問題] 共 {issues} 個問題：{mismatches} 個不一致，{duplicates} 個重複"

    # 修復操作
    FIXING_ISSUES = "[修復中] 開始修復發現的問題..."
    FIX_COMPLETED = "[完成] 修復操作已完成"

    # 結論
    CONCLUSION_PASS = "[結論] 審計通過，所有 Ticket 版本歸屬正確"
    CONCLUSION_FAIL = "[結論] 審計失敗，發現 {issues} 個問題，請執行 --fix 進行修復"


# ============================================================================
# TrackRelationsMessages - track_relations.py 相關訊息
# ============================================================================

class TrackRelationsMessages:
    """track_relations.py 相關訊息常數"""

    # execute_add_child 中已存在的子 Ticket 訊息
    CHILD_ALREADY_EXISTS_FORMAT = "[Info] {child_id} 已是 {parent_id} 的子 Ticket"

    # execute_add_child 中的父子關係標籤
    RELATION_PARENT_PREFIX = "   父 Ticket:"
    RELATION_CHILD_PREFIX = "   子 Ticket:"
    RELATION_OLD_PARENT_PREFIX = "   原父 Ticket:"
    RELATION_OLD_PARENT_SUFFIX = "(已更新)"

    # execute_phase 中有效的 Phase 值列表
    VALID_PHASES = [
        "Phase 0",
        "Phase 1",
        "Phase 2",
        "Phase 3a",
        "Phase 3b",
        "Phase 4",
    ]

    # execute_phase 中的有效值提示前綴
    PHASE_VALID_VALUES_PREFIX = "   有效值:"

    # execute_phase 中的 Phase 標籤
    PHASE_PREFIX = "   Phase:"

    # execute_phase 中的 Assignee 標籤
    PHASE_ASSIGNEE_PREFIX = "   Assignee:"

    # execute_agent 中的標題
    AGENT_SEPARATOR = "=" * 60

    # execute_agent 中的統計行標籤
    AGENT_IN_PROGRESS_LABEL = "進行中"
    AGENT_PENDING_LABEL = "待處理"
    AGENT_COMPLETED_LABEL = "已完成"
    AGENT_BLOCKED_LABEL = "被阻塞"

    # execute_agent 中的項目前綴
    AGENT_ITEM_PREFIX = "  -"


# ============================================================================
# TrackMessages - track.py 相關訊息
# ============================================================================

class TrackMessages:
    """track.py 相關訊息常數"""

    # help 文字（命令註冊時）
    HELP_CLAIM = "認領 Ticket"
    HELP_COMPLETE = "標記完成"
    HELP_RELEASE = "釋放 Ticket"
    HELP_SUMMARY = "快速摘要"
    HELP_QUERY = "查詢單一 Ticket"
    HELP_TREE = "顯示任務鏈樹狀結構"
    HELP_LIST = "列出 Tickets（支援狀態篩選）"
    HELP_CHAIN = "顯示完整任務鏈"
    HELP_FULL = "顯示 Ticket 完整內容"
    HELP_LOG = "顯示執行日誌"
    HELP_VERSION = "指定版本進度摘要"
    HELP_BATCH_CLAIM = "批量認領 Tickets"
    HELP_BATCH_COMPLETE = "批量完成 Tickets"
    HELP_SET_WHO = "設定 Ticket 的 who 欄位"
    HELP_SET_WHAT = "設定 Ticket 的 what 欄位"
    HELP_SET_WHEN = "設定 Ticket 的 when 欄位"
    HELP_SET_WHERE = "設定 Ticket 的 where 欄位（路徑型輸入同步更新 where.files；逗號分隔多路徑）"
    HELP_SET_WHY = "設定 Ticket 的 why 欄位"
    HELP_SET_HOW = "設定 Ticket 的 how 欄位"
    HELP_SET_PRIORITY = "設定 Ticket 的 priority 欄位"
    HELP_ADD_ACCEPTANCE = "追加驗收條件"
    HELP_REMOVE_ACCEPTANCE = "移除驗收條件（按編號）"
    HELP_ADD_SPAWNED = "追加 spawned_tickets 項目"
    HELP_SET_DECISION_TREE = "設定 decision_tree_path 欄位"
    HELP_WHO = "查詢 Ticket 的 who 欄位"
    HELP_WHAT = "查詢 Ticket 的 what 欄位"
    HELP_WHEN = "查詢 Ticket 的 when 欄位"
    HELP_WHERE = "查詢 Ticket 的 where 欄位"
    HELP_WHY = "查詢 Ticket 的 why 欄位"
    HELP_HOW = "查詢 Ticket 的 how 欄位"
    HELP_AGENT = "查詢代理人的所有 Tickets"
    HELP_PHASE = "更新 Ticket 的 TDD Phase"
    HELP_CHECK_ACCEPTANCE = "勾選或取消勾選驗收條件"
    HELP_APPEND_LOG = "追加執行日誌到 Ticket"
    HELP_ACCEPT_CREATION = "標記 Ticket 建立後驗收已通過"
    HELP_ADD_CHILD = "建立 Ticket 父子關係"
    HELP_AUDIT = "執行驗收檢查"
    HELP_BOARD = "顯示樹狀看板視圖"
    HELP_TRACK = "追蹤 Ticket 狀態"

    # 命令參數 help 文字
    ARG_TICKET_ID = "Ticket ID"
    ARG_VERSION = "版本號（自動偵測）"
    ARG_PENDING = "只顯示待處理的 Tickets"
    ARG_IN_PROGRESS = "只顯示進行中的 Tickets"
    ARG_COMPLETED = "只顯示已完成的 Tickets"
    ARG_BLOCKED = "只顯示被阻塞的 Tickets"
    ARG_VERSION_STR = "版本號（如 0.31.0 或 v0.31.0）"
    ARG_ROOT_TICKET_ID = "根 Ticket ID"
    ARG_TICKET_IDS = "Ticket ID 列表（以逗號分隔）"
    ARG_VALUE = "新的值"
    ARG_AGENT_NAME = "代理人名稱（支援模糊匹配，如 parsley）"
    ARG_PHASE = (
        "TDD Phase，支援多種格式："
        " phase0, phase1, phase2, phase3a, phase3b, phase4"
        " 或 'Phase 0', 'Phase 1' 等（引號包裹）。"
        " 範例: ticket track phase <ID> phase2 <agent>"
    )
    ARG_AGENT = (
        "負責該 Phase 的代理人名稱。"
        " 範例: lavender-interface-designer, sage-test-architect,"
        " pepper-test-implementer, parsley-flutter-developer,"
        " cinnamon-refactor-owl"
    )
    ARG_PARENT_ID = "父 Ticket ID"
    ARG_CHILD_ID = "子 Ticket ID"
    ARG_INDEX = "驗收條件索引（1 開始）"
    ARG_UNCHECK = "取消勾選（預設為勾選）"
    ARG_CHECK_ACCEPTANCE_ALL = "勾選（或 --uncheck 時取消勾選）所有驗收條件"
    ARG_SECTION = "日誌區段 (Problem Analysis/Context Bundle/重現實驗結果/Solution/Test Results/Execution Log/NeedsContext/Exit Status)"
    ARG_CONTENT = "日誌內容"
    ARG_WAVE = "只顯示特定 Wave"
    ARG_STATUS = "篩選狀態（pending/in_progress/completed/blocked，支援多個值）"
    ARG_FORMAT = "輸出格式（table/ids/yaml，預設 table）"
    ARG_ALL = "顯示所有任務（包含已完成）"

    # create 命令參數 help 文字
    ARG_CREATE_ACTION = (
        "動詞：描述任務要做什麼（必填）。"
        " 範例: 實作, 修復, 重構, 分析, 建立, 改善"
    )
    ARG_CREATE_TARGET = (
        "目標：描述任務對象（必填）。"
        " 範例: SessionListPage 排序功能, ticket CLI 參數引導"
    )

    # create 缺少必填參數時的友善錯誤提示
    ERROR_MISSING_ACTION_TARGET = (
        "[ERROR] 缺少必填參數 --action 和/或 --target。\n"
        "ticket create 需要至少指定 --action（動詞）和 --target（目標）。\n"
        "範例:\n"
        "  ticket create --action 實作 --target 'SessionListPage 排序功能' --wave 3\n"
        "  ticket create --action 修復 --target 'ticket CLI 參數引導' --wave 3"
    )

    # phase 缺少 agent 參數時的友善錯誤提示
    ERROR_MISSING_PHASE_AGENT = (
        "[ERROR] 缺少必填參數 agent（負責代理人）。\n"
        "用法: ticket track phase <ticket_id> <phase> <agent>\n"
        "範例:\n"
        "  ticket track phase 0.2.0-W3-001 phase1 lavender-interface-designer\n"
        "  ticket track phase 0.2.0-W3-001 phase3b parsley-flutter-developer\n"
        "常用代理人:\n"
        "  Phase 0:  saffron-system-analyst\n"
        "  Phase 1:  lavender-interface-designer\n"
        "  Phase 2:  sage-test-architect\n"
        "  Phase 3a: pepper-test-implementer\n"
        "  Phase 3b: parsley-flutter-developer\n"
        "  Phase 4:  cinnamon-refactor-owl"
    )


# ============================================================================
# MigrateMessages - migrate.py 相關訊息
# ============================================================================

class MigrateMessages:
    """migrate.py 相關訊息常數"""

    # _extract_id_components 中的錯誤訊息
    INVALID_TICKET_ID_FORMAT = "[ERROR] Ticket ID 格式無效"

    # _migrate_single_ticket 中的預覽頭
    DRY_RUN_HEADER = "預覽遷移: {source_id} → {target_id}"

    # _migrate_single_ticket 中的標籤
    DRY_RUN_TITLE_PREFIX = "  標題:"
    DRY_RUN_STATUS_PREFIX = "  狀態:"

    # _load_migration_config 中的錯誤訊息
    CONFIG_FILE_NOT_FOUND = "[ERROR] 配置檔案不存在:"
    CONFIG_FORMAT_NOT_SUPPORTED = "[ERROR] 不支援的配置格式，請使用 .yaml 或 .json"
    CONFIG_FORMAT_INVALID = "[ERROR] 配置格式無效，應包含 'migrations' 欄位"
    MIGRATIONS_FIELD_NOT_LIST = "[ERROR] 'migrations' 應為清單"
    CONFIG_LOAD_FAILED = "[ERROR] 載入配置失敗:"

    # _batch_migrate 中的訊息
    MIGRATION_SUMMARY = "遷移摘要"

    # execute 中的錯誤訊息
    VERSION_NOT_SPECIFIED = "[ERROR] 無法自動偵測版本，請使用 --version 指定"
    MISSING_PARAMETERS = "[ERROR] 缺少必要參數: source_id 和 target_id"

    # _update_cross_references 中的成功訊息
    CROSS_REFERENCES_UPDATED = "[OK] 已更新 {count} 個 Ticket 的交叉引用"

    # 命令參數 help 文字
    ARG_SOURCE_ID = "來源 Ticket ID (格式: {version}-W{wave}-{seq})"
    ARG_TARGET_ID = "目標 Ticket ID (格式: {version}-W{wave}-{seq})"
    ARG_CONFIG = "批量遷移配置檔案 (.yaml 或 .json)"
    ARG_VERSION = "指定版本 (如不指定則自動偵測)"
    ARG_DRY_RUN = "預覽遷移結果，不實際執行"
    ARG_BACKUP = "遷移前備份（預設啟用）"
    ARG_NO_BACKUP = "停用備份"
    ARG_FORCE_OVERWRITE = "明示授權覆寫目標 ID 既有 Ticket（預設拒絕；會記錄至 audit log）"
    HELP_MIGRATE = "遷移 Ticket ID（支援單一和批量遷移）"

    # Collision detection 訊息（W14-048）
    # dry-run 階段警告：目標已存在會被覆寫
    WARN_MIGRATE_TARGET_EXISTS = (
        "[WARNING] 目標 Ticket 已存在，實際執行時將被覆寫:\n"
        "  目標路徑: {target_path}\n"
        "  既有標題: {existing_title}\n"
        "  既有狀態: {existing_status}\n"
        "  若確認覆寫請執行時加上 --force-overwrite"
    )
    # 實際執行階段拒絕覆寫
    ERROR_MIGRATE_TARGET_EXISTS = (
        "[ERROR] 拒絕覆寫既有 Ticket: {target_id}\n"
        "  目標路徑: {target_path}\n"
        "  既有標題: {existing_title}\n"
        "  既有狀態: {existing_status}\n"
        "  如確認覆寫，請加上 --force-overwrite 旗標明示授權"
    )
    # 批量遷移 fail-fast
    ERROR_BATCH_COLLISION = (
        "[ERROR] 批量遷移偵測到目標 ID 撞既有 Ticket，已 fail-fast 不執行任何遷移:\n"
        "{collisions}\n"
        "  如確認全部覆寫，請加上 --force-overwrite 旗標"
    )
    # --force-overwrite audit log
    INFO_FORCE_OVERWRITE = (
        "[AUDIT] --force-overwrite 已啟用，覆寫既有 Ticket: {target_id}\n"
        "  覆寫時間: {timestamp}\n"
        "  既有標題: {existing_title}"
    )


# ============================================================================
# BulkCreateMessages - bulk_create.py 相關訊息
# ============================================================================

class BulkCreateMessages:
    """bulk_create.py 相關訊息常數"""

    # execute 中的訊息
    HELP_BATCH_CREATE = "從模板 + 目標清單快速建立多個 Ticket"
    ARG_TEMPLATE = "使用的模板名稱（如 impl-parsley）"
    ARG_TARGETS = "目標清單，逗號分隔（如 'BookCard Widget,LibraryListPage'）"
    ARG_VERSION = "目標版本（如 0.31.0）"
    ARG_WAVE = "Wave 編號"
    ARG_PARENT = "父 Ticket ID（用於建立子任務）"
    ARG_DRY_RUN = "預演模式：只顯示摘要，不建立檔案"

    # _print_batch_summary 中的摘要標題
    BATCH_CREATE_SUMMARY_TITLE = "批次建立摘要"
    SUMMARY_TEMPLATE_PREFIX = "模板："
    SUMMARY_VERSION_PREFIX = "版本："
    SUMMARY_WAVE_PREFIX = "Wave："
    SUMMARY_TOTAL_PREFIX = "待建立："
    SUMMARY_MODE_DRY_RUN = "預演（不建立檔案）"
    SUMMARY_MODE_NORMAL = "實際建立"
    SUMMARY_MODE_PREFIX = "模式："

    # _print_batch_summary 中的待建立 Ticket 清單標題
    TICKETS_LIST_TITLE = "待建立 Ticket："
    TICKET_FORMAT = "  {seq:2d}. {id}: {title}"

    # _print_batch_result 中的完成訊息
    BATCH_CREATE_COMPLETE = "批次建立完成"
    RESULT_FORMAT = "成功: {created}/{total}  警告: {warned}/{total}  失敗: {failed}/{total}"

    # execute 中的錯誤訊息
    TEMPLATE_NOT_FOUND = "模板不存在：{template}"
    VERSION_NOT_DETECTED = "無法偵測版本"
    WAVE_INVALID = "Wave 編號無效"
    TARGETS_EMPTY = "目標清單為空"

    # _create_ticket_config 中的 what 欄位範本
    WHAT_TEMPLATE = "實作 {target}"

    # _print_batch_result 中的失敗項目標籤
    FAILED_ITEMS_TITLE = "失敗項目："

    # _print_batch_result 中的警告項目標籤
    WARNED_ITEMS_TITLE = "警告項目："

    # _create_batch_tickets 中的 checklist 缺欄位警告格式（1.0.0-W1-027）
    CHECKLIST_WARNING_FORMAT = "缺必填欄位: {fields}"


# ============================================================================
# GenerateMessages - generate.py 相關訊息
# ============================================================================

class GenerateMessages:
    """generate.py 相關訊息常數"""

    # execute 中的錯誤訊息
    PLAN_PARSE_FAILED = "Plan 解析失敗:"

    # execute 中的成功訊息格式
    TICKETS_SAVED_FORMAT = "已保存 {saved}/{total} 個 Tickets"

    # _print_generation_summary 中的標題
    GENERATION_SUMMARY_TITLE = "[Generation Summary]"

    # _print_generation_summary 中的標籤
    SUMMARY_PLAN_FILE_PREFIX = "Plan 檔案:"
    SUMMARY_GENERATED_COUNT_PREFIX = "生成 Tickets:"
    SUMMARY_GENERATED_COUNT_SUFFIX = "個"
    SUMMARY_MODE_PREFIX = "模式:"
    SUMMARY_MODE_DRY_RUN = "預演"
    SUMMARY_MODE_NORMAL = "正常"
    SUMMARY_TICKETS_LIST_TITLE = "Tickets 清單:"

    # _print_generation_summary 中的 Ticket 列表格式
    SUMMARY_TICKET_FORMAT = "   {id}:{title}"
    SUMMARY_TICKET_DETAILS_FORMAT = "      Wave: W{wave}, TDD:{phases}"
    SUMMARY_TICKET_DETAILS_NO_TDD = "無 TDD"

    # _save_tickets 中的錯誤訊息（使用 BACKUP_FAILED，但這裡保留以供參考）
    # 注：實際使用來自 WarningMessages.BACKUP_FAILED

    # _print_generation_summary 中的 checklist 缺欄位警告（1.0.0-W1-027，warning 級不阻擋）
    CHECKLIST_WARNING_TITLE = "[WARNING] 以下 Ticket 缺必填欄位（warning 級，未阻擋建立）："
    CHECKLIST_WARNING_ITEM = "   {id}: 缺 {fields}"

    # register 中的命令 help 文字
    HELP_GENERATE = "從 Plan 檔案生成 Atomic Tickets"

    # register 中的命令參數 help 文字
    ARG_PLAN_FILE = "Plan 檔案路徑（Markdown 格式）"
    ARG_VERSION = "版本號（如 0.31.0）"
    ARG_WAVE = "基礎 Wave 編號"
    ARG_DRY_RUN = "預演模式（不實際建立檔案）"


# ============================================================================
# VersionShiftMessages - version_shift.py 相關訊息
# ============================================================================

class VersionShiftMessages:
    """version-shift 命令相關訊息常數"""

    # CLI 幫助資訊
    HELP_VERSION_SHIFT = "將整個版本的 Ticket 遷移至新版本"
    ARG_FROM_VERSION = "來源版本號（無 v 前綴，如 0.1.0）"
    ARG_TO_VERSION = "目標版本號（無 v 前綴，如 0.2.0）"
    ARG_DRY_RUN = "預覽模式，不執行任何修改"
    ARG_NO_BACKUP = "跳過備份步驟（風險自負）"
    ARG_SKIP_TODOLIST = "不更新 todolist.yaml"

    # 步驟訊息
    STEP_VALIDATE = "[1/8] 前置驗證..."
    STEP_BACKUP = "[2/8] 備份原始目錄..."
    STEP_UPDATE_TICKETS = "[3/8] 更新 Ticket 版本欄位..."
    STEP_RENAME_TICKETS = "[4/8] 重新命名 Ticket 檔案..."
    STEP_CROSS_REFS = "[5/8] 更新跨版本交叉引用..."
    STEP_RENAME_DIR = "[6/8] 重新命名 worklog 目錄..."
    STEP_UPDATE_TODOLIST = "[7/8] 更新 todolist.yaml..."
    STEP_SUMMARY = "[8/8] 輸出操作摘要..."

    # 驗證訊息
    ERROR_INVALID_VERSION_FORMAT = "版本號格式無效：{version}（預期 N.N.N 格式）"
    ERROR_FROM_VERSION_NOT_EXISTS = "版本目錄不存在：docs/work-logs/v{version}/"
    ERROR_TO_VERSION_EXISTS = "目標版本目錄已存在：docs/work-logs/v{version}/，請先確認目標目錄內容"
    INFO_SAME_VERSION = "來源版本與目標版本相同（{version}），無需遷移"

    # 備份訊息
    BACKUP_SUCCESS = "備份完成：{path}"
    BACKUP_SKIP = "跳過備份步驟（已指定 --no-backup）"
    ERROR_BACKUP_FAILED = "備份失敗：{error}。操作已中止。如需跳過備份，請使用 --no-backup（風險自負）"

    # 處理訊息
    TICKETS_UPDATED = "處理 {count} 個 Ticket"
    TICKET_PARSE_ERROR = "跳過無法解析的檔案：{filename}"
    AUXILIARY_FILES_UPDATED = "附屬文件更新: {count} 個"
    CROSS_REFS_UPDATED = "跨版本引用更新: {count} 個"
    DIRECTORY_RENAMED = "docs/work-logs/v{from_version}/ → docs/work-logs/v{to_version}/"
    TODOLIST_FIELDS_UPDATED = "todolist.yaml 欄位更新: {count} 個"

    # 警告訊息
    WARNING_NO_TICKETS_DIR = "找不到 tickets/ 子目錄，跳過 Ticket 更新"
    WARNING_TODOLIST_NOT_EXISTS = "todolist.yaml 不存在，跳過版本記錄更新"
    WARNING_CURRENT_VERSION_MISMATCH = "當前版本號不匹配，todolist.yaml 的 current_version 未更新"

    # Dry-run 訊息
    DRY_RUN_HEADER = "[DRY-RUN] 以下為預計執行的操作（未實際修改任何檔案）："
    DRY_RUN_PLAN_TITLE = "版本遷移計畫："
    DRY_RUN_FROM = "  來源: {version}"
    DRY_RUN_TO = "  目標: {version}"
    DRY_RUN_TICKETS_PREVIEW = "Ticket 更新預覽（{count} 個）："
    DRY_RUN_AUXILIARY_PREVIEW = "附屬文件更新預覽："
    DRY_RUN_DIRECTORY_OPERATION = "目錄操作："
    DRY_RUN_TODOLIST_PREVIEW = "todolist.yaml 更新預覽："
    DRY_RUN_BACKUP = "備份：不執行（dry-run 模式）"
    DRY_RUN_FOOTER = "執行實際遷移請移除 --dry-run 旗標。"
    DRY_RUN_PREVIEW_ELLIPSIS = "（以及其他 {count} 個 Ticket）"

    # 摘要訊息
    SUMMARY_TITLE = "============================================================\nversion-shift 完成摘要\n============================================================"
    SUMMARY_FROM_VERSION = "來源版本: {version}"
    SUMMARY_TO_VERSION = "目標版本: {version}"
    SUMMARY_BACKUP_LOCATION = "備份位置: {path}"
    SUMMARY_RESULTS = "處理結果:"
    SUMMARY_TICKETS_UPDATED = "  Ticket 更新: {count} 個"
    SUMMARY_AUXILIARY_UPDATED = "  附屬文件更新: {count} 個"
    SUMMARY_CROSS_REFS_UPDATED = "  跨版本引用更新: {count} 個"
    SUMMARY_TODOLIST_UPDATED = "  todolist.yaml 欄位更新: {count} 個"
    SUMMARY_FILES_SKIPPED = "  跳過的檔案: {count} 個"
    SUMMARY_DIR_OPERATION = "目錄操作:"
    SUMMARY_SEPARATOR = "============================================================"


# ============================================================================
# 輔助函式
# ============================================================================

def format_msg(template: str, **kwargs) -> str:
    """
    格式化訊息範本

    Args:
        template: 包含 {placeholder} 的訊息範本
        **kwargs: 替換值字典

    Returns:
        格式化後的訊息字串

    Example:
        >>> format_msg(TrackQueryMessages.SUMMARY_TITLE, version="0.31.0", completed=5, total=10)
        "[Summary] 0.31.0 (5/10 完成)"
    """
    try:
        return template.format(**kwargs)
    except KeyError as e:
        raise ValueError(f"缺少格式化參數: {e}")


# ============================================================================
# ClaimWrapMessages - 認領時簡化 WRAP 三問提示（Ticket 0.18.0-W10-028）
#
# 來源：0.18.0-W10-027 ANA 分析結論。所有 ticket claim 時強制提示 PM 回答
# 簡化 WRAP 三問（Widen / Attain distance / Prepare to be wrong），
# 避免預設選項未經評估。ANA 類型額外提示完整 /wrap-decision 框架。
# ============================================================================


class ClaimWrapMessages:
    """claim 命令附加的簡化 WRAP 三問提示訊息"""

    # 區段標題（含來源 ticket 標注）
    WRAP_SECTION_TITLE = "簡化 WRAP 三問 — 認領品質 Checkpoint（[Ticket 0.18.0-W10-027]）"

    # 引導文字
    WRAP_INTRO = (
        "請在開始執行前回答以下三問，可寫入 ticket Problem Analysis 或\n"
        "commit message："
    )

    # 三個問題
    WRAP_WIDEN = (
        "  W（Widen）—— 有其他做法嗎？\n"
        "    至少列 2 個候選方案（含目前方案），確認選擇非默認值。"
    )
    WRAP_ATTAIN_DISTANCE = (
        "  A（Attain distance）—— 機會成本是什麼？\n"
        "    執行這個 ticket 會擠壓哪個更重要的目標？"
    )
    WRAP_PREPARE_WRONG = (
        "  P（Prepare to be wrong）—— 最可能失敗的原因是什麼？\n"
        "    行前預想 1 條：12 小時後失敗最可能的原因，對應防護措施。"
    )

    # 適用範圍說明（以 {ticket_type} 格式化）
    WRAP_APPLIES_TO = "適用範圍：所有 ticket 強制；本 ticket 類型為 {ticket_type}。"

    # S 問（SKILL trigger）—— framework 規則層 Edit 提示（[Ticket 0.18.0-W17-125]）
    # 觸發條件：type=IMP 且 where.files 任一路徑命中 framework 路徑前綴
    WRAP_SKILL_TRIGGER = (
        "  S（SKILL trigger）—— framework 規則層 Edit 提示\n"
        "    本次 ticket where.files 含 framework 路徑（規則/方法論/skill/agent），\n"
        "    故建議 Read .claude/skills/compositional-writing/SKILL.md。\n"
        "    （同 session 已 Read 過、或本次 Edit 屬純格式調整時可省略以下成本對照）\n"
        "    成本對照：Read 約 2-3K token 換取首次撰寫品質；\n"
        "    跳過則事後 Layer 2 委員補修約 5-10K token（估算值）。"
    )

    # ANA 類型專屬第四問（PC-063 防護 4/4）
    ANA_REALITY_TEST = (
        "  R（Reality Test）—— 真根因驗證了嗎？\n"
        "    在列任何候選方案前，必須先做重現實驗：\n"
        "    1. 列出當前接受的根因假設\n"
        "    2. 用最小指令/測試重現問題\n"
        "    3. 區分「已驗證的事實」與「仍未驗證的假設」\n"
        "    4. 將實驗結果寫入 Ticket「重現實驗結果」章節\n"
        "    禁止：未完成重現實驗即列方案（PC-063 教訓）"
    )

    # ANA 類型額外提示
    ANA_EXTRA_HEADER = "[ANA 類型額外要求]"
    ANA_EXTRA_BODY = (
        "本 ticket 為 ANA（分析），簡化三問不足以保證分析品質。\n"
        "請執行完整 /wrap-decision 框架（W/R/A/P 四階段 + 絆腳索）。"
    )


__all__ = [
    "TrackQueryMessages",
    "TrackBoardMessages",
    "TrackBatchMessages",
    "TrackAcceptanceMessages",
    "TrackAuditMessages",
    "AuditVersionMessages",
    "TrackRelationsMessages",
    "TrackMessages",
    "BulkCreateMessages",
    "MigrateMessages",
    "GenerateMessages",
    "ClaimWrapMessages",
    "format_msg",
]
