排队号

排队号是顾客加入队列时向其签发的队列条目。它是排队系统的核心单位——从显示屏到服务台界面，一切都围绕排队号展开。

排队号包含什么

• 排队号编号——顾客可见的顺序整数，显示在自助终端打印的纸质排队号、显示屏和服务台等待列表上。编号按队列作用域单调递增——永不重置。
• 排队号哈希——22 个字符的随机字符串，具有 128 位熵。该哈希是顾客的匿名持有凭证（见下文）。
• 状态——六个值之一（见下文）。
• 队列——排队号所属的队列。
• 时间戳——排队号创建、呼叫、完成等的时间。
• 备注（可选）——工作人员输入的元数据：顾客姓名、人数和自由文本备注。参见排队号备注。

排队号状态

排队号在其生命周期中经历以下状态：

状态	终态？	含义
WAITING	否	顾客在队列中，等待被呼叫。
CALLED	否	服务台已呼叫该排队号；顾客应前往柜台。
SKIPPED	否	服务台跳过了该排队号。可召回——工作人员可以将其移回 WAITING。
COMPLETED	是	服务台已标记服务完成。
CANCELED	是	顾客取消了自己的队列位置。
NO_SHOW	是	服务台确认顾客不在场。在分析中与 SKIPPED 分开统计。

状态流转

WAITING  → CALLED   → COMPLETED
                    ↘ SKIPPED   → WAITING  (desk recalls the customer)
                               ↘ NO_SHOW  (desk confirms absence)
                               ↘ CANCELED (customer cancels their deferred spot)
WAITING  → CANCELED  (customer-initiated)
CALLED   → CANCELED  (customer-initiated)
SKIPPED  → CANCELED  (customer-initiated — removes from recallable pool)

SKIPPED 与 NO_SHOW

SKIPPED 是可召回的暂缓——顾客被跳过，但排队号仍然有效。工作人员可以使用服务台查询视图中的 召回队列 操作，或在跳过后的 5 秒内按下 撤销 来召回顾客。被跳过顾客的推送通知订阅保持活跃，因此召回 → 呼叫的推送通知即使在排队号页面已关闭的情况下也能送达。

NO_SHOW 是已确认的终态不在场。排队号从可召回池移除，并在分析中单独统计。仅在确定顾客已离开时使用。

完整的服务台工作流参见处理未到场。

排队号备注

工作人员可以使用服务台上的添加备注操作，为任何排队号附加轻量级元数据：

• 顾客姓名——在服务台上始终显示。仅当队列的 按姓名呼叫 设置开启时才在显示屏上显示，且仅以简化形式（“Alice S.”）显示——绝不显示全名。
• 人数——始终在服务台显示，并广播到显示屏（低敏感度的计数）。
• 备注——自由文本的后台备注。仅服务台可见；绝不发送到显示屏或顾客。

跳过原因（在跳过排队号时在 跳过原因（可选） 字段中输入）存储在排队号的备注字段中，并显示在服务台查询视图中。

在排队号处于非终态期间，可以随时添加或更新备注。

转移排队号

WAITING 状态的排队号可以使用服务台上的 转移 按钮转移到同一门店内的其他队列。当顾客加入了错误的队列，或分诊后发现其需要其他服务时，这很有用。

转移规则：

• 只有 WAITING 状态的排队号可以转移。CALLED 状态的排队号必须先完成、跳过或标记未到场。
• 源队列和目标队列必须在同一门店。
• 目标队列必须为 ACTIVE。
• 服务台必须同时被分配到源队列和目标队列。
• 需要有效的订阅。

转移后的排位——排队号保留顾客原始的加入时间，外加 5 分钟惩罚。这保留了他们已经等待的时间，同时防止他们插队到目标队列中等待更久的顾客前面。

排队号哈希被保留——顾客的排队号页面 URL 仍然有效。排队号在目标队列中获得新的顺序编号。实时更新立即广播到两个队列。

逐步操作说明参见服务台指南的将排队号转移到其他队列部分。

排队号哈希作为凭证

顾客是匿名的——加入队列不需要登录或账户。相反，22 个字符的排队号哈希充当顾客的所有权证明。它嵌入在排队号页面 URL 中：

https://customer.jonot.io/{org}/{location}/{queue}/{ticket-hash}/

知道哈希即证明您拥有该排队号。API 使用哈希进行授权：

• ticketByHash——查询您的排队号和位置
• cancelTicket——取消您自己的排队号（适用于 WAITING、CALLED 和 SKIPPED 排队号）

这是有意的设计：它消除了加入队列的一切摩擦。不需要账户、不需要应用、不需要密码——只需要一个 URL。

该哈希具有 128 位熵（相当于 UUID v4），在计算上不可能猜出其他顾客的排队号哈希。

异常流量下的验证

正常使用中，加入始终无摩擦。作为防滥用保护措施，如果单个队列在短时间窗口内收到异常大量的加入，通过 Web（二维码或链接）加入的顾客可能会被要求先完成一次快速的“我是人类”验证，然后才会签发排队号。大多数合法访问者会无感知地通过。它只在流量激增时出现——正常流量下不显示任何验证——并且绝不应用于现场自助终端，因为自助终端的加入通过设备凭证被信任。

等待时间估算

当排队号处于 WAITING 状态时，顾客的排队号页面显示估算的等待时间。同样的估算值也显示在自助终端加入后的确认屏幕上，以便顾客离开自助终端时记住一个数字。这是尽力而为的估算，不是保证。

估算值基于该队列最近的服务间隔计算：如果最近 90 分钟内存在足够多的已完成排队号，服务器会推导中位服务时间，并乘以顾客在队列中的位置（前面的人数 + 0.5）。当顾客是下一位（前面零人）时，估算值报告为零。当最近历史较少时，使用队列配置的预计服务时长作为回退值。估算值带有置信度指示器（基于实时数据推导或顾客是下一位时为 high，回退到配置默认值时为 low）。

估算值仅对 ACTIVE 队列中 WAITING 状态的排队号显示。队列暂停时不显示，排队号被呼叫后消失。

顾客体验

1. 顾客通过二维码或自助终端加入 → 签发 WAITING 状态的排队号。
2. 顾客打开排队号页面 → 看到自己在队列中的位置，以及在可用时的实时估算等待时间。
3. 服务台呼叫其编号时，排队号移入 CALLED → 顾客的页面立即更新。
4. 顾客前往柜台。服务完成后，服务台标记为 COMPLETED。
5. 如果顾客没有回应，服务台可以：
   • 跳过 → 排队号移入 SKIPPED（可召回的暂缓）。 顾客屏幕显示其被跳过，可选择继续等待或重新加入。
   • 未到场 → 排队号移入 NO_SHOW（终态）。 分析中将其与跳过的排队号分开统计。
6. 被跳过的顾客可以被工作人员召回（在队列前端移回 WAITING），或取消自己的位置并从队尾重新加入。