メインコンテンツへスキップ
見出し画像

開発史-クイズプラットフォーム-その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 が切れる。ロック解除しても、ボタンが効かない時間がある。気づかないと「なんで押せないんだ?」となる。

    対策:

    1. Socket.IO の `connect` / `disconnect` / `reconnect_attempt` を購読して `connectionState` を 3 状態(connected / reconnecting / disconnected)で管理

    2. 全画面の左上に 🟢/🟡/🔴 バッジ を常時表示

    3. 入室成功時に `sessionStorage` に認証情報(GM なら `gm_key`、プレイヤーなら `name + pin`)を保存

    4. 再接続時に自動で `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)。仕様書を一緒に書いて、実装してテストしてレビューしてもらう、という流れが今のところ一番生産性が高い。

     
     
    SWエンジニアではない(経歴も無い) 複写機でエレキ設計 4年 半導体製造装置(前工程)でPDM 4年 ロボットベンチャーで PM、組織マネージャ 1.5年 自動運転 物流管制、監視システム開発 PM 現職

    あなたへのおすすめ