TUAT T&F

東京農工大学陸上競技部の部員向けアプリ。練習記録・予定・出欠・大会結果・ノートを共有する。

• 公開URL: https://app.tuat-tf.workers.dev
• 技術: Next.js 16 / React 19 / Tailwind CSS 4 / Supabase（PC内で自前運用）

この文書は人間（管理者・後任）向けの入口。AIへの作業規則は AGENTS.md。

---

1. 全体の構成

部員のスマホ
   │
Cloudflare（公開URL・入口）
   │  Tunnelでつなぐ
本番PC（このWindows PC）
   └─ WSL（Ubuntu）の暗号化された領域 /var/lib/tuat-local
        ├─ アプリ（Next.js）
        ├─ DB（PostgreSQL）・ログイン（Supabase Auth）・DB API
        ├─ 画像
        └─ 定期処理（Jobs）・毎日のバックアップ
                 │
           Google Drive（部活アカウント）に暗号化して保存

• データの正本はこの本番PCの中だけ。ほかのPCの同名フォルダやDBは本番ではない。

• 本番用のDocker・DBは、通常のDockerとは別の専用のもの（unix:///run/tuat-local/docker.sock、DBコンテナは tuat-local-db）。

• WSL内の主なサービス（systemd）:

  サービス	役割
  tuat-local-app	アプリ本体
  tuat-local-jobs	定期処理（記録・大会・通知など）
  tuat-local-backup.timer	毎日1回のバックアップ
  tuat-local-tunnel	Cloudflareとの接続
  tuat-local-docker / tuat-local-containerd	本番専用のDocker

• Windows起動時は、タスクスケジューラの「TUAT Local Runtime」がWSLと上のサービスを起動する。

• 旧Vercel URLは案内用に残っているが、本番ではない。旧クラウドSupabaseは削除済み（2026-11-11）。旧R2も削除済み（2026-11-11）。旧中継は停止済み。どれも再開しない。

• アプリのコードは本番PCの構成だけに対応している（2026-11-11に、旧クラウドログイン・PC試験版・Vercel中継・R2画像の分岐を削除）。残してあるのは、旧Vercel URLで「URLが変わりました」と案内する分岐（src/proxy.ts の VERCEL_ENV === "production" と vercel.json）だけ。Vercel側のプロジェクトを消したら、この分岐も消してよい。

• Googleスプレッドシート連携はGAS（gas/）経由。現役は gas/sync-clasp/Code.js。gas/combined.gs（旧合体版）は使われている可能性があるため消さない。

2. 日常の運用

コマンドはすべて本番PCのPowerShellで実行する（管理者権限は不要）。

本番で動いている版を確かめる

https://app.tuat-tf.workers.dev/api/version を開く。version がGitのcommit SHA。

本番を更新する（本番反映）

1. 変更を master に入れてGitHubへpushする。
2. そのcommitのSHA（40桁）を確かめる: git rev-parse HEAD
3. 反映する:

wsl -d Ubuntu -u root -- python3 -I -B /mnt/d/TUAT_TF/ops/pc-host/pc-release.py release <40桁のSHA>

ビルド・切替・起動確認まで自動で行い、起動しなければ元の版に戻す。終わったら /api/version が新しいSHAになっていることを確かめる。

• 計画だけ見る: ... pc-release.py switch <SHA>（何も変えない）
• 古い版を片付ける: ... pc-release.py prune --keep 2（確認のみ）→ --execute を付けて実行
• package-lock.json が変わった版は、本番PCにnpmを入れていないため --node-modules <Linux用node_modulesのdir> が必要（package.json だけの変更なら不要）。2026-11-11の用意の仕方: WSLの一般ユーザー（ubuntu）のホームに使い捨てフォルダを作り、その commit の package.json と package-lock.json だけを置いて、WSL の Node 24 で Windows 側の npm（.../mise/installs/node/22.14.0/node_modules/npm/bin/npm-cli.js）を ci --ignore-scripts で動かす。反映が済んだらそのフォルダは消してよい。
• 反映が済んだ版のフォルダ内で git コマンドを打たない（中身の照合が崩れ、次回起動を拒否する）。

バックアップが動いているか確かめる

wsl -d Ubuntu -u root -- systemctl show tuat-local-backup.service -p Result -p ExecMainExitTimestamp

Result=success と最近の日時が出ればよい。毎日1回、DB・ログイン情報・画像を暗号化してGoogle Driveへ保存し、読み戻しと別DBへの復元まで確認している。

DBの中身を見る（読み取りのみ）

$OutputEncoding = New-Object System.Text.UTF8Encoding $false
[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false
"BEGIN READ ONLY; SELECT count(*) FROM profiles; ROLLBACK;" | wsl -d Ubuntu -u root -- docker --host unix:///run/tuat-local/docker.sock exec -i tuat-local-db psql --host=/tmp --port=18304 -U supabase_admin -d postgres -X -q -P pager=off

• BEGIN READ ONLY; ... ROLLBACK; で囲むと、間違ってもデータは変わらない。
• Windows PowerShellでは、SQLに日本語を入れると文字化けする。列の別名などは英字にする。
• 予定を誰が作ったかは practice_schedules.created_by（profiles.id）で分かる。編集した人は記録されていない。

3. 止まったとき

1. /api/version が開くか確かめる。
2. 開かなければ、サービスの状態を見る:

wsl -d Ubuntu -u root -- systemctl list-units --all --no-pager 'tuat-local*'

3. PCを再起動したあとなら、タスクスケジューラで「TUAT Local Runtime」が動いているか確かめる。再起動後は手で何も起動しなくても本番が戻る（2026-11-11に確認。起動の数秒後にタスクが始まり、サービスがすべて立ち上がった）。

過去に起きたこと

• 再起動後、前回の backup-owner.lock が残っていて起動に失敗したことがある。前のプロセスがもういないことを確かめてから外す必要がある。
• アプリを止めると監視がWSLのサービスやmountまで落としたことがある。計画的に止めるときは注意する。
• バックアップが失敗したままの状態で本番反映をしたら、反映の最後にバックアップがすぐ走り、定期処理（Jobs）の起動と重なって両方とも止まった（2026-11-11）。Jobs はバックアップのサービスが failed の間は起動しない。直し方: systemctl reset-failed tuat-local-backup.service → systemctl start tuat-local-jobs.service。そのあとバックアップが periodic-prior-unknown-hold で止まる場合は、中断が撮影の前だったこと（/var/lib/tuat-local/backup-stage が空、アプリと Jobs が動いている）を確かめてから、/var/lib/tuat-local/backup/periodic-attempt.json を /var/lib/tuat-local/private/reviewed-backup-attempt-<日付>-<attemptId>/ へ移し（消さない。installation-<版> の中には置かない。次の本番反映が「想定外のファイル」として止まる）、systemctl start tuat-local-backup.service で1回走らせる。本番反映の最後には毎回バックアップが1回走る。反映の前にバックアップが Result=success であることを確かめておくと、この重なりは起きにくい。
• 暗号化領域が開いているかは、作業用のシェルではなくsystemd側（nsenter -t 1 -m）で確かめる。

やってはいけないこと

• WSLの全停止（wsl --shutdown）、Nodeの全終了、Docker volumeの削除を、試しにやらない。
• D:\TUAT_TF\node_modules を消さない。
• 新しいDBや別のストレージを作って「直す」ことをしない。

PCが壊れて別のPCへ移すときの手順は ops/handoff/README.md。

4. 鍵とアカウント

詳しい一覧は ops/handoff/KEYS-MAP.md（値は書いていない）。要点:

• バックアップの鍵がいちばん大事。これがあればDriveのバックアップから、データもほかの鍵もすべて戻せる。ないと何も戻せない。PCの中のほか、管理者個人のパスワードマネージャー（iPhoneの「パスワード」）に控えがある。部活側にはまだない。Driveのバックアップと同じ場所（Driveのファイル）には置かない。
• アプリが使うそのほかの鍵（ログイン、DB、Cloudflare接続、Drive送信など）はPCの中にあり、バックアップにも含まれている。人が控える必要はない。
• サービスの管理は部活アカウントで行う: 部活Google（Drive・Google Cloud・GAS）、GitHub tuat-tf、Cloudflare。後任へはこれらのログイン手段とバックアップの鍵を渡す。
• 秘密の値はGit・チャット・ログに出さない。

D:\TUAT_TF\.contingency\ を消さない。 移行作業中の秘密・個人データの平文コピーは2026-11-09に削除し、残っているのはWindowsの起動に使うフォルダ（pc-auth-source-private-20261012\linux-storage-20261013\）だけ。起動タスクがここを使っており、消すと再起動後に本番が起動しない。詳しくは鍵の地図の4章。

5. 開発

1. Node.js 22.12 以上を使う（このPCの開発用は mise の 22.14。本番は WSL 内の 24.19 で、開発用とは別）。
2. npm ci
3. .env.example を見て .env.local を用意する（本番の値を入れない）。
4. npm run dev → http://localhost:3000

コマンド	用途
npm run check:environment	Node・依存の版がロックファイルと合っているか
npx tsc --noEmit	型検査
npx eslint <変更ファイル>	lint
npx vitest run	テスト
npm run test:ops	運用スクリプトのテスト（Windowsで動く分）
npm run build	ビルド

This is the beginning of the README. Read the rest at the original. Read the full README ↗