waiting-list

ウェイティングリストポータル

このスキルは、「ウェイティングリストが必要です」という要望を、誠実な製品の約束、適切なシステム境界、実装可能な提供計画へと落とし込むために使用します。関心のある人のリスト、公平な対応順、トラフィックゲート、予約は、それぞれ異なるものです。洗練されたランディングページによって、その意味が暗黙のうちに決められてしまわないようにしてください。

読み込むタイミング

ユーザーが、先行アクセス、新製品のローンチ需要、希少商品の販売、予約、会員登録、イベント、ベータプログラム、またはアクセス集中時の入場に向けたポータルを設計、レビュー、実装、比較している場合に、このスキルを読み込みます。

使用しないケース

• コピー、ビジュアルデザイン、SEO、またはアクセシビリティだけが対象の場合は、該当するフロントエンドまたはコンテンツのスキルを使用し、このスキルはリストの動作に関する場合にのみ追加します。
• 一般的な API、データベース、メール、セキュリティ、または決済の実装には、担当する専門スキルを使用します。このスキルは、ウェイティングリスト固有の契約と障害モードを提供します。
• 稼働中のウェイティングルームベンダーやキューデータストアについては、最新の公式ドキュメントを確認してください。このスキルは設計手法であり、ベンダーの運用手順書や法律上の助言に代わるものではありません。
• 単独の CRM 移行やメール／SMS キャンペーンには、担当する連携スキルを使用します。CRM が、ウェイティングリストにおける連絡先確認後のライフサイクルの下流に位置する場合は、このスキルを読み込みます。

基本的なワークフロー

デフォルトの方針とマーケターの体験

新しいマーケティング用ウェイティングリストでは、静的な HTML ページを 1 つ、Alpine.js（CSP ビルド）、Vite によるパッケージング、カスタム CSS、Vercel の Node.js ランタイム上の TypeScript API 関数、マネージド Neon Postgres を使用します。メール（SendGrid を使用）と任意の SMS 認証には Twilio Verify コードを使用し、CRM はサーバー側のランタイム設定で選択できるようにします。Python バックエンドと Rails は避けてください。既存のホスティング環境や要件に適している場合は、Go または Rust も明示的な代替案です。これらはデフォルトであり、既存の正常に動作している連携を置き換える理由ではありません。

構築またはデプロイする前に、references/default-stack.md をお読みください。プロバイダーの方針、Vercel の制限、リポジトリの構成、ワーカーの実行、代替手段について定めています。新しいポータルではすべて、references/brand-and-marketer-workflow.md をお読みください。キャンペーン概要、ブランドガイド、ロゴ、参考画像、任意の動画を収集し、本番環境に接続する前にブランドを反映したプレビューを提示します。平易な言葉でのヒアリングには、templates/campaign-brief.md を使用してください。技術的な記録はエージェントが作成します。マーケターに ORM、フレームワーク、再試行アルゴリズム、データベーススキーマを選ばせないでください。 プレミアム、シネマティック、動きの多い、または参考資料を重視するキャンペーンでは、references/engagement-and-visual-system.md もお読みになり、関連する体験概要、フォールバック、パフォーマンス、ビジュアルテストの方針を記録してください。参考サイトは、観察可能なインタラクションの原則を知るための情報源として扱い、そのブランド、アセット、ソース、レイアウト、希少性を訴求する表現、製品の主張をコピーしてよいという意味ではありません。 キャンペーンのヒーロー画像、製品シーン、エディトリアルイラストには、承認済みの提供アセット、または画像生成で作成したオリジナルアートワークを使用してください。生成したアートワークは、公開前にプレビューを提示して承認を得てください。ユーザーがその美的表現を明示的に希望しない限り、キャンペーンのアートワークを CSS の図形やグラデーション、インライン SVG の描画、キャンバスのスケッチ、絵文字、ASCII、アイコンのコラージュで代用しないでください。 チャート、図、コントロール、ステータス表示など、情報そのものが幾何学的表現である場合は、プログラムによるグラフィックが適しています。 templates/campaign-config.example.json をサーバー側設定の例として使用してください。未設定の本番環境向け選択項目は、実際の送信を有効にする前に解決する必要があります。

デフォルトのキャンペーンは、メールへの関心を受け付け、メール確認を必須とし、電話番号の収集と紹介を無効にし、順位を表示せず、予約を暗示せず、CRM は未接続の状態にします。SMS を有効にする際、指定されたやり取りの形式がない場合は、マネージド OTP を優先してください。SMS のマジックリンクが明示的に要件として指定されている場合は、そのデフォルトよりも要件を優先し、プロバイダーの機能上の制約を説明してください。

このスキルをポータルの実装に使用すると、デプロイを作成したりメッセージを送信したりすることがあります。作業に着手する前に、対象、範囲、ロールバック手順を確認してください。読み取り専用の調査は、確認なしで進めてもかまいません。既存の承認でこれらの詳細がすでにカバーされている場合は、それを使用してください。まずローカルの成果物とプレビューを準備してください。モックフォームが実際の登録情報を収集するかのように説明してはなりません。

1. 技術を選ぶ前に、約束する内容を決める

次の質問に、わかりやすい言葉で答えます。

1. 参加するとはどういう意味ですか。関心を示すこと、順番待ちリストに加わること、招待を受ける資格を得ること、割り当ての抽選機会を得ること、サービス枠を申し込むことのどれですか。
2. 何が保証されますか。別途確定する手続きがない限り、参加しても在庫、支払いの優先権、予約、入場は確保されないことを明記します。
3. どのような出来事によって、その人は次の段階に進みますか。確認、容量の確保、予定された提供開始、キャンセル、スコア、紹介、抽選、運営者の判断のどれですか。
4. 連絡先の確認は任意ですか、必須ですか、それともありませんか。確認済みのメールアドレスや電話番号によって、実際に何が、どのくらいの期間許可されますか。また、招待の期限が切れたとき、登録解除されたとき、重複した登録が届いたときはどうなりますか。
5. 提供開始時に何が満たされている必要がありますか。ピーク時のアクセス数、許容できる損失、公平性のルール、地域、アクセシビリティ、言語、データの保存場所、連携、ロールバックの手順を確認します。

前提は前提として記録します。運営者がセグメントや適合度によって選ぶ可能性がある場合は、「現在の順位」と表現せず、「関心リスト」または「推定順位」と呼びます。

2. 主なパターンを1つ選ぶ

約束を実現できる最小限のパターンを使います。パターンを組み合わせるのは、その境界と移行が明確な場合に限ります。

パターン	信頼できる唯一の情報源	推奨される基本構成	主な落とし穴
関心リスト	リレーショナルテーブル、CRM、またはESP	静的／SSRページと、サーバー側のフォームエンドポイントおよび非同期メール	順番待ちの列ではありません。架空の順位を表示しないでください
確認済みの先行アクセス用キュー	データベースとイベント／アウトボックスレコード	プログラムと正規化された連絡先を一意に管理し、適切な場合はダブルオプトインを使い、招待の状態を管理します	確認済みのメールアドレスは、本人であることや購入の証明にはなりません
紹介による優先権	データベースのイベント台帳	不変の到着キーと、確認済みの紹介イベントおよびバージョン管理されたポリシー	自己紹介、購入されたトラフィック、「口コミで広がった」という主張は、公平性を損なう可能性があります
仮想待合室	エッジ／ゲートウェイと永続キュー	署名付き入場トークン、Cookieによる継続性、アトミックな入場、上限付きのポーリング	ページへの入場許可は、在庫への権限やチェックアウトの直列化を意味しません
予約枠の補充	スケジュール／容量サービス	空いた枠、希望条件、有効期限に基づいて利用者をマッチングします	全体で1つのFIFOキューにすると、公平性を欠いたり、運用上役に立たなくなったりする可能性があります
割り当て、抽選、または予約注文	在庫／支払い／割り当てサービス	資格の判定と、割り当て、予約、支払い、履行を分離します	割り当てを「ウェイトリスト」と呼ぶと、過剰販売や返金義務が見えにくくなります
ヘッドレス／埋め込みAPI	独立したAPIとイベント境界	スコープ付き認証情報、CORS、冪等性、Webhookを備えた公開書き込み契約	ブラウザーに保持されたシークレットは、サーバーのシークレットではありません

シンプルな提供開始前ページなら、まず関心リストのパターンを使います。提供開始日にアクセスが急増するなら、まず仮想待合室またはエッジ製品を使います。希少なリソースが製品やサービスの本当の課題である場合は、まず在庫またはスケジュールの境界を設計し、その境界にリストを接続します。

パターンの比較、スケールのモデル化、キュー、紹介ループ、予約、ベンダーが必要かどうかの判断には、references/architecture-patterns.mdを参照してください。

3. 状態マシンとデータ契約を定義する

実装時は、具体的なエンドポイント、永続化、検証、CRM、障害に関する契約について、 references/implementation-contract.md を参照してください。

不透明な ID を使い、連絡先データを URL、ログ、分析ラベル、 公開ランキングページに含めないでください。基本形として、次のようにします。

submitted -> verification_pending -> active -> invited -> claimed
                                  \-> suppressed/removed
invited -> expired

待機室には、別個のキュー／受付状態を設けてください。

identified -> queued -> admitted -> consumed
                     \-> abandoned/expired

ポータルで連絡先を検証する場合は、1 つの過剰な意味を持つ verified フラグを 使わず、チャネルごとに個別にモデル化してください。

email: unrequested -> sent -> clicked/verified | expired/revoked
phone: unrequested -> sent -> clicked/verified | expired/revoked

「検証済み」とは、指定された方法とタイムスタンプに基づいて、そのチャネルの証明が承認されたことを意味します。法的な本人確認が完了したこと、入力された人物がそのアカウントを所有していること、その番号がマーケティングに適していること、または連絡先情報が今後も正確であることを証明するものではありません。連絡先情報の証明または CRM へのデータ配信が対象となる場合は、 references/contact-verification-and-crm.md を参照してください。

各状態遷移について、実行者、前提条件、副作用、再試行時の動作、 監査イベント、ユーザーに表示するメッセージを定義してください。最低限、次の情報を保存します。

• program_id、不透明な entry_id、created_at、および安定したタイブレークキー。
• 正規化バージョンを文書化し、元の値を保護したうえでの正規化済み連絡先の一意性。キー付き検索ハッシュを導入する場合は、キーのローテーション計画を立てること。
• 同意の目的、流入元／UTM のアトリビューション、検証日時、抑制日時。
• 明示的なステータス、ポリシー／バージョン識別子、招待／登録申請の有効期限、および選考やサービスとの照合に必要な属性のみ。
• 有効化する場合は、紹介コードの所有者と紹介イベント。変更可能なクライアント状態から件数を推測しないこと。
• チャネルごとの検証方法、証明 ID、verified_at、有効期限／取り消し日時、同意の目的。生のトークンは保存しないこと。
• CRM 同期ステータス、マッピング／バージョン、プロバイダーのレコード ID、冪等性キー、最終エラー。これらは連携状態として保持し、待機リストの信頼できる唯一の情報源にはしないこと。
• 状態変更と外部への処理を記録する、追記専用の監査／イベントレコード。

POST は、冪等性キーまたはデータベースの一意性制約を用いて、安全に再試行できるようにしてください。重複時の動作は意図的に定義します。通常、すでに登録済みの連絡先には汎用的な成功レスポンスを返し、エンドポイントがメールアドレス列挙のオラクルにならないようにします。並び順と公開ルールによってその主張の正当性が担保されない限り、生のレコード件数を個人の順位として公開しないでください。

4. 通常のリクエスト経路を構築する

デフォルトの経路は次のとおりです。

page -> server endpoint -> validate/normalize -> abuse gates -> durable write
     -> enqueue notification -> generic response
                                      \-> worker/provider -> delivery events

サーバー側で検証します。多層の制御を適用します。スキーマと長さの制限、同一オリジンのフォームに対する CSRF 保護、ヘッドレスクライアントに対する厳格な CORS、IP ごとおよび連絡先ごとのレート制限、ハニーポットまたはタイミングのシグナル、リスクの高いトラフィックに対するボットチャレンジを導入します。Turnstile を使う場合は、サーバーから Siteverify を呼び出す必要があります。ブラウザーのトークンだけでは保護になりません。選択したプロバイダーと障害モードで測定するまでは、「200 ms 未満」などの特定のレイテンシを保証しないでください。

エントリーと通知の意図を、トランザクションまたは永続的なアウトボックスを介して書き込みます。ワーカーは再試行可能にし、送信する Webhook は冪等にします。同期レスポンスは短く保ちますが、プロバイダーが利用できない場合にメール送信の意図を黙って失わないようにしてください。

リストの品質、同意の証明、または入力ミスへの耐性が重要な場合は、ダブルオプトインを使用し、未検証レコードの権限と保持期間を明確にします。トランザクション用の検証・招待メールとマーケティング更新を分離し、配信停止と登録解除の状態を尊重し、送信ドメインを認証して、バウンスと苦情を処理します。詳しい制御チェックリストについては、references/operations-and-abuse.md を参照してください。

CRM への配信を有効にする場合は、設定された適格性の判定条件（多くの場合、連絡先の有効化と該当する同意）の後にのみキューへ登録します。承認済みのフィールドだけをマッピングし、サーバー側の認証情報を使用します。また、アダプターは再試行可能かつ冪等にします。CRM の障害によって、永続化されたローカル登録の確認が妨げられたり、ローカルレコードが黙って失われたりしないようにしてください。同期状態を見えるようにし、復旧可能なアウトボックス項目を残す必要があります。

5. ランキングと参加条件を正確に示す

FIFO では、到着順・タイブレーク用のキーを永続的なアトミック操作で一度だけ割り当てます。セグメント化、スコアリング、紹介、抽選を行う場合は、選定ルール、入力、ポリシーのバージョン、および結果が保証済み、推定、裁量のいずれであるかを公開します。派生順位は永続化された事実から再計算し、クライアントから referrals_count、position、priority を送信させないでください。

紹介による追加機能については、次のようにします。

• 推測できず、取り消し可能なコードを生成し、認可ではなくアトリビューション用トークンとして扱います。
• 必要な検証と重複排除の期間を経た後で、適格な下流エントリーのみをカウントします。クリックとコンバージョンの両方を記録します。
• 自己紹介と明らかな自動化を防ぎ、影響に上限を設けます。また、ポリシーを変更または削除できるよう、元のキューキーを保持します。
• 順位に影響する競合イベントがある場合は、メリットと明確な幅・推定値を示します。商業的な報酬を転送や紹介に結び付ける前に、法務およびポリシーのレビューを受けてください。

仮想待合室では、可能な限りローカルで検証できる署名付き入場トークン、Cookie／セッションの継続性、アトミックなキュー遷移、ジッターを加えたポーリング、そしてフェイルオープンとフェイルクローズのどちらを選ぶかを慎重に決定します。フェイルオープンはマーケティングプレビューの可用性を守るうえで有効な場合がありますが、希少な在庫に対する唯一の制御として使うのは安全ではありません。下流の予約、チェックアウト、割り当てサービスにも、独自の冪等性と並行性の制御が必要です。

6. ユーザー向け画面と運用担当者向け画面を設計する

公開フローでは、参加することの意味、収集するデータ、情報の訂正や参加の取り消し方法、その後の流れ、順位が確定しているかどうかを説明します。アクセシブルなフォーム、キーボードで認識できるエラー、実用可能な範囲での JavaScript を使わない場合や再試行の手順を用意し、アカウントの存在が漏れない一般的な重複・エラーメッセージを使用します。キューでは、過度に正確さを装わず、最終更新時刻と誠実な推定値を表示します。

運用担当者には、検索、セグメント、ステータス遷移、エクスポート、招待バッチ、配信抑制、監査履歴、プロバイダーの健全性、検証ステータス、CRM 同期ステータス、インシデント制御にアクセスできる、認証済みで最小権限の画面を用意します。手動の一括操作にはすべて、プレビュー、対象範囲、実行者、タイムスタンプ、理由、取り消し可能な手順が必要です。

7. 準備完了と判断する前に検証する

永続的な決定記録には、 templates/waitlist-decision-record.md のテンプレートを使用してください。少なくとも次の項目をテストします。

• 重複送信と同時送信、再試行、検証トークンと招待トークンの再利用、期限切れの申請、およびウェブフックの重複配信や順不同配信。
• ボットの急増、レート制限の動作、キューの頻繁な変動、放棄されたセッション、プロバイダーの停止、データベースの停止、およびフェイルオープン／フェイルクローズの動作。
• ランキングの不変条件、紹介の不正利用、割り当て数の過剰販売、予約の期限切れ、運用担当者による一括操作のロールバック。
• アクセシビリティ、プライバシー／保持期間、配信停止／登録解除、一般的なエラーメッセージ、および JavaScript が無効な環境や低速ネットワークでの動作。
• 検証リンク／コードの再利用、有効期限、再送信の制限、スキャナー／事前取得の動作、異なるチャネルからの試行、および CRM のマッピング、再試行、重複排除、削除／配信停止の伝播。
• 代表的なピーク負荷テスト、およびモバイルとデスクトップで表示した状態の手動レビュー。

出力要件

アーキテクチャまたは実装に関する回答では、次のようにしてください。

マーケター向けプレビュー、キャンペーンの選択肢、接続状況、次のアクションから始めてください。以下のエンジニアリングの詳細はプロジェクトの成果物に残し、メインのセットアップ会話には記載せず、成果物へのリンクを示してください。

1. 名称付きの約束と選択した主要パターン。
2. コンテキスト図と状態／遷移表。
3. 冪等性とプライバシーを含む、スキーマとエンドポイント／イベントの契約。
4. メールアドレス／電話番号の任意の所有確認のセマンティクス、および実行時の CRM マッピング／アウトボックス。
5. 不正利用、メール、公平性、アクセシビリティ、障害モードに関する制御。
6. 段階的なビルド順序と、元に戻せるフォールバック。
7. テスト、運用シグナル、未確認事項の明示的な一覧。

README、GitHub のスター数、または正常系のデモが成功したことだけを根拠に、テンプレートを本番環境対応と判断しないでください。実際のコードと最新のプロバイダーのドキュメントを確認し、その根拠と日付を記録してください。

完了基準

約束、主要パターン、状態機械、データ境界、不正利用とメールのライフサイクル、公平性／参加条件のセマンティクス、運用担当者の制御、範囲を限定した検証計画が明確になった時点で終了してください。連絡先の検証が対象範囲に含まれる場合は、所有確認のセマンティクス、トークンのライフサイクル、同意、不正利用の制限、復旧手順も明確にしてください。CRM が対象範囲に含まれる場合は、実行時の設定、フィールドマッピング、冪等性、再試行／デッドレター処理、配信停止／削除の動作も明確にしてください。プロバイダー、法的規則、在庫情報、または現在のプロジェクト機能が重要であり、検証できない場合は、記憶で補わず、その阻害要因を報告してください。

ビルドを依頼された場合、決定記録だけでは不十分です。実行可能な HTML／JavaScript と TypeScript のソース、マイグレーション、プロバイダーアダプター、セットアップ手順、機能テストとビジュアルテストの記録を納品してください。 references/release-evidence.md のリリースゲートを適用してください。プレビュー、接続テスト済み、本番稼働可能の準備状況はそれぞれ別に報告してください。未テストのプロバイダー設定だけでは、連携が機能していることの証明にはなりません。