客流用设备消息 numberstat，或云端 heatmapDetect；离岗用增值接口 absenceDetect，输入是抓图。乐橙设备绑定后可抓图调用；海康、大华、宇视可先经 GB28181 进入平台。是否可用，以设备能力集和 AI 服务是否开通为准。
标书里的「一次交付」对不上接口
智慧连锁方案里常见一句「统一 AI 摄像头，客流 + 离岗一次交付」。把接口名写出来就会分开：客流要的是进出或热力数据，离岗要的是收银台这一刻有没有人。这是两种数据。写成同一个型号承诺后，试点店容易出现人数对不上，或人员离开后系统没有记录。
视频预览仍用视频监控。智能分析用AI 服务说明中的增值接口，以及事件消息里已经定义的客流类型。方案不写死某一款枪机型号。
两条链路怎么接
| 需求 | 接法 | 品牌与设备 | 边界 |
|---|---|---|---|
| 设备上报客流 | setMessageCallback 的 callbackFlag 包含 numberstat |
先看 listDeviceDetailsByPage 的能力集 |
无此能力则不会推送 numberstat / manyStay |
| 热力，且可过滤员工 | 抓图后调用 heatmapDetect |
能稳定抓图即可 | 增值服务，需开通试用或正式额度 |
| 设备本机热度图 | getHeatMapData |
能力集含 HeatMap | 没有该能力不要调用 |
| 收银台是否有人 | 抓图后调用 absenceDetect |
画面覆盖工位 | detectResult 为 true 表示在岗，false 表示离岗 |
| 先看画面 | 轻应用 / OpenSDK | 乐橙绑定，或海康大华宇视 GB28181 | 国标解决视频接入，不自动带上客流算法 |
品牌只落到接入轨：
- 新店： 使用能绑定到开发者账号的乐橙设备。绑定、列表、抓图、预览走现行 OpenAPI。
- 店内已是海康、大华、宇视： 先按 GB/T 28181 注册，督导可在同一页看画面。客流和离岗是否可做，等设备进入列表后查看能力集。
heatmapDetect、absenceDetect的输入是图片；国标通道能否抓图，以实测和现行文档为准。 - 方案中不宜出现的表述： 「某品牌全系支持客流和离岗」。能力集没有，或 AI 服务未开通，调用失败是预期结果。
heatmapDetect 可传 excludeRepositoryIds，过滤已注册工装库中的人员，减少把员工算进顾客热力。离岗若要区分是否为工装员工，向 absenceDetect 传入 repositoryId。工装库未建成时，方案里不写「可排除员工」。
试点店可按营业时间分开跑。支持客流的设备，numberstat 进入小时表，供看板看趋势，不直接进入店长群。不支持时，过道抓图调用 heatmapDetect，间隔先按分钟级，确认抓图额度后再缩短。收银台另一路按固定周期抓图，只调用 absenceDetect。连续两个周期 detectResult 为 false，且落在营业时间内，再生成待办，待办附图片 URL。闭店后两条任务停止，避免空店被记成离岗。督导核对时，用轻应用打开该路预览。
接入步骤
第一步：先开通 AI 试用
heatmapDetect、absenceDetect 属于按需订阅的增值服务。用试点店图片跑通后，再把准确率相关描述写入交付说明。文档见热力数据分析和离岗检测。
第二步：设备进入同一开发者账号
乐橙设备走绑定；海康、大华、宇视走国标。用 `listDeviceDetailsByPage` 确认在线，并查看能力集中是否有客流、HeatMap。说明见设备能力集。
第三步：客流走推送
setMessageCallback 的 callbackFlag 写入 numberstat。需要告警时再加 alarm。numberstat 为客流量上报，manyStay 为人员滞留，见事件消息类型定义。回调使用公网 HTTPS，先回 200。设备没有客流能力时，改走下一步的云端热力。
第四步：热力使用抓图
性能较好的设备调用 setDeviceSnapEnhanced，间隔不少于 1 秒；较老设备调用 setDeviceSnap，间隔不少于 3 秒。返回 URL 约 2 小时有效。将该 URL 作为 type=0 的 content 传给 heatmapDetect。threshold 取值范围为 (0,1]。检测区域最多 3 组，每组 3 到 6 个点，平台转换为外接矩形。设备若具备 HeatMap，也可评估 getHeatMapData，没有该能力则不要调用。
第五步：离岗单独抓收银台
同一抓图策略调用 absenceDetect。单次 false 不直接作为处罚依据。连续两次为离岗，且在营业时间内，再生成督导单。detectRegions 框住收银台，避免把过道顾客判为在岗。
第六步：看板与告警分开
客流和热力进入数仓或连锁看板。离岗进入工单。预览仍用轻应用，便于核对画面。抓图有每日次数限制，见接口调用限制。
threshold 用同一张试点图取两档对比，把结果和原图留给业务选择，再写入配置。区域坐标为归一化的 0 到 1，更换分辨率后重新标注。参数与图片一并留档。
方案首页可以只保留四句可核对的话：新装设备绑定到开发者账号；存量海康、大华、宇视经 GB28181 进入同一账号；有客流能力则订阅 numberstat，否则抓图调用 heatmapDetect；离岗用工位抓图调用 absenceDetect。准确率和「某型号支持客流」改为「以设备能力集与开通服务为准，试点店复核」。
流程示意
text
listDeviceDetailsByPage → 在线 + 能力集
│
├─ 有客流能力 ─ setMessageCallback(callbackFlag 含 numberstat)
├─ 无客流能力 ─ setDeviceSnapEnhanced → heatmapDetect
└─ 收银台工位 ─ 抓图 → absenceDetect（true 在岗 / false 离岗）签名按开发规范使用 HMAC-SHA256。管理员 token 见 accessToken。
边界与踩坑
云端检测针对单张图片，不是视频中的连续轨迹。numberstat 是设备上报的客流；heatmapDetect 是画面中的热力目标。两个数字不宜相加后称为精确进店人数。
| 现象 | 原因 | 处理 |
|---|---|---|
订阅了 numberstat 但没有消息 |
能力集无客流 | 改云端热力，或更换具备该能力的设备 |
absenceDetect 无权限 |
AI 服务未开通 | 先申请试用 |
| 人在收银台侧面被判离岗 | 区域或阈值不合适 | 调整 detectRegions、threshold，用试点图回归 |
| 员工进入客流热力 | 未过滤工装库 | 传入 excludeRepositoryIds |
| 抓图超限 | 每日次数或间隔过密 | 拉长周期；客流与离岗尽量复用抓图 |
| 国标有画面、没有客流 | 视频接入被当成算法接入 | 分开验收 |
检测结果保留图片 URL 和阈值，便于复核。