# 技师工作状态同步(独立测试环境候选) 更新时间:2026-11-01(美国东部时间)。本说明及配套 OpenAPI 为候选;已部署至独立测试环境,正式环境尚未部署。以目标环境 `/info.features` 包含 `technician_availability_events` 确认能力;真实软件商联调和手表验收尚待完成。 ## 工作状态及职责 手表技师本人或门店管理端调整工作状态:`available` 上班中、`absent` 下班中、`leave` 休假中。技师本人只能通过本人的已绑定设备变更本人状态;软件商 Bearer key 不能直接设置这一状态。员工 `active` 仅表示员工账号启用,与工作状态不同;`/catalog.people` 不接受 `availability` 字段。下班或休假不会中止已经开始的服务,服务可正常下钟、加钟。 厂商从 `/events` 读取 `technician.availability.changed` 事件,按 `event_id` 幂等处理并在持久保存处理结果后推进 `cursor`。事件 payload 为 `{person_external_id, availability, version}`;`version` 是摩师人员实体版本,不是原系统 `source_version`。事件仅在门店接入已启用、人员已建立本接入映射时产生;无映射或停用期间的变更不会生成该事件。接入启用、重启、掉线恢复或发现事件缺口后,按已映射的每名技师调用下列当前状态接口重新核对,不能仅依赖事件。 ``` GET /api/partner/v1/technician-availability?person_external_id= Authorization: Bearer <本门店厂商密钥> 响应示例: {"person_external_id":"tech-58","availability":"leave","version":12,"server_time":1800000000000} ``` 只返回当前密钥对应门店已映射的技师状态;接入停用返回 409 `PARTNER_DISABLED`,不存在映射返回 409 `PARTNER_REFERENCE`,映射非技师返回 404;无效/撤销密钥返回 401。客户端不得将 key 放入网页或手表。事件不含手机号。`version` 可能因人员其他资料更新而增加;不能要求事件版本连续。 原系统仍负责实际派单规则,并应结合自身队列中的 `unavailable_person_external_ids`、技师当前状态和业务事务重新检查;手表可用状态不会自动更改原系统不可用名单。`active=true`、人员在原系统名单中和手表在岗均满足时,仍须验证忙碌状态及原系统规则。 ## 并发与对账 确认页面出现后、提交前发生状态变更会要求重新核对。对于 `assignment.create` 与 `replacement.approve`,候选服务在厂商首次领取排队命令时事务内再次检查技师可用性和队列;不满足时返回 409 `PARTNER_TECH_UNAVAILABLE`,该未领取命令标记为 failed 并产生 `command.status` 事件,不应执行原系统操作。该检查不能替代厂商事务内的最终检查。 **已领取后的状态变化无法撤回已进入原系统的执行**。厂商必须在自己的事务边界再次核对工作状态和业务条件;如果已经执行或不能确定是否执行,按原始 `command_id`、租约和事务台账回传真实结果或按 unknown 对账,不得虚报失败、不重新派单。手表工作状态事件和厂商侧数据库之间没有分布式原子事务;双方须约定网络延迟、失联时的处理及人工升级策略,再进行压力、断网、并发和实表验收。 ## 手表版本 0.3.97/0.3.98 原有普通版本缺少测试接入模式要求的设备协议及完整交互,不能声称已支持软件商接入;独立测试 APK 已构建,仍须完成软件商端到端联调及实表测试。设备长轮询与回执合并不属于软件商 API。此文档不提供上线承诺或正式环境开通通知。 ## 绑定身份版本核对(独立测试环境候选) 候选在厂商接入模式下,手表/设备 `POST /api/pair/status` 返回 `needs_confirmation` 时,所有角色(技师、店长、服务员)均返回 `person_version_required:true` 和当前 `person_version`。设备显示员工身份并让本人确认后,`POST /api/pair/confirm` 必须原样回传该次查询的 `person_version`;资料发生变化应重新查询并核对。接入状态在分配后切换时,服务端仍保留该次配对会话的版本校验要求。 若同时返回 `phone_required:true`,仍须显示脱敏号码和说明,并额外提交 `notice_acknowledged:true` 与原 `phone_notice_version`;这不是短信本人验证或本人授权证明。版本缺失或过期将被拒绝,按错误码重新核对。 旧测试服务员 APK 若不回传版本,在升级后的厂商接入模式无法完成新的配对;已绑定设备不因这一规则自动解绑。非接入模式保留既有配对行为和手机号规则。以上是设备配对接口,不使用软件商 Bearer Key,仅在独立测试环境部署;正式环境尚未部署。确认请求结果丢失或中途重新配对造成绑定状态不明时,在商家后台核对设备;如已有残留绑定,由商家撤销旧表授权后重新绑定,不能重复猜测或共享设备凭据。