不是做一個爬蟲網站，
而是做一個能長期運行的交通事件資料庫

01定位與取捨

整個專案只靠一個判斷成立：觀測比結果值钱。 官方頁面只告訴你「現在」，而且隨時改版；你要做的是把「每一個現在」變成歷史， 然後從歷史推導出官方永遠不會發布的指標。

02產品範圍與優先級

按「可取得性 × 事件定義清晰度」排序。第一版只做四類，且先做機場。

可行性這一欄是這一輪新增的：規劃階段就應該把「來源能不能取到」當成排程依據， 而不是等做到第 3 週才發現要逆向。

03三層資料模型（核心原則）

04系統架構

官方網站 / App API / 公告 RSS / 社交平台公告
                    |
                    v
   Collector Workers（Python + httpx，必要時 Playwright）
   ├─ mfm_airport_collector        每 5 分鐘    [已實作並驗證]
   ├─ dsat_bus_realtime_collector  每 30-60 秒  [需先逆向]
   ├─ dsat_notice_collector        每 2-5 分鐘
   ├─ parking_collector            每 2-5 分鐘
   ├─ lrt_notice_collector         每 10-30 分鐘
   └─ smg_weather_warning_collector 每 5 分鐘（延誤原因變數）
                    |
        +-----------+------------+
        v                        v
  Raw Storage               PostgreSQL (+ TimescaleDB)
  R2 / S3 / MinIO           ├─ 主檔資料
  大型 HTML / 截圖           ├─ 時序觀測
  小型 JSON → inline         ├─ 事件資料
                            └─ 品質與異常紀錄
                    |
                    v
   Analytics Jobs（每小時 / 每日 / 每月）
   取消率、延誤分佈、實際候車時間、班距異常、滿位熱圖、颱風關聯
                    |
                    v
   FastAPI ── Next.js Dashboard / 公眾查詢頁 / Telegram 提醒

05來源實測結果（這一輪的新证据）

規劃裡最大的不確定性是「這些頁面到底能不能穩定取到結構化資料」。這一輪直接驗證了。

機場頁面實際長什麼樣

每趟航班是一個 <tr>，關鍵欄位直接以 attribute 呈現， 對解析器非常友善：

<tr class="detail" id='NX856'
     data-flight-date="2026-09-28"
     data-is-departure="1">
  <td class='d-none d-md-table-cell'>08:20</td>              -- 計劃時間
  <td><span style='display:none'>Air Macau</span>            -- 航空公司（隱藏但可取）
      <img src='.../Airlines/NX.png'/></td>                   -- IATA code 在圖檔名裡
  <td class='d-none d-md-table-cell'>Osaka-Kansai</td>       -- 航點
  <td class='d-none d-md-table-cell'>7</td>                  -- 登機閘口
  <td class='green-flight d-none d-md-table-cell'>
    TOOK OFF AT 08:27                                        -- 狀態 + 實際時間
  </td>
  <td><span class='d-none'>iscompleted</span></td>           -- 完成旗標
</tr>

頁面另有 Last updated on: 28/09/2026 13:20:01。探集器必須把官方發布時間與自己的抓取時間分開存， 才能判斷究竟是官方沒更新還是採集器死了。

停車場頁面實際長什麼樣

每個停車場是一個 <tr>，車種以並排的 inline-block 儲存格呈現， 詳情頁的儲存格直接寫著 available/total：

<div style="width:140px;display:inline-block">
  <span class="carpark_icon_wrap">
    <img src="./images/carpark_car.png?v=20260915" />   -- 車種（小客車）
    <img src="./images/carpark_n.jpg" alt="夜" />       -- 夜間服務徽章
  </span>
  143/247                                              -- 可用/總車位
</div>

這裡有三個會咬人的細節，解析器已經用回測 fixture 把它們鎖住：

• 徽章會插在圖示與數字之間。用「圖示往後 N 個字元找數字」的方式， 在亞馬喇前地（id 6009）會整個解不到——必須先剝掉標籤、再讀储存格尾端的數字。
• 詳情頁還有一塊 <!-- ... --> 註解掉的舊車位表。註解一定要先拿掉，否則會把官方早就放棄維護的欄位當成第二個資料來源。
• - 不是 0。91 個停車場中有 38 個至少有一個車種顯示 -，6 個完全沒有小客車感測器。把它們當成 0，等於對全澳門宣告 「這些停車場都滿了」。

為什麼排程用 Cloudflare Workers，不是 GitHub Actions

原本考慮用 GitHub 的 worker 每 30 分鐘抓一次，實查後三個理由改判：Actions 的 scheduled workflow 在最壞情況下會延遲數十分鐘且順序不保證；每個公开 repo 的 60 天無活動後排程會被停用；而每一次运行都要重新下載依賴。Workers 的 Cron Trigger 是平台層排程，D1 則是帶事務的關式庫——雨者都在免費方案內，而且寫入做成冪等 （unique (facility_id, source_updated_at)），不會把 30 分鐘的重複 採樣變成重複資料。

取捨：D1 免費層從 2026-09-01 開始真正執行每日列數上限，所以採集器必須寫得冪等， 而不是依賴「每天只會抓 48 次」。這是同一個決策逼出來的工程約束。

06資料庫 Schema

先用 Supabase PostgreSQL 建，資料量起來再上 TimescaleDB。 下面是三個骨架表，完整 DDL 見 db/schema.sql。

6.1 原始快照表（最重要的一張）

create table raw_snapshots (
  id bigserial primary key,
  source_id uuid not null references data_sources(id),
  fetched_at timestamptz not null default now(),   -- 我何時抓的
  source_published_at timestamptz,                  -- 官方何時发布的
  request_url text not null,
  response_status integer,
  content_hash char(64) not null,                   -- SHA-256
  storage_uri text,                                 -- 大型 HTML/截圖 → R2/S3
  inline_payload jsonb,                             -- 小型 JSON → 直接入表
  parser_version text,
  parse_status text not null default 'pending',
  parse_error text,
  duration_ms integer
);
-- 同一來源、同一內容、同一小時不重複入库
create unique index uq_raw_snapshot_source_hash_hour
  on raw_snapshots (source_id, content_hash, date_trunc('hour', fetched_at));

6.2 航班觀測

create table flight_observations (
  id bigserial primary key,
  flight_id uuid not null references flights(id),
  raw_snapshot_id bigint references raw_snapshots(id),
  observed_at timestamptz not null,
  source_updated_at timestamptz,
  scheduled_time timestamptz,
  estimated_time timestamptz,   -- 'Expected at' → 低信心
  actual_time timestamptz,      -- 'TOOK OFF AT' / 'Landed at' → 高信心
  gate text, checkin_counter text, baggage_belt text,
  raw_status text,              -- 保留原字串，永不丢
  normalized_status text not null,
  delay_minutes integer,
  delay_confidence numeric(4,3),-- 1.000 實際 / 0.700 估計（實測新增）
  is_cancelled boolean not null default false,
  source_record jsonb not null
);

flight_key 規則：MFM:{YYYY-MM-DD}:{arrival|departure}: {flight_number}:{station}， 例：MFM:2026-09-28:departure:NX856:Osaka-Kansai。 這個鍵是去重與事件串接的基礎，必須穩定。

6.3 統一事件流（前端只查這張）

create table transport_events (
  id uuid primary key default gen_random_uuid(),
  transport_mode text not null,   -- flight|bus|lrt|parking|ferry|traffic
  entity_type text not null, entity_id text not null,
  event_type text not null,
  severity text not null default 'info',   -- info|minor|major|critical
  status text not null default 'active',   -- active|resolved|superseded|unknown
  started_at timestamptz not null, ended_at timestamptz,
  title_tc text not null, description_tc text, cause_category text,
  source_url text, confidence numeric(4,3), metadata jsonb
);

前端不需要分别查 flight_events、bus_service_events、 parking_observations，一張事件流就能拼出統一時間軸：

14:05  機場   | 離港 NX123     | 取消        | 高
14:07  巴士   | 路線 25B        | 班距異常 23 分 | 中
14:10  停車場 | 栢港停車場      | 滿位        | 低

07事件判定規則

不要直接相信文字狀態，以時間差作主判定；文字狀態只作辅證。

路線 25B · 亞馬喇前地 · 平日 08:00-09:00
歷史中位班距 8 分；今日相鄰兩班相隔 23 分
→ 服務異常，excess_wait = 15 分
→ 不断言「班次取消」，除非官方公告可驗證

採集器内的事件偵測流水線

1 抓取 → 2 存 raw snapshot → 3 SHA-256 去重 → 4 解析成標準化紀錄
→ 5 與最近一筆觀測比較 → 6 找出欄位變化 → 7 產生/更新事件
→ 8 更新 entity.last_seen_at → 9 送進聚合 → 10 符合條件则觸發通知

這一輪已在 collectors/mfm_airport.py:diff_events() 實作步驟 5-7， 並用真實來源驗證了三段行為：首次運行產生 192 筆 first_seen； 4 秒後再次運行，因來源內容未變而產生 0 筆事件（去重與 diff 正確）； 8 分鐘後的第三次運行抓到 2 筆真實狀態變化（BR802 departed、 FD763 boarding）。這就是一個可用的事件流的雛形。

08採集頻率分級

原規劃的 6 分鐘級距經過實測微調：機場頁面的 Last updated 實際約為每分鐘刷新， 所以 5 分鐘是安全的；巴士如果取不到 API 而必須走頁面，頻率就要往下修正以免形成壓力。

09四週路線圖（含驗收標準）

技術選型（定案）

10資料品質與合規紅線

11最小可行產品與價值路徑

最值得先做的仍舊是那句結論：「澳門機場航班取消與延誤歷史資料庫」。 理由在本輪實測後更硬：事件定義清晰（官方直接寫 CANCELLED）、 單页就能拿到 192 筆結構化觀測、不需要瀏覽器自動化、 而且一天内就出現了 22 筆取消舆 7 筆延誤 —— 資料量可控但訊號足ク。

GET /api/v1/flights?date=&direction=
GET /api/v1/flights/{flight_key}/history
GET /api/v1/flights/metrics?from=&to=
GET /api/v1/bus/routes/{code}/reliability
GET /api/v1/parking/heatmap?day_type=
GET /api/v1/events?mode=&status=
GET /api/v1/events/timeline

12尚未驗證、需要下一步確認