ARCH-1 編排演算法實作啟動：ADR-007 技術地基 + L0/L1 data-model schema 層¶

背景¶

travel_helper 自 ARCH-5 渲染層設計收尾後，業主拍板下一主軸＝ARCH-1 編排演算法「實作」——從設計正式跨入產品程式碼。這是專案第一份產品程式碼（此前 repo 僅有 docs/scripts）。

本批為實作首個里程碑：鎖定技術地基（ADR-007）+ 落地 L0 專案骨架 + L1 data-model schema 層 + qa 驗收。L2 五階段編排管線（演算法主體）尚未實作，ARCH-1 整體維持 。

變更內容¶

ADR-007 實作技術地基（新增）¶

• Python 3.11+ / Pydantic v2 BaseModel / src layout / package travel_helper_core（不含 UI，與 ARCH-6 解耦）
• planning_config 採 .py 常量模組為 O-1-7-a 單一來源（收口載體未定；備 .toml 覆寫層退路）
• adapter Protocol + fixture-backed stub 隔離 ARCH-2~4 採集層（本輪不實作，契約由 core 定義，真實採集日後只換實作）
• 測試工具鏈：pytest + pytest-mock + freezegun + pytest-benchmark
• 否決 stdlib dataclass（V-hard 剔除散落/DM-P2 散寫）、attrs+cattrs、planning_config .toml
• tree/adr 節點 + 00-index 已落（verification_status: pending）

L0 專案骨架¶

• pyproject.toml（hatchling + 依賴宣告 + src layout）
• planning_config.py：Q10-followup-j 待校準暫定常量集中單源、標 TODO、保守值

L1 data-model schema 層（22 檔產品碼）¶

• 9 型 Node + discriminated union 拆分：Day.nodes[] 用 7 型可排程 union（排除 weather/safety_reference）
• V-hard 序列化剔除（DM-S1）：persist JSON 不含 Google Content 現值、以佔位替換
• lazy migration（DM-P2）：@model_validator(mode='before') 集中欄位映射 + 缺欄補預設
• extra='forbid' 白名單禁入：把 C-9/C-10/C-5 從事後抽查升為載入時強制拒絕（合規強化）
• 儲存層：原子寫（temp→os.replace）+ revision 樂觀鎖 + manifest 自動重建

GAP-2/3/4 architect 裁定落 data-model 明文（規格細化，無新 ADR）¶

• §6.0（新增）：weather/safety 雙軌——Day.nodes[] 排除 weather/safety_reference，二者走專屬欄位 Day.weather_node/Day.safety_ref/Trip.safety_ref，不進 Stage C 排序池
• §7.5 第 3 點：V-hard round-trip 載入後 None 語義恆＝「待重查」，與 DM-P3「查無」明確區分（不需額外旗標）
• §6 accommodation：score(V-hard) 剔除、score_status/score_source(P) 保留，存檔可知「過門檻+來源」不知數值（C-3 可追溯 + C-7 不長存兩全）
• Gap-1：§5.1 DM-S7 AVAILABLE_MINUTES 修正表 defer（720 基準，key 結構骨架待 Q10-followup-j）

驗收標準¶

• pytest 124 passed / 0 failed（測試碼落 tests/）
• IF-T-1~5 全覆蓋：round-trip discriminator 保真 / DM-P3 三態 None 不被吞 / V-hard 序列化無現值 / extra=forbid 白名單載入時拒絕 / planning_config 單源
• 40 BLOCKED 誠實列出（皆 L2 五階段 / ARCH-2 採集 / ARCH-5 渲染 / ARCH-6 UI 依賴，非失敗）
• .gitignore 補 Python/venv/__pycache__ + 本機 trips/exports（C-5/C-8 不入版控）
• 無新 constraint、無降級、無影響任何既有 ；ARCH-1 整體維持 （演算法主體 L2 未實作）

後續¶

• L2-A~H 五階段編排管線（Stage A 切日 → B 分桶 → C DayScheduler 方案 A 求解器 → D 交通+停車 → E 負載守恆）
• Ln 端到端負載測試（C-4 子場景 + ADR-002 1~3 分鐘預算）——完成後 ARCH-1 具備升 前提
• Gap-2/3/4 完整解 + Q10-followup-j 校準批於對應 L2 階段觸發