绑定身份版本核对(独立测试环境候选)
厂商接入模式下,设备查询配对状态后,所有角色均收到 person_version_required:true 和 person_version。设备必须向 /api/pair/confirm 回传本次查询的 person_version;资料变化须重新核对。接入关闭后,本次已受保护的配对会话仍要求版本。
返回 phone_required:true 时,仍须核对脱敏号码和用途说明并回传 notice_acknowledged:true、phone_notice_version。旧服务员测试 APK 若不传版本,将无法完成新的接入模式配对;已绑定设备不因此自动解绑。非接入模式保留旧行为和原有手机号规则。
配对接口使用设备绑定会话,不能使用厂商密钥。确认回包丢失或绑定状态不明时,商家先检查设备列表;如已有残留,撤销旧表授权后重新绑定。
技师工作状态同步(独立测试环境候选)
更新时间:2026-11-01(美国东部时间)。候选接口已部署至独立测试环境,正式环境尚未部署;请确认目标环境 /info.features 含 technician_availability_events,并完成软件商联调及实表验收。
状态与权限
可取 available(上班中)、absent(下班中)、leave(休假中)。仅本人手表或门店管理端按角色权限变更,厂商密钥只读取;人员 active 表示启用,不能替代工作状态。离岗不结束进行中的服务。
当前状态与事件
GET /api/partner/v1/technician-availability?person_external_id=原系统技师ID,使用本门店 Bearer Key。返回 person_external_id、availability、摩师人员 version、server_time。接入需启用且人员须为本门店已映射技师。
通过 /events 消费 technician.availability.changed;payload 字段为 person_external_id、availability、version。先持久化处理,再推进 event_id 游标。未映射或接入停用期间不生成该事件;启用、重连或发现缺口后按每名技师查询当前状态。version 不是原系统 source_version。
队列和并发
原系统队列的不可用名单与手表状态分别生效;仍须检查人员启用及忙碌状态。待领取的派单和换人审批在首次领取时重查状态、队列,不符合时返回 409 PARTNER_TECH_UNAVAILABLE 并将命令置为 failed。厂商应在自身业务事务中再次检查。
已领取后的状态变化不能撤销可能已执行的业务。应按原 command_id 和原事务台账回传真实结果或保留 unknown 并对账。双方系统不构成分布式原子事务,失联与延迟规则需双方约定并完成实表验收。
0.3.97/0.3.98 原有普通 APK 尚未验证兼容接入模式;独立测试 APK 和上述接口尚待软件商联调及实表验收。完整协议及错误码请阅读 候选说明。
2026-11-01 手表版本兼容说明
文档更新时间:2026-11-01(美国东部时间)。本次核对 0.3.96 的技师工作状态及 0.3.97–0.3.98 的同步优化;0.3.98 为候选版,实表验收尚未完成。
- 原正式协议尚未包含技师工作状态同步;独立测试环境候选新增状态查询和变更通知,尚不是双向修改接口。人员
active表示启用状态,不能代替工作状态;请勿提交未经协议定义的availability字段。 - 手表工作状态与软件商原系统排钟、派单的联动尚未完成端到端验证;暂不能保证手表切换状态会同步原系统或阻止原系统派单。正式使用前请与摩师确认状态归属、同步方式并完成真实门店验收。
- 0.3.98 候选客户端与厂商接入模式兼容性尚待确认和端到端测试;请使用摩师专门提供的联调版本,不要直接替换。
- 手表端长轮询和省电优化属于设备与摩师服务之间的通信,软件商继续使用现有命令与事件接口。
- 测试环境候选协议仍为 v1;具体能力以测试环境
/info及双方验收结果为准。
软件商首次接入
目标:在隔离测试门店跑通“同步 → 手表发起 → 软件商执行 → 手表收到确定结果”。测试地址、门店密钥与测试 App 由摩师对接人员单独提供。公开资料不包含可用凭证,正式门店需另行开通。
准备与职责
准备一个测试门店、真实角色测试员工、项目、包厢和原系统测试库。由商家建立接入并取得门店专属 key;软件商不用商家账号密码调用厂商接口。密钥只放服务端环境或密钥管理系统,不能嵌在手表、浏览器或公开代码中。
原系统需要实现两个后台循环:命令消费者和事件消费者。命令消费者配套持久化执行台账;演示适配器只能用于沙箱,不可替代现有业务事务。
接入顺序
GET /api/partner/v1/info检查协议、门店接入与 capabilities。POST /catalog同步房间、员工、项目;员工手机号绑定政策及配对详见 README.md。首次先少量验证映射。POST /state同步在店客人、已有派单和服务,以及有序 technician_queue;所有编号取原系统稳定主键。- 商家确认映射完整后启用连接及实际支持的能力。未支持的动作不要勾选。
- 手表发起排钟/点钟或其他动作,软件商消费者领取命令,在原系统事务内执行并回传结果。
- 持久处理 events 游标,展示 SOS、终端回执及任务变化。软件商确认知晓不会解除 SOS。
- 完成下方验收后再安排正式部署与真实手表验收。
最小调用示例
以下 Bash 命令只读取接入信息。环境变量填写本门店测试值,BASE_URL 不含 /api/partner/v1 路径。正式地址必须 HTTPS。
export MOSHI_PARTNER_URL='https://由摩师提供的测试域名'
read -r -s -p '测试门店 key: ' MOSHI_PARTNER_KEY
export MOSHI_PARTNER_KEY
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $MOSHI_PARTNER_KEY" \
"$MOSHI_PARTNER_URL/api/partner/v1/info"
Node.js 22.13+ 可使用本包 SDK(无第三方依赖):
import {VendorClient} from './examples/vendor-client.mjs';
const client = new VendorClient({baseUrl:process.env.MOSHI_PARTNER_URL,apiKey:process.env.MOSHI_PARTNER_KEY});
console.log(await client.info());
// 只有店长手表可以解除 SOS。软件商仅查看、记录知晓。
let cursor;
do {
const page=await client.sos({limit:50,...(cursor?{cursor}:{})});
console.log(page.alerts.map(a=>({id:a.alert_id,status:a.status})));
cursor=page.next_cursor;
} while(cursor);
先按 examples/phone-catalog-example.mjs 准备人员数据,再参照 README.md 的完整起钟示例与 WORKFLOWS.md 的排钟、换人、任务流程。demo-adapter.mjs 和 workflow-demo.mjs 演示本地事务台账。不要直接照搬演示的房态和计费规则。
可交付验收记录
每项记录测试门店、command_id/request_id、原系统执行台账、回传结果和手表显示结果;禁止把密钥放进验收记录。
| 验收项 | 预期 |
|---|---|
| 起钟、下钟、加钟、拒单 | 原系统实际变化一次,手表只在确定成功后更新 |
| 排钟与点钟 | 项目明确,技师/队列冲突时拒绝,成功派单归属正确 |
| 起钟前及服务中换人 | 店长审批,新旧记录完整衔接,费用由原系统处理 |
| 打扫任务 | 原系统确认 idle/clean 后任务才完成 |
| 普通任务 | 指派、接手、反馈、回复、完成按真实员工权限执行 |
| SOS | 手表即时店内广播;厂商可读/知晓;厂商解除被拒,店长手表可解除 |
| 重复调用与并发领取 | 相同业务只执行一次,相同版本不同内容拒绝 |
| 断网、租约到期、回传丢失 | unknown 经台账对账恢复,禁止重复执行 |
| 错误批次 | 全批回滚,已结束记录不能复活,不出现双重占用 |
| 门店隔离与凭证撤销 | 不能跨店查询/操作,撤销凭证失效 |
接口文档与自动测试不能替代双方联调与实表验收记录。
摩师足浴智能手表标准厂商接入 API v1
本接口供足浴软件厂商自主接入。摩师提供手表、主页 AI、统一 HTTP 协议和执行结果展示;厂商开发自己的适配模块,连接原系统、执行业务并回传真实状态。电脑安装软件可以主动向外发起 HTTPS 请求,无需给前台电脑开放公网入口。
本文对应 API v1 接入协议(文档版本 1.2.0 候选)。独立测试环境已部署;真实软件商适配及实表验收须按项目完成。正式门店需单独授权开通,现有独立模式不会自动切换。
1. 业务范围和责任
| 事项 | 责任方 |
|---|---|
| 员工、包厢、项目、原系统 ID 和版本 | 厂商同步,本平台保存手表所需镜像 |
| 排钟顺序、点钟和派单决策 | 原系统决定并同步,摩师不重新排钟 |
| 手动及主页 AI 发起起钟、下钟、加钟、拒绝派单 | 手表统一核对,确认后提交标准命令 |
| 执行起钟、下钟、加钟、拒绝派单 | 厂商在原系统内执行,并保证幂等 |
| 项目实际金额、订单、结账、会员、提成 | 原系统负责,本接口不结算 |
| 命令状态、通知送达和播报回执 | 摩师记录,厂商可以查询 |
可授权命令共 8 项:service.start、service.stop、service.extend、assignment.reject、assignment.create(排钟/点钟)、replacement.request、replacement.approve、room.clean。厂商只开启已适配能力。普通任务和 SOS 有独立接口;打扫任务完成会转为原系统清洁确认命令,真实回执成功后才完成任务。收银、会员、订单、计费和提成仍由原软件管理。
新增能力的字段、完整流程、SOS 与任务接口、失败恢复及验收要求见 业务流程补充。
厂商不能仅收到文字后回复“成功”。送达、显示、播报和员工已阅都不等于业务已执行。 起钟等命令在确认后先显示“已提交,等待原系统处理”;只有原系统回传可信成功状态,手表才显示实际完成。
2. 文件和地址
- OpenAPI 3.1.1 协议:请求、字段、返回结果和鉴权定义。
- Node.js 客户端:超时有限制,不自动重试,不在错误中输出密钥。
- 本地演示适配器:SQLite 模拟原系统及持久执行台账,不连接收银或真实计费。
- 手机号同步示例:仅展示虚构沙箱数据及供应方声明字段,不发送短信或验证本人。
- 本地服务器默认示例地址为
http://127.0.0.1:18080。独立在线测试地址为 https://partner-test.mosizb.cn;正式接入需另行开通并使用 HTTPS。 - 公开文档入口为 https://www.mosizb.cn/developers/partner-v1/ 。接入开通和管理由摩师对接人员与商家另行安排。
协议路径固定为 /api/partner/v1。本次在员工资料中增加可选字段,不要求未使用手表的员工提供号码;参与绑定的技师/店长须满足下述手机号规则。向后不兼容变更使用新的版本路径,返回对象里的未来新增字段应忽略。
3. 商家授权与密钥
商家使用自己的管理账号创建接入。厂商不应获得商家密码、商家会话、手表绑定码或手表令牌。每项接入绑定一个门店,密钥只能操作这家店。新接入默认关闭,不能把仍在独立模式起钟的门店直接切过去。
| 商家管理接口 | 用途 |
|---|---|
GET /api/integrations |
查看本店接入、有效密钥和状态 |
POST /api/integrations |
{name, capabilities?} 创建接入,返回一次性 api_key、key_id 和 integration |
POST /api/integrations/{id}/configure |
{enabled?, capabilities?} 启用、停用或调整能力 |
POST /api/integrations/{id}/keys |
增加一把密钥,最多五把有效密钥 |
POST /api/integrations/{id}/keys/{key_id}/revoke |
撤销旧密钥 |
商家完成资料同步、确认没有独立模式未结束派单/服务后才启用。关闭期间上传的数据只保存在接入暂存区,不改变原有手表身份、员工状态、房态或触发派单;商家启用时才一次性应用。员工编号和角色唯一对应时保留原绑定,身份冲突会拒绝启用,新员工在启用后绑定。
启用前须结清独立模式的未结费用并结束在店客人记录。本接口不自动迁移旧账务。停用只停止原系统联动,不会把原系统镜像转换成本地业务;如需迁回独立经营,应另行完成资料与业务迁移。
存在待执行或结果不明的命令时不能切换模式或能力;存在接入模式未结束派单/服务时不能退回独立模式。应先在原系统收尾并完成状态核对。
厂商请求使用 Authorization: Bearer <api_key>。密钥只在创建响应中返回一次,服务端保存哈希。轮换时先新增、验证新密钥,再撤销旧密钥;新增不会自动撤销旧密钥。将密钥放在系统安全配置中,不提交到代码、截图、对话或日志。执行台账含租约令牌,同样应限制文件访问;真实系统宜加密保存。
4. 基础资料和派单同步
所有写入使用 JSON 对象。request_id 是调用方生成并持久化的请求编号,最长 128 字符;同一路径、同门店、同编号和相同内容重放返回原结果,不重复变更。相同编号搭配不同内容返回 PARTNER_REQUEST_REUSED。
业务 ID 为不透明、区分大小写的字符串,最长 128 字符。不要把原系统 ID 改成摩师内部 ID。source_version 是针对同一资源严格递增的正整数,最大 9007199254740991;不是时间字符串或浮点数。相同版本及相同内容可以重放,同版本不同内容拒绝,旧版本拒绝。
| 接口 | 请求 | 结果 |
|---|---|---|
GET /info |
无 | 接入配置、能力、限制、服务器时间和协议版本 |
POST /catalog |
{request_id, rooms?, people?, projects?} |
resources 包含原系统 ID 与摩师 ID 映射 |
POST /state |
{request_id, rooms?, assignments?, services?} |
真实派单、服务和房态同步结果 |
POST /notifications |
{request_id, person_external_ids, text} |
status: accepted 及通知 ID;不创建待办任务 |
以上表格中的路径相对 /api/partner/v1。资料同步允许在接入启用前完成,通知及命令处理需要启用。
rooms/people/projects/assignments/services 每个数组最多 200 条;请求是增量更新,未出现的资源保持原样。停用员工/项目使用 active:false,取消派单使用 cancelled,服务结束使用 ended。不能把已取消/拒绝的派单或已结束的服务恢复为进行中。员工角色不能通过同步改变已有绑定身份。
同步顺序为:包厢、员工、项目 → 派单 → 服务。每次派单及服务都使用原系统的 visit_external_id 表示本次客人/开房记录,同一个客人记录不能跨包厢;服务必须引用已经 started 的派单。员工必须是技师,派单与服务的员工、包厢、客人身份要一致,原派单的项目引用保持不变。
起钟时如果手动或 AI 核对后选择了另一基础项目,实际服务的 project_external_id 可以与原派单项目不同,但必须与该起钟命令选定的项目一致。厂商回传实际服务项目,不修改原派单项目来迁就结果。起钟之后不能改写已有服务的基础项目身份。
{
"request_id": "catalog-0001",
"rooms": [{"external_id":"room:306","source_version":1,"number":"306","status":"pending","clean":true}],
"people": [{"external_id":"employee:28","source_version":1,"employee_no":"28","name":"28号技师","role":"technician","active":true,"phone":"19900000028","phone_processing_authorized":true}],
"projects": [{"external_id":"project:footbath","source_version":1,"name":"经典足浴","price_minor":12800,"minutes":60,"active":true,"extension":false}]
}
{
"request_id": "state-0001",
"assignments": [{"external_id":"dispatch:0001","source_version":1,"room_external_id":"room:306","person_external_id":"employee:28","project_external_id":"project:footbath","visit_external_id":"visit:306:0001","status":"pending","dispatch_mode":"requested"}]
}
房态支持 idle/pending/serving/awaiting_stop/unpaid/dirty;clean 也是原系统同步的实际状态。摩师不会依据历史服务猜测“已付”或“待结账”。dispatch_mode 为 rotation(排钟)或 requested(点钟)。金额字段 price_minor 使用人民币分,表示原系统项目数据,不用于本平台财务结算。服务 items 最多 50 项,其 minutes × quantity 合计必须等于服务的 minutes。
员工手机号与绑定
catalog.people 可增加 phone 和 phone_processing_authorized。号码用于工作身份核对和设备服务联系,不向普通手表、主页语音 AI 或其他商家返回完整号码。普通厂商密钥也不能调用管理端完整号码查询或导出接口。
| 字段或情况 | 规则 |
|---|---|
phone 未传 |
保留已有号码,不自动从其他字段推断或生成 |
phone 提交非空号码 |
使用大陆 11 位手机号,可传 +86 或 86 前缀;服务端去除首尾空白并规范成 11 位,不接受 null 或其他类型 |
phone:"" |
仅在规则允许的未绑定人员上清空;不得清空已绑定且要求手机号的人员 |
phone_processing_authorized:true |
提交非空号码必须同时提供,声明供应方已完成相关用途的告知及适用授权 |
| 手表绑定中的有效技师/店长 | 须已有有效手机号;缺号不能新绑定,已绑定人员缺号不能启用接入 |
| 未使用手表的员工 | 不强制收集手机号,不应为满足格式自动补虚构号码 |
| 服务员 | 保留原绑定规则,不新增强制收集要求 |
| 已绑定且有效的技师/店长 | 不得清空号码;更新使用真实资料、更高 source_version 及新的请求编号 |
供应方声明会被记录,但 true 不是员工本人同意证明,也不是短信验证结果。供应方必须按实际处理安排完成告知和适用授权,不得用该字段替代真实流程。门店正式启用前,相关负责方还须明确真实处理者、联系方式、保存期限及权利请求渠道;短绑定提示及这个声明不能自动构成完整说明或合规证明。
资料未传 phone 时保留最新本地号码,不复制过时的原系统空值或自动覆盖商家补录。关闭期间暂存过明确的手机号更新后,后续未传 phone 的请求仍保留该明确更新。同步响应只返回资源映射,不返回完整号码或供应方声明。
启用检查覆盖整店所有已绑定且有效的技师/店长,包括尚未映射到厂商资料的本地店长。商家可按管理端的手机号补录流程完善现有人员;缺号会使整次启用失败,不能绕过未映射人员检查。该规则不会要求未绑表员工或服务员批量提供号码。
商家及具备相应权限的摩师总后台可查看员工联系方式,目录默认脱敏,查看完整号码及导出记录审计。平台管理接口只接受真实平台管理身份,不能向厂商开放总后台权限。目录/设备快照、事件、业务命令及语音上下文不应暴露完整手机号。
手表绑定查询 POST /api/pair/status 使用 {pair_id,pair_secret}。需要手机号的人员在 needs_confirmation 返回中看到 phone_required:true、phone_masked、phone_notice、phone_notice_version:"employee-phone-v1" 和 person_version,不会获得完整号码。确认 POST /api/pair/confirm 除原有 {pair_id,pair_secret} 外须回传 notice_acknowledged:true、相同的 phone_notice_version 和 person_version。资料或说明版本已变化时应重新查询和核对,不能复用旧确认。
绑定说明的确认仅表示已阅读提示并核对显示的号码。本版未实现 SMS 验码,不能保证号码真实属于绑定员工,也不能保证员工已实际完成完整的个人信息授权流程。 完整号码来源及本人归属由供应方/门店真实流程核实,不能依据格式正确或接口成功推断。
上方 JSON 的 19900000028 及手机号示例文件均是虚构沙箱输入,不能保证这些格式示例没有被通信运营商分配。不得在正式门店自动上传、填充或联系这些号码。示例中的 phone_processing_authorized:true 仅展示报文字段,不表示发生过真实员工告知或授权。
5. 领取、执行、回传的闭环
- 读取
GET /commands?limit=50获得queued命令。手表未确认的核对不会生成命令。 - 在原系统持久台账保存
command_id、完整业务内容、worker_id及不可预测的随机lease_token,保存成功后再请求POST /commands/{id}/claim,请求体为{worker_id, lease_token}。 - 获得有效租约后,原系统校验目标版本、员工权限和自己的业务规则,在自己的事务内执行业务。不要用接口显示文字替代执行。
- 把实际业务状态与结果写入持久台账。尽量将业务修改和台账写入原系统同一事务,避免业务成功但台账丢失。
POST /commands/{id}/result上传原租约令牌、固定result_id、真实状态与权威数据。网络回复丢失后先查询原command_id,再按原结果核对回传,不再次起钟、加钟或扣费。
租约令牌为 32~128 个 base64url 字符,推荐 32 随机字节的 base64url;示例提供 createLeaseToken()。活动租约内,相同 worker 和令牌再次领取返回原租约,不延长时间。不同 worker 或令牌不能领取同一命令。领取响应丢失也使用领取前已保存的同一令牌核对。
命令结构包含 command_id/request_id/action/target/params/operator/protocol_version/status/created_at/expires_at。target 包含 {type, external_id, source_version};operator 包含原系统员工引用及编号;加钟的 params 包含 project_external_id 和 project_source_version。baseline 是核对时的业务基准,供验证使用,厂商不能改写它。
| 状态 | 含义及处理 |
|---|---|
queued |
已确认,原系统尚未领取;可领取 |
claimed |
已领取,可能正在执行;查询原命令和台账,不能再次执行 |
unknown |
执行结果无法确定;先核对原系统,不自动重新排队 |
succeeded |
原系统已回传并证明成功;终态 |
failed |
确定未执行或被原系统拒绝;终态 |
未领取命令默认五分钟过期为 failed;领取租约默认一分钟,过期成为 unknown。以 /info 和服务器时间为准。如果结果不明,保留原令牌和台账;查清原系统后用 reconciliation:true 回传核对结果。一个仍然 unknown 的对象不能发起新的重复操作。
import { VendorClient, createLeaseToken } from './examples/vendor-client.mjs';
const client = new VendorClient({
baseUrl: process.env.MOSHI_PARTNER_URL,
apiKey: process.env.MOSHI_PARTNER_KEY,
});
const { commands } = await client.commands({ limit: 50 });
for (const command of commands) {
const leaseToken = createLeaseToken();
// 必须先持久化 command、workerId 和 leaseToken,示例用伪函数说明厂商责任。
await vendorLedger.saveBeforeClaim(command, 'front-desk-1', leaseToken);
await client.claim(command.command_id, 'front-desk-1', leaseToken);
// 下面必须由厂商实现:按 command_id 幂等执行 + 权威状态 + 原系统事务台账。
const outcome = await originalSystem.executeOnce(command);
await vendorLedger.saveOutcome(command.command_id, outcome);
await client.report(command.command_id, { lease_token: leaseToken, ...outcome });
}
该片段说明调用顺序,vendorLedger 和 originalSystem 不是本 SDK 的现成功能。无原系统事务台账时,不能把“本地没有记录”视为“原系统未执行”。
6. 成功结果必须证明实际动作
result_id 最长 128 字符,每次已确定的结果固定保存。相同 ID 和完全相同请求内容重放返回原结果;不同内容拒绝。最终结果不能改写。unknown 之后的核对终态使用新的结果 ID;不要把一次不明结果覆盖成成功。
| 动作 | succeeded 所需实际数据 |
|---|---|
service.start |
更高版本派单为 started,对应实际服务为 running 且基础项目与核对命令一致,实际房态 |
service.stop |
更高版本目标服务为 ended,实际结束时间,实际房态 |
service.extend |
更高版本目标服务,实际时长已增长且新增所选项目,实际房态 |
assignment.reject |
更高版本目标派单为 rejected,实际房态 |
正常起钟/加钟成功应反映进行中服务。租约过期后才完成核对时,服务可能已在原系统下钟;可回传当下的更高版本 ended 状态,但必须证明该次实际起钟或所选加钟已发生,不能把旧的进行中快照覆盖当前结束状态。
failed 必须提供 {code,message},只在确定业务未执行时使用;不可因 HTTP 超时就上报失败。failed/unknown 不接受 state,需要同步原系统状态时另用 /state。成功不允许只传一句“完成”,缺少权威状态或动作后置条件不符会拒绝回传,并回滚本次镜像同步。
GET /commands/{id} 返回 {command, result, server_time};领取返回 {command, lease_token, lease_expires_at, server_time};结果回传返回业务结果对象 {status, request_id, command_id, entity?, error?, reconciled?, execution_receipt?, server_time}。厂商 entity 仅返回 {type, external_id, source_version};手表内部结果投影不对厂商开放。历史补报可不返回 entity。status:pending 与 status:succeeded 含义不同,HTTP 200 本身也不是业务成功证明。
7. 通知、事件和异常恢复
通知最多 100 名收件人,正文最多 500 字符。返回 accepted 只表示服务接受并创建了通知。通知不会产生“本人待办”,因此收到通知后显示零待办是正常现象。
通过 GET /events?after=0&limit=100 拉取递增 event_id;处理并持久化后再保存 cursor,不要在处理前推进游标。命令事件通知状态变化,通知事件记录 notification_id/person_external_id/stage/received_at。
通知回执包括 delivered、presented、presentation_failed、speech_started、speech_completed、speech_failed 和 acknowledged。不同员工、不同阶段分别处理;收到 speech_failed 不能视为完整播报,任何通知阶段都不能改成业务成功。
SDK 每次请求只发送一次。超时返回 TRANSPORT_ERROR,无效 JSON 返回 INVALID_RESPONSE;两者均不能证明原系统是否执行。厂商可按自己的有上限退避策略恢复同步请求,但必须保留原请求编号及内容。命令恢复先按台账查询,禁止循环重复执行业务。
| 错误 | 处理 |
|---|---|
PARTNER_UNAUTHORIZED / STORE_DISABLED |
停止请求,核对商家授权或停用状态 |
PARTNER_STALE_VERSION / PARTNER_VERSION_CONFLICT |
查询原系统最新资源,修复版本来源;不强制覆盖 |
PARTNER_REQUEST_REUSED / PARTNER_RESULT_REUSED |
核对台账,不复用编号提交不同内容 |
PARTNER_LEASE_BUSY |
查询原命令和已保存的领取凭据,不能另开执行者重复执行 |
PARTNER_RECONCILIATION_REQUIRED / PARTNER_OUTCOME_UNKNOWN |
查清原系统真实结果,再显式核对回传 |
PARTNER_RESULT_STATE |
检查实际状态、资源版本、项目与目标;不得伪造成功 |
PARTNER_PENDING |
当前对象或接入仍有未解决命令,先核对收尾 |
PARTNER_PHONE_INVALID |
核对手机号格式和类型,不以虚构号码补齐正式资料 |
PARTNER_PHONE_AUTHORIZATION |
先完成相关告知和适用授权,再提交供应方声明,不能盲目添加 true |
PARTNER_PHONE_REQUIRED |
为需要绑定的真实技师/店长补全号码,或撤销不适用的绑定计划;不自动批量收集其他员工 |
| HTTP 429 / 5xx / 网络超时 | 有上限等待、查询原请求;不推断已执行或未执行 |
8. 本地演示和联调验收
Node.js 示例使用内置 node:sqlite,运行环境与本项目一致,需 Node.js 22.13 以上。DemoAdapter.seed({rooms,projects,people,visits,assignments,services,replacements,technician_queue}) 准备模拟原系统数据;runVendorOnce(client, adapter) 进行一次有限批次处理。演示将业务行和结果台账放在同一个 SQLite 事务,程序重启后只重传已执行结果。
node examples/demo-adapter.mjs --once
运行前设置 MOSHI_PARTNER_URL、MOSHI_PARTNER_KEY 和可选的 MOSHI_DEMO_LEDGER,并准备同一数据库的演示数据。不要把示例数据库和模拟派单用于真实客人。--once 不循环运行;没有演示数据的命令会被明确拒绝,不会假装执行。
厂商联调至少应通过以下项目,电脑测试与实表验收分别记录:
- 两家门店、两把密钥隔离;越权 ID、撤销密钥及停用门店均被拒绝。
- 资料相同版本重放、旧版本、同版本不同内容、未知引用及重复员工/包厢号。
- 原系统点钟/排钟同步,正确技师收到正确包厢和项目,其他终端不误收。
- 手动与自然语音的核对、取消、更正;确认前原系统没有业务变更。
- 起钟、加钟、下钟、拒绝派单:分别验证手动与主页 AI 确认流程,对象、实际状态、技师、项目和房态全链路一致;另测起钟改选基础项目,实际服务项目正确且原派单项目不变。
- 同一命令重复提交、两个执行者竞争、领取响应丢失和结果响应丢失;原系统只执行一次。
- 已领取超时、程序重启和结果不明:保留台账及凭据,核对后恢复,不重复计费。
- 项目/服务版本在确认后变化、员工停用、错误成功状态及终态改写均不能绕过校验。
- 通知正确员工的完整正文播报与回执,通知零待办,通知回执不计为业务成功。
- 原系统结账后房态同步正确,摩师不依据历史服务重新推断待结账。
- 未实现能力不能从手动或 AI 绕过;现有独立门店不受接入配置影响。
- 商家启用、轮换、撤销及停用的操作,不能留下未解决业务或丢失结果台账。
- 手机号省略时保留本地补录,规范
+86/86输入,非法/null拒绝;缺少供应方声明时拒绝非空号码,同步返回不回显号码。 - 缺号的技师/店长不能新绑定,已绑定缺号不能启用;未参与绑定的员工及服务员无需新增强制收集。已绑定且要求手机号的人员不能清空,商家更新后使用新版本核对。
- 绑定只显示脱敏号码和用途说明;确认回传说明及人员版本,资料/说明已变化则拒绝旧确认。该结果不能记录为 SMS 本人验证或真实员工同意证明。
- 普通设备、主页 AI、厂商密钥及其他门店不能读取完整号码;仅本店商家和获授权总后台可访问,默认脱敏,完整查看/导出有审计。
当前候选客户端对接入模式业务写请求声明 X-Moshi-Partner-Protocol: 1。现有未支持该协议的 APK 在接入门店写业务会被拒绝,防止把提交成功显示为已执行;厂商不能替手表伪造这个标记。部署及指定客户端的实表验收后才能为商家启用,不能凭本地测试直接宣称正式验收完成。
OpenAPI 文件遵循 OpenAPI 3.1.1 官方规范。
协议约定与故障处理
本文为公开接入技术规范。独立测试环境已部署;正式门店授权与真实联调须另行完成。协议路径保留 /api/partner/v1,protocol_version=1。文档修订号不改变业务协议号。协议使用 HTTP JSON,OpenAPI 3.1.1 描述可供软件商导入工具;并不表示获得第三方标准认证。
规范依据:OpenAPI 3.1.1、HTTP 语义 RFC 9110。业务规则以本包代码、OpenAPI 与流程说明为准。
1. 接入边界
- 软件商凭证只访问绑定接入的门店,不能在请求中换 store_id。商家登录凭证、手表凭证与软件商 Bearer Key 不能互换。
- 员工、房间、项目、客人、派单、服务、换人、队列和账务由原系统维护。手表提交的是待处理命令;软件商在自己的事务中执行并回传结果。
- 普通服务任务由摩师维护。软件商传真实员工编号;服务端仍检查角色和任务所有权,但软件商自身必须先认证操作员工。
- SOS 由手表发起。软件商只能查预警、读事件/终端回执、确认知晓;解除必须由店长在手表端操作。商家网页账号、服务员和技师均不能代替店长手表解除接入门店的预警。软件商旧发起/解除调用返回 403。
2. HTTP 与数据格式
正式环境使用 HTTPS,由摩师提供具体域名与门店凭证;不要将示例 localhost 当作正式地址。请求头为 Authorization: Bearer <密钥>;POST 使用 Content-Type: application/json,UTF-8 编码。POST 最大 262144 字节。每个 key 每 60 秒固定窗口最多 120 次请求(所有软件商路由合计),超过返回 429 与 Retry-After 秒数。同一来源 IP 另有所有 API 合计每 60 秒 600 次的网关限额;多门店共用出口也须统筹。带浏览器 Origin 的 POST 必须同源,禁止跨站请求。两个轮询器应共享预算,例如分别每 2 秒一次并在空闲时退避;突发执行还需留出领取和结果回传额度。
GET 查询参数不允许未知或重复字段。整数仅允许十进制数字,禁止空字符串、负号、科学计数法或十六进制。commands.limit 为 1–100,默认 50;events.limit 为 1–300,默认 100;events.after 默认 0。
所有时间戳为 Unix 毫秒,时长为分钟,金额为人民币分;整数不得超过 9007199254740991。厂商资源字符串长度按 Unicode 码点计算;任务正文沿用终端规则,以 UTF-16 码元计数(常见汉字计 1,表情可能计 2);标识符不得为空、纯空白或含控制字符。编号大小写及首尾空格保持原样,软件商应生成无首尾空格的稳定编号。
请求对象拒绝未知字段。可省略不代表允许 null;仅明确声明 nullable 的字段接受 null,例如进行中 service.ended_at 必须为 null。资源数组省略或 [] 表示本次不更新,不能用 null 清空。队列名单是全量替换,空数组清空名单;省略整个 technician_queue 保留旧队列。
每个软件商 HTTP 响应含 X-Request-Id,用于查服务端请求日志;它不是业务幂等 request_id,不应用于重试去重。
3. 编号和版本不要混用
| 名称 | 生成方 | 用途 |
|---|---|---|
| external_id | 原系统 | 稳定业务编号,按接入和资源类型隔离;房号/姓名不是可靠主键 |
| source_version | 原系统 | 单资源递增版本;同版本同内容可重放,旧版本或同版本不同内容拒绝 |
| request_id | 本次 API 调用方 | 同接口业务请求去重;超时保持原编号和请求体 |
| command_id | 摩师 | 原系统执行台账去重键;先落盘后执行业务 |
| result_id | 软件商 | 已保存执行结果的编号;重传相同结果保持不变 |
| task_id / alert_id / version | 摩师 | 任务/预警操作引用及并发检查;expected_version 取当前 version |
| lease_token | 软件商 | 随机领取凭据;与 worker_id 一起持久保存,不记录明文日志 |
幂等不是“所有内容相近的请求合并”。新业务要新编号;原请求重试要原编号和原请求体。若结果不确定,查台账和 GET /commands/{command_id},不要换编号再执行。
4. 原子同步和状态约束
catalog 先建立房间、人员和项目。state 可在同一事务提交客人、派单、服务、换人和队列;引用必须已存在或在该批内按支持的依赖建立。关闭客人和结束其服务可以同批提交;释放旧服务后派同一技师的新单也可以同批提交。
整批完成后,一个技师最多一条 pending 派单或 running 服务,closed 客人不得有这些活动记录。身份引用不能原地换成另一技师/客人/包厢;换人要结束旧记录并新建派单。已结束记录不能恢复。任何条目失败,整批资源、事件与成功结果一起回滚。按原系统真实提交后的快照同步,不能为通过校验虚构版本或状态。
每个资源数组最多 200 条,服务 items 最多 50 条。大批量拆分时先同步被引用资源,保持每批可验证;拆分的多个 HTTP 请求不组成一个跨请求事务。
5. 命令可靠执行
- 读取 commands 得到 queued 命令。这个列表不是所有历史命令,已经 claimed/unknown 的命令应按持久保存的 command_id 单独查询。
- 先在原系统台账持久保存 command_id、worker_id、随机 lease_token,再 claim。相同 worker 和 token 可重试领取;其他领取返回冲突。
- 领取后再次检查权限、目标版本、项目、技师可用性及排钟制度。在原系统同一事务里保存业务变更和命令执行结果。
- 回传 result。succeeded 必须携带能够证明本次动作完成的 state;failed 必须携带 error;unknown 表示不能确定。failed/unknown 不可附带 state。
- 领取有效期为 60 秒。租约到期不会授权别人再次执行;命令进入 unknown,需要核对原系统台账,使用原凭据加 reconciliation:true 回传确定结果。queued 到期也不能再执行业务。
- 结果上传丢失时查询命令,重传已保存的同一结果。HTTP 200 返回 pending 或 unknown 时,不向用户提示“已完成”。
八类命令的结果证据详见 WORKFLOWS.md。收到 succeeded 但缺少正确状态会返回 PARTNER_RESULT_STATE;此时原系统可能已经做成,修正回传快照,不要重复执行业务。
6. 事件、任务和预警
事件采用轮询和持久游标,首次 after=0。按返回 event_id 顺序处理,以 event_id 去重;先持久提交本页消费结果,再推进 cursor。序号可跳号,不按“上一个 + 1”猜测。处理失败从旧游标重试。事件和当前资源查询互为补充:连接恢复时核对 SOS 当前状态,不靠历史事件推断仍在报警。
GET /sos 和 GET /tasks 使用 limit(默认50、1–100)与 cursor,返回 has_more 和 next_cursor(末页null)。tasks 仍按 operator_external_id 检查当前可见权限。游标签名且绑定接入、列表及员工,可跨进程重启、同接入key轮换后继续;不能跨员工、跨门店或跨列表复用。每次遍历固定已登记记录的上界,新插入记录由下次遍历或 events 补入;内容和权限是逐页实时检查,不是历史快照,不保证遍历期间新增可见权限的旧记录全部出现。客户端须遍历全部页面并结合 events,正文仍遵循保留策略。
sos.vendor_acknowledge 仅表示软件商知晓;sos.receipt 中 delivered、presented、speech_completed、acknowledged 表示不同终端阶段,不能互相替代。只有店长手表解除后的 sos.resolved 才表示预警解除。软件商停机不阻塞店内 SOS 广播。
7. 错误与重试
错误 JSON 为 { "status":"failed", "code":"...", "message":"..." }。以 code 分支,message 仅供展示。SDK 不自动重试。日志记录追踪编号、命令号和错误码,密钥、租约凭据、手机号与任务正文需脱敏。
| HTTP / code | 含义 | 处理 |
|---|---|---|
| 400 PARTNER_INVALID / JSON | 类型、枚举、字段、参数或 JSON 错误 | 修正请求;不要原样循环重试 |
| 401 UNAUTHORIZED / PARTNER_UNAUTHORIZED | 缺少、失效或不匹配凭证 | 核对门店密钥,停止使用错误凭证 |
| 403 FORBIDDEN / PARTNER_SOS_WATCH_ONLY | 角色不允许或 SOS 手表专属操作 | 不重试绕过;SOS 由店长手表解除 |
| 404 NOT_FOUND | 编号不存在或不在当前授权范围 | 核对本店编号及同步顺序 |
| 405 METHOD | 路径对应方法不支持 | 按 Allow 和 OpenAPI 调整方法 |
| 409 PARTNER_STALE_VERSION / PARTNER_VERSION_CONFLICT | 旧版本或同版本不同内容 | 从原系统读最新版本;不能单纯加版本掩盖覆盖 |
| 409 PARTNER_REFERENCE / PARTNER_IDENTITY_CONFLICT | 引用缺失或身份被改写 | 补同步引用或创建新业务记录 |
| 409 PARTNER_TECH_BUSY / PARTNER_STATE_CONFLICT | 最终业务状态冲突 | 核对原系统状态与完整同步批次 |
| 409 VERSION_CONFLICT | 摩师任务/预警 version 已变 | 重新查询并让操作者核对新状态 |
| 409 PARTNER_LEASE_BUSY | 已领取或待对账 | 查命令和台账,不抢领执行 |
| 409 PARTNER_RECONCILIATION_REQUIRED | 执行结果需要核实 | 查原系统台账后对账回传 |
| 409 PARTNER_RESULT_STATE | 成功证据不足 | 修正已提交业务的回传状态;不重新执行 |
| 409 PARTNER_REQUEST_REUSED / PARTNER_RESULT_REUSED / REQUEST_REUSED | 相同编号用于不同内容 | 找到原持久化请求,排查编号复用 |
| 413 TOO_LARGE / 415 CONTENT_TYPE | 请求过大或格式不支持 | 按依赖拆批;使用 JSON |
| 429 RATE_LIMIT | 限流 | 至少等 Retry-After,增加抖动并共享限额 |
| 网络超时 / 5xx | 不能确定是否执行 | 先查命令/台账;同步类复用原请求体和编号 |
具体业务错误可能扩展。未知 4xx 应停止该条并人工核对;未知 5xx 按结果未确认处理。响应新增字段应兼容读取,未知 action 不可执行。新能力需商家在 capabilities 中启用。
厂商结果与新版本迁移
厂商HTTP命令结果使用 VendorResult,移除 operation_id 和内部entity,成功entity仅含type/external_id/source_version;普通任务使用TaskActionReceipt。手表原接口不变。升级旧候选客户端时必须移除内部字段依赖,并按next_cursor读完任务/SOS;路径仍为v1,OpenAPI文档版本为1.2.0候选。通过/info.features识别执行凭据和分页能力。
补报早于当前业务状态的成功结果时按 RECONCILIATION.md 提交真实execution_receipt;最新state与历史effects分开。没有凭据时保留unknown并核对原台账,禁止倒退版本或重新执行业务。
排钟、点钟、换人、SOS 与任务接入
本文对应 2026-10-18 接入协议。独立测试环境已部署;真实软件商及实表验收按项目完成。协议仍为 /api/partner/v1,只对商家主动开启的能力发出新命令;旧适配器不应开启未实现能力。手机号规则保持 employee-phone-v1。
1. 能力与责任
| 手表业务 | 软件商接法 | 成功依据 |
|---|---|---|
| 排钟 / 点钟 | assignment.create 命令;dispatch_mode=rotation/requested |
原系统新增同客人、技师、项目、钟类的派单,并更新房态 |
| 起钟 / 下钟 / 加钟 / 拒单 | 原有四类命令 | 原系统实际状态及更高版本 |
| 换人申请 | replacement.request |
新的 pending 申请,关联原派单或服务,原因一致 |
| 换人审批 | replacement.approve |
申请 approved,原派单 replaced 或原服务 ended,指定接替技师的新派单及房态 |
| 换人拒绝 / 撤销 | 原系统通过 /state 更新 replacement 为 rejected/cancelled |
不可把已结束申请恢复为 pending |
| 打扫完成(包括打扫任务) | room.clean |
房间 clean:true,status:idle 且版本前进后,完成本地打扫任务 |
| 普通服务任务 | /tasks、/tasks/actions |
摩师任务状态、员工归属及通知;不改原系统账务 |
| 员工通知 | 原有 /notifications |
通知回执;不会自动创建任务 |
| SOS | /sos、确认知晓接口、/events |
分别记录预警、终端回执、软件商知晓及解除 |
原系统继续负责开房入座、客人离店、计费、结账、会员、提成和排钟制度。同步在店客人及排钟名单后,手表才有可派单对象。手表的金融结算并非本接入包新增功能。技师在岗/请假在原软件调整并同步队列,不生成第二套排钟制度。
2. 先同步在店客人与排钟队列
POST /state 新增 visits、replacements、technician_queue。旧数组仍为增量更新;technician_queue.person_external_ids 为完整有序名单,空数组表示无可排钟人员;没有提供 queue 字段表示保留旧队列。
{
"request_id":"state-20261018-001",
"visits":[{"external_id":"visit-101-A","source_version":1,"room_external_id":"room-101","status":"open"}],
"technician_queue":{
"source_version":1,
"person_external_ids":["tech-58","tech-66"],
"unavailable_person_external_ids":[]
}
}
员工和包厢须已在 /catalog 映射。名单只允许技师;不可用名单必须是有序名单的子集。相同版本只允许相同内容;更旧版本拒绝。手表展示按原名单过滤已停用、忙碌及原软件标记不可用的技师。领取派单命令后,软件商仍须在自己的业务事务内检查队列顺序、在岗与占用,不能仅信任手表预览。
客人只允许 open → closed,不能跨包厢或恢复已关闭记录。可在同一批次同步服务结束/派单取消及客人关闭;最终状态不得留下 pending 派单或 running 服务。过去由派单隐式创建的 visit 如补充显式状态,应使用更高版本。
3. 新命令契约
沿用 /commands → /claim → /result 和持久台账。以下均要求有效角色、商家已开启能力、二次确认和当前对象版本。手表提交后显示 pending;软件商失败时不能伪造成功状态。
| action | target.type | params(软件商收到) |
|---|---|---|
| assignment.create | visit | visit_external_id/visit_source_version、technician_external_id/technician_source_version、project_external_id/project_source_version、dispatch_mode |
| replacement.request | assignment 或 service | reason(1–200 字) |
| replacement.approve | replacement | technician_external_id/technician_source_version、dispatch_mode;原记录引用及版本在 baseline.source |
| room.clean | room | 空对象 |
派单须明确项目;未指定项目的旧客户端须更新。店长派单/审批,技师仅申请自己的换人,店长或服务员可提交打扫完成。无已同步队列时不允许排钟/点钟。
成功回执 state 可携带全部新增字段。换人申请可只携带 replacements,其余新命令必须更新对应包厢版本。命令领取 60 秒超时进入 unknown;只有用原租约并声明 reconciliation:true 才能对账,不能重新执行。保留 command_id 和原结果编号,重传完全相同的结果。详情沿用主文档。
4. 换人状态实例
起钟前申请:
{"replacements":[{"external_id":"replace-001","source_version":1,"source_type":"assignment","source_external_id":"assignment-001","reason":"客人要求更换","status":"pending"}]}
服务中申请用 source_type:service 和真实 service 外部编号。申请同步成功后店长收到通知,手表显示待审批;起钟前的 pending 申请阻止原派单起钟。
批准时在同一 /state 或命令结果事务中提供:
- 原 assignment 更高版本
status:replaced;服务中换人则原 service 更高版本status:ended,带实际结束时间。 - 新 assignment:同包厢、客人、项目,指定接替技师,正确 dispatch_mode,
status:pending。 - replacement 更高版本
status:approved,assignment_external_id:<新派单编号>。 - 包厢更高版本的实际房态。队列发生变化也一并同步。
审批只转派人员,不自动为新技师起钟。不得把原 assignment 的技师改为接替者,也不得把已结束 service 重新改为 running。原系统自行处理费用及优惠,本平台不生成二次收费。
5. SOS
| 方法与路径 | 内容 |
|---|---|
| GET /sos | 本门店 alerts;alert_id、version、status、created_at、resolved_at、initiator_external_id |
| POST /sos/{alert_id}/acknowledge | {request_id,expected_version,note?};仅记录软件商知晓,预警仍 active |
软件商不能发起或解除 SOS。解除只允许店长在手表端确认操作;软件商尝试旧发起/解除路径返回 403 PARTNER_SOS_WATCH_ONLY。 |
alert_id 是摩师生成的不透明编号,不是原系统服务单号。操作使用告警当前 version,重复请求必须使用原 request_id 和完全相同内容。每店沿用现有规则只存在一个 active 预警。
软件商持续按持久游标读取 /events:sos.active、sos.acknowledged、sos.resolved、sos.vendor_acknowledge 和 sos.receipt。receipt 含 alert_id、event_type、person_external_id(无法映射时 null)、stage、received_at;delivered、presented、speech_completed、acknowledged 等不能互相替代。无回执不能推断员工已知晓。
手表 SOS 的店内广播不等待软件商轮询、领取或回传。软件商离线时,店内预警继续按现有逻辑运行;软件商重连后从已保存游标恢复事件,并 GET /sos 核对当前状态。软件商知晓不会伪装成员工的手表已阅。
6. 普通服务任务
GET /tasks?operator_external_id=<员工外部编号> 返回该员工可见任务,使用摩师 task_id 与 version;返回 room/creator/assignee 的外部编号和经过保留策略处理的消息。
POST /tasks/actions:
{"request_id":"task-create-001","operator_external_id":"tech-58","action":"task.create","params":{"room_external_id":"room-101","description":"送两条毛巾"}}
动作回执只保存任务编号、版本、状态及归属,不缓存任务正文;用 GET /tasks 查询当前正文及消息,沿用任务内容保留规则。非 create 还须 task_id、expected_version。允许参数:
| action | params | 规则 |
|---|---|---|
| task.create | room_external_id, description | 本店有效员工发起 |
| task.assign | person_external_id | 店长指派给服务员/店长 |
| task.claim | 空 | 待接手且未分给他人的任务 |
| task.takeover | 空 | 店长接管 |
| task.feedback | text | 当前负责人反馈后 waiting |
| task.reply | text | 原发起人回复后 processing |
| task.complete | 空 | 当前负责人完成 processing 任务 |
| task.cancel | reason | 店长或原发起人取消 |
description/text/reason 最长 240。任务接口并不授予员工额外角色权限;软件商须保存实际操作员工编号,不能将所有动作标为店长。task.changed 事件仅提供任务编号、版本、状态和房间引用,软件商按授权员工再查询任务正文。通知接口不能代替任务归属。
清洁任务完成返回 pending 时,用 command_id 处理对应 room.clean 命令;权威房态回传后任务才完成。原调用重试保持原请求编号,原响应可以仍为 pending;以命令查询和任务查询获取最新状态。
7. 演示、兼容与验收
vendor-client.mjs 提供 sos/acknowledgeSos/tasks/taskAction。demo-adapter.mjs 引用 workflow-demo.mjs,模拟八类命令并使用同一 SQLite 事务持久化业务与结果;仅用于沙箱。seed 可传 people、visits、replacements 和 technician_queue,不能拿演示的房态推断替换真实原软件规则。
商家在接入设置显式启用新增能力;旧接入保留原能力列表。已发布手表 APK 不因服务端候选而自动更新;测试 App 由摩师单独提供;正式切换前确认客户端兼容性并完成实表验收。
联调至少验证:两种派单、两阶段换人、拒绝/撤销、旧审批与人员/队列变化、起钟与换人冲突、重复/竞争领取、断线和超时对账、失败回执原子回滚、跨门店拒绝、普通任务完整对话与真实归属、打扫成功前保持未完成,以及软件商在线/离线情况下 SOS 本店广播、每台终端回执、软件商知晓不解除、店长手表解除后的状态同步。
当前状态已经继续变化时
普通成功回传按本文证据表执行;派单/服务/换人已进入后续状态时,先同步最新状态,再按 历史执行补报 确认原事务。不要为了补报把取消的派单恢复pending,或把已下钟服务恢复running。任务/SOS列表现在需要遍历next_cursor;普通任务feedback后为waiting,原发起人reply后回到processing,再由负责人complete。SOS仅服务员/店长可发起,厂商仅查询与确认知晓,解除只允许店长手表。
逐项字段参考
由本包 openapi.json 生成。必填标记针对所在对象;动作附加条件见 OpenAPI allOf、WORKFLOWS.md、RECONCILIATION.md。请求未知字段拒绝;客户端应兼容未来新增的响应字段。
ExternalId
ExternalId 的协议结构;必填、类型及取值范围以此定义为准。
约束:{"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"}
Room
包厢及权威房态;与服务状态一并同步。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
原系统生成的稳定业务编号;在本接入、本资源类型内唯一。保留大小写与空格,不用员工显示名称代替。 |
| source_version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
原系统针对该资源递增的整数版本;业务 ID 为不透明字符串。 |
| number | 是 | {"type": "string", "minLength": 1, "maxLength": 24, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
number 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| status | 是 | {"type": "string", "enum": ["idle", "pending", "serving", "awaiting_stop", "unpaid", "dirty"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| clean | 是 | {"type": "boolean"} |
原系统房间是否已打扫;打扫完成命令须同时回传 clean=true 和 status=idle。 |
Person
厂商员工资料。本次新增手机号可选输入。未参与手表绑定的员工不强制收集;active technician/manager绑定前须有有效号码,已绑定对应人员不得清空。服务员保留原规则。供应方授权声明写入处理记录,不能作为本人已同意或短信验证的证据。 启用检查覆盖整店所有已绑定active技师/店长,包括未映射本地人员;未绑表员工及服务员不强制收集。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
原系统生成的稳定业务编号;在本接入、本资源类型内唯一。保留大小写与空格,不用员工显示名称代替。 |
| source_version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
原系统针对该资源递增的整数版本;业务 ID 为不透明字符串。 |
| employee_no | 是 | {"type": "string", "minLength": 1, "maxLength": 24, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
门店员工工号,用于显示与映射检查;不同于 external_id。 |
| name | 是 | {"type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
name 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| role | 是 | {"type": "string", "enum": ["technician", "waiter", "manager"]} |
role 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| active | 是 | {"type": "boolean"} |
原系统是否启用此员工或项目;false 表示停用,省略不能代替停用。 |
| phone | 否 | {"type": "string", "pattern": "^\\s*(?:(?:\\+?86)?1[3-9][0-9]{9})?\\s*$"} |
仅用于工作身份核对与设备服务联系。大陆11位手机号,可带+86/86前缀,首尾空白被移除。省略保留已有号码;空字符串仅在绑定规则允许时清空;null无效。绑定中的有效技师/店长须有号码。普通设备、语音AI、厂商响应不返回完整号码。 |
| phone_processing_authorized | 否 | {"type": "boolean"} |
本员工项非空phone必传true,记录供应方声明已履行相关用途告知及适用授权。声明不是本人同意证明或SMS验证结果;未真实完成流程不得仅为通过校验填true。 |
Project
Project 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
原系统生成的稳定业务编号;在本接入、本资源类型内唯一。保留大小写与空格,不用员工显示名称代替。 |
| source_version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
原系统针对该资源递增的整数版本;业务 ID 为不透明字符串。 |
| name | 是 | {"type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
name 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| price_minor | 是 | {"type": "integer", "minimum": 0, "maximum": 100000000} |
原系统项目标价,人民币分。本平台不依据该字段结算。 |
| minutes | 是 | {"type": "integer", "minimum": 1, "maximum": 1440} |
服务或项目时长,单位分钟;服务总时长须等于 items 中 minutes × quantity 之和。 |
| active | 是 | {"type": "boolean"} |
原系统是否启用此员工或项目;false 表示停用,省略不能代替停用。 |
| extension | 是 | {"type": "boolean"} |
是否加钟项目;加钟选择必须符合项目类型。 |
CatalogInput
关闭接入时仅暂存;启用时一次性应用,不影响独立模式手表身份、房态或派单。 可选手机号数据遵循employee-phone-v1;未传保留最新本地资料,非空号码须本员工供应方授权声明,响应不返回号码。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| request_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
调用方生成并持久保存的幂等编号;同接入、同接口重试必须复用编号和完全相同请求体。新业务使用新编号。 |
| rooms | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Room"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
| people | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Person"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
| projects | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Project"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
Assignment
派单;身份引用不可改写,换人须新建派单。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
原系统生成的稳定业务编号;在本接入、本资源类型内唯一。保留大小写与空格,不用员工显示名称代替。 |
| source_version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
原系统针对该资源递增的整数版本;业务 ID 为不透明字符串。 |
| room_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 room 的 external_id;须先同步或在允许的同批次内建立引用。 |
| person_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 person 的 external_id;须先同步或在允许的同批次内建立引用。 |
| project_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 project 的 external_id;须先同步或在允许的同批次内建立引用。 |
| visit_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 visit 的 external_id;须先同步或在允许的同批次内建立引用。 |
| status | 是 | {"type": "string", "enum": ["pending", "started", "rejected", "cancelled", "replaced"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| dispatch_mode | 是 | {"type": "string", "enum": ["rotation", "requested"]} |
rotation=排钟;requested=点钟。原系统执行前重新验证人员可用性与队列。 |
ServiceItem
ServiceItem 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| project_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 project 的 external_id;须先同步或在允许的同批次内建立引用。 |
| minutes | 是 | {"type": "integer", "minimum": 1, "maximum": 1440} |
服务或项目时长,单位分钟;服务总时长须等于 items 中 minutes × quantity 之和。 |
| price_minor | 是 | {"type": "integer", "minimum": 0, "maximum": 100000000} |
人民币分,非元;整数 12800 表示 128.00 元。仅同步原系统价格,摩师不二次计费。 |
| quantity | 是 | {"type": "integer", "minimum": 1, "maximum": 99} |
该服务项目数量;与单项分钟数相乘计入总时长。 |
Service
items 时长乘以数量的合计必须等于 minutes。服务的员工、包厢、客人与派单一致。起钟核对选定另一基础项目时,服务的 project_external_id 可以不同于原派单,但必须符合起钟命令,原派单项目不变。已有服务身份及起钟时间不可改变;已下钟服务不能恢复进行中。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
原系统生成的稳定业务编号;在本接入、本资源类型内唯一。保留大小写与空格,不用员工显示名称代替。 |
| source_version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
原系统针对该资源递增的整数版本;业务 ID 为不透明字符串。 |
| assignment_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 assignment 的 external_id;须先同步或在允许的同批次内建立引用。 |
| room_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 room 的 external_id;须先同步或在允许的同批次内建立引用。 |
| person_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 person 的 external_id;须先同步或在允许的同批次内建立引用。 |
| project_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 project 的 external_id;须先同步或在允许的同批次内建立引用。 |
| visit_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 visit 的 external_id;须先同步或在允许的同批次内建立引用。 |
| status | 是 | {"type": "string", "enum": ["running", "ended"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| started_at | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
Unix 毫秒 |
| ended_at | 是 | {"type": ["integer", "null"], "minimum": 0} |
结束时间 Unix 毫秒;进行中传 null |
| minutes | 是 | {"type": "integer", "minimum": 1, "maximum": 1440} |
服务或项目时长,单位分钟;服务总时长须等于 items 中 minutes × quantity 之和。 |
| items | 否 | {"type": "array", "maxItems": 50, "minItems": 1, "items": "#/components/schemas/ServiceItem"} |
items 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
StateInput
增量同步原系统真实状态;排钟队列是完整有序名单。换人申请成功可只回传 replacements;派单、审批、打扫以及钟务成功必须回传更新后的包厢状态。详见 WORKFLOWS.md。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| request_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
调用方生成并持久保存的幂等编号;同接入、同接口重试必须复用编号和完全相同请求体。新业务使用新编号。 |
| assignments | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Assignment"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
| services | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Service"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
| rooms | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Room"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
| visits | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Visit"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
| replacements | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Replacement"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
| technician_queue | 否 | {"$ref": "#/components/schemas/TechnicianQueue"} |
technician_queue 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
ResultState
增量同步原系统真实状态;排钟队列是完整有序名单。换人申请成功可只回传 replacements;派单、审批、打扫以及钟务成功必须回传更新后的包厢状态。详见 WORKFLOWS.md。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| assignments | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Assignment"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
| services | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Service"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
| rooms | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Room"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
| visits | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Visit"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
| replacements | 否 | {"type": "array", "maxItems": 200, "items": "#/components/schemas/Replacement"} |
增量资源列表:省略或 [] 表示本批不更新该类型;不能传 null,未列出的记录不删除。 |
| technician_queue | 否 | {"$ref": "#/components/schemas/TechnicianQueue"} |
technician_queue 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
NotificationInput
NotificationInput 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| request_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
调用方生成并持久保存的幂等编号;同接入、同接口重试必须复用编号和完全相同请求体。新业务使用新编号。 |
| person_external_ids | 是 | {"type": "array", "minItems": 1, "maxItems": 100, "items": "string"} |
人员外部编号列表;TechnicianQueue 中为完整有序技师名单,空数组清空队列。 |
| text | 是 | {"type": "string", "minLength": 1, "maxLength": 500, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
text 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
ResourceMapping
ResourceMapping 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| type | 是 | {"type": "string", "enum": ["room", "person", "project", "assignment", "service", "visit", "replacement"]} |
type 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
原系统生成的稳定业务编号;在本接入、本资源类型内唯一。保留大小写与空格,不用员工显示名称代替。 |
| native_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
native_id 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| source_version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
原系统针对该资源递增的整数版本;业务 ID 为不透明字符串。 |
SyncResult
SyncResult 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| status | 是 | {"const": "succeeded"} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| request_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
调用方生成并持久保存的幂等编号;同接入、同接口重试必须复用编号和完全相同请求体。新业务使用新编号。 |
| resources | 是 | {"type": "array", "items": "#/components/schemas/ResourceMapping"} |
resources 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
Target
Target 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| type | 是 | {"type": "string", "enum": ["assignment", "service", "visit", "replacement", "room"]} |
type 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
原系统生成的稳定业务编号;在本接入、本资源类型内唯一。保留大小写与空格,不用员工显示名称代替。 |
| source_version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
原系统针对该资源递增的整数版本;业务 ID 为不透明字符串。 |
Command
Command 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| request_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
调用方生成并持久保存的幂等编号;同接入、同接口重试必须复用编号和完全相同请求体。新业务使用新编号。 |
| action | 是 | {"type": "string", "enum": ["service.start", "service.stop", "service.extend", "assignment.reject", "assignment.create", "replacement.request", "replacement.approve", "room.clean"]} |
action 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| target | 是 | {"$ref": "#/components/schemas/Target"} |
target 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| params | 是 | {"type": "object"} |
钟务项目、排钟/点钟、换人及打扫参数见 WORKFLOWS.md。所有 _id 关联转为 _external_id 和 *_source_version。换人审批原服务引用与版本在 baseline.source;队列和人员可用性必须在原系统事务内再次核对。 |
| status | 是 | {"type": "string", "enum": ["queued", "claimed", "unknown", "succeeded", "failed"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| created_at | 是 | {"type": "integer", "maximum": 9007199254740991} |
Unix 时间戳,单位毫秒;允许 null 时表示尚未发生。 |
| lease_expires_at | 否 | {"type": ["integer", "null"]} |
Unix 时间戳,单位毫秒;允许 null 时表示尚未发生。 |
| command_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
摩师生成的命令编号;原系统事务台账的去重键,禁止用员工或包厢编号替代。 |
| expires_at | 是 | {"type": "integer", "maximum": 9007199254740991} |
Unix 时间戳,单位毫秒;允许 null 时表示尚未发生。 |
| operator | 是 | {"type": "object"} |
手表发起操作的员工引用;原系统执行时须再次核对权限。 |
| protocol_version | 是 | {"const": 1} |
业务协议版本,目前固定为 1;与 OpenAPI 文档版本无关。 |
| baseline | 否 | {"type": "object"} |
发起命令时的原系统状态和引用快照;用于原系统执行前检查并发变化。 |
CommandResult
CommandResult 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| command | 是 | {"$ref": "#/components/schemas/Command"} |
command 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| result | 是 | {"anyOf": ["#/components/schemas/VendorResult", "null"]} |
result 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| server_time | 是 | {"type": "integer", "maximum": 9007199254740991} |
摩师服务端当前 Unix 时间戳,单位毫秒。 |
CommandList
CommandList 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| commands | 是 | {"type": "array", "items": "#/components/schemas/Command"} |
commands 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
ClaimInput
ClaimInput 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| worker_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
软件商工作进程稳定编号;领取重试时与原 lease_token 一起复用。 |
| lease_token | 是 | {"type": "string", "minLength": 32, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$"} |
调用方在领取前持久化的不可预测随机令牌;推荐 32 随机字节的 base64url。 |
ClaimResult
ClaimResult 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| command | 是 | {"$ref": "#/components/schemas/Command"} |
command 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| lease_token | 是 | {"type": "string", "minLength": 32, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$"} |
调用方在领取前持久化的不可预测随机令牌;推荐 32 随机字节的 base64url。 |
| lease_expires_at | 是 | {"type": "integer", "minimum": 0, "maximum": 9007199254740991} |
Unix 时间戳,单位毫秒;允许 null 时表示尚未发生。 |
ErrorDetail
ErrorDetail 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| code | 是 | {"type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
code 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| message | 是 | {"type": "string", "minLength": 1, "maxLength": 300, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
message 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
ResultInput
ResultInput 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| lease_token | 是 | {"type": "string", "minLength": 32, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$"} |
软件商生成并先持久保存的随机领取凭据(32–128 位 base64url);推荐 SDK createLeaseToken()。日志应脱敏。 |
| result_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
软件商持久保存的结果编号;同命令重传相同结果时保持不变。 |
| status | 是 | {"type": "string", "enum": ["succeeded", "failed", "unknown"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| error | 否 | {"$ref": "#/components/schemas/ErrorDetail"} |
error 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| state | 否 | {"$ref": "#/components/schemas/ResultState"} |
普通成功:提交动作所需的权威状态;历史补报:只放最新状态,若已通过/state同步则传{}。严禁把历史effects当state重放。 |
| reconciliation | 否 | {"type": "boolean", "default": false} |
默认 false。命令 unknown 或租约过期后,核对原系统事务台账并取得确定结果,才可设置 true。禁止据此重新执行业务。 |
| execution_receipt | 否 | {"$ref": "#/components/schemas/ExecutionReceipt"} |
结构详见 openapi.json。 |
PartnerInfo
PartnerInfo 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| integration | 是 | {"$ref": "#/components/schemas/Integration"} |
integration 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| server_time | 是 | {"type": "integer", "maximum": 9007199254740991} |
摩师服务端当前 Unix 时间戳,单位毫秒。 |
| limits | 是 | {"type": "object"} |
limits 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| business_authority | 是 | {"const": "partner"} |
business_authority 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| protocol_version | 是 | {"const": 1} |
业务协议版本,目前固定为 1;与 OpenAPI 文档版本无关。 |
| features | 是 | {"type": "array", "items": "string"} |
能力探测标记;本候选包含 task_cursor_pagination, sos_cursor_pagination, public_command_results, execution_receipts。旧服务缺少标记时不可发送新凭据字段。 |
Event
Event 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| type | 是 | {"type": "string", "minLength": 1, "maxLength": 64} |
type 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| payload | 是 | {"type": "object"} |
payload 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| created_at | 是 | {"type": "integer", "maximum": 9007199254740991} |
Unix 时间戳,单位毫秒;允许 null 时表示尚未发生。 |
| event_id | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
单调事件编号;用作消费去重键,序号可跳号,不保证连续。 |
EventList
EventList 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| events | 是 | {"type": "array", "items": "#/components/schemas/Event"} |
events 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| cursor | 是 | {"type": "integer", "minimum": 0, "maximum": 9007199254740991} |
本页末尾游标;持久处理本页后用于下次 after。空页保留原游标。 |
| server_time | 是 | {"type": "integer", "maximum": 9007199254740991} |
摩师服务端当前 Unix 时间戳,单位毫秒。 |
Error
Error 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| status | 是 | {"const": "failed"} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| code | 是 | {"type": "string", "minLength": 1, "maxLength": 64} |
code 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| message | 是 | {"type": "string", "minLength": 1, "maxLength": 500} |
message 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
IntegrationCreate
IntegrationCreate 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| name | 是 | {"type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
name 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| capabilities | 否 | {"type": "array", "items": "string"} |
capabilities 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
IntegrationConfigure
IntegrationConfigure 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| enabled | 否 | {"type": "boolean"} |
enabled 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| capabilities | 否 | {"type": "array", "items": "string"} |
capabilities 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
KeyCreate
KeyCreate 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
Integration
Integration 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| id | 否 | {"type": "string", "minLength": 1, "maxLength": 128} |
id 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| name | 否 | {"type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
name 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| enabled | 否 | {"type": "boolean"} |
enabled 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| store_id | 否 | {"type": "string", "minLength": 1, "maxLength": 128} |
store_id 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| capabilities | 否 | {"type": "array", "items": "string"} |
capabilities 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| created_at | 否 | {"type": "integer", "maximum": 9007199254740991} |
Unix 时间戳,单位毫秒;允许 null 时表示尚未发生。 |
| protocol_version | 否 | {"const": 1} |
业务协议版本,目前固定为 1;与 OpenAPI 文档版本无关。 |
KeyResult
KeyResult 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| key_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
key_id 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| api_key | 是 | {"type": "string", "minLength": 1, "maxLength": 512} |
api_key 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| integration | 否 | {"$ref": "#/components/schemas/Integration"} |
integration 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
NotificationResult
NotificationResult 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| status | 是 | {"const": "accepted"} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| request_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
调用方生成并持久保存的幂等编号;同接入、同接口重试必须复用编号和完全相同请求体。新业务使用新编号。 |
| notifications | 是 | {"type": "array", "items": "object"} |
notifications 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| server_time | 是 | {"type": "integer", "maximum": 9007199254740991} |
摩师服务端当前 Unix 时间戳,单位毫秒。 |
IntegrationList
IntegrationList 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| integrations | 是 | {"type": "array", "items": "#/components/schemas/Integration"} |
integrations 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
IntegrationResult
IntegrationResult 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| integration | 是 | {"$ref": "#/components/schemas/Integration"} |
integration 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
KeyRevokeResult
KeyRevokeResult 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| status | 是 | {"const": "revoked"} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| key_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
key_id 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
PairStatusInput
PairStatusInput 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| pair_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
pair_id 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| pair_secret | 是 | {"type": "string", "minLength": 1, "maxLength": 256} |
设备自己持有的绑定会话凭据,不能交给厂商。 |
PairConfirmInput
仅设备绑定确认。查询返回phone_required:true时,三个新增确认字段均必需;独立模式原请求保持兼容。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| pair_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
pair_id 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| pair_secret | 是 | {"type": "string", "minLength": 1, "maxLength": 256} |
设备自己持有的绑定会话凭据,不能交给厂商。 |
| notice_acknowledged | 否 | {"const": true} |
需手机号的人员表示已阅读用途提示及核对脱敏号码,不是本人同意或短信验证。 |
| phone_notice_version | 否 | {"const": "employee-phone-v1"} |
phone_notice_version 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| person_version | 否 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
取绑定查询顶层原始值;人员资料变化必须重新查询。 |
PairStatusResult
PairStatusResult 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| status | 是 | {"type": "string", "enum": ["waiting", "needs_confirmation"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| person | 否 | {"type": "object"} |
person 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| store_name | 否 | {"type": "string"} |
store_name 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| phone_required | 否 | {"const": true} |
phone_required 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| phone_masked | 否 | {"type": "string"} |
phone_masked 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| phone_notice | 否 | {"type": "string"} |
phone_notice 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| phone_notice_version | 否 | {"const": "employee-phone-v1"} |
phone_notice_version 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| person_version | 否 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
person_version 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
PairConfirmResult
PairConfirmResult 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| status | 是 | {"const": "bound"} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| token | 是 | {"type": "string"} |
仅设备本人保存的新会话令牌,禁止提供给厂商。 |
| device_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
device_id 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| expires_at | 是 | {"type": "integer", "maximum": 9007199254740991} |
Unix 时间戳,单位毫秒;允许 null 时表示尚未发生。 |
Visit
单次在店客人/开房记录;open → closed,不得跨房或重开。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
原系统生成的稳定业务编号;在本接入、本资源类型内唯一。保留大小写与空格,不用员工显示名称代替。 |
| source_version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
原系统维护的资源版本,正整数。每次内容变化递增;同版本仅接受相同内容;旧版本拒绝。与摩师 version 不可混用。 |
| room_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 room 的 external_id;须先同步或在允许的同批次内建立引用。 |
| status | 是 | {"type": "string", "enum": ["open", "closed"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
Replacement
换人申请;pending → approved/rejected/cancelled,终态不可改写。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
原系统生成的稳定业务编号;在本接入、本资源类型内唯一。保留大小写与空格,不用员工显示名称代替。 |
| source_version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
原系统维护的资源版本,正整数。每次内容变化递增;同版本仅接受相同内容;旧版本拒绝。与摩师 version 不可混用。 |
| source_type | 是 | {"type": "string", "enum": ["assignment", "service"]} |
source_type 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| source_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 source 的 external_id;须先同步或在允许的同批次内建立引用。 |
| reason | 是 | {"type": "string", "minLength": 1, "maxLength": 200} |
reason 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| status | 是 | {"type": "string", "enum": ["pending", "approved", "rejected", "cancelled"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| assignment_external_id | 否 | {"type": "string", "minLength": 1, "maxLength": 128} |
关联原系统 assignment 的 external_id;须先同步或在允许的同批次内建立引用。 |
TechnicianQueue
完整有序队列;省略整个对象表示保留,提供对象表示替换名单。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| source_version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
原系统维护的资源版本,正整数。每次内容变化递增;同版本仅接受相同内容;旧版本拒绝。与摩师 version 不可混用。 |
| person_external_ids | 是 | {"type": "array", "maxItems": 200, "items": "string"} |
人员外部编号列表;TechnicianQueue 中为完整有序技师名单,空数组清空队列。 |
| unavailable_person_external_ids | 否 | {"type": "array", "maxItems": 200, "items": "string"} |
当前不可排钟的技师编号,必须为队列子集;省略默认空数组。 |
SosAlert
SosAlert 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| alert_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
摩师生成的预警编号;用于查询与确认知晓,软件商无解除权限。 |
| version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
摩师资源当前版本;执行任务或确认知晓时原样填写 expected_version。 |
| status | 是 | {"type": "string", "enum": ["active", "resolved"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| created_at | 是 | {"type": "integer", "maximum": 9007199254740991} |
Unix 时间戳,单位毫秒;允许 null 时表示尚未发生。 |
| resolved_at | 是 | {"type": ["integer", "null"]} |
Unix 时间戳,单位毫秒;允许 null 时表示尚未发生。 |
| initiator_external_id | 是 | {"type": ["string", "null"]} |
发起预警员工的外部编号;无法映射时为 null。 |
SosActionInput
SosActionInput 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| request_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
调用方生成并持久保存的幂等编号;同接入、同接口重试必须复用编号和完全相同请求体。新业务使用新编号。 |
| expected_version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
摩师查询响应中的当前 version,用于并发检查;不使用 source_version。 |
| note | 否 | {"type": "string", "minLength": 1, "maxLength": 300} |
软件商确认知晓的备注;不改变 SOS 状态,不代表任何手表员工已阅。 |
SosResult
SosResult 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| status | 是 | {"type": "string", "enum": ["accepted", "succeeded"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| alert | 是 | {"$ref": "#/components/schemas/SosAlert"} |
alert 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| server_time | 是 | {"type": "integer", "maximum": 9007199254740991} |
摩师服务端当前 Unix 时间戳,单位毫秒。 |
SosList
SosList 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| alerts | 是 | {"type": "array", "items": "#/components/schemas/SosAlert"} |
alerts 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| server_time | 是 | {"type": "integer", "maximum": 9007199254740991} |
摩师服务端当前 Unix 时间戳,单位毫秒。 |
| has_more | 是 | {"type": "boolean"} |
是否还有可见记录。 |
| next_cursor | 是 | {"type": ["string", "null"]} |
下一页游标;末页为null。 |
Task
Task 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| task_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
task_id 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
摩师资源当前版本;执行任务或确认知晓时原样填写 expected_version。 |
| status | 是 | {"type": "string", "enum": ["pending", "processing", "waiting", "completed", "cancelled"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| task_type | 否 | {"type": "string"} |
task_type 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| description | 否 | {"type": "string"} |
description 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| room_external_id | 是 | {"type": ["string", "null"]} |
关联原系统 room 的 external_id;须先同步或在允许的同批次内建立引用。 |
| creator_external_id | 否 | {"type": ["string", "null"]} |
关联原系统 creator 的 external_id;须先同步或在允许的同批次内建立引用。 |
| assignee_external_id | 是 | {"type": ["string", "null"]} |
关联原系统 assignee 的 external_id;须先同步或在允许的同批次内建立引用。 |
| created_at | 否 | {"type": "integer", "maximum": 9007199254740991} |
Unix 时间戳,单位毫秒;允许 null 时表示尚未发生。 |
| completed_at | 否 | {"type": ["integer", "null"]} |
Unix 时间戳,单位毫秒;允许 null 时表示尚未发生。 |
| messages | 是 | {"type": "array", "items": "object"} |
messages 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
TaskList
TaskList 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| tasks | 是 | {"type": "array", "items": "#/components/schemas/Task"} |
tasks 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| server_time | 是 | {"type": "integer", "maximum": 9007199254740991} |
摩师服务端当前 Unix 时间戳,单位毫秒。 |
| has_more | 是 | {"type": "boolean"} |
是否还有可见记录。 |
| next_cursor | 是 | {"type": ["string", "null"]} |
下一页游标;末页为null。 |
TaskActionInput
按 action 限制 params。create: room_external_id,description;assign: person_external_id;feedback/reply: text;cancel: reason;其余为空。非 create 必须 task_id,expected_version。员工角色和任务所有权仍被验证。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| request_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
调用方生成并持久保存的幂等编号;同接入、同接口重试必须复用编号和完全相同请求体。新业务使用新编号。 |
| operator_external_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
实际操作员工的原系统编号;必须映射且有效。软件商负责确认操作者身份,不得冒用店长。 |
| action | 是 | {"type": "string", "enum": ["task.create", "task.claim", "task.takeover", "task.assign", "task.feedback", "task.reply", "task.complete", "task.cancel"]} |
action 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| task_id | 否 | {"type": "string", "minLength": 1, "maxLength": 128} |
task_id 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| expected_version | 否 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
摩师查询响应中的当前 version,用于并发检查;不使用 source_version。 |
| params | 否 | {"type": "object"} |
按 action 选择参数;只允许该动作支持的字段。 |
TaskActionResult
TaskActionResult 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| status | 是 | {"type": "string", "enum": ["succeeded", "pending", "unknown"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| entity | 否 | {"$ref": "#/components/schemas/TaskActionReceipt"} |
稳定的任务操作回执,仅含TaskActionReceipt定义字段。 |
| command_id | 否 | {"type": "string", "minLength": 1, "maxLength": 128} |
摩师生成的命令编号;原系统事务台账的去重键,禁止用员工或包厢编号替代。 |
| request_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
调用方生成并持久保存的幂等编号;同接入、同接口重试必须复用编号和完全相同请求体。新业务使用新编号。 |
| server_time | 是 | {"type": "integer", "maximum": 9007199254740991} |
摩师服务端当前 Unix 时间戳,单位毫秒。 |
TaskActionReceipt
TaskActionReceipt 的协议结构;必填、类型及取值范围以此定义为准。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| task_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128} |
task_id 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
摩师资源当前版本;执行任务或确认知晓时原样填写 expected_version。 |
| status | 是 | {"type": "string", "enum": ["pending", "processing", "waiting", "completed", "cancelled"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| room_external_id | 是 | {"type": ["string", "null"]} |
关联原系统 room 的 external_id;须先同步或在允许的同批次内建立引用。 |
| assignee_external_id | 是 | {"type": ["string", "null"]} |
关联原系统 assignee 的 external_id;须先同步或在允许的同批次内建立引用。 |
VendorEntityRef
厂商结果资源引用,不包含本地实体ID、费用、手机号或手表内部结构。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| type | 是 | {"enum": ["room", "visit", "assignment", "service", "replacement"]} |
结构详见 openapi.json。 |
| external_id | 是 | {"$ref": "#/components/schemas/ExternalId"} |
结构详见 openapi.json。 |
| source_version | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
该结果入库时的原系统版本;不是当前最新版本。 |
ExecutionReceiptSummary
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| transaction_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
已确认的原系统事务编号。 |
| executed_at | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
该事务提交完成时间,Unix毫秒。 |
VendorResult
厂商专用命令结果。手表接口仍使用内部投影;厂商不得依赖 operation_id 或内部entity字段。历史补报可以没有entity,按command_id查询原系统台账。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| status | 是 | {"type": "string", "enum": ["pending", "succeeded", "failed", "unknown"]} |
当前状态;只允许列出的枚举值。业务流转与成功证据见 WORKFLOWS.md。 |
| request_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
调用方生成并持久保存的幂等编号;同接入、同接口重试必须复用编号和完全相同请求体。新业务使用新编号。 |
| command_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
摩师生成的命令编号;原系统事务台账的去重键,禁止用员工或包厢编号替代。 |
| entity | 否 | {"$ref": "#/components/schemas/VendorEntityRef"} |
结构详见 openapi.json。 |
| error | 否 | {"$ref": "#/components/schemas/ErrorDetail"} |
error 字段;类型、必填性和限制见本结构,省略与 null 不等价。 |
| server_time | 是 | {"type": "integer", "maximum": 9007199254740991} |
摩师服务端当前 Unix 时间戳,单位毫秒。 |
| reconciled | 否 | {"const": true} |
已按持久化执行凭据确认历史执行结果。不会据此回滚当前业务状态。 |
| execution_receipt | 否 | {"$ref": "#/components/schemas/ExecutionReceiptSummary"} |
结构详见 openapi.json。 |
ExecutionEffect
原系统事务台账记录的提交效果,不是当前状态同步。只允许该类型字段;每种类型/编号唯一。动作要求详见RECONCILIATION.md。
按type选择一种结构;完整互斥条件见openapi.json。
ExecutionReceipt
经厂商凭证认证的原系统台账声明,并非独立的密码学执行证明。必须与实际业务事务原子持久化;摩师校验租约、指令、作用对象、版本及动作证据,信任软件商对原系统事实负责。
| 字段 | 必填 | 类型 / 约束 | 说明 |
|---|---|---|---|
| transaction_id | 是 | {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\u0000-\\u001f\\u007f]+$"} |
接入内唯一的原系统事务/执行台账编号;禁止复用于其他command_id。 |
| started_at | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
事务开始时间,Unix毫秒;须在本次领取租约内。 |
| executed_at | 是 | {"type": "integer", "minimum": 1, "maximum": 9007199254740991} |
事务提交完成时间,Unix毫秒;不早于started_at,不晚于摩师当前时间。 |
| command | 是 | {"type": "object"} |
|
| effects | 是 | {"type": "array", "minItems": 1, "maxItems": 10, "items": "#/components/schemas/ExecutionEffect"} |
结构详见 openapi.json。 |
历史执行结果补报
本候选通过 GET /info 的 features: ["execution_receipts", ...] 声明支持。已有普通结果回传仍然可用;历史补报通过同一个 POST /commands/{command_id}/result 接口完成。
解决的问题
原系统已执行成功,但回传丢失;随后派单被取消、换人申请已批准、服务已结束,或房间已进入下一轮业务。此时不能重新上传旧 pending/running/idle 状态,也不能重新执行业务。用最新 state 保持当前镜像,再用执行时持久保存的 execution_receipt 确认历史命令。
凭据是由已认证软件商提交的原系统事务台账声明,不是摩师独立观察到执行、也不是独立密码学证明。软件商必须对其真实性负责;禁止根据当前状态猜造历史。租约、版本和引用校验不能取代原系统的事务幂等。
事务中保存什么
在业务提交与台账同一可靠事务边界保存:command_id、完整 command(含 target/params/source_version)、worker_id、领取前保存的 lease_token、事务编号、开始/提交时间、执行后的 effects、稳定 result_id、原普通结果体。事务编号在本门店接入内唯一,不同命令不能复用。
examples/execution-receipt.mjs 的 makeExecutionReceipt() 仅负责格式构造,传入的必须是真实提交后的数据。demo-adapter.mjs 演示 SQLite 业务与凭据同事务提交;生产中请换成原软件实际事务。
| 字段 | 约束 |
|---|---|
| transaction_id | 1–128 字符,接入内唯一,能查询原系统执行台账 |
| started_at | Unix 毫秒,须在该 command 的本次领取租约内,不能提前于领取 |
| executed_at | Unix 毫秒,不早于 started_at、不晚于服务端当前时间;执行可在租约内开始并在租约后提交 |
| command | 精确回填 {command_id, action, target, params};params 中的版本字段也不能省略 |
| effects | 1–10 条、type/external_id 唯一;执行提交时的资源版本不高于当前已同步版本 |
服务端时间从 /info 或领取响应获取,软件商主机应校时。禁止为了过校验修改已保存的时间;发现时钟/台账异常时人工核对并保留 unknown。
各动作必须证明的效果
每条 effect 基础字段:type, external_id, source_version, status。房间还必须有 clean;服务加钟和换人申请另有下表字段。这里的版本和状态是该事务刚提交时的值。
| action | 必须包含的 effects |
|---|---|
| service.start | 原 assignment 更新为 started;与之关联且项目匹配的 service 为 running;baseline.room 版本增加 |
| service.stop | 目标 service 版本增加且 ended;baseline.room 版本增加 |
| service.extend | 目标 service 版本增加且 running,minutes 至少增加所选项目时长,item_count 增加,added_project_external_id 匹配指令、added_minutes 至少为所选项目时长;baseline.room 版本增加 |
| assignment.reject | 目标 assignment 版本增加且 rejected;baseline.room 版本增加 |
| assignment.create | 指定客人、技师、项目和派单方式的 assignment 为 pending;baseline.room 版本增加 |
| replacement.request | 引用指定 assignment/service 的 replacement 为 pending;reason 与指令相同;无需房间效果 |
| replacement.approve | 目标 replacement 版本增加且 approved;baseline.source 更新为 replaced(派单)或 ended(服务);关联的接替 assignment 为 pending 且技师/派单方式匹配;baseline.room 版本增加 |
| room.clean | 目标 room 版本增加、status=idle、clean=true |
关联资源必须已通过当前状态同步建立映射。服务、派单等身份引用按现有不可变规则核对。与当前相同版本的 effect 必须与当前状态、clean/minutes/reason/item_count 一致;较早版本允许体现历史状态,但不会被写回当前业务记录。
原系统已批准的换人记录可在当前同步中引用后来取消、拒绝或被替换的接替派单;审批关系仍保留。普通“批准成功”回传仍须提供 pending/started 的接替派单;后续状态已变化时使用历史凭据。
实际调用顺序
- 从本地持久台账恢复 command_id 与原 lease_token,查询
/commands/{id}。已 succeeded/failed 就停止执行;结果与台账冲突则交人工核对。 - 如果确认没有执行,回传 failed +明确原因+reconciliation:true;无法确认则保持 unknown。只有核实执行成功且具备凭据,才走下面步骤。
- 通过
/state同步最新完整相关记录(可按最多200条/类分批,保持业务关系原子一致),使用其自身持久化 request_id。不要把历史效果放在 state 里。 - 回传:
await client.report(commandId, {
lease_token: savedLeaseToken,
result_id: savedReconciliationResultId,
status: 'succeeded',
reconciliation: true,
state: {}, // 当前状态已在上一步同步
execution_receipt: savedReceipt
});
也可以把尚未同步的最新状态放进本次 state。状态更新、凭据校验和结果入库在同一事务中,任何校验失败整批回滚。该请求必须持久保存,重试时 result_id 与请求体不变。若之前普通结果的请求体已改变,应为新的对账结果使用新的 result_id;原结果若已终结则查询终态,不再改写。
响应示例:
{"status":"succeeded","request_id":"watch-request-id","command_id":"original-command-id","reconciled":true,"execution_receipt":{"transaction_id":"vendor-tx-123","executed_at":1800000000000},"server_time":1800000060001}
历史补报不重新收费、不重新派单、不重放派单通知,不附带旧 entity。手表按已确认结果结束等待,并读取最新快照。打扫补报只完成命令创建时已经存在且版本未变的原打扫任务;后来新建或被修改的任务保留现状,需按最新情况处理。不能根据一张旧“打扫完成”凭据把当前已入住的房间清空。
主要错误码
| code | 应对 |
|---|---|
| PARTNER_EXECUTION_PROOF | 核对原命令、效果引用和版本;先同步最新状态;缺乏真实证据时不要伪造 |
| PARTNER_EXECUTION_REUSED | 事务号已用于其他命令;核对业务台账唯一键 |
| PARTNER_RECONCILIATION_REQUIRED | 租约过期后先查台账,再显式对账 |
| PARTNER_RESULT_REUSED | 相同 result_id 的内容变了;恢复原请求,或先查命令终态 |
| PARTNER_RESULT_FINAL | 已是终态;查询结果,不覆盖 |
| PARTNER_LEASE_INVALID | 必须使用原领取前持久保存的随机令牌,不换令牌重领 |
| PARTNER_INVALID | 字段类型、时间范围或 action 组合不合法;以原台账核对,不能随意改时间 |
联调资料清单(可直接填写)
目前未选定软件商也可先使用本包开发准备与本地沙箱。现在不必提供真实客户资料或密钥。 确定合作方后,把下面表格填好交给对接负责人;不知道的项目写“待确认”,不要猜填。
A. 你/商家先提供
| 项目 | 填写 |
|---|---|
| 软件商名称、现用系统名称/版本 | 待确定 |
| 软件商技术联系人、联系方式、可联调时间 | 待确定 |
| 测试门店名称、独立测试库/测试账套是否可用 | 待确定 |
| 手表型号、Android版本、已安装摩师App版本、数量 | 待确定 |
| 门店网络:Wi-Fi/4G、外网访问限制、软件服务器在本地还是云端 | 待确定 |
| 第一批要开通的动作(勾选下面能力表) | 待确定 |
测试员工至少安排:店长1名、服务员1名、技师2名;准备包厢1–2间、普通项目1个、加钟项目1个。开发样本使用脱敏/虚构信息;真实设备绑定需要实际员工授权及真实有效资料,按约定安全渠道提供,不放进群聊、代码或测试日志。
B. 请软件商提供
| 项目 | 必要内容 / 填写 |
|---|---|
| 原系统开放方式 | HTTP API/插件扩展/受支持数据库接口及文档;认证和调用限制 |
| 数据主键与版本 | 员工、房间、项目、客人、派单、服务、换人申请的稳定ID;source_version来源 |
| 脱敏数据样例 | 每类1–3条JSON/字段表;包含一次正常流程和一次拒绝/取消流程 |
| 原系统业务规则 | 排钟顺序、点钟选择、忙碌判定、替换前后关系、加钟项目及下钟房态 |
| 原事务去重方式 | command_id如何成为唯一键、如何与业务提交原子保存、跨库如何查询确定结果 |
| 原事务查询方式 | 按command_id/transaction_id查询是否提交;超时无法确认时负责人 |
| 执行凭据 | started_at、executed_at、提交效果、事务编号的真实来源与留存期限 |
| 员工信息授权 | 手机号由谁采集、授权依据、更新/删除与绑定变更流程;不得默认伪造授权 |
| 部署方式 | 适配器所在主机、语言/版本、进程数量、网络出口、代理/白名单要求 |
| 业务规模 | 门店数、每店手表/员工数、峰值每分钟业务次数、任务/SOS历史量 |
| 故障处理 | 断网补传策略、最长离线时间、监控告警、支持联系人与维护窗口 |
C. 摩师侧在真实联调前提供
| 项目 | 交付内容 |
|---|---|
| 测试环境 | 已部署本候选功能的HTTPS根地址、版本、接口文档地址、网络可达要求 |
| 测试门店连接 | store_id、integration_id、capabilities、启用状态;key由商家管理账号创建并安全交付 |
| 设备侧 | 可安装的测试APK/版本说明、配对流程、语音/手动操作入口、日志采集方法 |
| 规则与限制 | 请求大小、批量/频率限制、超时、分页、保留策略、支持的动作及不支持范围 |
| 支持窗口 | 摩师联调负责人、测试时间、故障追踪方法、环境回退安排 |
本包没有替这些“待开通”的项目预填正式值。key、lease_token、商家密码、设备token通过安全配置/专门渠道管理;验收表只保留脱敏标识。
D. 能力确认表
| 能力 | 首批需要? | 软件商已支持? | 对应原系统接口/事务 | 负责人 |
|---|---|---|---|---|
| assignment.create 排钟/点钟 | 待定 | 待定 | 待填 | 待填 |
| service.start 起钟 | 待定 | 待定 | 待填 | 待填 |
| service.extend 加钟 | 待定 | 待定 | 待填 | 待填 |
| service.stop 下钟 | 待定 | 待定 | 待填 | 待填 |
| assignment.reject 拒单 | 待定 | 待定 | 待填 | 待填 |
| replacement.request 申请换人 | 待定 | 待定 | 待填 | 待填 |
| replacement.approve 批准换人 | 待定 | 待定 | 待填 | 待填 |
| room.clean 打扫确认 | 待定 | 待定 | 待填 | 待填 |
| 普通任务与反馈/回复 | 待定 | 待定 | 待填 | 待填 |
| SOS查看/知晓、事件与终端回执 | 必核对 | 待定 | 待填 | 待填 |
| 历史执行补报和异常对账 | 必核对 | 待定 | 待填 | 待填 |
双方联调验收记录模板
本表供真实软件商+隔离测试门店+真实手表验收。随包自动测试不能填写为这里的“通过”。
日期:待填 摩师版本:待填 软件商/版本:待填 测试门店:待填
摩师负责人:待填 软件商负责人:待填 商家确认人:待填
每项保存:编号、command_id/request_id、原系统transaction_id、执行次数、API状态/trace_id、手表实际显示、通过/失败、缺陷编号。不要记录完整key、lease_token、手机号或设备会话。
| 编号 | 操作/故障注入 | 通过条件 | 实测/证据 |
|---|---|---|---|
| 01 | 首次资料同步、重复同步、同版本改内容 | 正确映射;完全相同请求幂等;同版本不同内容拒绝;失败批次无部分更新 | 待测 |
| 02 | 商家启用、停用、密钥轮换/撤销、跨店请求 | 门店隔离;未开启能力拒绝;新旧key按授权窗口切换;撤销立即失效 | 待测 |
| 03 | 绑定店长/技师/服务员;缺号、资料变更后确认 | 现有角色及手机号规则生效;手表展示脱敏告知;过期person_version拒绝 | 待测 |
| 04 | 排钟与点钟;忙碌/队列变化 | command参数明确;原系统仅派一次;原系统冲突被呈现 | 待测 |
| 05 | 起钟,含明确选择不同项目 | 原系统所选项目正确;只产生一次服务;手表只在确定成功后更新 | 待测 |
| 06 | 加钟与重复回传 | 新项目及新增时长正确;原系统只加一次;费用由原系统计算 | 待测 |
| 07 | 下钟及原系统结账 | 服务结束、后续房态按原系统同步;摩师不重新计费 | 待测 |
| 08 | 拒单;拒单后重试原请求 | 同一派单只拒绝一次;不会误取消另一新派单 | 待测 |
| 09 | 起钟前和服务中申请/批准换人 | 原人与接替人、客人、项目一致;旧记录结束;忙碌技师不能接替 | 待测 |
| 10 | 房间离店后打扫 | 无在店客人/活动服务后确认clean;原系统房态及任务一致 | 待测 |
| 11 | 普通任务创建/指派/接手/反馈/回复/完成/取消 | 反馈进入waiting,原发起人回复后继续;角色及归属校验正确 | 待测 |
| 12 | 服务员/店长手表SOS、软件商知晓、解除 | 店内即时广播;软件商无权发起/解除;只能店长手表解除 | 待测 |
| 13 | 两个消费者同时领取;领取响应丢失 | 唯一有效领取者;恢复原lease_token;原业务执行一次 | 待测 |
| 14 | 执行提交成功,结果回传丢失 | 重查command与事务台账;不重复扣费/派单;终态不可覆盖 | 待测 |
| 15 | 租约超时,确认未执行 / 无法确定 | 明确未执行可failed对账;无法确定仍unknown;不自动重做 | 待测 |
| 16 | 成功后又取消派单/结束服务,再补历史凭据 | 历史命令成功,当前终态不被恢复;凭据重传不产生新业务 | 待测 |
| 17 | 打扫成功丢失回传,已新入住/新建打扫任务 | 凭据仅处理原任务;不清空新房态、不完成新任务 | 待测 |
| 18 | 错命令、错令牌、重复事务号、未来版本/时间凭据 | 全部拒绝;同时提交的当前状态也回滚;原命令不被错误结案 | 待测 |
| 19 | 超过一页任务/SOS;翻页时新增、停用员工 | 完整遍历至has_more=false;无重复;新记录由下一轮/事件补入;不能跨员工/门店使用cursor | 待测 |
| 20 | 断网后事件补收、手表掉线重连、重启适配器 | 持久游标和台账恢复;不遗漏需处理事件;终端回执不等同业务成功 | 待测 |
| 21 | 高峰业务、网关限流、长时间断网 | 达到双方约定容量/延迟;按Retry-After退避;无积压失控和重复执行 | 待测 |
| 22 | 关闭接入/回退、存在unknown时尝试切换 | 按门店状态限制拒绝不安全切换;先对账,不删台账或重置版本 | 待测 |
峰值门店/设备数量:待填 测试持续时间:待填 最长离线时长:待填
约定延迟/吞吐指标:待填 遗留问题与责任人:待填
结论:未开始 / 不通过 / 限定能力通过 / 全部约定能力通过(选择)
实际准许开启的 capabilities:待填。只有已验收的能力才进入正式连接配置。
申请测试接入
准备软件名称、技术联系人、原系统接口说明及计划接入的能力,联系摩师开通隔离测试门店。测试根地址、门店密钥和测试 App 将单独交付。
可通过官网在线客服咨询“软件商 API 对接”;也可使用现有系统合作入口留下联系方式,由摩师继续沟通接入事项。
联系系统合作 返回官网 · 在线客服