mcj-schedule

社内システム全体図 / 2026-10-14 時点
機材情報 関係者 予定表管理 警告・注意条件 背景色設定 ADSB Debug SWIM PKG SWIM ATS 秘書コマンド XO開発 システム全体図

この資料の位置づけ

社内システム全体の見取り図。社外のSEに「何がどこにあり、どう直して、どう本番に出るのか」を 引き渡すために作ったもので、そのまま社内の全体把握にも使う。 数字はすべて 2026-10-14 時点のコードと Cloudflare の実機から取った実測値。

この資料で分かること / 分からないこと

  • 分かること — システム構成、使用言語、本番の置き場所、データの所在、秘密情報の管理方法、デプロイ手順、既知の落とし穴
  • 分からないこと — 各業務の仕様そのもの(運航管理・料金計算・整備のドメインルール)。 それらは各プロジェクトの <project>/docs/*.html に設計資料として129ファイル・約6.4万行ある

ひとことで言うと

Cloudflare の上に全部乗っている、ビルド工程のない「静的HTML + Workers API」の集合体。

自前サーバもコンテナもKubernetesもない。フロントは素の HTML/CSS/JavaScript、 バックエンドは TypeScript の Cloudflare Workers(Hono)、DBは D1(SQLite互換)。 この1パターンを十数個のプロジェクトで繰り返している。 npm install も webpack も Docker も不要で、HTMLを1枚書けばその日のうちに本番に出せるのが利点。 その代わり型チェック・テストの網が薄く、品質は「マージ前に人とCIが見る」に依存している。

規模(2026-10-14 実測)

13
WORKERS(API)
稼働12・休眠1
11
PAGES(Git連携)
このリポジトリ由来
10
D1 データベース
SQLite互換
3
KV ネームスペース
バインド済みのもの
4
R2 バケット
PDF・画像の実体
647
API エンドポイント
Worker の route 定義数
8
CRON トリガー
7 Worker・5分〜日次
5
GitHub Actions
PR時のみ実行

コード規模(git 追跡ファイル、node_modules 除く)

種別ファイル行数中身
画面 HTML13889,5981画面=1ファイル。CSS・JS も同じファイルに直書きが基本
設計・壁打ち資料 HTML12963,953docs/ 配下。file:// で直接開く前提の自己完結HTML
TypeScript6041,721Workers の API 実装
JavaScript9818,661フロント共通JS と Pages Functions
.mjs(ツール・テスト)17736,790ローカル検証ハーネス・データ採取ツール・単体テスト26本
SQL23813,983schema.sql と migrations/
行数はコメント・空行を含む概算。HTMLが一番大きいのは、画面のロジック(描画・バリデーション・状態管理)が すべてインライン <script> に入っているため。1画面で数千行のファイルが複数ある。

リポジトリと本番の対応

項目値
GitHub リポジトリgithub.com/mcjet-dev/mcj-engineering
Cloudflare アカウントmcjet-dev(workers.dev サブドメインが mcjet-dev)。アカウントIDは各 wrangler.toml 記載
本番ドメイン原則 https://<project>.pages.dev / API は https://<worker>.mcjet-dev.workers.dev。独自ドメインは未使用
会社HP別リポジトリ mcj-web(mcj-web.pages.dev / mcj-web-admin)。このリポジトリには入っていない
社内ポータルmcj-portal.pages.dev — Git未連携の直接アップロード型。本番ソースはこのリポジトリに無い(要注意)
開発ドキュメントリポジトリ内 CLAUDE.md(技術ルール)、docs/(設計資料)、Scrapbox mcj-system(日報・議事録)

3層構造とリクエストの流れ

どのプロジェクトもほぼ同じ形をしている。違うのは「どの層を持たないか」だけ。

ブラウザ 社員 / 代理店 オーナー / 乗員 Cloudflare Pages フロント層 静的 HTML / CSS / JS ビルド工程なし 一部 PWA(sw.js) Pages Functions functions/api/*.js (素のJS・CORS回避と  秘匿情報の中継) mainマージで自動デプロイ Cloudflare Workers API 層 TypeScript + Hono 4 src/index.ts が入口 ORM なし・SQL 直書き HMAC 自前トークン認証 Cron Triggers 同じ Worker が定期処理も 担当(scheduled ハンドラ) 手動 deploy が必要 D1 SQLite互換 主DB・10本 KV キャッシュ・共有状態 R2 PDF・画像の実体 外部サービス LINE Messaging API SWIM(国交省・航空局) 気象(AWC / Open-Meteo) Google Sheets API 自社 SMTP(mcjet.jp) XO(Vista Global)配信 Web Push(FCM / VAPID) いずれも Worker 側から サーバ間通信で呼ぶ HTTPS Service Binding 画面から API を直接叩く経路もある(workers.dev・別オリジン → CORS 設定が必要) Cron Triggers(5分 / 30分 / 日次)
フロントは Pages、APIは Workers、保存は D1/KV/R2。Pages から Worker へは Service Binding(HTTPを経由しない内部呼び出し)、 ブラウザから Worker を直接叩く画面も残っている。

段で見る依存

プロジェクト単位で、どの段がどの段を使うかを並べたもの。矢印は上から下の一方向だけで、 例外は「業務の芯」の中の相互参照だけ。新しいプロジェクトを足すときも、まずこの5段のどこに置くかを決める。

画面だけ 業務の芯 業務 部品 基盤 mcj-companyapps 社内ツールのハブ mcj-sales 代理店 mcj-ownerportal オーナー sales / ownerportal は自前のAPIを持たず mcj-reservation に相乗りする mcj-schedule 運航管理・行動予定表 mcj-reservation 予約・受注・見積 相互参照 mcj-shift 当番シフト mcj-alcohol 検査記録 mcj-crew 乗員ポータル mcj-airport-usage 空港使用届 mcj-maintenance 整備管理 mcj-pricing 料金計算 mcj-wxbrief WXブリーフィング mcj-usage 使用量の監視 画面を持たない。companyapps の中の 画面から Service Binding で呼ばれる mcj-master 全社マスタ。14本中13本が参照する mcj-line-bot LINE の送信口。通知は全部ここを通る 上の段が下の段を使う
mcj-trial(体験搭乗・要確認)と line-secretary(休眠)はどの段にも繋がっていないため省いた。

相関図(プロジェクト同士の呼び出し)

上の図から基盤への矢印を省いて、プロジェクト同士のやり取りだけを描いたもの。 master へは13本すべてが向かうので、描くと線が潰れて読めなくなる。

mcj-companyapps 画面のハブ 画面を持たない部品 mcj-pricing mcj-wxbrief mcj-usage mcj-schedule 運航管理 mcj-reservation 予約・受注 相互参照 mcj-airport-usage mcj-crew mcj-alcohol mcj-shift mcj-line-bot LINE の送信口 画面から部品を呼ぶ crew → shift 通知する6本はすべて line-bot を通る reservation / schedule / shift / alcohol / wxbrief / usage 凡例 画面 → API API → API(業務の呼び出し) 通知(LINE 送信) ※ mcj-master への13本は省略
line-bot は受けるだけでなく自分からも呼ぶ(alcohol / schedule / shift)。LINE から来た操作を各システムへ流すため。 網羅的な対応は下のマトリクスを見ること。

Worker 間の依存(Service Binding)

Worker 同士は URL fetch ではなく Service Binding で直結している。 同一アカウント内の Worker を URL で fetch すると Cloudflare の 1042 エラーになるため、この形が必須。 行は「呼ぶ側」、列は「呼ばれる側」。

呼ぶ側 \ 呼ばれる側 masterline-botschedulereservation shiftalcoholpricingairport-usagewxbriefusage
mcj-companyapps Pages ●-●---●●●●
mcj-master Pages ●---------
mcj-maintenance Pages ●---------
mcj-reservation-api ●●●-●-●---
mcj-schedule-api ●●-●------
mcj-line-bot ●-●-●●----
mcj-alcohol-api ●●●-------
mcj-airport-usage-api ●-●●------
mcj-crew-api ●-●-●-----
mcj-shift-api ●●--------
mcj-wxbrief-api ●●--------
mcj-usage-api ●●--------
mcj-pricing-api ●---------
mcj-trial-api ----------

この表から読み取ってほしい3点

  • master-api が全社の単一情報源 — 14の呼び出し元のうち13が参照している。ここを壊すと全システムが止まる
  • line-bot が唯一の送信口 — LINEのトークンを1か所に集めるため、通知は必ずここを通す
  • schedule ↔ reservation が相互参照 — 循環依存。片方の変更がもう片方に波及しやすい

Service Binding の落とし穴

  • Service Binding 経由の fetch() は ホスト名が無効。呼び出し側が https://dummy/api/... や https://internal/... のような架空のホスト名を使う
  • 受け側に認証を足すとき、この架空ホスト名を素通しにしないと内部呼び出しが黙って全部落ちる。各 Worker の auth.ts に INTERNAL_HOSTS という許可リストがある
  • Pages のバインド順序 — Pages が参照する Worker が存在しないと、Pages 全体がデプロイできない。新規 Worker は先に deploy する
  • mcj-pricing-api だけは master の D1 を直接バインドしている(API経由でない)。master のスキーマ変更時はここも見る

プロジェクト一覧

1ディレクトリ=1プロジェクト。frontend/ が Pages、workers/ が Worker、functions/ が Pages Functions。 行数はコメント・空行込みの概算(docs/ 配下の資料は除く)、「-」はその層を持たないという意味。

中核(ここが止まると業務が止まる)

ディレクトリ役割本番URLWorker(API数)データ規模
mcj-master 全社マスタ(機体・空港・乗員・機種・料金表)。単一情報源 mcj-master.pages.dev mcj-master-api(62)
cron 日次
D1 mcj-master-prod
KV DOC_FILES / R2 機体資料
HTML 1.5k
TS 1.4k
SQL 3.1k
mcj-schedule 運航管理・行動予定表。FPL台帳、W&B、SWIM連携、XO配信、LINE共有 mcj-schedule.pages.dev mcj-schedule-api(143)
cron 30分
D1 mcj-schedule-prod HTML 20.4k
TS 8.8k
SQL 1.9k
mcj-reservation 予約・受注・見積・案件チャット・運航依頼書。最大のプロジェクト mcj-reservation.pages.dev mcj-reservation-api(305) D1 mcj-reservation-prod(22MB・最大)
R2 バナー画像
HTML 17.0k
TS 15.1k / JS 4.3k
SQL 3.2k
mcj-companyapps 社内ツールのハブ。飛行可否計算 / FPL整形・作成 / 空港・空域NOTAM / WXブリーフィング / 料金計算 / 航空路マップ / PDF加工 / 空港使用届 / FedEx請求照合 / 機体セールス資料 mcj-companyapps.pages.dev Pages Functions(22本) KV COMPARISON_CACHE
他はService Binding越し
HTML 17.6k
JS 8.4k

業務システム

ディレクトリ役割本番URLWorker(API数)データ規模
mcj-line-bot LINE の送信口と webhook 受け口。トークンを1か所に集約し、各システムの通知はここを通す 公開ページなし mcj-line-bot(10) D1 mcj-line-bot-prod
KV line-shared-images
TS 3.6k
mcj-alcohol アルコール検査記録・点検記録・教育記録。検査のリマインドも持つ mcj-alcohol.pages.dev mcj-alcohol-api(26)
cron 5分 / 30分
D1 mcj-alcohol-prod HTML 3.8k
TS 1.5k / SQL 4.2k
mcj-shift 電話当番シフト表。残業・日勤リマインドと月次シフトの自動生成 mcj-companyapps.pages.dev/shift/ mcj-shift-api(20)
cron 30分
D1 mcj-shift-prod HTML 1.4k
TS 2.2k
SQL 0.3k
mcj-crew 乗員向けポータル(PWA)。本人のフライトアサイン・電話番シフト・乗務NG日 mcj-crew.pages.dev mcj-crew-api(19)
cron 15分
D1 mcj-crew-prod(通知だけ)
業務データは master / schedule / shift へ中継
HTML 2.8k
TS 1.8k
mcj-usage Cloudflare 使用量と LINE メッセージ枠の監視。上限に当たる前に LINE で警告する 公開ページなし
画面は companyapps 内
mcj-usage-api(5)
cron 30分
D1 mcj-usage-prod TS 0.7k
SQL 48行
mcj-maintenance 整備管理。Due / Tolerance 計算(3レジーム+アンカー) mcj-maintenance.pages.dev Pages Functions(8本) D1 mcj-maintenance HTML 3.1k
JS 1.5k
mcj-sales 代理店ポータル(空き状況カレンダー・問合せ・TRNG残枠) mcj-sales.pages.dev 専用Workerなし
reservation-api に相乗り
(reservation の D1) HTML 7.0k
mcj-ownerportal オーナー向けポータル(仮押さえ・稼働実績) mcj-ownerportal.pages.dev 専用Workerなし
reservation-api に相乗り
(reservation の D1) HTML 1.7k
mcj-pricing 料金計算エンジン(API専業)。HP料金の凍結版 v0 を含む 公開ページなし
画面は companyapps 内
mcj-pricing-api(8) KV PRICING_PARAMS
master の D1 を直接参照
TS 1.3k
mcj-wxbrief WXブリーフィングの自動生成・LINE配信。Browser Rendering で PDF 化 公開ページなし
画面は companyapps 内
mcj-wxbrief-api(12)
cron 日次
R2 mcj-wxbrief TS 1.6k
mcj-airport-usage 空港使用届。PDF様式への配置プリセットと AI 取り込み 画面は companyapps 内
/airport-usage
mcj-airport-usage-api(26) D1 mcj-airport-usage-prod
R2 …-forms
TS 1.0k
SQL 0.6k

要確認・休眠

ディレクトリ状態内容
mcj-trial 要確認 体験搭乗の会員システム(ログイン・パスワード再発行メール)。TS 1.1k。 wrangler.toml が参照する D1 mcj-trial-prod が Cloudflare 上に存在しない — Worker は未デプロイか、DBが削除済みと思われる。使うなら作り直し、使わないなら撤去
line-secretary 休眠 旧 LINE 秘書 Bot(TS 1.4k)。機能は mcj-shift / mcj-line-bot に移設済み。 wrangler.jsonc を使う唯一のプロジェクト。改修はここではなく移設先で行う
撤去済み。2026-09-28 に11プロジェクト(mcj-lp / mcj-app / mcj-journey-log / mcj-agent-portal / mcj-ops / mcj-law / mcj-finance / mcj-calendar / mcj-booking / mcj-quote など)、 2026-10 に mcj-crew-mgmt(乗員データの Excel 取り込み)を撤去した。 Pages・Worker・D1・KV ごと消してあるので、古い資料に出てくる URL は繋がらない。

Pages プロジェクトと Git 連携の対応(Cloudflare 実機から取得)

Pages プロジェクトGit 連携由来マージで本番に出るか
mcj-master / mcj-schedule / mcj-reservation / mcj-companyapps / mcj-shift / mcj-maintenance / mcj-sales / mcj-ownerportal / mcj-alcohol / mcj-trial / mcj-crewありこのリポジトリ出る(自動デプロイ)
mcj-web / mcj-web-adminあり別リポジトリ mcj-webこのリポジトリとは無関係
mcj-portalなし不明(本番ソースがこのリポジトリに無い)出ない。更新は要相談
mcj-glossary / mcj-fleet / mcj-accounting / mcj-internal-q2-2026 / mcj-tsukamoto / jetx 系 / albatross 系なし過去の単発資料・試作数か月更新なし。実質廃止

D1(主データベース・10本)

SQLite 互換のマネージドDB。1プロジェクト=1 D1 が原則で、DB 間の JOIN はできない。 横断が必要なところは Service Binding 越しに API で取りに行っている。

データベース名所有プロジェクトサイズ主なテーブル
mcj-master-prodmcj-master432 KB aircraft aircraft_registrations aircraft_types airports crew airport_type_ops(空港×型式の就航可否) crew_type_ops airport_alerts handling_companies fuel_suppliers line_groups price_books price_rules price_zones ほか計23
mcj-schedule-prodmcj-schedule29 MB action_plans(行動予定の単位) action_plan_legs action_plan_tasks action_plan_crew action_plan_timeline plan_changes deleted_plans crew_unavailable(乗務NG日) fpl_flights fpl_messages wb_leg_input xo_push_* ほか計33
mcj-reservation-prodmcj-reservation / mcj-sales / mcj-ownerportal22 MB reservations flight_events order_quotes(見積の原本) order_messages(案件チャット) charter_request_forms(運航依頼書) agencies owners customer_contacts handling_fees trng_days tf_slots push_subscriptions ほか計54
mcj-shift-prodmcj-shift3.0 MB staff shifts shift_months reminder_ack reminder_snooze notification_log
mcj-alcohol-prodmcj-alcohol1.7 MB test_records devices device_inspections education_records inspection_supervisors crew kv_store
mcj-maintenancemcj-maintenance96 KB aircraft items history
mcj-airport-usage-prodmcj-airport-usage140 KB forms form_versions form_fields field_defaults airport_usage_profiles standing_documents
mcj-line-bot-prodmcj-line-bot52 KB kv_store(送信状態の保持のみ。業務データは持たない)
mcj-usage-prodmcj-usage40 KB cf_usage_daily line_quota_monthly kv_store
mcj-crew-prodmcj-crew44 KB notifications push_subscriptions(クルーポータルの通知だけ。業務データは持たない)
同一アカウントに残っている無関係なD1が2本ある — mcj-web-news(別リポジトリ mcj-web のもの)と mcj-accounting-prod(撤去済みプロジェクトの残骸、2026-05 以降更新なし)。削除判断は未実施。

KV(バインド済み 3ネームスペース)

ネームスペースバインド名使う側中身
COMPARISON_CACHE COMPARISON_CACHE
PRICING_PARAMS
mcj-companyapps
mcj-pricing-api
1つのネームスペースを2つの用途で共有している。FedEx請求照合のキャッシュと料金パラメータが同居
line-shared-imagesLINE_SHARED_IMAGESmcj-line-botLINE共有用に生成した画面スクショ(html2canvas 出力)
mcj-master-api-DOC_FILESDOC_FILESmcj-master-api機体資料のメタ情報
Cloudflare 上には他に AP_CACHE / GLOSSARY_COMMENTS / OCR_CACHE / WXBRIEF_KV の 4つがあるが、現在のコードはどこからもバインドしていない(撤去済みプロジェクトまたは休眠コードの残骸)。

R2(オブジェクトストレージ・4バケット)

mcj-master-aircraft-docs
機体ごとの書類 PDF(耐空証明・保険証券など)
mcj-reservation-banners
TRNG / 遊覧のバナー画像
mcj-wxbrief
自動生成した WX ブリーフィングの PDF・画像の保管庫
mcj-airport-usage-forms
空港使用届の様式 PDF と取り込み済みファイル

リポジトリ外にあるデータ

引継ぎで一番漏れやすいのがここ。コードを読んでも場所が分からない。

何どこ用途・注意
空港情報スプレッドシートGoogle スプレッドシート「空港情報」 master の airports の元データ。抽出用 GAS が mcj-master/tools/gas/airport-info-export.gs。セルの色に意味がある
FedEx 請求照合の対象スプシGoogle スプレッドシート(ID は Pages secret SHEETS_SPREADSHEET_ID) サービスアカウント経由で読み取り専用アクセス
77KC 予約状況スナップショットGoogle スプレッドシート「77KC 予約状況」 本番 D1 から月次で集計して追記する運用ツール
空港情報 raw CSV担当者PCのローカル 共有ストレージに無い。引継ぎ時に受け渡しが必要
D1 バックアップ(ダンプ)担当者PCのリポジトリ外 絶対にコミットしない。乗員の社員証番号=社内ログインのパスワードが入っている
設計資料・日報・議事録Scrapbox mcj-system 日次の作業ログと MTG 議事録。要件の経緯はここにある
社内ポータルの本番ソース所在不明(このリポジトリに無い) mcj-portal.pages.dev。このリポジトリから deploy すると既存ページが消えるリスク
会社HP別リポジトリ mcj-web HP・ドメイン・サイト移行の資料はすべて向こう側に置く規約

バックアップとリストア

D1 には「ひとつ前に戻す」機能が無い。特に mcj-master-prod は全社の単一情報源で、 1行の取り違えが全システムに波及する。master のデータを変える作業は、必ず先に全体バックアップを取ってから始める。 手順は mcj-master/tools/backup/README.md。
# master の全体バックアップ(読み取りのみ。書き込みは発生しない)
npx wrangler d1 export mcj-master-prod --remote \
  --output=<リポジトリ外のパス>/mcj-master-prod-YYYYMMDD-HHMM.sql
  • --remote を忘れるとローカルの空DBを吐く(気づきにくい)
  • 戻すときは「丸ごとインポート」が無いので、ダンプから対象テーブルの INSERT だけ抜き出して当てる
  • 自動バックアップは設定されていない。作業前の手動取得のみ。定期化は改善候補

認証方式

Auth0 / Firebase Auth / JWT ライブラリは使っていない。 WebCrypto(crypto.subtle)で HMAC 署名トークンを自前生成・検証している。 設計資料は docs/internal-apps-auth.html。

社内ユーザー

「氏名 + 社員証番号」で master の crew テーブルと照合し、HMAC 署名トークンを発行。

  • ログインできるのは crew に「若者」タグがあり社員証番号が登録済みの人
  • トークン有効期間 14日・端末単位(localStorage)
  • 社員証番号が実質パスワードなので、master のダンプは最高機密

代理店・オーナー

ID + パスワードで照合し、別の署名鍵でトークン発行。

  • 鍵は AGENCY_AUTH_SECRET / OWNER_AUTH_SECRET と社内用で別系統
  • reservation-api の /api/* は既定拒否+公開許可リスト方式

鍵の ON/OFF の仕組み

AUTH_SECRET が未設定なら認証は素通しになる設計。

  • コードのデプロイと「鍵を掛ける」を分離できる
  • 解除も secret を削除するだけで済む(revert 不要)
  • Pages は secret を消しても再デプロイするまで効き続ける。Worker は即反映
画面の認証はブラウザ側のガード。auth.js は未ログインなら login.html へ飛ばすが、 HTML そのものは誰でも取得できる(この画面も同じ)。守られているのは API が返すデータの方で、 画面の中身は秘密にできない。
セッションはアプリごとに独立(mcj_sched_auth / mcj_apps_auth / mcj_alc_auth …)。 pages.dev は公開サフィックスのためクッキーを横断共有できず、シングルサインオンにできない。 統合するなら独自ドメイン化か SSO の導入が必要。

シークレットの管理場所

リポジトリには一切コミットしない。.dev.vars / .env は gitignore 済みで、 .dev.vars.example にキー名だけを残す運用。

本番(Worker)

cd <proj>/workers
npx wrangler secret put NAME

実行ディレクトリの Worker に設定される。ディレクトリ違いの事故が起きやすい

本番(Pages)

npx wrangler pages secret put NAME \
  --project-name <pages-project>

ダッシュボードの Settings → Variables and Secrets でも可。反映には再デプロイが必要

ローカル開発

<proj>/workers/.dev.vars
(gitignore 済)

テンプレートは .dev.vars.example。実値は現担当者からの個別受け渡し

シークレット一覧(名前と置き場所。値は含まない)

名前置き場所用途
AUTH_SECRETschedule-api / reservation-api / alcohol-api / crew-api Worker
companyapps / maintenance Pages
社内ログインの署名鍵。未設定=認証なし
AGENCY_AUTH_SECRETreservation-api代理店ポータルのログイン
OWNER_AUTH_SECRETreservation-apiオーナーポータルのログイン
AGENCY_MASTER_PW_HASHreservation-apiMCJ側が代理店画面を閲覧するモードのパスワードハッシュ
LINE_CHANNEL_ACCESS_TOKEN
LINE_CHANNEL_SECRET
line-botLINE Messaging API の送信とwebhook署名検証
SWIM_ID / SWIM_PASSWORDschedule-api国交省 SWIM へのログイン(PKG・ATS・FPL)
SWIM_INTERNAL_KEYschedule-api + companyapps PagesSWIM 中継 API の内部認可(両側で同じ値)
PRICING_INTERNAL_KEY
PRICING_ADMIN_KEY
pricing-api + companyapps Pages料金APIの内部呼び出しとパラメータ編集
FPL_TEMPLATE_ADMIN_KEYcompanyapps PagesFPL テンプレートの管理操作
XO_OPERATOR_ID / XO_AUTH_TOKENschedule-apiXO(Vista Global)へのスケジュール配信
VAPID_PUBLIC_KEY
VAPID_PRIVATE_KEY
reservation-apiWeb Push(ブラウザ通知)の署名
ADMIN_PUSH_TOKENline-bot管理操作のプッシュ送信
GOOGLE_SA_EMAIL
GOOGLE_SA_PRIVATE_KEY
SHEETS_SPREADSHEET_ID
companyapps PagesGoogle Sheets 読み取り(FedEx請求照合)のサービスアカウント
MAIL_HOST / MAIL_USER / MAIL_PASS
WB_MAIL_USER / WB_MAIL_PASS
trial-api / schedule-api自社 SMTP(mcjet.jp:587)からのメール送信
ANTHROPIC_API_KEYairport-usage-api空港使用届 PDF の AI 取り込み
CLOUDFLARE_API_TOKENusage-apiCloudflare 使用量モニタ(自アカウントの使用量を読む)
FR24_API_TOKENローカルのみFR24 航跡データ採取ツール。本番 Worker では未使用
GITHUB_TOKENline-secretary 休眠旧秘書Botの残骸
外部に引き継ぐときに必ずやること —— どの値を共有し、どれをローテーションするかを決める。 特に LINE_CHANNEL_ACCESS_TOKEN・SWIM_PASSWORD・GOOGLE_SA_PRIVATE_KEY・ ANTHROPIC_API_KEY は漏れたときの影響が社外に及ぶ。

守りの形

本番は *.pages.dev / *.workers.dev に出ている。 守っているのはアプリ層の認証で、そこが実質的に唯一の壁という前提で設計している。 ここは「どういう考え方で守っているか」と「触るときに守るルール」をまとめたもの。 現状の棚卸しと残課題は別資料にある(末尾参照)。

Cloudflare 側でまかなわれている層

  • DDoS 緩和・TLS 終端(全通信が HTTPS)
  • D1 / KV / R2 の保存時暗号化
  • R2 は公開URL(r2.dev)を使わない方針。 ファイルへの入口は必ず Worker を通す

自分たちで作っている層

  • 既定拒否の /api/* 関門
  • HMAC 署名トークン(WebCrypto で自前生成・検証)
  • LINE webhook の署名検証
  • 機微な列をサーバ側で落とす

この構成に含まれていないもの

必要になったら別途入れる、と整理しているもの。

  • IP制限・VPN・Cloudflare Access
  • SSO・多要素認証
  • WAF のカスタムルール
  • 外部診断(第三者によるテスト)

誰が何を見られるか

権限の設計。どの画面を足すときも、この5つのどれに当たるかを先に決める。

立場認証見える範囲
社内 氏名 + 社員証番号
(crew に「若者」タグがある人)
行動予定表・予約管理・社内アプリ・整備・アルコール・シフトの全機能。トークンは14日・端末単位
乗員 同上(クルーポータル専用セッション) 本人の分だけ(フライトアサイン・電話番シフト・乗務NG日・通知)
代理店 / オーナー ID + パスワード
(社内とは別系統の署名鍵)
自社・自機に関する範囲のみ。空き状況・問合せ・仮押さえ
役員セッション 社内と同じ 案件チャットはサーバ側で外している。画面を隠すだけでは API を直接叩けるため
内部(Worker 同士) Service Binding のホスト名で判定 素通し。各 Worker の auth.ts の INTERNAL_HOSTS が許可リスト
顧客に URL を渡して開いてもらう口(key リンク)だけは、この5つの外側にある。 運航依頼書・TF申込フォームなど。ログイン不要で開ける代わりに、 推測できない key を知っていることが認証そのものという作り。 URL が流れた時点で誰でも読めるので、置く情報の範囲は慎重に決める。

仕組みとして効いている3つ

1. 既定拒否

/api/* はまず全部拒否し、公開したい口だけを明示的に許可する。

許可リスト方式だと「API を足すたびに書き足すのを忘れる」事故が起きる。 既定拒否なら新しい口は最初から閉じている。足し忘れても漏れない側に倒す。

2. 鍵の ON/OFF は AUTH_SECRET だけ

未設定なら素通し。デプロイと鍵掛けを分けられ、戻すのも secret delete 1発で済む。

裏返すと、コードが正しくても secret が無ければ開いたまま。 閉じているかは /api/auth/state で確認する。Pages は再デプロイしないと反映されない。

3. 内部呼び出しはホスト名で判定

Service Binding 経由は https://internal/… のような架空ホスト名で届く。 これを素通しにして内部通信を通している。

ここを塞ぐと内部が静かに死ぬ。呼び出し側が例外を握りつぶすので、 画面にもログにも出ない。鍵を足すときは必ず許可リストを確認する。

画面は秘密を守らない

auth.js はブラウザ側のガードで、未ログインなら login.html へ飛ばすだけ。 HTML そのものは誰でも取得できる(この画面も同じ)。 守られているのは API が返すデータの方であって、画面に書いた内容は秘密にできない。
  • 機密は必ずサーバ側で落とす。画面で非表示にするだけでは、API を直接叩けば読めてしまう。 master が crew の機微な列を公開経路から削っているのが実例。 案件チャットを役員セッションから外しているのも同じ考え方
  • トークンは fetch にしか付かない。<a href="/api/…">・ download・iframe src はブラウザの直接ナビゲーションなので Authorization が無く 401 になる。 API の中身をユーザーに渡すときは fetch → blob(URL.createObjectURL)にする。 鍵を掛けるまでは動いていたので、鍵掛けの日から静かに壊れる種類の不具合
  • CORS は全オリジン許可。防御はトークンの方で、オリジンでは何も守っていないと理解しておく

触るときのルール

  • D1 のダンプをコミットしない・チャットに貼らない。 crew の社員証番号は社内ログインのパスワードそのもの。保存はリポジトリの外に
  • 内部からしか呼ばない Worker は workers_dev = false にする。 公開ルートが無ければ、そもそも外から届かない。いちばん確実
  • 公開許可リストに「とりあえず」足さない。 一度開けた口は閉じ忘れる。直リンクが必要なら key 必須にする
  • 画面側で隠して済ませない。サーバで落とす
  • 秘密をコードに書かない。wrangler secret put / .dev.vars に置く(→「認証とシークレット」)
  • 鍵を足したら実際に叩いて確かめる。ソースを読むテストは、本番が古いままでも通ってしまう

何かあったときの初動

  1. 鍵を掛ける / 外す — wrangler secret put AUTH_SECRET で即座に全閉、 secret delete で元に戻る。Worker は即反映、Pages は再デプロイが要る
  2. LINE の署名検証を戻す — LINE_ENFORCE_SIGNATURE を "0" にして deploy。約30秒で復旧
  3. master を触る前に全体バックアップ — D1 に巻き戻しは無い。 npx wrangler d1 export mcj-master-prod --remote --output=<リポジトリ外>
  4. 生きているかを確かめる非破壊GET(デプロイ後の確認にも使う)
    <worker>/api/auth/state            # locked:true なら鍵が入っている
    mcj-schedule-api/api/auth/users    # 0人なら internal / master 経路が壊れている
    mcj-shift-api/api/secretary-crew   # 0件なら dummy 経路が壊れている
  5. ログは Cloudflare ダッシュボード(外部APMなし)。保持期間が短いので、 疑わしいときはその場で記録を取る

現状の棚卸しと残課題はどこにあるか

このページには載せていない。この画面は URL を知っていれば誰でも読めるため、 「いまどこが弱いか」はここに書かない方針にしている。次を見ること。
  • 経営向けの報告資料(概要版・詳細版の2本立て)— 費用と残件の優先順位。最新は第2版
  • Scrapbox mcj-system — 監査の記録と、塞いだ穴ごとの経緯
  • 各 PR — 何をどう直したかはコミットと PR 本文に残っている
  • docs/internal-apps-auth.html — 社内ログインの設計そのもの

デプロイ経路(Pages と Workers で違う)

ここが一番の躓きどころ。Pages は main マージで自動デプロイされるが、 Workers は Git 連携を設定していないため、マージ後に手動 wrangler deploy が必要。 フロントだけ新しくなって API が古いまま、という半端な状態になりやすい。
これは Cloudflare 側の制約ではなく、うちの設定の問題。 Workers にも Pages と同じ Git 連携(Workers Builds)があり、Worker ごとに root directory(例 mcj-schedule/workers)と build watch paths を指定すれば このモノレポ構成のまま入る。GitHub Actions + cloudflare/wrangler-action でも同じことができる。 導入すれば下の「未反映コミットの滞留」は消える。優先度の高い改善点。
Cloudflare Pages(フロント)Cloudflare Workers(API)
Git 連携あり(11プロジェクト)未設定(Workers Builds で可能。やっていないだけ)
ソースの履歴どちらも mcj-engineering に全部入っており git で完全に追える。 追えないのは「いま本番に出ているのがどのコミットか」で、これは手動 deploy が commit と紐づかないため (wrangler deployments list の Source は Unknown (deployment) になる)
本番反映main マージで自動マージ後に cd <proj>/workers && npx wrangler deploy
ビルドなし(静的ファイルをそのまま配信)wrangler が esbuild で束ねる
ロールバックダッシュボードから過去デプロイを再公開wrangler rollback または前コミットから再 deploy
注意新規追加アセットは数十秒 404 を返す期間があるdeploy 直後 30〜60秒は新旧が混ざり断続的に 404/401 が返る

複数 Worker をまたぐ変更の手順

  1. 触った Worker を全部出す。主役でない Worker を1行だけ直したときに取りこぼす。 PR をマージしたら git diff --stat <merge>^ <merge> -- '*/workers/*' で触れた Worker を列挙してから deploy する
    node scripts/check-worker-deploys.mjs   # 全 Worker の 最終コミット vs 最終デプロイ
  2. 依存の下流から deploy する — master-api を先に出し、その後 shift / schedule / reservation。 Pages が参照する新規 Worker は、Pages より先に出す(でないと Pages 全体がデプロイ失敗する)
  3. D1 のマイグレーションは --remote を必ず付ける
    npx wrangler d1 execute <db-name> --remote --file=migrations/xxx.sql
    付け忘れるとローカルの空DBにだけ当たり、本番は無反応のまま壊れる
  4. deploy 後 1分ほど置いて、数回サンプルして安定を確認してから完了とする
2026-10-12 の実例。cron の移設で mcj-line-bot の内部ホスト許可リストに1行足したのに、 その Worker を deploy しなかった。移設先と移設元は出したので終わったつもりでいた結果、 アルコール検知器の点検リマインドが3日間 LINE に飛ばなかった (Bot が 401 を返し、呼び出し側は例外を握りつぶすので画面にもログにも出ない)。

Git 運用ルール

ブランチとPR

  • main 保護。直 push 禁止
  • ブランチ名は feature/<説明> または fix/<説明>
  • PR 必須・レビュー1名以上
  • コミットメッセージは日本語可。変更内容が分かる粒度で
  • 関連する複数項目は1 PR にまとめる運用

作業ツリーの分離(重要)

  • 本クローンではコードを書かない。最新 main・クリーンに保ち、確認とPRレビュー用に留める
  • 書く作業は git worktree add ../_wt/<task> -b <type>/<task> origin/main で専用ツリーを切る
  • git add -A / git add . / git commit -a は使わない。 自分が触っていないファイルまで stage される
  • これらは tools/claude-hooks/ のフックで機械的に拒否している

背景:同一の作業ツリーを複数の作業セッションが共有しており、 2026-09-18 に git commit -a で無関係な編集中ファイルが main までマージされた事故があった。

CI(GitHub Actions・PR時のみ)

「間違えてもエラーにならず、出力だけが静かにずれる」種類のバグをマージ前に止めるためのもの。 網羅的なテストスイートではない。

ワークフロー対象何を止めるか
frontend-syntax各 frontend/ の HTMLインライン <script> の構文エラー。1つで画面の全機能が死ぬため
sql-d1-limits全 *.sqlD1 の上限(バインド変数100個・巨大 compound SELECT)に当たる SQL。 ローカル検証に使う node:sqlite は上限が緩くすり抜ける
pricing-tests料金エンジン丸め単位・立ち寄り回数の数え方・凍結版 v0 の再現。金額が静かにずれる変更
fplform-testsFPL 整形・作成ZZZZ置換・0埋め・右詰め。帳票の中身だけがずれる
preflight-testsNOTAM / WXブリーフィングNOTAM 本文の読み取りとハイライト境界

テストの実情

  • Jest / Vitest は未導入。Node 標準の node:test を使った *.test.mjs が26本のみ
  • 対象は副作用のない純粋関数に限られる(料金計算、FPL整形、DH人員の再構成、整備トレランス、W&B、Web Push署名など)
  • 画面と API の結合テストは手動確認。ただし reservation にはローカル E2E ハーネスがあり、本番非破壊で実経路を叩ける
  • 実行は node --test <file> を手で叩く

定期処理(Cron Triggers)

Worker間隔処理内容
mcj-schedule-api30分XO配信の送信、受注・依頼書への反映の送り直し、 削除ゴミ箱の24時間purge、SWIM からの FPL 通報取り込み(SWIM側から消えるので落とすと二度と取れない)
mcj-alcohol-api5分アルコール検査の承認リマインド / 未記入リマインド
mcj-alcohol-api30分センサー点検・月次点検・日常点検のリマインド
mcj-shift-api30分残業・日勤リマインド、月次シフトの自動生成
mcj-usage-api30分LINEメッセージ枠の監視(閾値で警告)、Cloudflare 使用量の監視
mcj-crew-api15分クルーポータルの通知ダイジェスト(本人のアサイン変更をまとめて知らせる)
mcj-wxbrief-api日次 06:00/06:15/06:30 JSTWXブリーフィングの自動生成と LINE 配信
mcj-master-api日次 00:00 JST機体レジ番の現行値を同期する
Workers の実行時刻は UTC。new Date() のローカル時刻は UTC になるので、 JST が必要な箇所は明示的に +9h している(datetime('now','localtime') も D1 上では UTC)。 cron 式も UTC で書く。

監視とコスト

  • 各 Worker は [observability] enabled = true。ログは Cloudflare ダッシュボードで見る(外部APMなし)
  • 異常の一次検知は mcj-usage の自前 cron 監視+LINE 通知(LINEメッセージ枠と Cloudflare 使用量)
  • D1 の日次上限に当たって全社ログインが止まった事例がある。Workers Paid プランの範囲内で運用中
  • アラートの宛先は LINE グループ。メールの常時監視はしていない

外部に渡すもの・渡す順番

  1. GitHub への招待 — mcjet-dev/mcj-engineering(社内システム)と、HPも見るなら mcj-web。 コードとドキュメントがここに全部ある
  2. Cloudflare アカウントへの招待 — mcjet-dev アカウント。 Workers / Pages / D1 / KV / R2 の権限。本番DBを触れるので権限範囲は要検討
  3. この資料と CLAUDE.md を読んでもらう — CLAUDE.md がコーディング規約・禁止事項・ 過去の事故とその対策の一次情報。docs/onboarding.md は環境構築手順(ただし後述のとおり一部古い)
  4. シークレットの受け渡し方針を決める — 全部渡すのか、ローテーションしてから渡すのか。 .dev.vars の中身は口頭・パスワード管理ツール経由などで個別に渡す(チャットに貼らない)
  5. Scrapbox mcj-system への招待 — 要件の経緯・日報・MTG議事録。 「なぜこの作りなのか」はここにしか無いものが多い
  6. Google ドライブ/スプレッドシートの共有 — 「空港情報」「77KC 予約状況」ほか。 コードから参照しているがリポジトリには無い
  7. LINE 公式アカウント(Messaging API)の管理権限 — Bot の改修には LINE Developers 側の権限も要る
  8. SWIM(国交省)のアカウント — 利用申請ベース。担当者名義のものを引き継ぐのか追加申請するのかを確認

開発環境の立ち上げ(初日にやること)

# 1. ツール
#    Git for Windows / Node.js LTS(一部テストは Node 22 以降が必要) / VS Code
npm install -g wrangler
wrangler login                     # Cloudflare アカウントへの招待を受けた後

# 2. clone(親フォルダではなくリポジトリ直下で作業する)
git clone https://github.com/mcjet-dev/mcj-engineering.git
cd mcj-engineering

# 3. 作業用ツリーを切る(本クローンでは書かない)
git worktree add ../_wt/my-task -b feature/my-task origin/main
cd ../_wt/my-task

# 4. 対象プロジェクトを起動
cd mcj-schedule/workers
npm install
npx wrangler dev                   # http://localhost:8787

# 5. フロントは静的なのでファイルを開くだけでも動く画面が多い
#    API を叩く画面は wrangler dev と併用する
docs/onboarding.md は内容が古い。次の3点は現行ルールと食い違っているので、この資料側を正とする。
  • 例として挙がっている mcj-booking は撤去済み
  • git add -A を推奨しているが、現在は禁止(フックで拒否される)
  • 「手動 wrangler deploy は NG」と書かれているが、Workers は手動 deploy が必須に変わった

Windows 環境固有の注意

Windows PC から Git Bash を使うと、エラーにならずに違うものが出来上がる事故が複数起きている。

やりがちなこと何が起きるか対策
cd C:\Users\...引用符の外の \ を bash がエスケープ文字として食い、別のディレクトリでコマンドが走るパスは /c/Users/... 形式で書く
ヒアドキュメントでソースを書く本文の \\ が \ に潰れる。正規表現の意味が変わったまま保存されるファイルはエディタで書く。ヒアドキュメントで流し込まない
cmd1 ; cmd2cd が失敗しても後続が走る&& で繋ぐ

PowerShell では \ は通常の文字なのでこの問題は起きない。パス操作が主なコマンドは PowerShell の方が安全。 判定ロジックは tools/claude-hooks/guard-bash-backslash.mjs にフックとして入っている。

引継ぎ前に決めておきたいこと

権限の範囲

  • Cloudflare の権限を本番DB書き込み可で渡すか、読み取り主体に絞るか
  • mcj-master-prod を触る作業の承認フローをどうするか(現状は「触る前に全体バックアップ+高橋に相談」)
  • PR のマージ権限を渡すか(現状はレビュー後に手動マージ)

作業の線引き

  • 任せる範囲(新規開発 / 既存改修 / 基盤整備のどれか)
  • 障害時の一次対応は誰か。連絡経路(現状は LINE グループ)
  • 所在不明な mcj-portal の本番ソースを探すか、作り直すか

踏みやすい落とし穴

どれも実際に起きたもの。共通点は「エラーにならないので、結果を見ても気づけない」こと。

症状原因対策
Worker 間 fetch が 1042 エラー同一アカウントの Worker を URL で fetch したService Binding を使う
内部呼び出しが黙って全部落ちるService Binding はホスト名が架空(https://dummy/...)。認証を足すとそこで弾かれ、呼び出し側が例外を握りつぶす架空ホスト名を素通しにする(INTERNAL_HOSTS)。足したらその Worker も deploy する
Pages 全体がデプロイできないPages が参照する Worker がまだ存在しないWorker を先に deploy する
外部API が CORS エラーService Worker が外部 fetch を壊すPages Functions のプロキシ経由にする
migration が本番だけで落ちるD1 のバインド変数(100個)・compound SELECT の項数上限。node:sqlite は上限が緩く再現しないINSERT を文ごとに分ける。CI の sql-d1-limits で検査
本番DBが更新されない/Bot が無反応wrangler d1 execute に --remote を付け忘れた必ず付ける。ローカルの空DBに当たっても成功したように見える
本番にある列が schema.sql に無い本番へ ALTER で足した列が schema.sql に書き戻されていない。同じ意味の列をもう1本足しかける列を足す前に本番の実物を見る(SELECT sql FROM sqlite_master)
secret を消したのに認証が効き続けるPages の secret は再デプロイまで反映されないPages は再デプロイする(Worker は即反映)
iPhone で表示が崩れるposition:fixed が iOS Safari で効かないposition:absolute + -webkit-fill-available
画面の全機能が死ぬインライン <script> の構文エラー1つCI の frontend-syntax で検知
KV のデータが消えるlocalStorage / KV 同期で空データを上書きロード完了ガード・空データ書き込み禁止
新規追加したファイルが 404Pages の新規アセットは反映まで数十秒かかる待つ。デプロイ直後の検証は数回サンプルする
時刻が9時間ずれるWorkers のローカル時刻は UTCJST が必要なら明示変換

技術的負債・改善候補

構造

  • 画面が巨大な単一HTML — 描画・状態管理・バリデーションが全部インラインで、分割もテストもしづらい
  • 型チェックが CI で走っていない — npm run typecheck があるのは一部プロジェクトのみで、CI には入っていない
  • schedule ↔ reservation の循環依存 — 片方の変更がもう片方に波及する
  • D1 をまたぐ参照が JOIN できない — 表示順の不整合などが残っている
  • pricing-api が master の D1 を直接バインド — API 越しの原則から外れている
  • KV 1本を2用途で共有(COMPARISON_CACHE = PRICING_PARAMS)

運用

  • Workers の Git 連携が未設定で手動 deploy — 未反映コミットが各 Worker に滞留する。 Workers Builds(root directory + build watch paths)を入れれば解消するので優先度は高い
  • D1 の自動バックアップが無い — 作業前の手動ダンプのみ。定期化が望ましい
  • ステージング環境が無い — mcj-shift-api-dev の定義だけあるが DB ID が placeholder で未整備
  • アプリごとに別ログイン — pages.dev ではクッキーを共有できず SSO 不可。独自ドメイン化が前提になる
  • Cloudflare 依存度 100% — 他クラウドへの移行は事実上作り直し

片付け待ちのもの

対象状態やること
mcj-trialD1 mcj-trial-prod が Cloudflare 上に存在しないWorker の稼働状況を確認し、使うなら DB を作り直す/使わないなら撤去
line-secretary休眠(機能は移設済み)削除してよいか確認
mcj-portal本番ソースの所在が不明探す/作り直す。このリポジトリから deploy すると既存ページが消える
AP_CACHE / GLOSSARY_COMMENTS / OCR_CACHE / WXBRIEF_KVどこからもバインドされていない KV中身を確認して削除
mcj-accounting-prod撤去済みプロジェクトの D1 が残っている中身を確認して削除
docs/onboarding.md記載が現行ルールと食い違う(3点)更新する
docs/tech-stack.html2026-08-10 時点の内容。撤去済みプロジェクトを現役として記載この資料で置き換えるか、更新する

関連資料の在りか

CLAUDE.md
コーディング規約・禁止事項・過去の事故と対策。最初に読むもの
docs/tech-stack.html
技術スタックの詳細(2026-08-10 時点・一部古い)
docs/onboarding.md
環境構築手順(一部古い)
docs/internal-apps-auth.html
社内ログインの設計(HMAC トークン・AUTH_SECRET の考え方)
system-map.html
プロジェクト間の関係図
<project>/docs/*.html
各業務の設計・壁打ち資料(129ファイル)。file:// で直接開ける自己完結HTML
mcj-master/tools/backup/README.md
master D1 のバックアップ・リストア手順
tools/claude-hooks/
事故防止フックの実体とテスト
Scrapbox mcj-system
日報・MTG議事録・要件の経緯