入場管理pj 要件定義書
0. ドキュメント情報
| 項目 | 内容 |
|---|---|
| プロジェクト名 | 入場管理 |
| バージョン | v0.1.0 |
| 作成日 | 2026/6/30 |
| 最終更新日 | 2026/7/7 |
| 作成者 | @凶兆の黒猫 |
| 承認者 | |
| ステータス | 検討中 / レビュー中 / 承認済み |
更新履歴
| バージョン | 日付 | 変更内容 | 担当者 |
|---|---|---|---|
| v0.1.0 | 2026/6/30 | 初版作成 | @凶兆の黒猫 |
| v1.0.0 | 2026/7/7 | 欠けている項目を追記 | @凶兆の黒猫 |
1. 概要
1.1 背景・目的
- 入場時、QRコードスキャンを通して入場処理を行う。
- どの時間帯にどの受付からどの年齢層・性別がどのくらいの人数の塊で入場したかを把握するのが主目的。
1.2 ゴール
- 入場をスムーズに行えるようにする
- 統計がsho-room上で確認できるようにする
1.3 スコープ
対象範囲（Scope In）
- Android端末 FZ-N1のスキャン機能を用いた入場処理
対象外（Scope Out / Out of Scope）
- QRの表示機能(入場者サイドの処理)
1.4 用語定義
| 用語 | 説明 |
|---|---|
| 蒼翔祭 | 本プロジェクトが対象とする会津大学の学園祭 |
| 学祭委員 | 学園祭実行委員（本システムの主要ユーザー） |
| FZ-N1 | 現場でのQRスキャンに使用するPanasonic製Android端末 |
| sho-room | 学祭委員向けの管理画面。入場者数の可視化等に使用 |
| 受付 | 入場処理を行う設置場所（正面・西など） |
| 再入場 | 同一QRコードで2回目以降のスキャンが行われた状態 |
| 手動登録 | QRコード未所持者・当日未登録者に対し、専用端末でその場で入場登録を行う対応 |
| ゲスト1-10 | 手動登録の来場者に割り当てる仮の識別名（実名を扱わないための代替表記） |
2. ステークホルダー
| 役割 | 氏名 |
|---|---|
| プロジェクトリーダー | @二枚貝 |
| 開発担当 | @凶兆の黒猫 @novice |
| 利用者・対象ユーザー | 当日シフト担当 |
3. 利用者・ユースケース
3.1 想定利用者（ペルソナ）
- 当日シフト対応者(学祭委員)
3.2 ユースケース一覧
| ID | ユースケース名 | 概要 | 優先度 |
|---|---|---|---|
| UC-01 | 来場者のQR読み取り | 端末を操作してQRコードの読み取りを受け付ける状態にし、準備させたQRコードを読み取る。 | 高 |
| UC-02 | 入場済み判定・多重判定防止 | 同じQRコードで2回の入場があった際、再入場とみなして以降のフローをすべて飛ばして通す。 | 高 |
| UC-03 | 手動登録 | 端末を持っていない層や当日で登録をしていなかった層のために手動登録の場所(専用端末/LINEによる新規登録)へ案内する。 | 高 |
| UC-04 | リアルタイム入場者数の確認 | sho-roomの画面でリアルタイムの入場者数を視覚化する。 | 低 |
| UC-05 | 通信障害時のオフライン入場記録 | 入場記録ネットワーク不通時にローカルで記録し、復旧後に同期する | 低 |
4. 機能要件
優先度は MoSCoW（Must / Should / Could / Won't）などで管理すると後で取捨選択しやすい
| ID | 機能名 | 説明 | 優先度 | 関連UC |
|---|---|---|---|---|
| F-001 | QR読み取りモード起動 | 起動端末でQRスキャンを開始/待機状態にする | Must | UC-01 |
| F-002 | QRコードスキャン・照合 | 読み取ったQRコードをDB上の登録情報と照合する | Must | UC-01 |
| F-003 | 入場情報の記録 | 照合成功時に入場時刻・受付の場所・入場者などを記録する | Must | UC-01 |
| F-004 | スキャン結果のフィードバック表示 | 「入場OK」「再入場」「未登録」などを担当者が一瞬で判別できるよう画面/音で通知する | Must | UC-01, UC-02 |
| F-005 | 手動登録機能(専用端末) | 専用端末側で年齢層、性別を入力し、その場で入場登録する | Must | UC-03 |
| F-006 | 入場者数の可視化表示(sho-room) | 集計値をsho-room画面上にグラフ/数値で表示する | Could | UC-04 |
| F-007 | オフライン時のローカル記録 | 通信不通を検知し、入場データを端末内に一時保存する | Could | UC-05 |
| F-008 | オフラインデータの自動同期 | 通信復旧を検知し、ローカル保存データをサーバーに送信・反映する | Could | UC-05 |
| F-009 | 同期時の重複/競合解消 | オフライン中に複数端末で記録されたデータの突合・重複排除を行う | Could | UC-05 |
4.1 機能詳細
F-001: QR読み取りモード起動
- 概要：シフト担当者の操作で、FZ-N1端末をQRスキャン待機状態にする
- 入力：担当者によるスキャン開始操作（画面タップ等）
- 処理：スキャナの起動、スキャン待機UIへの遷移
- 出力：スキャン待機画面の表示
- 異常系・エラー処理：カメラ/スキャナの起動失敗時はエラー表示のうえ再試行を促す
- 関連する画面/コマンド：S-01 スキャン画面
F-002: QRコードスキャン・照合
- 概要：読み取ったQRコードの値を、DB上の来場者登録情報と照合する
- 入力：QRコードの読み取り値
- 処理：APIキー認証でHonoサーバーへ照会し、D1上の来場者テーブルと突合
- 出力：照合結果（入場OK／再入場／未登録）
- 異常系・エラー処理：QRコード破損・読み取り不可時は再スキャンを促す表示。DB該当なしの場合はエラー音と表示を行う。
- 関連する画面/コマンド：S-01 スキャン画面、照合API
F-003: 入場情報の記録
- 概要：照合成功時に入場時刻・受付場所・来場者情報を記録する
- 入力：来場者ID、スキャン日時、受付場所（端末に紐づく設置場所）
- 処理：入場記録テーブルへのINSERT
- 出力：登録完了レスポンス
- 異常系・エラー処理：DB書き込み失敗時はF-007のオフライン記録に切り替える
- 関連する画面/コマンド：入場記録API
F-004: スキャン結果のフィードバック表示
- 概要：「入場OK」「再入場」「未登録」を担当者が一瞬で判別できるよう画面・音で通知する
- 入力：F-002の照合結果
- 処理：判定結果に応じた色・アイコン・音の出し分け
- 出力：結果表示（画面＋効果音）
- 異常系・エラー処理：判定に時間がかかる場合はローディング表示を挟む
- 関連する画面/コマンド：S-01 スキャン画面
F-005: 手動登録機能(専用端末)
- 概要：端末未所持者や当日未登録の来場者に対し、専用端末で年齢層・性別を入力しその場で入場登録する
- 入力：年齢層、性別（実名は扱わず、識別名は「ゲスト◯」等を自動採番）
- 処理：来場者レコードの新規作成（登録区分＝手動）、入場記録への即時反映
- 出力：登録完了通知
- 異常系・エラー処理：必須項目未入力時はバリデーションエラーを表示
- 関連する画面/コマンド：S-02 手動登録画面
F-006: 入場者数の可視化表示(sho-room)
- 概要：入場記録の集計値をsho-room画面上にグラフ・数値で表示する
- 入力：入場記録テーブルの集計データ（時間帯別、受付場所別、年齢層・性別別）
- 処理：集計処理（バッチ集計またはリアルタイム集計）
- 出力：sho-room画面上のグラフ・数値表示
- 異常系・エラー処理：データ取得失敗時は前回値を保持しつつエラー表示
- 関連する画面/コマンド：S-03 sho-room表示画面
F-007: オフライン時のローカル記録
- 概要：通信不通を検知した際、入場データを端末内に一時保存する
- 入力：F-002/F-003で発生する入場データ
- 処理：通信状態の監視、不通時はローカルストレージへの書き込みに切り替え
- 出力：ローカル保存完了
- 異常系・エラー処理：ローカルストレージ容量超過時の対応方針を別途検討
- 関連する画面/コマンド：ローカルDB/ストレージ処理（バックグラウンド）
F-008: オフラインデータの自動同期
- 概要：通信復旧を検知し、ローカル保存データをサーバーに送信・反映する
- 入力：ローカル保存済みの入場データ
- 処理：通信復旧検知 → 順次サーバーへ送信 → 送信成功分をローカルから削除
- 出力：同期完了通知
- 異常系・エラー処理：送信中の再切断時は再送対象として保持する
- 関連する画面/コマンド：同期処理（バックグラウンド）
F-009: 同期時の重複/競合解消
- 概要：オフライン中に複数端末で記録されたデータの突合・重複排除を行う
- 入力：各端末から同期されてきた入場データ群
- 処理：QRコード（来場者ID）をキーとした重複検出。最も早い記録を正として採用
- 出力：重複排除済みの確定入場記録
- 異常系・エラー処理：完全に同時刻の場合の優先順位ルールは別途定義が必要
- 関連する画面/コマンド：同期処理内のロジック
5. 非機能要件
| 区分 | 要件 |
|---|---|
| 性能 | QRスキャンから結果表示まで3秒以内(目安：行列が詰まらない速度) |
| 可用性 | イベント当日のスキャン受付時間中、サービス停止が発生しないこと |
| セキュリティ | 端末-サーバー間通信のHTTPS化、不正端末からのアクセス制限 |
| 拡張性 | 来場者数の急増(想定外の混雑)にも耐えられる設計 |
| 運用・保守性 | 当日のシフト担当者が短時間の説明で操作できる(UIのシンプルさ、誤操作リスクの低さ) |
| 互換性 | Android 6.0.1 (Java v7互換) |
| コスト | 端末数: 7台(正面3, 西4台)。wifiは当日用に整備したものを使用 |
6. システム構成・アーキテクチャ
6.1 全体構成図
図やリンクを貼る（draw.io, Mermaid, 画像など）
暫定のデータフロー（正式な図は別途作成）：
FZ-N1端末（Java）
└─ APIキー認証 ─→ Cloudflare Workers（Hono）
└─ Drizzle ORM ─→ Cloudflare D1
└─ Hono API ─→ sho-room（Web閲覧画面）
6.2 使用技術・技術スタック
| 区分 | 技術 | 選定理由 |
|---|---|---|
| 言語 | Java / TypeScript | 端末ではJava、apiはTypeScriptを使用。 |
| フレームワーク | Toughpad SDK / Hono | Toughpad SDKに関してはそれしかないため。Honoに関してはCloudflare Workers上で軽量に動作するため。 |
| インフラ/ホスティング | Cloudflare Workers | サーバーレスで運用コストが低く、エッジで動くため当日の応答速度に強い |
| データベース | Cloudflare D1 / Drizzle ORM | Workersとの親和性が高く、SQLiteベースで扱いやすいため。Drizzleは型安全なクエリが書け、D1との相性が良いため。 |
| 認証 | APIキー | Java端末→Honoサーバーで認証をする方法がこれしかない |
6.3 外部連携・API
| 連携先 | 用途 | 認証方式 |
|---|---|---|
| 来場者向けLIFFアプリ（別プロジェクト） | 来場者ID・QRコードの発行元データとの整合（要すり合わせ） | 未確定 |
| sho-room | 入場統計の閲覧（内部API） | 既存の学祭委員向け認証基盤に準ずる想定 |
補足：本システムはQRの表示・発行を対象外としているため、QRコード・来場者IDの発行は別プロジェクト（来場者向けLIFFアプリ）が担う想定です。どちらのIDを正として扱うか、来場者IDの発行タイミング・形式については、両プロジェクト間で事前にすり合わせが必要です。
7. データ要件
7.1 データモデル概要
ER図やテーブル定義へのリンク
来場者(1) — (多)入場記録 の1対多の関係。来場者IDをキーに、同一QRコードの複数回スキャンを入場記録側で時系列に記録し、F-002の照合時に「初回か再入場か」を判定する。
来場者 (Attendee)
└─< 入場記録 (EntryLog) ※来場者IDで紐付け
7.2 主要エンティティ
| エンティティ名 | 概要 | 主な属性 |
|---|---|---|
| 来場者 | 入場資格を持つ来場者の情報 | 来場者ID, 登録経路(事前/当日手動), 名前(※下記注), 年齢層, 性別, 登録区分(事前/手動) |
| 入場記録 | 実際の入場ログ | ログID(auto increment), 来場者ID, スキャン日時, 受付場所, 日付, 登録区分 |
※識別用なのでリアルネームである必要はない。手動時はゲスト1などで処理。
8. 画面・UI要件（該当する場合）
| 画面ID | 画面名 | 概要 |
|---|---|---|
| S-01 | スキャン画面 | QR読み取り・結果フィードバック表示(F-001〜F-004) |
| S-02 | 手動登録画面 | 専用端末での情報入力・登録(F-005) |
| S-03 | sho-room表示画面 | 入場者数のリアルタイム可視化(F-006) |
9. 制約条件
- 予算・期間の制約：イベント当日までに開発・テストを完了する必要がある
- 技術的制約：Cloudflare Workers上での実装が前提(D1のクエリ制限、Workers実行時間の制限等)
- Workers Paidがあるのである程度は気にしなくていい
- 規約・ポリシー上の制約：来場者の個人情報を扱う場合、保管期間・取り扱い方針を定める必要あり
- プライバシーポリシーは前年度のものを改良(前年度はデータの利用をしない方針だったのでそれを変更)
- 体制・リソースの制約：シフト担当者はIT部員以外も配属の可能性があるため、操作に不慣れな人でも扱える必要がある
10. 前提条件
- 来場者は事前にチケット(QRコード)を取得済みであること
- 当日の受付会場にはネットワーク環境(Wi-Fiまたはモバイル回線)が用意されていること
- 専用端末は主催側で用意し、運営/来場者の私物端末は使用しないこと
11. リスク・課題
| ID | 内容 | 影響度 | 対応方針 | 担当者 |
|---|---|---|---|---|
| R-01 | 会場のネットワーク環境が不安定な場合、オフライン機能(F-007〜F-009)の重要度が変わる | 中 | 事前に会場のネット環境を確認し、優先度を再設定 | |
| R-02 | 当日の混雑状況によりスキャン処理が性能要件を満たせない可能性 | 中 | 事前に想定来場者数でのテスト・台数調整 | |
| R-03 | 来場者ID・QRコードの発行元（LIFFアプリ側）とのデータ形式のすり合わせが未確定 | 中 | 早期に両プロジェクト間でID・QR形式の仕様を確定する |
12. マイルストーン・スケジュール
| フェーズ | 内容 | 期限 | ステータス |
|---|---|---|---|
| 要件定義 | 本ドキュメントの確定 | 2026/7/5 | 進行中 |
| 設計 | データモデル・画面設計・API設計 | 2026/7/12 | 未着手 |
| 実装 | F-001〜F-009の開発 | 2026/9/15 | 未着手 |
| テスト | 当日想定でのリハーサル(複数端末同時スキャン含む) | 2026/9/30 | 未着手 |
| リリース | イベント当日の運用開始 | 2026/10/10 | 未着手 |
13. 受け入れ条件（Acceptance Criteria）
- 正常なQRコードをスキャンした場合、1秒以内に入場記録され「入場OK」が表示される
- 同一QRコードを2回スキャンした場合、再入場として正しく検知され、エラーなく処理が完了する
- 未登録QRコードまたは端末未所持者に対し、手動登録導線へ正しく案内される
- 専用端末での手動登録が完了し、入場記録に反映される
- (Could要件を含める場合)通信不通時もローカル記録され、復旧後に重複なくサーバーに同期される
- シフト担当者が事前説明5分程度で問題なく操作できる
14. 承認
| 役割 | 氏名 | 承認日 | サイン/コメント |
|---|---|---|---|
付録
- 関連ドキュメントへのリンク
- 参考資料