招待特典 受付・発送システム
招待チケットで人を呼んでくれたお客様（招待者）から、特典の送付先を集めて発送まで管理するシステムです。
公演ごとに作っていた Google フォーム（人数で分岐するセクション形式）の置き換えです。
- 公開フォーム
/{公演のURL名}: スマホ向けのステップ形式。招待者情報 → 招待した人数 → 特典ごとの希望メンバー → 送付先 → 確認（個人情報の取り扱いに同意）→ 受付番号とQRの表示
- 入力途中の内容はそのタブの中だけに保持（再読み込みしても続きから。タブを閉じると消える）
- 郵便番号から住所を自動入力、電話番号は自動でハイフン、メールのよくある打ち間違い（gmial.com など）は候補を表示
- 受付完了メールの修正リンク
/{URL名}/edit?token=… から、受付期間中は希望メンバーと送付先を直せる（人数・チケット番号は直せない。発送準備に入ると直せなくなる）
- 管理画面
/admin（会社の Google アカウントでログイン。@focpro.co.jp は初回ログインで自動的にスタッフになる）
- 当日受付: スタッフのスマホで、お客様の完了画面のQRを読み取るか受付番号を入れて、ワンタップで人数を確定。氏名・住所は出ない
- 回答 / 集計 / 発送: 回答一覧と人数確認、特典×メンバーの必要数、発送（CSV・宛名ラベル・ピッキングリスト・追跡番号の取り込み・発送完了メール）
- 設定: 公開までのチェックリスト、お客様画面のプレビュー、受付開始/終了のボタン、特典（段）を表でまとめて編集（並び替え・追加・削除）、メンバー、告知画像、QRコード
- 操作ログ: 個人情報の表示・CSV出力・印刷などを誰がいつしたか
特典のしくみ
- 公演ごとに「段」（必要人数・特典名・希望メンバーを選ぶか・発送か当日手渡しか）を管理画面で登録します
- 累積: 上の段に届くと下の段の特典もすべてもらえます（例: 10人なら 1・3・5・10人の特典）
- フォームの「招待した人数」の選択肢は、登録した段の必要人数です
- 人数はお客様が申告し、スタッフが管理画面で確定人数を入れます。確定人数を変えると特典が組み直されます
- 届かなくなった特典は外れ、残る特典の希望メンバーはそのまま残ります
- 新しく届いた特典は「メンバー未選択」で追加されるので、詳細画面で選びます
- 同じ公演で同じチケット番号は1回しか受け付けません。メールか電話番号が同じ回答には「重複の疑い」の印がつきます
回答の状態
| 状態 | 意味 |
|---|
| 受付 | お客様が送信した直後。人数は未確認 |
| 人数確認済 | スタッフが人数を確認した。発送対象になる |
| 発送準備 | 発送作業中（宛名を出力した） |
| 発送済 | 発送した（追跡番号の取り込みなど） |
| 保留 / 無効 | 発送対象から外す。無効は集計からも外す |
当日と発送の流れ
- 管理画面で公演を作り（前の公演の特典とメンバーを複製できます。URL名は空欄なら自動）、「設定」のチェックリストに沿って特典・告知画像を設定し、プレビューで確認して「受付を開始する」
- 「設定」タブの QR コード（PNG）を印刷して会場で案内する
- お客様が入力 → 完了画面（受付番号とQR）をスタッフに見せる
- スタッフが「当日受付」でQRを読み取り（または受付番号を入力）、「申告どおり確定」か人数を直して確定
- 「集計」で特典×メンバーの必要数を確認して制作する
- 「発送」タブで
- 発送対象を「発送準備」にする
- CSV（汎用 / クリックポスト）を出力、または宛名ラベル（A4 12面）とピッキングリストを印刷
- 追跡番号の CSV を取り込む（受付番号・追跡番号の2列）→「発送済」になる
- 発送完了メールを送る
公演日から「個人情報の保存期間」（初期値90日）が過ぎると、送付先・電話・メールは毎日の定期処理で自動削除されます。
セキュリティ
| 対策 | 内容 |
|---|
| 暗号化 | 氏名・電話・郵便番号・住所・メールは、サーバーで AES-256-GCM で暗号化してから DB に保存（鍵 PII_ENCRYPTION_KEY は DB とは別に環境変数で管理）。重複チェックは別の鍵 PII_HASH_KEY の HMAC で行う |
| ログイン | 管理画面は会社の Google アカウントでログイン。staff_email_domains（初期値 focpro.co.jp）のドメインで Google が確認したアドレスだけが自動でスタッフになる。ほかのアカウントはログインしても何も見えない。パスワードでのログインも残してあり、その場合は認証アプリ（TOTP）の2段階認証が必須。DB の RLS も「Google ログインか2段階認証済み」のスタッフしか通さない |
| 秘密鍵を持たない | アプリは Supabase の service_role 鍵を持たない。公開フォームは publishable key で、公開中の公演情報の読み取りと、サーバーキー（APP_SERVER_KEY。DB にはハッシュだけ）を確認する送信・修正用の関数しか使えない |
| 自動ログアウト | 30分操作がなければログアウト（サーバー側と画面側の両方） |
| 画面での伏せ字 | 回答詳細では個人情報を伏せ字で出し、「表示」を押したときだけ見せる。表示は操作ログに残る。当日受付にはニックネームしか出ない |
| 操作ログ | 個人情報の表示・CSV出力・ラベル印刷・人数確定・状態変更などを記録（追記のみ。画面から消せない） |
| 公開フォーム | 送信はサーバー経由（サーバーキーが必要）で、Turnstile と送信回数制限（同じ IP から10分に5件まで）をかける |
| 修正リンク | 推測できないランダムなトークン（DB にはハッシュだけ保存）。受付終了か発送準備で使えなくなる |
| 同意 | 利用目的・保存期間・問い合わせ先をフォームに表示し、同意を必須にして日時を保存 |
| 削除 | 公演日から保存期間（初期値90日）を過ぎると、送付先・連絡先・ハッシュ・修正トークンを DB の定期実行（pg_cron、毎日 3:00 JST）で自動削除し、操作ログに残す |
| HTTP | CSP・HSTS・X-Frame-Options などを設定。管理画面と修正ページはキャッシュさせず、検索エンジンにも載せない |
暗号化鍵の扱い: PII_ENCRYPTION_KEY を失うと保存済みの個人情報は読めなくなります。作ったらパスワード管理ツールなどに控え、変えないでください。漏れた疑いがある場合は、公演ごとの受付を止めてから相談してください（鍵の入れ替えは今のところ未対応です）。
スタッフにするドメインの追加: Supabase の SQL Editor で insert into staff_email_domains (domain) values ('example.co.jp');。ドメイン以外の人を個別に追加する場合は、その人が一度 Google でログインしたあと insert into staff (user_id, display_name) select id, email from auth.users where email = '…';。外す場合は delete from staff where user_id = …。
構成
- Next.js 16（App Router）/ TypeScript / Tailwind CSS
- Supabase（Postgres・Auth・Storage）。RLS で、データの閲覧と更新は
staff に登録したユーザーだけに限定
- 公開フォームはサーバー側から
public_submit_invitation 関数（サーバーキー必須）を呼んで1トランザクションで登録
- 個人情報の自動削除は pg_cron
- Vercel（ホスティング）/ Resend（メール）/ Cloudflare Turnstile（ボット対策）/ zipcloud（郵便番号検索）
supabase/migrations/ テーブル・RLS・DB関数（public_submit_invitation, public_*_invitation_by_token, set_confirmed_count, purge_personal_data, スタッフ自動登録のトリガー）
supabase/seed.sql 開発用データ（SCRAMBLE SMILE のメンバーと 2nd SMILE の特典）
src/app/[slug]/ 公開フォーム（edit/ は修正リンク）
src/app/admin/ 管理画面
src/app/api/ 郵便番号検索
src/lib/ 特典の計算・入力チェック・暗号化（crypto.ts）・伏せ字・CSV・メールなど
db-tests/ 素の Postgres で動く DB テスト
e2e/run.mjs Playwright の E2E
開発
npm install
npx supabase start # ローカルの Supabase（Docker が必要）。migrations と seed.sql が入る
cp .env.example .env.local # `npx supabase status` の URL / Publishable key を書く（APP_SERVER_KEY はそのままでよい）
# PII_ENCRYPTION_KEY と PII_HASH_KEY は `openssl rand -base64 32` で別々に作る
# ローカルでは Google ログインの代わりにパスワードのスタッフを作る（SUPABASE_SECRET_KEY にローカルの Secret key を書く）
npm run staff:create -- [email protected] password1234 "鍋島"
npm run dev # http://localhost:3000/2nd-smile と http://localhost:3000/admin
# 初回ログイン時に認証アプリの登録画面が出ます
テスト:
npm test # ユニットテスト（特典の計算・入力チェック・CSV）
npm run test:db # DB テスト（ローカルの Postgres。DATABASE_URL で接続先を変えられる）
npm run test:e2e # E2E（supabase start と npm run build && npm start が動いている状態で。スタッフは認証アプリ未登録にしておく）
npm run typecheck && npm run lint
本番の環境
公開までの残りの手順は docs/DEPLOY.md を参照。
| もの | 場所 |
|---|
| DB・ログイン | Supabase プロジェクト「Syotaitokuten」 |
| 公開 | Vercel プロジェクト「syotaitokuten」（GitHub の main に入ると自動で公開） |
| メール | Resend（送信元 [email protected]） |
本番の環境変数は Vercel に設定済み。PII_ENCRYPTION_KEY / PII_HASH_KEY / APP_SERVER_KEY は Vercel の画面（Settings → Environment Variables）で確認できるので、パスワード管理ツールにも控えておくこと。
APP_SERVER_KEY を変えるときは、Vercel の値と DB のハッシュを両方変える:
update app_private.server_keys set key_hash = encode(sha256(convert_to('<新しいキー>', 'UTF8')), 'hex') where name = 'app';
マイグレーションを追加したら npx supabase link --project-ref <ref> → npx supabase db push で本番に流す。
未対応・要確認
- 15人・20人・40人の特典は内容が未定のため seed に入れていません。管理画面の「設定 → 特典（段）」から追加してください
- 1人以上の「限定ポストカード」は seed では「発送」にしています。会場で手渡しする場合は「当日手渡し」に変えてください
- クリックポストの CSV は「まとめ申込」の列構成（郵便番号・氏名・敬称・住所4行・内容品）に合わせていますが、実際の取り込み画面で一度確認してください
- ヤマト B2 クラウド・ゆうパックプリントの取込形式は、汎用 CSV を各サービスの取込設定で割り当てて使ってください
- Cloudflare Turnstile（ボット対策）は未設定です。設定する場合は
NEXT_PUBLIC_TURNSTILE_SITE_KEY と TURNSTILE_SECRET_KEY を Vercel に追加してください（送信回数の制限は設定なしでも効いています）
