摩师 开发者中心

← 返回接入首页

绑定身份版本核对(独立测试环境候选)

下载候选 OpenAPI(独立测试环境)

厂商接入模式下,设备查询配对状态后,所有角色均收到 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;软件商不用商家账号密码调用厂商接口。密钥只放服务端环境或密钥管理系统,不能嵌在手表、浏览器或公开代码中。

原系统需要实现两个后台循环:命令消费者和事件消费者。命令消费者配套持久化执行台账;演示适配器只能用于沙箱,不可替代现有业务事务。

接入顺序

  1. GET /api/partner/v1/info 检查协议、门店接入与 capabilities。
  2. POST /catalog 同步房间、员工、项目;员工手机号绑定政策及配对详见 README.md。首次先少量验证映射。
  3. POST /state 同步在店客人、已有派单和服务,以及有序 technician_queue;所有编号取原系统稳定主键。
  4. 商家确认映射完整后启用连接及实际支持的能力。未支持的动作不要勾选。
  5. 手表发起排钟/点钟或其他动作,软件商消费者领取命令,在原系统事务内执行并回传结果。
  6. 持久处理 events 游标,展示 SOS、终端回执及任务变化。软件商确认知晓不会解除 SOS。
  7. 完成下方验收后再安排正式部署与真实手表验收。

最小调用示例

以下 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. 领取、执行、回传的闭环

  1. 读取 GET /commands?limit=50 获得 queued 命令。手表未确认的核对不会生成命令。
  2. 在原系统持久台账保存 command_id、完整业务内容、worker_id 及不可预测的随机 lease_token,保存成功后再请求 POST /commands/{id}/claim,请求体为 {worker_id, lease_token}。
  3. 获得有效租约后,原系统校验目标版本、员工权限和自己的业务规则,在自己的事务内执行业务。不要用接口显示文字替代执行。
  4. 把实际业务状态与结果写入持久台账。尽量将业务修改和台账写入原系统同一事务,避免业务成功但台账丢失。
  5. 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 不循环运行;没有演示数据的命令会被明确拒绝,不会假装执行。

厂商联调至少应通过以下项目,电脑测试与实表验收分别记录:

  1. 两家门店、两把密钥隔离;越权 ID、撤销密钥及停用门店均被拒绝。
  2. 资料相同版本重放、旧版本、同版本不同内容、未知引用及重复员工/包厢号。
  3. 原系统点钟/排钟同步,正确技师收到正确包厢和项目,其他终端不误收。
  4. 手动与自然语音的核对、取消、更正;确认前原系统没有业务变更。
  5. 起钟、加钟、下钟、拒绝派单:分别验证手动与主页 AI 确认流程,对象、实际状态、技师、项目和房态全链路一致;另测起钟改选基础项目,实际服务项目正确且原派单项目不变。
  6. 同一命令重复提交、两个执行者竞争、领取响应丢失和结果响应丢失;原系统只执行一次。
  7. 已领取超时、程序重启和结果不明:保留台账及凭据,核对后恢复,不重复计费。
  8. 项目/服务版本在确认后变化、员工停用、错误成功状态及终态改写均不能绕过校验。
  9. 通知正确员工的完整正文播报与回执,通知零待办,通知回执不计为业务成功。
  10. 原系统结账后房态同步正确,摩师不依据历史服务重新推断待结账。
  11. 未实现能力不能从手动或 AI 绕过;现有独立门店不受接入配置影响。
  12. 商家启用、轮换、撤销及停用的操作,不能留下未解决业务或丢失结果台账。
  13. 手机号省略时保留本地补录,规范 +86/86 输入,非法/null 拒绝;缺少供应方声明时拒绝非空号码,同步返回不回显号码。
  14. 缺号的技师/店长不能新绑定,已绑定缺号不能启用;未参与绑定的员工及服务员无需新增强制收集。已绑定且要求手机号的人员不能清空,商家更新后使用新版本核对。
  15. 绑定只显示脱敏号码和用途说明;确认回传说明及人员版本,资料/说明已变化则拒绝旧确认。该结果不能记录为 SMS 本人验证或真实员工同意证明。
  16. 普通设备、主页 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. 命令可靠执行

  1. 读取 commands 得到 queued 命令。这个列表不是所有历史命令,已经 claimed/unknown 的命令应按持久保存的 command_id 单独查询。
  2. 先在原系统台账持久保存 command_id、worker_id、随机 lease_token,再 claim。相同 worker 和 token 可重试领取;其他领取返回冲突。
  3. 领取后再次检查权限、目标版本、项目、技师可用性及排钟制度。在原系统同一事务里保存业务变更和命令执行结果。
  4. 回传 result。succeeded 必须携带能够证明本次动作完成的 state;failed 必须携带 error;unknown 表示不能确定。failed/unknown 不可附带 state。
  5. 领取有效期为 60 秒。租约到期不会授权别人再次执行;命令进入 unknown,需要核对原系统台账,使用原凭据加 reconciliation:true 回传确定结果。queued 到期也不能再执行业务。
  6. 结果上传丢失时查询命令,重传已保存的同一结果。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 或命令结果事务中提供:

  1. 原 assignment 更高版本 status:replaced;服务中换人则原 service 更高版本 status:ended,带实际结束时间。
  2. 新 assignment:同包厢、客人、项目,指定接替技师,正确 dispatch_mode,status:pending。
  3. replacement 更高版本 status:approved,assignment_external_id:<新派单编号>。
  4. 包厢更高版本的实际房态。队列发生变化也一并同步。

审批只转派人员,不自动为新技师起钟。不得把原 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 的接替派单;后续状态已变化时使用历史凭据。

实际调用顺序

  1. 从本地持久台账恢复 command_id 与原 lease_token,查询 /commands/{id}。已 succeeded/failed 就停止执行;结果与台账冲突则交人工核对。
  2. 如果确认没有执行,回传 failed +明确原因+reconciliation:true;无法确认则保持 unknown。只有核实执行成功且具备凭据,才走下面步骤。
  3. 通过 /state 同步最新完整相关记录(可按最多200条/类分批,保持业务关系原子一致),使用其自身持久化 request_id。不要把历史效果放在 state 里。
  4. 回传:
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 对接”;也可使用现有系统合作入口留下联系方式,由摩师继续沟通接入事项。

联系系统合作 返回官网 · 在线客服