访客系统与闸机对接，往往被当成一个简单的接口开发。真做过项目就知道，问题基本集中在这三处。

坑一：凭证格式与设备能力不匹配

闸机通常只接受很短的一串卡号或二维码内容，而我们系统里生成的凭证带过期时间、签名。

做法：先生成短凭证（8~16 位）落到设备能识别的格式，有效期与签名由系统校验，设备只管「这个号现在能不能开」。

坑二：超时与重复放行

访客在闸机前多刷几次，或凭证在有效期内被截图转发，容易出现「一码多人进」。

做法：凭证一次性使用或限定次数；同一凭证在极短时间内的重复请求直接判定为异常并记录。

坑三：断网就等于瘫痪

现场网络抖动、交换机重启都会让门岗卡住，安保最后只能拿钥匙开门，系统形同虚设。

做法：门岗端支持离线登记与离线校验（缓存当日在场凭证），网络恢复后自动补传记录；同时给安保留一套明确的应急预案。

一句话总结

设备对接的难点不在协议，而在异常路径：超时、重复、断网、误操作。把这四条写进测试用例，项目就稳了。