メインコンテンツまでスキップ

入場管理システム 仕様共有資料

0. ドキュメント情報​

項目内容
プロジェクト名入場管理
文書種別実装向け仕様共有資料
バージョンv0.1.0
作成日2026/7/22
原資料detail_01.md
ステータスレビュー完了

0.1 本書の方針​

  • 本書はdetail_01.mdだけを根拠として作成する。
  • 原資料に明記されていない仕様は補完しない。
  • 未記載、複数案、不整合がある内容は「要確定」とする。
  • 別プロジェクトの内部仕様を本システムの仕様として定義しない。
  • 「要確定」の内容は、決定されるまで実装上の前提にしてはならない。

0.2 仕様状態​

状態意味
確定原資料に明記されている
条件付きCould要件等、実装対象に含めるか未確定
要確定原資料で未記載・不整合・別途検討となっている

1. 概要​

1.1 目的​

  • 入場時にQRコードを読み取り、入場処理を行う。
  • 受付の行列を滞留させず、入場を円滑にする。
  • 時間帯、受付、年齢層、性別、グループ人数の入場統計を取得する。
  • 入場統計をSho-Roomで確認できるようにする。

1.2 対象範囲​

  • Panasonic FZ-N1のスキャン機能を利用した入場処理
  • QRコードの照合
  • 初回入場・再入場の判定
  • 入場記録
  • 専用端末による手動登録
  • Sho-Roomでの入場者数表示
  • 条件付きで、オフライン記録・同期・競合解消

1.3 対象外​

  • 来場者側でのQRコード発行・表示
  • 別プロジェクトが管理する来場者向け画面

1.4 用語​

用語定義
蒼翔祭会津大学の学園祭
学祭委員本システムを運用する学園祭実行委員
FZ-N1QR読取に使用するPanasonic製Android端末
Sho-Room学祭委員向け管理画面
受付正面、西等の入場処理場所
再入場同一QRコードの2回目以降の読取
手動登録QR未所持者・当日未登録者を専用端末で登録する対応
ゲスト1〜10手動登録者に割り当てる仮の識別名

2. 利用者・関係者​

2.1 利用者​

  • 当日シフト担当者
  • 手動登録担当者
  • Sho-Roomで統計を確認する学祭委員

2.2 ステークホルダー​

役割氏名
プロジェクトリーダー@二枚貝
開発担当@凶兆の黒猫 @novice
利用者当日シフト担当

3. システム構成​

3.1 確定している構成​

3.2 技術スタック​

区分技術状態
FZ-N1実装Java確定
端末SDKToughpad SDK確定
API言語TypeScript確定
APIフレームワークHono確定
インフラCloudflare Workers確定
データベースCloudflare D1確定
ORMDrizzle ORM確定
端末認証APIキー確定

3.3 未確定の構成​

  • QR発行元とのAPIまたはデータ連携方式
  • 入場管理APIとSho-Roomの接続方式
  • Javaの具体的な言語レベル
  • オフライン用ローカルストレージの方式
  • 外部ログ・監視システム

4. 機能仕様​

4.1 機能一覧​

ID機能仕様優先度状態
F-001QR読取モード起動FZ-N1をQRスキャン待機状態にするMust確定
F-002QRコード照合QR値をDB上の登録情報と照合するMust確定
F-003入場情報記録入場時刻、受付、来場者等を記録するMust確定
F-004結果フィードバック入場OK、再入場、未登録を画面と音で表示するMust確定
F-005手動登録専用端末から来場者情報と入場を登録するMust確定
F-006入場者数表示Sho-Roomへ集計値を表示するCould条件付き
F-007オフライン記録通信不通時の入場データを端末へ保存するCould条件付き
F-008オフライン同期通信復旧後にローカルデータを送信するCould条件付き
F-009重複・競合解消複数端末の同期データを突合するCould条件付き

4.2 QR読取モード​

入力

  • シフト担当者によるスキャン開始操作

処理

  • Toughpad SDKを用いてスキャナを起動する。
  • QRスキャン待機画面へ遷移する。

出力

  • スキャン待機状態

異常系

  • スキャナ起動失敗時はエラーを表示し、再試行を案内する。

画面タップ、物理ボタン等の具体的な開始操作は要確定とする。

4.3 QRコード照合​

入力

  • FZ-N1が読み取ったQR値

処理

  • APIキー認証付きでHono APIへ照会する。
  • D1上の登録情報と照合する。

出力

  • 入場OK
  • 再入場
  • 未登録

異常系

  • QR破損・読取不可時は再スキャンを案内する。
  • DBに該当しない場合はエラー音と表示を行う。

要確定

  • QR文字列の形式
  • 照合に使用する来場者ID
  • APIのパス、要求・応答JSON
  • APIキーの発行単位と送信ヘッダー
  • QR失効・対象日外等の追加判定

4.4 入場情報記録​

入力

  • 来場者ID
  • スキャン日時
  • 受付場所

処理

  • 入場記録テーブルへ追加する。
  • DB書込み失敗時は、F-007を実装する場合にローカル記録へ切り替える。

出力

  • 登録完了または失敗

受付場所を端末へ設定する方法、端末IDを記録するか、日時の基準は要確定とする。

4.5 初回入場・再入場​

  • 同一QRコードの2回目以降を再入場として扱う。
  • 再入場の場合は以降の登録フローを省略し、通行可能とする。
  • 再入場を初回入場と異なる画面・音で通知する。

次の内容は要確定とする。

  • 再入場判定を日ごとにリセットするか
  • 再入場スキャン自体を入場記録へ残すか
  • 再入場をSho-Roomの人数へ加算するか
  • 複数受付で同時に読み取った場合の判定

4.6 結果フィードバック​

  • 入場OK、再入場、未登録を一目で区別できること。
  • 画面表示と効果音を組み合わせること。
  • 判定に時間がかかる場合は処理中表示を行うこと。

色、アイコン、音、表示時間、次のスキャンへの復帰方法はUI設計で確定する。

4.7 手動登録​

対象

  • QR未所持者
  • 端末未所持者
  • 当日未登録者

入力

  • 年齢層
  • 性別

処理

  • 実名を要求せず、ゲスト1等の識別名を自動採番する。
  • 登録区分「手動」で来場者レコードを作成する。
  • 入場記録へ即時反映する。

異常系

  • 必須項目が未入力の場合は登録しない。

要確定

  • 専用端末の種類
  • 年齢層・性別の選択肢
  • ゲスト1〜10の採番範囲と一意性
  • LINEによる当日登録との使い分け
  • 手動登録者の再入場方法

4.8 Sho-Room入場統計​

集計対象

  • 入場者数
  • 時間帯
  • 受付場所
  • 年齢層
  • 性別
  • グループ人数

表示

  • 数値
  • グラフ

異常系

  • データ取得失敗時は前回値を保持し、エラーを表示する。

集計間隔、更新間隔、グラフ種別、再入場の扱いは要確定とする。

5. オフライン仕様​

5.1 確定している要件​

  • 通信不通を検知する。
  • 通信不通時は入場データを端末内へ一時保存する。
  • 通信復旧を検知したら保存データをサーバーへ送信する。
  • 送信成功分をローカルから削除する。
  • 同期中に再切断した場合は再送対象として保持する。
  • 複数端末の同一QR記録を重複として検出する。
  • 最も早い記録を正として採用する。

5.2 要確定事項​

  • オフライン時に登録済みQRを判定する方法
  • オフライン時に表示する結果
  • 端末へ事前データを配布するか
  • ローカルDB・ストレージ
  • 保存可能件数と容量超過時の動作
  • 同時刻記録の優先順位
  • 端末時刻ずれの扱い
  • 同期APIの形式、バッチ件数、再試行
  • 二重送信を防ぐ識別子

これらが確定するまでF-007〜F-009の実装方式を固定しない。

6. 外部連携​

6.1 QR発行元​

  • QR表示・発行は別プロジェクトの責務である。
  • 本システムは、別プロジェクトが発行したQRを読み取る。
  • 来場者ID、QR形式、発行タイミングは両担当間で確定する必要がある。

別プロジェクトのAPI、DB、内部構成は本書では定義しない。

6.2 Sho-Room​

  • Sho-Roomへ入場統計を提供する。
  • Sho-Room側の認証は既存の学祭委員向け認証基盤に従う想定である。

統計API、認可、表示更新方法は要確定とする。

7. データ仕様​

7.1 論理モデル​

Attendee 1 --- N EntryLog

7.2 エンティティ​

エンティティ原資料にある属性要確定
Attendee来場者ID, 登録経路, 名前, 年齢層, 性別, 登録区分ID型、名前の保存方法、更新日時
EntryLogログID, 来場者ID, スキャン日時, 受付場所, 日付, 登録区分再入場、端末、同期状態

7.3 要確定事項​

  • 主キーの型と採番方式
  • 来場者IDとQR発行元IDの対応
  • 同一来場者に複数入場記録を許可する条件
  • 再入場の保存方法
  • 論理削除・物理削除
  • データ保持期間
  • オフライン操作・同期状態のエンティティ

8. 画面仕様​

画面ID画面内容
S-01スキャン画面QR読取、待機、入場結果表示
S-02手動登録画面年齢層・性別入力、登録結果表示
S-03Sho-Room入場統計入場者数のグラフ・数値表示

8.1 操作性​

  • IT部員以外のシフト担当者でも扱えること。
  • 事前説明5分程度で主要操作を実行できること。
  • 入場結果を画面と音で即座に判断できること。

具体的なレイアウト、文言、色、アイコン、物理ボタン割当は画面設計で確定する。

9. 認証・セキュリティ​

  • FZ-N1からHono APIへの要求はAPIキーで認証する。
  • 端末とサーバー間はHTTPSを使用する。
  • 不正端末からのアクセスを制限する。
  • 来場者の個人情報を扱う場合はプライバシーポリシーを整備する。

次の内容は要確定とする。

  • APIキーの発行単位
  • APIキーの保存、配布、失効、再発行
  • 端末紛失時の対応
  • APIのレート制御
  • 個人情報・ログの保存期間

10. 非機能要件​

10.1 性能​

記載箇所要件
非機能要件QRスキャンから結果表示まで3秒以内
受け入れ条件正常QRは1秒以内に記録・表示

1秒と3秒で不一致のため、正式な性能目標は要確定とする。

10.2 可用性​

  • イベント当日の受付時間中にサービス停止が発生しないことを目標とする。
  • オフライン機能を実装する場合は通信障害時も記録を継続する。

数値目標と障害時運用は要確定とする。

10.3 互換性・端末​

  • Android 6.0.1に対応する。
  • FZ-N1を7台使用する想定である。
  • 内訳は正面3台、西4台である。
  • 当日用Wi-Fiを使用する。

Javaの言語レベルは原資料にJavaとJava v7互換の記載があるため要確定とする。

11. 受け入れ条件​

  • 正常なQRをスキャンして入場記録と入場OKを表示できる
  • 同じQRの2回目以降を再入場として処理できる
  • 未登録QRを手動登録窓口へ案内できる
  • 専用端末で手動登録し、入場記録へ反映できる
  • F-007〜F-009を実装する場合、通信不通時に保存し、復旧後に重複なく同期できる
  • シフト担当者が5分程度の説明で主要操作を行える

性能試験の合格値は、1秒・3秒の不一致を解消してから追加する。

12. 要確定事項​

ID分類要確定事項
TBD-001QRQR形式、識別ID、発行タイミング
TBD-002QRグループまたは個人のどちらを一回の入場単位にするか
TBD-003入場再入場の日付境界、ログ、統計
TBD-004入場同時スキャン時の判定
TBD-005手動登録専用端末とLINE登録の使い分け
TBD-006手動登録手動登録者の再入場方法
TBD-007統計更新間隔、集計粒度、再入場の扱い
TBD-008オフラインオフライン照合方法
TBD-009オフライン保存、同期、競合、冪等性
TBD-010APIAPIパス、JSON、エラー、認証ヘッダー
TBD-011認証APIキーのライフサイクル
TBD-012データID、制約、削除、保持期間
TBD-013性能1秒または3秒の目標値
TBD-014JavaJava言語レベル
TBD-015外部連携QR発行元・Sho-Roomとの連携方式

12.1 要確定事項の解消状況（2026/7/31 決定）​

Epic issue #399 での方針協議により、以下の通り決定した。来場者向けプラットフォーム側（docs/files/specifications/guestApp/spec.md）とも整合する内容である。

ID結論
TBD-001QRは署名付きJWT。予約確認画面を開くたびに10分程度の短命JWTを発行する（LIFFはオンライン前提のため）
TBD-002groupId/guestId両方発行し、受付は代表QR(groupId)を基本運用とする
TBD-003再入場は日ごとにリセット。記録(EntryLog)は残すが、Sho-Room人数統計には加算しない
TBD-004同一QRの同時スキャンは、日付+QR識別子への一意制約で先着1件のみ入場成立とする
TBD-005LINE所持者は当日でも来場者向けプラットフォームの予約フローで登録。専用端末はLINE非対応者向け（現場判断で併用可）
TBD-006手動登録者にQR等の再入場識別は設けない。入場後の再確認は不要とし、現場判断に委ねる
TBD-007フェーズ1はポーリング(数分間隔)。将来的にDurable Objectsでのリアルタイム化を検討
TBD-008通常はDB照合。DB問い合わせ失敗時のみJWT署名検証にフォールバックして一時的に通す
TBD-009端末はSQLite保存(上限1,000件)。オンライン復帰時にバッチ同期。冪等キーは「QR文字列+スキャン日時」のハッシュ。優先度は低（余力があれば）
TBD-010RESTful API（/api/v1/entries, /entries/sync, /stats）。JSON、エラーは{ error: { code, message } }形式、認証はX-API-Keyヘッダー
TBD-011単一APKで端末登録画面を用意し、Sho-Room発行のOTP(6桁)を入力してAPIKeyを紐付ける方式（端末ごとに個別キー発行）
TBD-012IDはUUID v4(Attendee)/auto increment(EntryLog)。論理削除が基本。大学への報告完了後に学祭委員側で削除
TBD-013性能目標は3秒以内を正式採用（1秒は参考値に降格）
TBD-014Java 8を採用（Android Gradle Plugin 3.0以降のcore library desugaringを利用）
TBD-015来場者向けプラットフォームとのQR/ID連携は上記TBD-001, 002の通り確定

13. スケジュール​

フェーズ原資料の期限ステータス
要件定義2026/7/5進行中
設計2026/7/12未着手
実装2026/9/15未着手
テスト2026/9/30未着手
リリース2026/10/10未着手

期限は原資料の記載をそのまま転記しており、現在日付に合わせた補正は行わない。

14. 承認​

役割氏名承認日コメント
プロジェクトリーダー@二枚貝
開発責任者
運用責任者