台灣旅行報告系統 (TW Travel Report)
Overview
生成「台灣→香港/深圳/珠海/澳門」雙向旅行規劃報告（繁中/英文，HTML/PDF），含即時航班數據。核心能力是透過 BitBrowser CDP + API 攔截 即時爬取攜程航班，繞過 WhaleGuard 反爬，並自動判斷走資料庫還是即時爬取。
語言規範（用戶確認 2026-08-14）
- 繁體中文覆蓋率：報告標題、標籤、統計項、天氣城市、實用資訊、時序全部繁體中文
- 目的地數據一律繁體中文：交通方式、酒店推薦、景點活動、美食推薦、實用資訊的內容全部使用繁體中文（不管去深圳、珠海或澳門）
- 系統名稱：「台灣，中國 旅行規劃系統」
- 天氣城市標籤：香港 / 珠海 / 澳門 / 深圳（中文）
- Hero 標題用中文城市名（台北、高雄、台中）
- 不含牙科指引 — build_dental() 和導航欄「牙科指引」已永久移除
觸發場景
- 「生成報告（台北，X月X日-X月X日，珠海/深圳/澳門）」
- 日期超出資料庫範圍，或資料庫航班數據缺失/不完整，需要即時爬取
-
需要英文版報告或 PDF 版報告
-
需要包含澳門替代路線、澳門→珠海交通、酒店價格
環境要求
- Python：
C:\Users\Administrator\.workbuddy\binaries\python\envs\default\Scripts\python.exe - BitBrowser：7.0+ 運行中，Local API port 54365
- Playwright：執行前必須清除
NODE_OPTIONS環境變量 - 工作目錄：腳本需在包含
tw_flight_db.xlsx的專案目錄運行
工作流程
1. 智能報告（自動判斷，推薦）
# 資料庫有數據 → 主方案（直讀）；缺數據 → 備選方案（即時爬取）
python tw_smart_report.py Taipei 2026-08-15 2026-08-20 zhuhai
# 強制即時爬取（資料庫有數據也要重新爬）
python tw_smart_report.py Taipei 2026-08-15 2026-08-20 zhuhai --force
參數：[城市] [去程日期] [回程日期] [目的地] [--force]
- 城市：Taipei / Kaohsiung / Taichung
- 目的地：zhuhai / shenzhen / macau
- 支援跨日期（去程和回程可以是不同日期）
2. 直接生成報告（不爬取）
python tw_gen_report.py Taipei 2026-08-15 2026-08-20 zhuhai # 繁中
python tw_gen_report_en.py Taipei 2026-08-15 2026-08-20 zhuhai # 英文
3. 轉 PDF
python tw_html2pdf.py 報告.html 輸出.pdf
4. 單獨即時爬取某條航線
python tw_standalone_scrape.py 2026-08-15 2026-08-15 "TPE->ZUH" 輸出.xlsx
澳門替代路線與澳門→珠海交通
珠海目的地報告自動包含「經澳門前往珠海」章節：
- TPE↔MFM 往返航班（資料庫查詢）
- 澳門→珠海交通：拱北口岸步行過關、港珠澳大橋穿梭巴士、橫琴口岸、九洲港碼頭渡輪、的士
- 若需要即時爬取澳門航班，用 --force 或單獨運行 tw_standalone_scrape.py 爬 TPE->MFM / MFM->TPE
關鍵注意事項
- BitBrowser 窗口選擇：
bb_pick_window()會跳過名稱含「被封」的窗口。若爬取超時，檢查是否有可用窗口 - NODE_OPTIONS：Playwright 無法啟動時，先清除環境變量
- 爬取緩衝：smart_report 爬取時自動帶 ±1 天緩衝（
2026-08-15→ 爬08-14~08-16） - 數據去重：報告顯示時按（起飛+抵達+航空）分組保留最低價，避免 7 月 DOM 數據重複
- 天氣：wttr.in 需依序請求+重試（並發 SSL 會失敗）
- xlsx 保存慢：批量爬取時每 10 次查詢保存一次
詳細參考
references/architecture.md— 系統架構、BitBrowser CDP 爬取流程、API 攔截詳解references/db-schema.md— tw_flight_db.xlsx 22 欄位 schema、航線覆蓋scripts/— 5 個核心腳本（smart_report / standalone_scrape / gen_report / gen_report_en / html2pdf）assets/monthly_data_template/— 月度靜態數據 JSON 模板（交通/酒店/景點/實用資訊）
報告輸出
tw_travel_report_{city}_{dest}_{dep}_{ret}.html/.pdf (繁中)
tw_travel_report_en_{dest}_{dep}_{ret}.html/.pdf (英文)
