很多团队看 Frontdesk 的第一反应是：前台访客来访时填一张表，系统打印个 badge，事情就结束了。可企业版源码真正实现的是一条站点配置 → kiosk 数据下发 → 访客状态推进 → 多角色通知的业务链，而不是“建访客记录”这么简单。
一、Frontdesk 站点本身就是一套可下发的 kiosk 配置
frontdesk_frontdesk.py 里的 _get_frontdesk_data() 会把公司信息、可用语言、站点字段、饮品配置一起打包给前端。也就是说 kiosk 页面不是自己乱拼接口，而是后端给它一个完整的“前台站点上下文”。
再结合 _compute_kiosk_url() 和 _get_tmp_code()，可以看出后端在意的不只是链接可打开，还要保证：
- kiosk 有稳定访问 URL；
- 移动端/临时接入有临时校验码；
- 站点复制后名称、token 等上下文仍然合理。
二、预约访客和现场访客并不是一回事
_get_planned_visitors() 会按一个前后时间窗口，把状态为 planned 的访客筛出来给 quick sign-in 使用。这说明 Frontdesk 不只是“有人来了再填”，它还支持“先预约、到场再快速确认”的双阶段流程。
这个设计能减少前台重复录入，但也带来一个新边界：预约窗口之外的访客，不会自动进入 quick sign-in 列表。
三、真正的业务事件是状态切换，而不是 create
FrontdeskVisitor.create() 之后会立即 _check_and_notify_visitor()；而 write() 中如果状态被写成 checked_in，系统会自动补 check_in 时间、触发 _notify()，若还点了饮品则继续 _notify_to_people()。写成 checked_out 时又会补 check_out 和 served。
这非常关键：Frontdesk 的主链路不是“表单提交成功”，而是状态变化触发现场动作。状态一变，通知、时间戳、后续服务都跟着走。
四、通知不是单一渠道，而是按角色拆分
_notify() 会根据站点负责人与 host 组合消息内容；_notify_to_people() 会把饮品需求通知到对应责任人；后续 _notify_by_discuss()、邮件、短信又是不同分发路径。
这意味着 Frontdesk 不是做一个消息模板，而是要解决：
- 前台负责人需要知道谁到了；
- 被访人需要知道客人已到；
- 饮品/接待服务人员需要知道附加需求；
- 某些 host 休假时还要触发异常提醒。
五、最容易被忽略的其实是“主机不可用”场景
_check_and_notify_visitor() 会检查 host 对应 resource 是否在请假，并向相关方发送提醒。这个细节很重要，因为它说明 Frontdesk 不是只处理“正常到访”，还在补“来宾到了，但人不在”的尴尬现场。
换句话说，企业版 Frontdesk 的价值之一，是把前台的临场混乱尽量前移到系统逻辑里。
六、新手误区
1. 以为 create 就代表 check-in
不是。create 只是记录建立，真正触发现场动作的是状态流转。
2. 以为通知只发给 host
源码里至少分前台负责人、host、饮品责任人三类收件人。
3. 以为预约访客一定会出现在快签列表
只有落在预设时间窗口内、且状态仍是 planned 的记录才会出现。
七、实战注意事项
- 站点语言、是否询问邮箱/电话/公司等字段要在后端统一配置，别让前端自己猜；
- 预约窗口太窄会让 quick sign-in 体验变差；
- check-in / check-out 尽量走动作方法或标准状态写入，别绕过 write 逻辑；
- 如果现场服务依赖饮品、短信或 discuss 通知，一定要先验证接收人配置完整。
结语
Frontdesk 不是一个“访客表单模块”，它更像一个把现场到访、预约衔接、状态推进和多角色通知压在一起的接待流程引擎。理解这条链路后，你就不会再把它当作“填表 + 打 badge”的小功能了。
DISCUSSION
评论区