✈️ fare-watchdog

机票价格监控服务 — 3x/day 抓取国内四大 OTA，跨平台比价，智能行李评估，微信实时推送。

• 四大平台抓取 — 飞猪、去哪儿、携程、同程，自动翻页 / 滚动加载
• 行李评估 — 自动识别免费托运行李额，无行李航班计入 ¥300 自购成本，按"真实价"排序
• 跨平台比价 — 同一航线聚合多平台数据，一目了然
• 智能推荐 — 综合评分：价格 60% + 行李 25% + 经停/时段 15%
• 定时抓取 — 每天 8:07 / 13:07 / 20:07 自动执行，覆盖早中晚三班
• 微信推送 — Server酱 + PushPlus 双通道互备，Markdown 日报直达微信
• 降价提醒 — 支持目标价预警和较上次降幅阈值提醒
• Web 仪表盘 — FastAPI 后端 + 移动端友好的前端
• 快速查询 — --quick 一行命令即查即看，无需改配置

fare-watchdog/
├── main.py              # CLI 入口
├── config.yaml          # 航线、平台、推送配置
├── data/                # 数据层 — 模型、SQLite、配置、城市注册表
├── core/                # 业务层 — 采集器、分析器、推送器、编排器
├── frontend/            # 表现层 — CLI、查询工具、终端报表
└── server/              # Web API — FastAPI 仪表盘

三层架构，frontend → core → data，单向依赖。

• Python 3.10+
• browser-harness（Python 3.11+，独立 CLI）
• Chrome 浏览器

git clone https://github.com/543877815/flight-watchdog.git
cd fare-watchdog
pip install -r requirements.txt

复制 config.yaml 并修改：

routes:
  - depart: "上海"        # 支持中文城市名，自动解析为 IATA 码
    arrive: "东京"
  - depart: "香港"
    arrive: "墨尔本"

platforms:
  - fliggy               # 飞猪
  - qunar                # 去哪儿
  - ctrip                # 携程
  - tongcheng            # 同程

notification:
  serverchan_key: "${SERVERCHAN_KEY}"   # 或直接填入 key
  pushplus_token: "${PUSHPLUS_TOKEN}"   # 或直接填入 token

设置推送密钥（二选一）：

# Server酱 SendKey (推荐)
$env:SERVERCHAN_KEY = "SCTxxxxxx"

# PushPlus Token
$env:PUSHPLUS_TOKEN = "your_token"

# 测试推送通道
python main.py --test-push

# 执行一次全量抓取 + 推送
python main.py --run

# 仅抓取，不推送
python main.py --run --no-push

# 快速查询（无需改配置）
python main.py --quick HKG MEL 2026-09-25
python main.py --quick HKG MEL 2026-09-25 --return 2026-09-28
python main.py --quick SHA BJS 2026-06-16 --platform tongcheng

# 启动定时调度（每天 3 次）
python main.py --schedule

# 查询已有数据
python main.py --route SHA-BJS

# 仅用已有数据生成报告并推送
python main.py --report

# 启动 Web 仪表盘
python server/main.py         # http://localhost:8080

航班的实际成本 = 票价 + 行李费。本项目自动识别免费行李额，对无行李航班加入预估自购成本（默认 ¥300/20kg），按含行李真实总价排序，避免被低价无行李航班误导。

排名  航班        票价    行李          真实总价
 1   MU567       ¥1,200  含 23kg×2     ¥1,200 ✅
 2   CA1234      ¥950    ❌ 无行李     ¥1,250 ⚠️

price_alert:
  enabled: true
  drop_threshold_pct: 10        # 降幅超过 10% 时提醒
  target_prices:
    "SHA-BJS": 600              # 低于 ¥600 即提醒
    "SHA-TYO": 1500

每家平台采集时保留 booking URL，日报中可一键跳转到 OTA 下单页。

城市注册表在 data/cities.py。已内置 ~100 个城市的中文名 → IATA 码映射。如需添加：

from data.cities import register_city
register_city("大阪", "KIX", name_en="Osaka", country="JP")

1. 在 core/collectors/ 下创建 <name>.py
2. 继承 BaseCollector，设置 platform = "<name>"
3. 实现 build_search_url(route) 和 extract_flights_js()
4. 在 config.yaml 的 platforms 中加入 <name>

插件式架构，自动注册，无需手动接线。

MIT