カスタムキー自動配布管理者マニュアル（管理画面用）

🎯 対象読者
Fortnite 大会 / スクリム運営スタッフ
PC 操作があまり得意でない人も想定（クリック場所まで丁寧に説明）

1. 機能の目的

スクリム／大会の カスタムキー配布を自動化 し、
- 「配布ミス」
- 「Discord での伝達漏れ」
- 「ロビー落ちが発生した後の再配布の混乱」を最小化することが目的です。
参加者側 は、GA にログインし、
- 運営から案内された「配布ページ URL」にアクセス
- ページを開いたまま待機するだけ
運営側（管理画面） は、
- ロビーの追加 / 組合せの再計算
- カスタムキーの入力
- 配布開始 / 配布取り消し / 試合開始 / キー出し直し
- Discord 向けテンプレートメッセージのコピーを、すべてブラウザ上から操作 できます。

2. 画面構成と用語

2.1 画面上部カード（ステータスサマリー）

画面上部に、3 つのカードが並んで表示されます。

👁️ 総閲覧数
- そのセッションの「配布ページ」を 一度でも開いたユニークユーザー数 の合計です。
- クリックすると、閲覧者一覧モーダル が開きます（後述）。
🌐 現在接続中
- 接続中と判定されている人数です。
- セッションに参加者（CustomKeySessionMember）が 1 人でもいると、DB 基準（is_connected と最終閲覧時刻 last_seen_at）で集計します。タブを閉じたり別タブに移ったりしても、数秒〜数十秒は「接続中」としてカウントされることがあります。
- 参加者がまだ誰もいない場合は、WebSocket の接続数で表示します。
- いずれも人数は数秒〜十数秒ほど遅れて反映されることがあります。
✅ 割り当て済み
- どこかのロビーに キー割り当てが完了している人数（最新状態） です。

🔍 閲覧者一覧モーダル（総閲覧数カードをクリック）

総閲覧数カードをクリックすると、最新状態だけをまとめた一覧 が表示されます。

タブ構成
- 全員
- オンライン
- オフライン
- 割り当て済み
主な列（例）
- ユーザー名 / Epic 名
- 所属ロビー（PREVIEW / 配布済み / 出発済み）
- 状態（閲覧中 / 閲覧離脱 / 割り当て済み）
- 最終アクセス時刻
- 接続状況（🟢オンライン / 🔴オフライン）
運営はここを見れば、
- 「今ページをちゃんと見ている人」
- 「誰にロビーが割り当て済みか」を一目で把握できます。

2.2 ロビー管理エリア

1. 配布状況サマリー

画面中段に、各ロビーの状態が タブ状のサマリー として表示されます。
例：
- SKY Scrim-ロビーA : 配布済み（2人）
- SKY Scrim-ロビーB : 未配布（PREVIEW 3人） など

2. ロビーカード（ロビーA / B / C…）

各ロビーごとに 1 枚のカードが表示されます。主な要素は次のとおりです。

🏷 ロビー名
- 例：SKY Scrim (SQUAD) Match 2 ロビーA
- 自動で命名されます（ロビー追加時に手入力は不要）。
📛 状態バッジ
- 未配布 … PREVIEW 状態（仮割り振りのみ。キーはまだ送られていない）
- 配布済み … キー配布が完了した状態
- 出発済み … 試合開始ボタンが押され、試合中 or 終了扱い
🔑 カスタムキー入力欄
- ゲーム内で設定したカスタムキーを入力します。
- 事前に決めておくか、「カスタムキー再生成」ボタンでランダム生成した値を使用します。
🎛 アクションボタン（カード右上）
- 状態に応じて、以下のボタンが表示されます：
  - このロビーに配布
  - 配布取り消し
  - 試合開始
  - キー出し直し
👥 メンバー関連ボタン（カード下部）
- メンバーリスト … そのロビーに割り当てられた（または仮割り振りされた）参加者の一覧を モーダル で表示。配布前は接続中の閲覧者、配布後は割り当て済みユーザーが対象です。表示件数は多数参加（数百人規模）にも対応しています。
- メンバーリスト頁を表示 … 試合開始後に有効。別タブの公開ページ で同じリストを表示
- ロビーごとの「最大人数」のような制限はありません。必要に応じてロビー数を増やして運用します。
💬 Discord 向けテンプレートボタン（カード下部）
- 状態に応じて、以下のグレー系ボタンが並びます：
  - PREVIEW（未配布）：カスタムキー受付開始用文章
  - 配布済み（未出発）：カスタムキー配布テンプレート
  - 出発済み：試合開始のテンプレ / キー出し直しのテンプレ
- 押すと テンプレ文プレビューモーダル が開き、その内容が自動でクリップボードにコピーされます。

3. 共通ボタン（画面右上）

➕ ロビー追加
- PREVIEW 状態のロビーを 1 つ末尾に追加します。
- ロビー名は自動で ロビーB / ロビーC ... のように付与されます。
🔁 組合せ更新
- すべての PREVIEW ロビー に属する閲覧者を、
  - 「ロビーごとの人数ができるだけ均等」になるように再割り振りします。
- すでに 出発済み のロビーは対象外です。
📘 マニュアル
- 今表示しているこのマニュアルを、画面上にモーダルで表示します。

2.3 外部ページ（参加者向け / 公開ページ）

管理画面からは、運営だけでなく 参加者向けのページ も連動しています。

🧑‍💻 配布用ページ（参加者が開いて待機するページ）
- URL 例：
  - /scrims/{scrimHashId}/matches/{matchHashId}/custom-keys/{sessionHashId}
- 参加者はここを開きっぱなしにして待機します。
- キーが割り当てられると、画面上に自分のロビー名とカスタムキーが表示されます。
📄 メンバーリストページ（公開ページ）
- URL 例：
  - /scrims/{scrimHashId}/matches/{matchHashId}/custom-keys/{sessionHashId}/{lobbyHashId}
- 対象ロビーが 出発済み のときだけ、割り振りメンバーリストが閲覧できます。
- 試合開始前にアクセスした場合は、
  - 「試合はまだ開始されていません」というメッセージが表示されます。
- カード下部の メンバーリスト頁を表示 ボタンから、別タブで開けます。

3. 基本的な運用フロー（ステップバイステップ）

3.1 試合開始前（配布準備）

1️⃣ セッション作成

GA の管理画面で、対象の スクリム or 大会の試合詳細ページ を開きます。
右側のメニューから 「カスタムキー配布」 をクリックします。
初回アクセス時、自動でセッションが作成され、
- 最初のロビー（ロビーA）が生成されます。

2️⃣ 参加者に案内（配布ページ URL の共有）

管理画面の情報から、対象セッションの 配布ページ URL を確認します。
Discord などで、参加者に次のように案内します：
- 「試合に出る人は、このページを開いてログインし、開いたまま待機してください」
管理画面上部の 「現在接続中」 が、参加者が増えるにつれて増加していくことを確認します。

💡 ポイント
参加者側のブラウザや回線状況により、人数表示は数秒〜十数秒遅れて反映されることがあります。

3️⃣ 必要に応じてロビー追加

参加人数に応じて、
- ロビー追加 ボタンで ロビーB / ロビーC ... を増やします。
ロビーを追加した直後は、人数の偏りがある可能性があります。
その場合は、組合せ更新 を押します。
- PREVIEW ロビー間で、閲覧中ユーザーが均等になるように再割り振りされます。

4️⃣ カスタムキーの入力

各ロビーカードの「カスタムキー」欄に、ゲーム内で設定したキーを入力します。
事前に決めておくか、管理画面の 「カスタムキー再生成」ボタン でランダムキーを生成して貼り付けます。
すべてのロビーで キーが正しく入力されているか を確認します。

3.2 配布（実際にキーを送る）

1️⃣ 配布前のチェック

次の 2 点を確認します：
- 上部カードの 「現在接続中」人数
- 各ロビーの「閲覧者（仮割り振り）」人数（PREVIEW 時）
想定より偏りがある場合：
- もう一度 組合せ更新 を実行して、再度人数を確認します。

2️⃣ 配布操作（2パターン）

全体配布（セッション全体を一括配布）
- 画面右上の 「配布開始」ボタン を押します。
- 現在接続中のユーザーが、ロビーに自動割り振りされ、
  - 各参加者の配布ページに 自分用のカスタムキー が表示されます。
ロビー単位での配布
- 個別ロビーカードの 「このロビーに配布」ボタン を押します。
- 対象ロビーに割り振られた閲覧者だけに、キーが送られます。

3️⃣ 配布後の確認

各ロビーの状態バッジが 「配布済み」 に変わっているか確認します。
ロビーカード下部の：
- メンバーリスト ボタンを押すと、配布先ユーザーの一覧がモーダルで表示されます。
必要に応じて、Discord 用のテンプレボタンを使って案内を送ります（次章参照）。

3.3 試合開始（出発）

各ロビーで、参加者が無事に試合ロビーへ入室できているか確認します。
問題がなければ、対象ロビーカード右上の 「試合開始」ボタン を押します。
状態バッジが 「出発済み」 に変わります。
出発済みロビーは、原則として 新規の割り振り対象外 になります。
出発済みロビーには、
- 試合開始のテンプレ
- キー出し直しのテンプレ
- メンバーリスト頁を表示 が利用可能になります。

4. Discord テンプレートボタンの使い方

💬 すべてのテンプレは Discord 向けに Markdown 形式で整形されています。
見出し（## / ###）
太字（**...**）
引用（block quote）
コードブロック（...）
絵文字（🎮 / 🔑 / ⚠️ など）
を利用して、読みやすく・パッと見で状況が分かるようになっています。

4.1 テンプレ共通の動作

ロビーカード下部の、目的に合った テンプレボタン をクリックします。
画面中央に 「テンプレート文」モーダル が開きます。
モーダルを開いた瞬間に、テンプレ文全体が 自動でクリップボードにコピー されます。
モーダル内のテキストを確認し、OKであれば：
- Discord の送りたいチャンネルを開く
- Ctrl + V（Mac は Cmd + V）で貼り付け
- 必要に応じて追記して送信
モーダルは閉じるか、再度コピーしたい場合はもう一度ボタンを押します。

4.2 状態別テンプレート一覧

🟡 PREVIEW（未配布）時

ボタン：カスタムキー受付開始用文章
- 参加者に対して「今からこの試合のカスタムキー受付を開始します」と案内するためのテンプレです。
- 主な内容：
  - スクリム名 + Match 番号（例：SKY Scrim (SQUAD) Match 2）
  - 配布ページ URL（参加者が開いて待機するページ）
  - 「パーティーメンバーで 一人だけ 閲覧してください」という重要な注意文
  - 「カスタムキー配布までお待ちください」という待機のお願い
  - 参加者向けマニュアルへのリンク（利用方法・ロビー・キー表示・参加メンバー確認・注意事項）
  - 関連ページへのリンク（スクリムページ・大会ページ・グループページ。紐づきがある場合のみ）
- Discord で使うときは、必要に応じて @everyone などを先頭に付けて送信してください。

🟢 配布済み（まだ出発していない）時

ボタン：カスタムキー配布テンプレート
- 「カスタムキーの配布を開始しました」という開始連絡に使うテンプレです。
- 主な内容：
  - @everyone
  - スクリム名 + Match 番号
  - 「カスタムキー配布を開始しました」という見出し
  - 「試合開始までお待ちください」という案内
- 受付開始テンプレ側で配布ページ URL や注意書きを出しているため、
  - このテンプレからは 配布ページ URL・キー本体・重要注意文の重複行を削除 しています。

🔵 出発済み（試合開始後）時

ボタン：試合開始のテンプレ
- 「ロビーA の試合を開始しました」という開始アナウンス用テンプレです。
- 主な内容：
  - @everyone
  - スクリム名 + Match 番号
  - ロビー名（例：SKY Scrim (SQUAD)-ロビーA）
  - 何人にキーを配布したか（例：✅ **1人** にキーを配布しました。）
  - メンバーリスト公開ページの URL（参加者が割り振りを確認できるページ）
ボタン：キー出し直しのテンプレ
- ロビー落ちやマッチ失敗時に、同じロビーで再試合を行う 場合に使うテンプレです。
- 主な内容：
  - @everyone
  - 上下を ⚠️ が並んだコードブロックで囲い、一目で異常事態と分かるデザイン
  - 見出し：⚠️ ロビー名（カスタムキー）のキーの再配布を行います（Markdown で太字＆コード表記）
  - 引用ブロックで：
    - 「⛔ 以下の対象者の方はゲームから抜けて運営の案内をお待ち下さい。」
  - Discord の文字数制限を考慮し、
    - 個別の配布リストや参加者リストは含めていません。

5. イレギュラー時の操作（詳細）

5.1 配布取り消し（出発前）

想定ケース

カスタムキーを間違えて入力していた
一部メンバーを別ロビーに移したい（まだ試合開始前）

操作手順

対象ロビーカードの 「配布取り消し」ボタン を押します。
状態バッジが 未配布（PREVIEW） に戻ります。
そのロビーに対して行われていた割り当てログは 「無効化」 されます。
閲覧中のユーザーは、再び PREVIEW ロビー群の仮割り振り対象に戻ります。
必要に応じて、
- 組合せ更新 を押して人数を再調整
- カスタムキーを修正
- 再度「このロビーに配布」または「配布開始」を実行します。

5.2 キー出し直し（試合開始後）

想定ケース

ロビーが落ちた
カスタムマッチが失敗して、同じ試合をやり直したい

操作手順

対象ロビーカードの 「キー出し直し」ボタン を押します。
ロビー状態が一旦 未配布（PREVIEW） に戻ります。
該当ロビーの出発済み割り当てログは 無効化 されます。
閲覧中のユーザーは PREVIEW ロビー群に再度仮割り振りされます。
新しいカスタムキーを入力し、
- 必要なら 組合せ更新 で人数調整
- 再度「このロビーに配布」を実行します。
Discord には 「キー出し直しのテンプレ」 を使って周知すると、
- 参加者にとっても「再試合が始まる」ことが分かりやすくなります。

⚠️ 注意
「出発済みロビー」に割り当たっていたユーザーが、
他の出発済みロビーと混ざってしまうことはない設計です。
基本的には、
「再配布したいロビー」と
「まだ出発していないロビー」だけを使ってやり直すイメージです。

5.3 ロビー追加・組合せ更新

ロビー追加
- 新しい PREVIEW ロビーを末尾に追加します。
- 追加後は、人数の偏りが生じるため、組合せ更新 を行うことを推奨します。
組合せ更新
- すべての PREVIEW ロビーに属する閲覧者を、
  - 「ロビーの現在人数が均等になるように」再割り振りします。
- 出発済みロビーや、すでに配布済みのロビーは対象外です。

5.4 ロビー削除

前提

最後の 1 ロビーは削除できません。
- UI 上でもボタンが非表示になり、API 側でも削除がガードされています。

削除可能な条件

該当ロビーが PREVIEW（未配布） 状態であること
セッション内に 2 ロビー以上 存在すること

挙動

削除されたロビーに仮割り振りされていた閲覧者は、
- 残りの PREVIEW ロビーに自動的に再割り振りされます。
出発済みロビーや配布済みロビーには移動されません。

6. 切断・再接続に関する注意

参加者が 配布ページを開くと、セッションの「メンバー」として DB に登録され、最終閲覧時刻（last_seen） で接続状態が更新されます。
配布ページを 閉じたり、別タブに移動したり しても、
- しばらくのあいだは「接続中」としてカウントされることがあります（閾値秒数以内の last_seen が使われるため）。
- WebSocket を使う場合も、切断が 数秒〜十数秒遅れて 反映されることがあります。
管理画面の「現在接続中」は、
- メンバーが 1 人でもいると DB 基準（is_connected と last_seen）で集計され、
- メンバーが誰もいないときは WebSocket（/channels/users）の結果で表示されます。
- いずれも表示上の人数が すぐには反映されない 場合があります。