ARCH-4-followup-transit-live 第一棒：TDX 真實大眾運輸 adapter（TRA/THSR）＋Q10-followup-b 配額實測收口（1238 測試綠）¶

背景¶

排程鏈至上一批（#405）為止全程 fixture-backed——「排程邏輯支援大眾運輸日」≠「真實班次資料可用」。本批為 ARCH-4 真實源接線第一棒（台灣 TDX），其第一優先前置為 Q10-followup-b：TDX 免費層配額數字官方文件三處不一致（「3 點/月」「5 次/分鐘」「50 次/日」），若「1 OD 對＝1 呼叫」照字面成立，單一 5 天行程 114 個 OD 對需 ≈23 分鐘發完、遠超 ADR-002 同步預算——配額語義不釐清則 adapter 的批次/快取策略無從設計。業主本批完成 TDX 會員註冊並提供金鑰（.env，不進版控）。

變更內容¶

1. Q10-followup-b 配額收口（文件＋實測雙軌，engineering-fieldtest，不驅動任何 升級）¶

• 文件層（research-primary，14 來源；主協調者抽查 2/2 逐字命中）：交通部收費要點法規逐字確認「基礎會員每月 3 虛擬點數＋用罄 5% 緩衝」；「每金鑰 5 次/分鐘」文件面僅第三方孤證；台灣手機註冊免審核即時生效；TDX 授權＝政府開放資料條款第 1 版（可長存快取，唯一義務顯名「資料介接『交通部TDX平臺』」，與 Google C-7 禁長存為截然不同體制）
• 實測層（24 次呼叫，≤25 預算、≥13 秒間隔）：「每金鑰 5 次/分鐘」由 API 回應標頭機械證實，且為跨端點共用之全域計數器（404 也扣；token 端點獨立 20/分鐘桶；429 之 Retry-After＝RateLimit-Reset）；批次端點證實存在——TRA v3 全網日時刻表（含逐站 StopTimes）、THSR v2 全量實測 271,057 bytes/161 班 → 「1 OD 對＝1 呼叫」假設推翻，呼叫量 114 → 個位數；點數扣減 API 層完全不可觀測（僅會員中心人工可查）
• 產出：docs/research/reports/2026-08-02_Q10-followup-b_tdx-quota-semantics_report.md＋experiments/tdx-quota-livetest/

2. TdxTransitAdapter 落地（純 opt-in，未接線編排流程，fixture 仍為預設，既有測試零受影響）¶

• 策略：batch_prefetch_schedules() 以「1 (網路, service_date)＝1 次批量呼叫＋本地 OD 索引」實作，Protocol 三方法簽章零改動
• 全域 5/分鐘限速器（跨端點共用、時鐘可注入）＋429 Retry-After 退避；記憶體/磁碟雙層 TTL 快取（TRA 自述 UpdateInterval=14400 為依據）；OIDC token 程序內快取重用
• 跨夜班次 minute-of-day >=1440（SC 契約）；站點解析誠實 miss（三態禁混同，不杜撰）
• live smoke 抓到兩個真實 bug 並修復：TRA「臺北」vs THSR「台北」用字不一致（封閉字元正規化）；TRA 舊縱貫線「左營」與 THSR「左營」同名異站（優先有直達班次網路）
• live smoke 5 次呼叫：台北→花蓮 TRA 35 班（含真實跨夜 >=1440 樣本）／台北→左營 THSR 73 班，快取重用零額外呼叫
• 常量入 planning_config（TDX_RATE_LIMIT_*/TTL/半徑，均【低信心】待校準批）

3. 品質鏈（qa＋devil 收口）¶

• qa 簽核通過（含界定）：補 9 條測試（含先前零覆蓋的「已查證無班次」降級分支）；發現 _fetch_cached() 例外處理缺 AttributeError 之真實 bug；界定原文「單元測試＋5 次 live smoke 通過 ≠ 本題已解決，成熟度維持 」
• devil 挑戰無阻擋級：C2（記憶體快取無 TTL 檢查＝長壽命進程永久快取）／C3（座標解析缺唯一性判定）／qa AttributeError 同批修復（含 qa 對斷言變更之增量覆核通過）；C1 揭露 livetest RESULTS.md「6 次塞單一 5 次窗口」算術錯誤，文字已誠實更正
• 產出：docs/research/devil-advocate/2026-08-02_tdx-transit-adapter_challenge.md＋experiments/tdx-adapter-smoke/

驗收標準¶

• python -m pytest tests/ -q → 1238 passed, exit 0（原 1159＋本批 79；主協調者獨立複跑同綠）
• live smoke ≤10 次呼叫預算內（實際 5 次）、兩組真實 OD 對 departures 非空且嚴格遞增、跨夜樣本 >=1440
• 憑證零洩漏（experiments/ 全檔機械檢查無 secret/token 明文）
• 既有 fixture 路徑為預設、TdxTransitAdapter 未接線任何編排流程
• 成熟度全部維持 （engineering-fieldtest 不驅動 ；接地上限條款）

殘餘（下一棒＝接線批）¶

• 阻擋級設計項：wall-clock 呼叫邊界閘（devil C1：>5 次批次呼叫跨速率窗口真實阻塞 sleep 最長 ~60s，接線進 Stage D-pre 同步流程前必設，形狀比照 ADR-010 L0-c）
• devil C4（service_date 時區日界線）／C5（端點改版聚合偵測）／C6（執行緒安全）觀察項
• ODPT（日）／韓國／Transitland 未開始；軌道類點數換算、跨金鑰配額、Bus 批次端點、304 未測；TTL/半徑常量併 Q10-followup-j 校準批