feat: 対人戦の記録・集計と大会掲示を接続する

[polyacetal]

変更内容

従来はダミーの得点計算と画面切り替えが中心で、対戦の記録から順位・掲示までを一続きに操作できませんでした。このPRで、各戦の得点と勝因を記録すると、2戦の試合判定、予選順位、本戦への勝ち上がり、会場掲示まで反映される対人戦の試作を追加します。

• 釧路を主対象に、先後を交換する2戦、グループ内総当たり、本戦トーナメント、訂正理由と再試合を扱います。旭川向けの対人戦計算方式も切り替えられます。
• 運営画面で参加者・結果・進出者を管理し、会場掲示をボタンで切り替えます。事前に表示順を組み、手動の「次へ」で進める進行表も用意します。
• 各戦終了後の入力値と掲示状態をSSEで共有し、JSONで永続化します。更新競合を検出し、CSV・JSONで記録を出力できます。
• 公開ルール、依頼者の運用説明、実装上の判断を分けて設計資料に残します。

可読性の改善

採点・大会進行・保存・画面描画を役割ごとに整理し、短縮した名前や深い条件分岐を改めました。大きな画面から、得点入力・参加者管理・掲示内容などのまとまりを分け、複数段階の操作には名前付きのハンドラーを用意しています。採点規則、保存形式、画面の振る舞いは維持しています。

コメントは、コードだけでは分からない理由や制約に絞っています。Prettierで書式を統一し、PRで整形・型・テストを自動検査します。命名や分割の良し悪しは自動検査だけで判断できないため、開発ガイドにレビュー時の基準と実装の入口を記載しました。

可読性改善の差分は、以下の5コミットの順に確認できます。整形だけの変更を先に分けています。

順序	コミット	主な確認点
1	fc66f4a 整形	Prettierの導入、一行に詰め込んだコードの展開
2	c946069 採点・進行	得点比較と順位集計の分離、参加者・予選・本戦・試合操作の責務、命名
3	fb6acd3 画面	運営・掲示・入力の役割分割、名前付きハンドラー、条件分岐の整理
4	839ac05 保存・通信	CSV生成とHTTP応答の分離、保存・SSE・更新処理の読みやすさ
5	3928d9f 継続的な確認	開発ガイド、PRの自動検査、実操作の検証記録

Zenn「可読性の低いコードはAIも読めない」の命名・処理のまとまり・書式・コメントの考え方と、Zenn「早期リターンを書こう」の条件分岐を浅くする方針を参考にしました。

初回実装のレビュー順序

コミットごとに目的を分け、依存する順序に並べています。各コミットのツリーを別ディレクトリに展開し、アプリ・shared・scoringの型検査と29件のテストが通ることを確認しました。新しい画面を接続する5番目までは、旧実装の公開型と関数を残しています。

順序	コミット	主な確認点
1	2b2f8c5 判定・大会進行	素点と勝因の保持、特殊P、2戦集計、順位、再試合、勝ち上がりの計算とテスト
2	d69d627 保存・API	更新番号による競合検出、保存・退避、履歴、CSV・JSON出力
3	bb0e938 会場掲示	6種類の表示、順位表・本戦表のページ分割、運営プレビューとの共用
4	9bc36e6 運営操作	先後・得点・勝因の入力、訂正理由、参加者・本戦管理、表示順の編集
5	11773f5 画面と記録の接続	ページ・SSE・見た目の切り替え、旧ダミー実装の削除、API結合テスト
6	d07ed5a 起動・保存設定	保存先とDockerの永続化volume、未使用DBの起動経路からの分離
7	65c198f 設計・確認資料	現在の実装と将来案の区別、大会ルールの出典、自主判断と操作手順

分割方針は、Zenn「レビューが爆速になる！レビュアーに優しいPull Requestの極意」の「変更目的の単位・理解しやすい順序」と、Qiita「おれおれレビューしやすいプルリクエスト」の「コミット単位で段階的にレビューできる構成」を参考にしました。デバッグの作業順ではなく、判定→保存→表示・操作→接続の順に再構成しています。

特に確認してほしい判断

試作提案の判断記録 D01〜D13に、根拠と確認点をまとめています。特に次の3点は試作として採用した判断であり、公式ルールとして確定した扱いにはしていません。

• D01：試合判定 — 特殊勝利を各1Pとし、2戦の「特殊P合計→得点合計」で比較する。
• D02：予選順位 — 釧路では「試合勝数→特殊P→合計得点」で比較する。
• D05：本戦配置 — 2組から各2名の場合はA1-B2／B1-A2とし、不足枠は上位シード側の不戦進出にする。

検証

• GitHub Actionsの自動検査で整形・型・テストがすべて成功
• 初回実装の7コミットで3パッケージの型検査・29件のユニットテスト・差分検査に成功。可読性改善後も29件通過し、整形と未使用変数・引数を含む型検査に成功
• 改善前後を一時検証スクリプトで比較し、採点・大会操作705件、掲示HTML・ページ分割90件、CSV24件が一致
• 可読性改善後のソースを独立したディレクトリに展開し、Next.js本番ビルド（Turbopack）に成功
• 専用の保存先・ポートで、参加者6名→2組の予選6試合→本戦3試合→決勝までのAPI結合テストに成功
• SSEの初期状態・更新通知、更新競合409、別オリジンからの書き込み拒否403、CSVの数式対策、JSON履歴出力を確認
• テスト用サーバーの再起動後、更新番号40・9試合を含む全状態が一致
• 運営画面・会場掲示のHTTP応答を確認
• 可読性改善後に、得点入力・先後交代・特殊勝利・別画面への結果反映・設定保存・順位表示・表示順編集・「次へ」を実操作で確認
• 画面内確認ダイアログのキャンセル／実行と、本戦生成をブラウザーで確認。運営・掲示画面の警告／エラーログなし
• Dockerでのビルド・起動、実会場の端末数・投影環境での確認

API結合テストは scripts/smoke-prototype.mjs に収録しています。大会を切り替えるため、別の CHROS_DATA_DIR とポートを使ったテスト用サーバーで実行します。

試し方と範囲

Node.js 22以降で pnpm install → pnpm dev を実行し、/console と /display を開きます。初回は架空の参加者8名のサンプル大会です。5分で試す手順から確認できます。

今回の対象は会場LAN内・単一サーバーでの対人戦です。試合サーバーとの自動連携、Bot戦、全国固有の採点方式、複数コートの割当、汎用規則エディターは含みません。既存の将来構想は docs/technical-roadmap.md に残しています。

[arumino-om]

LGTM