外部連携 / Vista Global — SkyBot

SkyBot スケジュールPUSH配信 — 技術論点の壁打ち

Vista Global の SkyBot から「運航スケジュールを PUSH で提供できないか」という問い合わせ。データ主体は行動予定表（運航一覧）を想定。先方仕様と我々のデータモデルを突き合わせ、実装前に詰めるべき論点を整理したたたき台。

先方仕様: SkyBot Schedule Push Endpoint ｜ 素材データ: mcj-schedule action_plan_legs ／ /api/plans/full ｜ 作成 2026-07-14
そのまま流用できる 新規実装が必要 要確認 / 制約あり 先方 or 高橋に要相談
ひとことで：先方は「オペレーター毎の AUTH_TOKEN / OPERATOR_ID を発行するので、フライト配列を JSON で POST してくれ」というシンプルな受け口。 我々の 1区間(leg) = 先方の 1 flight に対応させれば素材は揃う。ただし ①削除の伝え方 ②時刻のUTC変換 ③乗客数の欠落 の3点が実装前に必ず決めるべき論点。

全体像

MCJ（我々） mcj-schedule D1 action_plans / action_plan_legs 機体・空港・乗員は mcj-master 参照 配信ワーカー（新規） 確定便フィルタ・JST→UTC変換 disposition変換・差分/削除検出 cron 定期 or 保存時トリガ 配信ログ（送信済みID台帳・新規） HTTPS POST authorization: AUTH_TOKEN SkyBot（Vista Global） POST /operators/schedule/ update/{OPERATOR_ID} { id: OPERATOR_ID,   flights: [ …flight… ] } skybot.vistaglobal.com flight 1件 = 1区間 id / created / modified deleted（true|false） tail（機番） disposition（便種別CODE） depart / arrive（ICAO） departT / arriveT（epoch ms） passengers（数値）

先方（SkyBot）仕様の要約

フィールドマッピング SkyBot ↔ mcj-schedule

SkyBot フィールド 我々の保持元 状態 メモ
id
不変の一意ID		 action_plan_legs.id 要検討 区間単位で一意。ただし leg は物理削除される設計 → 消えたidを後から deleted:true で送れない。論点①
tail action_plans.aircraft_registration
（例 JA123F）		 ほぼOK そのまま使える。Vista側のtail表記（ハイフン有無・大文字小文字）だけ確認
depart / arrive dep_airport_icao / arr_airport_icao OK 最初からICAO保持で変換不要。ただし仮登録便は空文字 or 地域名(dep_area) → 除外。論点④
departT / arriveT flight_date(YYYY-MM-DD)
+ dep_time/arr_time(HH:MM)		 変換要 JSTローカルのHH:MM文字列。flight_dateと結合し JST(+9) として epoch ms(UTC)化。日跨ぎ注意。論点②
created / modified created_at / updated_at 変換のみ JST datetime文字列 → epoch ms。modifiedは差分配信の基準にも使える
deleted cnl_status='cancelled' or 物理削除 要検討 専用フラグなし。キャンセルは状態値、削除は行消滅。台帳が必要。論点①
disposition flight_purpose（区間: ND/PF/PO…）
+ flight_type（AGENT/FERRY/…）		 要確認 Vista側が期待するCODE体系の定義入手 → 変換表が必要。論点⑤
passengers —（数値PAX列なし） 欠落 氏名(passenger_name)のみ。leg.booking_id経由でmcj-bookingから拾うか、省略可否を確認。論点⑥

配信JSONのイメージ 変換後

// 1 leg を 1 flight に変換した例
{
  "id": "leg-4821",           // action_plan_legs.id（安定キー）
  "created": 1720915200000,
  "modified": 1720933200000,
  "deleted": false,
  "tail": "JA123F",
  "disposition": "CHARTER",      // flight_purpose/type からの変換（要定義）
  "depart": "RJTT",
  "arrive": "RJFF",
  "departT": 1720998000000,     // flight_date + dep_time(JST) → UTC epoch
  "arriveT": 1721004000000,
  "passengers": 2            // ← 現状データに無い（論点⑥）
}

技術論点（実装前に詰める）

1
削除・キャンセルの伝達 最重要
課題 — SkyBotは「一度送ったidを deleted:true で再送」して削除を伝える方式。一方 leg は物理DELETE（キャンセルは cnl_status、便自体は残す）。このままでは削除・キャンセルをVistaに伝えられない。
対応案 — 送信済みID台帳（配信ログテーブル）を新設。「前回送ったが今回消えている leg」を検出して deleted:true を送る。さらに cnl_status='cancelled' を deleted:true として扱うか、便は残して disposition で表すかを決める。
要決定: キャンセル便は先方に「削除」として送るか、種別変更として残すか。→ Vista側の運用イメージを確認
2
時刻のUTC変換
課題 — flight_date(YYYY-MM-DD) と dep_time/arr_time(HH:MM文字列) を結合し、JST(+9固定・日本はDST無し) として epoch ms(UTC) 化する。
注意 — 日跨ぎ便（arr_time < dep_time）は到着日を+1日する処理が要る。仮時刻(time_note='AM')は数値化不可 → 除外（論点④）。
対応は明確。純粋関数として実装しユニットテスト対象にする（TZ変換は事故りやすい）
3
全量PUSH か 差分PUSH か / 配信トリガ
選択肢 — (A) 全量: 対象期間の確定便を毎回まるごと送る（実装単純・冪等）。(B) 差分: updated_at（or /api/plans/sync）で変更分のみ送る（通信量小・削除検出は台帳併用）。
トリガ — cron定期（例: 5〜15分毎）か、保存時に即PUSHか。対象期間（未来分のみ／過去何日分含むか）も決める。
推奨たたき台: まず (A)全量 × cron定期 でシンプルに。安定後に差分化を検討。頻度・期間は先方の要望に合わせる
4
仮登録・未確定便の除外
課題 — is_tentative=1／空港未定(dep_area)／時刻ラフ(time_note) の便は ICAO/epoch 必須要件を満たさない。
対応 — 確定便のみ配信のフィルタ。判定条件（dep/arr両方がICAO埋まり・dep_time/arr_timeがHH:MM形式・is_tentative=0）を明文化。
仕様として除外条件を固定。除外した便数はログに残す（黙って落とさない）
5
disposition（便種別）コード体系
課題 — 先方の disposition:"CODE" が期待する値の定義が不明。我々は区間 flight_purpose（ND/PF/PO…）とヘッダー flight_type（AGENT/FERRY/TRAINING/OWNER）を持つ。
対応 — Vistaからコード一覧を入手し変換表を作る。対応が無い区分のデフォルト値も決める。
要確認: SkyBotの disposition コード定義（一覧）を先方に依頼
6
乗客数（passengers）の欠落
課題 — 現状データに数値PAX列が無い（氏名テキストのみ）。
対応案 — (A) leg.booking_id 経由で mcj-booking から人数を拾えるか調査。(B) 拾えない/必須でないなら 省略 or 0。
要確認: passengers は先方で必須か（欠落時の挙動）。必須なら供給元の確保が要る
7
版管理・表示状態のフィルタ
課題 — is_active=0（旧版）や visibility='hidden'/'done' の leg を誤配信しないこと。行動予定表は版管理・仮/確定・表示制御が絡む。
配信対象は is_active=1 かつ visibility='visible'（or 'done'）のアクティブ版のみ。overview/full のフィルタを踏襲
8
認証情報の管理と配信元Worker
対応 — AUTH_TOKEN/OPERATOR_ID は wrangler secret put で管理（コミット厳禁）。配信は mcj-schedule Worker からの外向き fetch（サーバ間なのでCORS不問）。
運用 — Workers は自動デプロイ非対象 → マージ後の手動 wrangler deploy 必要。cron追加時は wrangler.toml の triggers も。
実装は明確。秘密情報の受領方法（先方からの token 共有チャネル）だけ安全に
9
情報共有の合意（技術以前） 高橋確認
課題 — 運航スケジュール（機番・空港・時刻・便種別・場合により乗客数/氏名）を外部社（Vista）へ継続提供することの是非・範囲。
これは経営/合意判断。提供範囲（乗客情報を含めるか等）と併せて高橋に要相談

実装アプローチ（たたき台）

決定ログ

論点状態内容 / 次アクション
データ主体 = 行動予定表(leg)確定1区間 = 1 flight で対応可能
粒度・一意ID = leg.id確定安定キーとして利用。台帳と併用
①削除/キャンセルの表現相談台帳で削除検出は確定。キャンセル便を deleted 扱いにするかVistaに確認
②時刻UTC変換方針確定JST+9で合成、日跨ぎ処理、純粋関数化
③全量/差分・トリガ仮まず全量×cronで単純に。頻度は先方要望次第
④仮登録便の除外方針確定確定便フィルタ。除外数をログ
⑤disposition コード先方待ちVistaからコード一覧を入手
⑥passengers先方待ち必須か確認／供給元(booking)調査
⑨情報共有の合意相談提供範囲を高橋と確認
先方(Vista)に確認したいこと（まとめ）： ①キャンセル便の扱い（削除として送るか）／⑤disposition コードの定義一覧／⑥passengers は必須か・欠落時の挙動／ 配信頻度と対象期間の希望／tail の表記フォーマット。
たたき台 — 実装前の壁打ち用。素材データ: mcj-schedule/workers/schema.sql（action_plan_legs）, /api/plans/full。 先方仕様: SkyBot Schedule Push Endpoint（Vista Global）。作成 2026-07-14。