
開発史-クイズプラットフォーム-その1
この一言を忘れずに書いていきたい。
私は SWエンジニア ではない
前書き
・内P的なノリのクイズ大会を仲間内で楽しみたい
これだけのために、claude code で開発をスタートしてみた。
あわよくば、これを汎用的なプラットフォームにして、どこかのクラウドにデプロイして公開して、、、とかを目指す感じ。
ふとしたときに、youtubeのクイズ動画とかを仲間と見ながら、スマホ片手に早押しとかできたら楽しくね?的なお話。でもって、進行とかポイントとか順位とかをエクセルでやるのはだるいし、かといって気の利く感じのアプリやらサービスもないし、てなところで。
以下、AIがつくったサマリ
仲間内で遊ぶ早押しクイズアプリを作った話
~ Tailscale + Docker + WebSocket で「同じ部屋にいる感覚」を再現する ~
はじめに
オンライン飲み会でクイズ大会をやる、というよくある場面。クイズ番組のあの「ピンポン!」を再現したくて、自前で早押しクイズ Web アプリを作った。GM(出題者)1 名 + 回答者最大 10 名。リモートでも公平に押し順を判定したかった。
要件はシンプル:
スマホブラウザだけで参加できる
早押しの公平性は妥協しない
仲間内だけが入れる安全な配信
インストール不要、URL を共有するだけ
最終的にコア機能 + ライブ運用フィードバックを反映して、ライブで運用できる品質まで仕上げた。本記事では設計の勘所と、実際に動かして気づいた改善ポイントを書き残す。
技術スタック
| 層 | 採用技術 |
|---|---|
| 言語 | TypeScript(フロント・バック共通)|
| バック | Node.js 20 + Fastify + Socket.IO + better-sqlite3 |
| フロント | React 18 + Vite + Tailwind CSS + Zustand |
| バリデーション | Zod(共通スキーマ)|
| i18n | react-i18next(日本語 / English)|
| パッケージ管理 | pnpm workspaces(client / server / shared の monorepo)|
| コンテナ | Docker Compose |
| 配信 | Tailscale Serve(HTTPS)|
| テスト | Vitest(単体・統合)|
`shared/` に WebSocket イベント型と Zod スキーマを集約してフロント・バックで共有する構成にした。型の二重管理がなくなって楽。
アーキテクチャ概要
[スマホ Web (回答者×最大10)] ──┐
[PC ブラウザ (GM)] ├── HTTPS/WSS ──→ [Tailscale Serve]
┘ │
↓
[Node.js + Socket.IO (Docker)]
│
┌─────────┼──────────┐
↓ ↓ ↓
[SQLite] [/data/uploads] [メモリ状態]ホスト PC(自宅の Linux Docker)で 1 コンテナを動かし、Tailscale Serve で HTTPS 公開する。後述するが、Tailscale の Node Sharing で「個人 Tailnet を他人に開放せず、特定のマシン 1 つだけを共有する」という運用にした。
設計の勘所
1. 早押しの公平性はサーバ到着時刻のみで判定
これが一番大事な部分。クライアント側のタイムスタンプを使うとネットワーク遅延の差を悪用できるし、仮に意図的でなくても時計のずれで不公平になる。
// server/src/domain/buzz.ts
export function tryBuzz(queue, userId, name, blocked) {
if (blocked.has(userId)) return { success: false, reason: "locked" };
if (queue.entries.some(e => e.user_id === userId)) {
return { success: false, reason: "already_buzzed" };
}
const now = Date.now(); // ← サーバ時刻のみ
queue.entries.push({ user_id: userId, name, offset_ms: now - queue.t0 });
return { success: true };
}ポイント:
押下キューは到着順で全員分保持する。「最速 1 人」で打ち切らない
GM はキューから任意の順番で指名できる("先に押した B が答えに困ってるから A を当てたい" などの判断)
クライアントが送ってきた時刻情報は受け取っても使わない
仲間内利用なら同一 Wi-Fi が前提で、RTT 50ms 以下を想定。
2. 明示的なステートマシン
ゲーム進行を明示的なフェーズで管理する。フェーズ外のイベントは無視 + ログ警告。
const ALLOWED_TRANSITIONS = {
LOBBY: ["start_game"],
ROUND_START: ["show_question"],
QUESTION_PRELOADED: ["reveal_question", "abort_question"],
QUESTION_SHOWN: ["open_buzz", "abort_question"],
BUZZING: ["nominate", "abort_question", "buzz"],
ANSWERING: ["judge", "abort_question", "buzz"],
QUESTION_RESULT: ["next_question", "show_question", "end_round", "end_game"],
ROUND_RESULT: ["resume_from_break", "start_next_round", "end_game"],
BREAK: ["resume_from_break"],
GAME_FINISHED: ["reuse_room"],
};各 WS ハンドラはまず `isActionAllowed(phase, action)` をチェックして、不正な遷移はサイレントに無視。「タイミングのバグ」が発生しても整合性が保たれるようにした。
3. 問題表示の 2 段階制御(QUESTION_PRELOADED フェーズ)
最初の実装では「次の問題」ボタンを押すと即座に全員に問題文が配信される設計だった。実際にライブで使ってみると、GM が問題を読み上げる前にプレイヤーが見えてしまって白ける。
そこで `QUESTION_PRELOADED` フェーズを追加:
ROUND_START
↓ show_question(GM がボタン押下)
QUESTION_PRELOADED ← GM だけが問題を見られる
↓ reveal_question(GM が「問題を表示」を押下)
QUESTION_SHOWN ← プレイヤーにも問題文が届く
↓ open_buzz
BUZZINGサーバから送るイベントを 2 種類に分けた:
`game:question_loaded`(GM 専用、preload 時)
`game:question_shown`(全員、reveal 時)
GM が「読みます」と声をかけてから問題が出る、テレビのクイズ番組っぽい流れができた。
4. 1 文字ずつタイプライター表示
reveal 時の演出として、問題文を 1 文字ずつ表示するモードも入れた。
// AnimatedText.tsx
useEffect(() => {
if (mode === "instant") {
setShown(text);
return;
}
setShown("");
let i = 0;
intervalRef.current = setInterval(() => {
i++;
setShown(text.slice(0, i));
if (i >= text.length) clearInterval(intervalRef.current);
}, speedMs);
return () => clearInterval(intervalRef.current);
}, [text, mode, speedMs]);GM 画面の「準備室」でデフォルトを設定(全問共通)、出題前に個別切替も可能。WS payload に `animation: "instant" | "typewriter"` を載せて、全クライアントで描画モードを揃える。
5. 異議アリ機能
ライブでやってみると「今のは正解だろ!」「いや微妙だ」みたいな小競り合いが起きる。GM の采配に異議を唱える仕組みを追加した。
[Player] 異議アリ!ボタン (BUZZING / QUESTION_RESULT のみ)
→ [Server] objections に追加、全員に game:objections_update をブロードキャスト
[GM] 進行系ボタン(次の問題 / ラウンド終了 / ゲーム終了)が disabled に
→ 「異議を却下」を押すまで進めない
[GM] 異議却下 → objections クリア → 進行再開実装上は、フェーズ機械とは別軸の gate として扱う。`hasObjections(room)` を進行系ハンドラの先頭でチェックするだけ。状態機械を汚さない。
却下のみで判定の「取り消し」はしない。判定を覆したい場合は GM が手動でスコア調整する仕様。シンプル。
6. 接続状態の可視化と自動再認証
スマホで遊んでいて気づいた問題:画面ロックすると WebSocket が切れる。ロック解除しても、ボタンが効かない時間がある。気づかないと「なんで押せないんだ?」となる。
対策:
Socket.IO の `connect` / `disconnect` / `reconnect_attempt` を購読して `connectionState` を 3 状態(connected / reconnecting / disconnected)で管理
全画面の左上に 🟢/🟡/🔴 バッジ を常時表示
入室成功時に `sessionStorage` に認証情報(GM なら `gm_key`、プレイヤーなら `name + pin`)を保存
再接続時に自動で `PLAYER_JOIN` / `GM_JOIN` を再送 → サーバ側で `user_id` ベースに既存セッション復元
スマホがスリープから復帰しても、数秒で勝手に再接続して押下可能に戻る。
// client/src/stores/socket.ts
s.on("connect", () => {
store.getState().setConnectionState("connected");
if (store.getState().authenticated) {
reauthenticate(s); // sessionStorage から自動で再 join
}
});サーバ側は元から `user_id` ベースで再接続を受け入れる設計だったので、クライアント側の小さな変更だけで済んだ。
7. ルームの再利用と「別のクイズへ移行」
1 ゲーム終わった後、メンバーをそのまま使い回したいニーズが多い。ゲーム終了画面に 4 ボタンを並べた:
| 問題 | スコア |
|---|---|
| 同じ問題 | 0 リセット |
| 同じ問題 | 引継ぎ(連戦モード)|
| 別クイズ(インポート可)| 0 リセット |
| 別クイズ(インポート可)| 引継ぎ(ゲーム会の通算スコア)|
`gm:reuse_room` の payload に `clear_questions: boolean` を追加して、true なら `room.questions` と `rounds` を初期状態に戻す。GM はその後 JSON インポートで次のクイズパックを始められる。
`carry_over` + `clear_questions` の組み合わせは、複数のクイズパックを通しでやって「総合王者」を決めるのに使える。
ライブ運用で見えた改善点
実際にスマホ + ホスト PC で遊んだ結果、UI 面での気づきがいくつか:
ダークテーマのコントラスト不足
夜にスマホで遊ぶことが多いので、ダークモードを真面目に詰めた。ライト前提で書いた `bg-gray-50` / `text-gray-600` 系がダークでほぼ見えなかったので、Tailwind の `dark:` バリアントを全画面で網羅補完。
スコアボードの表示数
最初はトップ 5 名だけ表示にしてたが、自分が下位だと自分のスコアが見えない。全員表示 + overflow-y-auto に変えた。最大 10 名なので問題なし。
「準備室」という概念名
LOBBY フェーズの GM 画面 = 問題を準備して開始ボタンを押す場所、という認識を UI に出した。ヘッダーに「GM 準備室」バッジを表示、コンテンツ最上部に「問題表示モード(全問題共通)」設定を配置。
最初、アニメーションのトグルは「問題を表示」ボタンの隣にしか置いてなかった(出題ごとに切り替える発想)。実際使ってみるとほぼ全問同じモードでいいので、ルーム単位の既定値として準備室で 1 回だけ設定する形にした。出題ごとに変えたい場合は今まで通り出題前に切替できる。
PWA + Tailscale Node Sharing で配信
本番配信は自宅 PC + Tailscale Serve。
tailscale serve --bg --https=443 http://localhost:3080これだけで `https://<machine>.<tailnet>.ts.net` で HTTPS 公開できる。Let's Encrypt の手間も DNS 設定もいらない。Tailscale の中の人ありがとう。
ただし問題がひとつ:自分の個人 Tailnet に他人を入れたくない。仲間内とはいえ、自宅の他のマシンが全員から見えるのは抵抗がある。
解決策は Node Sharing。Admin Console から特定のマシン 1 つだけを共有して、相手は自分の Tailscale アカウント(無料)でその 1 ノードだけにアクセスできる。
自分の Tailnet:他のノードは見えないまま
相手:いつもの Tailscale で「あ、このマシンが共有されてる」と認識
セキュリティモデル:4 桁 PIN の脆弱性を Tailscale 越しの認証で補完
PWA 化(vite-plugin-pwa)してホーム画面に追加できるようにしたので、スマホからは「いつものアプリ」感覚で起動できる。
仕様書ドリブン開発
最初に `docs/spec.md` を 1000 行以上書いてから実装に入った。状態遷移図、WebSocket イベント表、SQLite スキーマ、画面仕様、お手付きルール 4 種、すべて先に固めた。
これがめちゃくちゃ効いた:
実装中に「あれ、ここの仕様どうする?」が激減
AI コーディング支援にも仕様書を読ませやすい
後から仕様逸脱を整合性レポート(`spec-audit.md`)として整理できた
仕様と実装がずれてきたら spec を更新するか実装を直すかの判断が明示的にできる。一人プロジェクトでも「過去の自分」と話す手段として仕様書は強い。
テスト
| レイヤー | 件数 |
|---|---|
| 単体(domain ロジック)| 48 |
| 統合(WebSocket フロー)| 8 |
| 合計 | 56 |
特に押下キュー、お手付きルール(`disqualify_round` のラウンド失格など)、状態遷移、再利用フロー、異議アリ、ラウンド + 休憩遷移はテストでガードしている。WebSocket の統合テストは Vitest + 実際の Socket.IO サーバを立てて、GM とプレイヤーの双方向シナリオを通す形にした。
「早押しの公平性」みたいに一度バグ込みでデプロイすると信頼を失う部分は、ユニットテストでもいいから固めておく価値が大きい。
まとめ
仲間内向けの小さなアプリだが、設計判断を真面目にやれば学びが多かった。特に:
状態機械 — 明示的なフェーズ管理は、UI の混乱とサーバの不整合を同時に防ぐ
公平性 — クライアント時刻を信じない。サーバ到着時刻のみ
PWA + Tailscale Node Sharing — 自前 HTTPS 配信のフリクションがほぼゼロで、しかもプライベート空間を保てる
仕様書ドリブン — 先に書く価値はある。AI 支援もしやすい
ライブ運用フィードバック — 動かして初めて見える「画面ロックで切れる」「ダークが見にくい」「異議出したい」みたいな小さなニーズが、品質の最後の 30% を決める
次に作るとしたら、ライブ配信の OBS 連携(GM 画面を OBS のソースとして取り込めるレイアウト)あたり。ゆくゆくは複数ルーム対応もやりたいが、まずは仲間内でいっぱい遊んで枯らす予定。
ソースコードは個人プロジェクトなので公開予定は今のところなし(情報の整理がついたら検討)。同じようなものを作りたい人の参考になれば。
使った AI コーディング支援: Claude Code(Anthropic)。仕様書を一緒に書いて、実装してテストしてレビューしてもらう、という流れが今のところ一番生産性が高い。