waiting-list

候补名单门户

使用此技能，将“我们需要一个候补名单”转化为真实可信的产品承诺、恰当的系统边界，以及可执行的交付计划。收集感兴趣的人、按公平顺序提供服务、流量闸门和预留名额是不同的事情。不要让精心设计的落地页悄然替你决定其含义。

何时加载

当用户正在设计、审查、实现或比较用于提前体验、产品发布需求、稀缺商品、预约、会员资格、活动、Beta 计划或高流量准入的门户时，加载此技能。

何时不使用

• 如果只涉及文案、视觉设计、SEO 或无障碍，请使用相应的前端或内容技能，仅在处理名单行为时引入此技能。
• 如果涉及通用 API、数据库、电子邮件、安全或支付实现，请使用负责该领域的专门技能；此技能提供候补名单专用的契约和故障模式。
• 对于线上候场室供应商或队列数据存储，请查阅其最新官方文档。此技能是一种设计方法，不能替代供应商运行手册或法律建议。
• 对于独立的 CRM 迁移或电子邮件／短信营销活动，请使用负责该领域的集成技能。当 CRM 是候补名单经验证联系人生命周期的下游系统时，再加载此技能。

核心工作流

默认方案与营销人员体验

对于新的营销候补名单，请使用一个静态 HTML 页面、Alpine.js（CSP 构建版）、Vite 打包、Vercel Node.js 运行时上的 TypeScript API 函数，以及托管式 Neon Postgres。使用 Twilio Verify 验证码进行电子邮件验证（搭配 SendGrid），并可选择启用 SMS 验证；通过服务端运行时配置保持 CRM 可选。避免使用 Python 后端和 Rails。如果现有托管环境或需求适合，Go 或 Rust 也是明确的替代方案。 这些是默认方案，不是替换现有可用集成的理由。

构建或部署前，请阅读 references/default-stack.md。该文件定义了供应商方案、Vercel 限制、代码仓库结构、工作器执行方式和替代方案。对于所有新门户，请阅读 references/brand-and-marketer-workflow.md，收集营销活动简介、品牌指南、徽标、参考图片和可选视频；连接生产环境前，先展示品牌化预览。 使用 templates/campaign-brief.md 作为通俗易懂的需求收集表。由 Agent 填写技术记录；不要要求营销人员选择 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. 选择一种主要模式

使用能够兑现承诺的最简模式。只有在明确了边界和转换方式时，才组合使用多种模式。

模式	记录系统	合适的默认方案	主要陷阱
兴趣名单	关系型表、CRM 或 ESP	静态/SSR 页面加服务端表单端点和异步电子邮件	它不是队列；不要显示虚构的位置
已验证的提前访问队列	数据库加事件/发件箱记录	唯一计划 + 规范化联系方式，适当时采用双重确认，并设置邀请状态	经验证的电子邮件不能证明某人是谁，也不能证明其完成了购买
推荐优先级	数据库事件账本	不可变的到达键，加上经过验证的推荐事件和带版本的策略	自我推荐、购买流量和“病毒式传播”的说法可能破坏公平性
虚拟等候室	边缘/网关加持久队列	签名准入令牌、Cookie 连续性、原子化准入、限频轮询	获准访问页面不代表拥有库存处置权，也不代表结账流程已串行化
预约候补	排程/容量服务	根据可用时段、偏好和过期时限匹配人员	全局 FIFO 队列可能有失公平，也可能不利于运营
配额分配、抽签或预购	库存/付款/分配服务	将资格与分配、预留、付款和履约分开处理	把配额分配称为“候补名单”，会掩盖超售和退款义务
无头式/嵌入式 API	独立的 API 和事件边界	公开写入契约，配备受限凭据、CORS、幂等性和 Webhook	浏览器中持有的密钥不属于服务端密钥

对于简单的上线前页面，从兴趣名单模式开始。对于发布当天的流量激增，从虚拟等候室或边缘产品开始。如果真正的难题是产品或服务的稀缺资源，先设计库存或排程边界，再将名单与之关联。

在比较模式、建模扩展能力，或判断是否需要队列、推荐机制、预留或供应商时，请阅读 references/architecture-patterns.md。

3. 定义状态机和数据契约

实现时，请阅读 references/implementation-contract.md，了解具体的端点、持久化、验证、CRM 和失败契约。

使用不透明 ID，并避免在 URL、日志、分析标签和公开排名页面中包含联系信息。一个实用的基线是：

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

使用单独的队列/准入状态表示候补室：

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

如果门户会验证联系信息，应分别为每个渠道建模，而不是使用一个含义过于宽泛的 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 模板记录可长期留存的决策。至少测试：

• 重复和并发提交、重试、重放验证令牌和邀请令牌、过期认领，以及 Webhook 重复和乱序投递；
• 机器人突发流量、速率限制行为、队列频繁变动、会话中途放弃、服务提供商故障、数据库故障，以及故障时选择放行或拒绝；
• 排名不变量、推荐滥用、配额超额分配、预留过期，以及运营人员批量操作回滚；
• 无障碍、隐私/数据保留、抑制/取消订阅、通用错误消息，以及无 JavaScript 或网络缓慢时的行为；
• 验证链接/代码重放、过期、重发限流、扫描器/预取行为、错误渠道尝试，以及 CRM 映射、重试、去重、删除/抑制传播；
• 一次有代表性的峰值负载测试，并手动审查渲染后的移动端和桌面端体验。

输出约定

对于架构或实现方面的回复，请按以下方式提供：

先展示营销人员预览、活动选项、连接状态和下一步操作。将以下工程细节保留在项目文档中，并链接到这些文档，而不是放在主要设置对话中：

1. 命名的承诺和选定的主要模式；
2. 上下文图和状态/转换表；
3. 架构和端点/事件契约，包括幂等性和隐私；
4. 可选的邮箱/电话验证语义，以及运行时 CRM 映射/发件箱；
5. 滥用防护、邮件、公平性、无障碍和故障模式控制；
6. 可增量实施的构建顺序，以及可回退的方案；
7. 测试、运营信号和明确列出的未知事项。

不要仅凭模板的 README、GitHub 星标或成功的理想路径演示，就宣称它已可用于生产环境。检查实际代码和当前服务提供商文档，然后留存证据并注明日期。

完成标准

当承诺、主要模式、状态机、数据边界、滥用与邮件生命周期、公平性/准入语义、运营人员控制和有界验证计划都已明确时，即可停止。如果范围包含联系人验证，还必须明确验证语义、令牌生命周期、用户同意、滥用限制和恢复路径；如果范围包含 CRM，还必须明确其运行时配置、字段映射、幂等性、重试/死信处理，以及抑制/删除行为。如果服务提供商、法律规定、库存事实或当前项目能力至关重要，却无法核实，请报告这一阻碍，不要凭记忆补全信息。

对于构建请求，仅提供决策记录并不足够。请交付可运行的 HTML/JavaScript 和 TypeScript 源码、迁移文件、服务提供商适配器、设置说明，以及留存的功能/视觉测试证据。应用 references/release-evidence.md 中的发布门槛。分别报告预览、连接测试和正式上线的就绪状态；未经测试的服务提供商配置不能证明集成可用。