この資料の位置づけ
社内システム全体の見取り図。社外の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 実測)
コード規模(git 追跡ファイル、node_modules 除く)
| 種別 | ファイル | 行数 | 中身 |
|---|---|---|---|
| 画面 HTML | 138 | 89,598 | 1画面=1ファイル。CSS・JS も同じファイルに直書きが基本 |
| 設計・壁打ち資料 HTML | 129 | 63,953 | docs/ 配下。file:// で直接開く前提の自己完結HTML |
| TypeScript | 60 | 41,721 | Workers の API 実装 |
| JavaScript | 98 | 18,661 | フロント共通JS と Pages Functions |
| .mjs(ツール・テスト) | 177 | 36,790 | ローカル検証ハーネス・データ採取ツール・単体テスト26本 |
| SQL | 238 | 13,983 | schema.sql と migrations/ |
<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層構造とリクエストの流れ
どのプロジェクトもほぼ同じ形をしている。違うのは「どの層を持たないか」だけ。
段で見る依存
プロジェクト単位で、どの段がどの段を使うかを並べたもの。矢印は上から下の一方向だけで、 例外は「業務の芯」の中の相互参照だけ。新しいプロジェクトを足すときも、まずこの5段のどこに置くかを決める。
相関図(プロジェクト同士の呼び出し)
上の図から基盤への矢印を省いて、プロジェクト同士のやり取りだけを描いたもの。 master へは13本すべてが向かうので、描くと線が潰れて読めなくなる。
Worker 間の依存(Service Binding)
Worker 同士は URL fetch ではなく Service Binding で直結している。 同一アカウント内の Worker を URL で fetch すると Cloudflare の 1042 エラーになるため、この形が必須。 行は「呼ぶ側」、列は「呼ばれる側」。
| 呼ぶ側 \ 呼ばれる側 | master | line-bot | schedule | reservation | shift | alcohol | pricing | airport-usage | wxbrief | usage |
|---|---|---|---|---|---|---|---|---|---|---|
| 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/ 配下の資料は除く)、「-」はその層を持たないという意味。
中核(ここが止まると業務が止まる)
| ディレクトリ | 役割 | 本番URL | Worker(API数) | データ | 規模 |
|---|---|---|---|---|---|
| mcj-master | 全社マスタ(機体・空港・乗員・機種・料金表)。単一情報源 | mcj-master.pages.dev | mcj-master-api(62) cron 日次 |
D1 mcj-master-prodKV 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 |
業務システム
| ディレクトリ | 役割 | 本番URL | Worker(API数) | データ | 規模 |
|---|---|---|---|---|---|
| mcj-line-bot | LINE の送信口と webhook 受け口。トークンを1か所に集約し、各システムの通知はここを通す | 公開ページなし | mcj-line-bot(10) | D1 mcj-line-bot-prodKV 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_PARAMSmaster の 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-prodR2 …-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 を使う唯一のプロジェクト。改修はここではなく移設先で行う |
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-prod | mcj-master | 432 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-prod | mcj-schedule | 29 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-prod | mcj-reservation / mcj-sales / mcj-ownerportal | 22 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-prod | mcj-shift | 3.0 MB | staff shifts shift_months reminder_ack
reminder_snooze notification_log |
| mcj-alcohol-prod | mcj-alcohol | 1.7 MB | test_records devices device_inspections education_records
inspection_supervisors crew kv_store |
| mcj-maintenance | mcj-maintenance | 96 KB | aircraft items history |
| mcj-airport-usage-prod | mcj-airport-usage | 140 KB | forms form_versions form_fields field_defaults
airport_usage_profiles standing_documents |
| mcj-line-bot-prod | mcj-line-bot | 52 KB | kv_store(送信状態の保持のみ。業務データは持たない) |
| mcj-usage-prod | mcj-usage | 40 KB | cf_usage_daily line_quota_monthly kv_store |
| mcj-crew-prod | mcj-crew | 44 KB | notifications push_subscriptions(クルーポータルの通知だけ。業務データは持たない) |
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-images | LINE_SHARED_IMAGES | mcj-line-bot | LINE共有用に生成した画面スクショ(html2canvas 出力) |
| mcj-master-api-DOC_FILES | DOC_FILES | mcj-master-api | 機体資料のメタ情報 |
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・ドメイン・サイト移行の資料はすべて向こう側に置く規約 |
バックアップとリストア
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_SECRET | schedule-api / reservation-api / alcohol-api / crew-api Worker companyapps / maintenance Pages | 社内ログインの署名鍵。未設定=認証なし |
| AGENCY_AUTH_SECRET | reservation-api | 代理店ポータルのログイン |
| OWNER_AUTH_SECRET | reservation-api | オーナーポータルのログイン |
| AGENCY_MASTER_PW_HASH | reservation-api | MCJ側が代理店画面を閲覧するモードのパスワードハッシュ |
| LINE_CHANNEL_ACCESS_TOKEN LINE_CHANNEL_SECRET | line-bot | LINE Messaging API の送信とwebhook署名検証 |
| SWIM_ID / SWIM_PASSWORD | schedule-api | 国交省 SWIM へのログイン(PKG・ATS・FPL) |
| SWIM_INTERNAL_KEY | schedule-api + companyapps Pages | SWIM 中継 API の内部認可(両側で同じ値) |
| PRICING_INTERNAL_KEY PRICING_ADMIN_KEY | pricing-api + companyapps Pages | 料金APIの内部呼び出しとパラメータ編集 |
| FPL_TEMPLATE_ADMIN_KEY | companyapps Pages | FPL テンプレートの管理操作 |
| XO_OPERATOR_ID / XO_AUTH_TOKEN | schedule-api | XO(Vista Global)へのスケジュール配信 |
| VAPID_PUBLIC_KEY VAPID_PRIVATE_KEY | reservation-api | Web Push(ブラウザ通知)の署名 |
| ADMIN_PUSH_TOKEN | line-bot | 管理操作のプッシュ送信 |
| GOOGLE_SA_EMAIL GOOGLE_SA_PRIVATE_KEY SHEETS_SPREADSHEET_ID | companyapps Pages | Google Sheets 読み取り(FedEx請求照合)のサービスアカウント |
| MAIL_HOST / MAIL_USER / MAIL_PASS WB_MAIL_USER / WB_MAIL_PASS | trial-api / schedule-api | 自社 SMTP(mcjet.jp:587)からのメール送信 |
| ANTHROPIC_API_KEY | airport-usage-api | 空港使用届 PDF の AI 取り込み |
| CLOUDFLARE_API_TOKEN | usage-api | Cloudflare 使用量モニタ(自アカウントの使用量を読む) |
| FR24_API_TOKEN | ローカルのみ | FR24 航跡データ採取ツール。本番 Worker では未使用 |
| GITHUB_TOKEN | line-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 が許可リスト |
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に置く(→「認証とシークレット」) - 鍵を足したら実際に叩いて確かめる。ソースを読むテストは、本番が古いままでも通ってしまう
何かあったときの初動
- 鍵を掛ける / 外す —
wrangler secret put AUTH_SECRETで即座に全閉、secret deleteで元に戻る。Worker は即反映、Pages は再デプロイが要る - LINE の署名検証を戻す —
LINE_ENFORCE_SIGNATUREを"0"にして deploy。約30秒で復旧 - master を触る前に全体バックアップ — D1 に巻き戻しは無い。
npx wrangler d1 export mcj-master-prod --remote --output=<リポジトリ外> - 生きているかを確かめる非破壊GET(デプロイ後の確認にも使う)
<worker>/api/auth/state # locked:true なら鍵が入っている mcj-schedule-api/api/auth/users # 0人なら internal / master 経路が壊れている mcj-shift-api/api/secretary-crew # 0件なら dummy 経路が壊れている - ログは Cloudflare ダッシュボード(外部APMなし)。保持期間が短いので、 疑わしいときはその場で記録を取る
現状の棚卸しと残課題はどこにあるか
- 経営向けの報告資料(概要版・詳細版の2本立て)— 費用と残件の優先順位。最新は第2版
- Scrapbox
mcj-system— 監査の記録と、塞いだ穴ごとの経緯 - 各 PR — 何をどう直したかはコミットと PR 本文に残っている
docs/internal-apps-auth.html— 社内ログインの設計そのもの
デプロイ経路(Pages と Workers で違う)
wrangler deploy が必要。
フロントだけ新しくなって API が古いまま、という半端な状態になりやすい。
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 をまたぐ変更の手順
- 触った Worker を全部出す。主役でない Worker を1行だけ直したときに取りこぼす。
PR をマージしたら
git diff --stat <merge>^ <merge> -- '*/workers/*'で触れた Worker を列挙してから deploy するnode scripts/check-worker-deploys.mjs # 全 Worker の 最終コミット vs 最終デプロイ - 依存の下流から deploy する — master-api を先に出し、その後 shift / schedule / reservation。 Pages が参照する新規 Worker は、Pages より先に出す(でないと Pages 全体がデプロイ失敗する)
- D1 のマイグレーションは
--remoteを必ず付ける
付け忘れるとローカルの空DBにだけ当たり、本番は無反応のまま壊れるnpx wrangler d1 execute <db-name> --remote --file=migrations/xxx.sql - deploy 後 1分ほど置いて、数回サンプルして安定を確認してから完了とする
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 | 全 *.sql | D1 の上限(バインド変数100個・巨大 compound SELECT)に当たる SQL。
ローカル検証に使う node:sqlite は上限が緩くすり抜ける |
| pricing-tests | 料金エンジン | 丸め単位・立ち寄り回数の数え方・凍結版 v0 の再現。金額が静かにずれる変更 |
| fplform-tests | FPL 整形・作成 | ZZZZ置換・0埋め・右詰め。帳票の中身だけがずれる |
| preflight-tests | NOTAM / 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-api | 30分 | XO配信の送信、受注・依頼書への反映の送り直し、 削除ゴミ箱の24時間purge、SWIM からの FPL 通報取り込み(SWIM側から消えるので落とすと二度と取れない) |
| mcj-alcohol-api | 5分 | アルコール検査の承認リマインド / 未記入リマインド |
| mcj-alcohol-api | 30分 | センサー点検・月次点検・日常点検のリマインド |
| mcj-shift-api | 30分 | 残業・日勤リマインド、月次シフトの自動生成 |
| mcj-usage-api | 30分 | LINEメッセージ枠の監視(閾値で警告)、Cloudflare 使用量の監視 |
| mcj-crew-api | 15分 | クルーポータルの通知ダイジェスト(本人のアサイン変更をまとめて知らせる) |
| mcj-wxbrief-api | 日次 06:00/06:15/06:30 JST | WXブリーフィングの自動生成と LINE 配信 |
| mcj-master-api | 日次 00:00 JST | 機体レジ番の現行値を同期する |
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 グループ。メールの常時監視はしていない
外部に渡すもの・渡す順番
- GitHub への招待 —
mcjet-dev/mcj-engineering(社内システム)と、HPも見るならmcj-web。 コードとドキュメントがここに全部ある - Cloudflare アカウントへの招待 —
mcjet-devアカウント。 Workers / Pages / D1 / KV / R2 の権限。本番DBを触れるので権限範囲は要検討 - この資料と
CLAUDE.mdを読んでもらう —CLAUDE.mdがコーディング規約・禁止事項・ 過去の事故とその対策の一次情報。docs/onboarding.mdは環境構築手順(ただし後述のとおり一部古い) - シークレットの受け渡し方針を決める — 全部渡すのか、ローテーションしてから渡すのか。
.dev.varsの中身は口頭・パスワード管理ツール経由などで個別に渡す(チャットに貼らない) - Scrapbox
mcj-systemへの招待 — 要件の経緯・日報・MTG議事録。 「なぜこの作りなのか」はここにしか無いものが多い - Google ドライブ/スプレッドシートの共有 — 「空港情報」「77KC 予約状況」ほか。 コードから参照しているがリポジトリには無い
- LINE 公式アカウント(Messaging API)の管理権限 — Bot の改修には LINE Developers 側の権限も要る
- 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 ; cmd2 | cd が失敗しても後続が走る | && で繋ぐ |
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 同期で空データを上書き | ロード完了ガード・空データ書き込み禁止 |
| 新規追加したファイルが 404 | Pages の新規アセットは反映まで数十秒かかる | 待つ。デプロイ直後の検証は数回サンプルする |
| 時刻が9時間ずれる | Workers のローカル時刻は UTC | JST が必要なら明示変換 |
技術的負債・改善候補
構造
- 画面が巨大な単一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-trial | D1 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.html | 2026-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議事録・要件の経緯