咖啡机接入整体流程图

沿用现有智慧食堂名称，不新增“咖啡商城”或新的用户端菜单

重庆环卫 · 妙雀 308 / 318K
一句话：用户在咖啡机选商品，扫描我方消费二维码完成扣款；咖啡机轮询结果后自行制作，并把出货结果回传。后台沿用 设备管理、设备映射、档口管理、菜品管理、餐厅设置、常规订单、订单退款。
现有系统入口需补充的设备适配能力成功结果异常处置
01　后台配置（管理员）
设备管理 / 设备信息登记咖啡机、点位、启停状态
→
设备管理 / 设备映射关联 machid、轨道号与商品；密钥安全保存
→
档口管理 + 菜品管理维护售卖档口、商品、价格
→
餐厅设置复用消费、退款与有效期规则

01-A　PC 管理端：从建档到订单处置

页面、路由和现有按钮均以当前 ai_store 为准；橙色“接入补充”只说明为了咖啡机闭环需补的字段，不视为已上线。

P1

设备管理 → 设备信息 现有

/device/equipment

用“新增设备”建立咖啡机；现有表单包含设备名称、设备编号、设备厂商、设备类型、状态，列表支持编辑、详情、启用/停用、删除。

咖啡接入补充在设备详情安全保存 machid、点位、appkey；密钥不在列表明文展示。
下一跳保存且启用后，进入“设备映射”选择该设备。
P2

设备管理 → 设备映射 现有接入补充

/device/mapping

点击“新增映射”，先选设备与档口；保存后可用已有“下发”动作，页面会显示映射状态和最近下发时间。

咖啡接入补充扩展为 machid + trackno → 菜品 + 价格 的明细校验。
下一跳到“档口管理 / 菜品管理”确认档口、商品与价格；厂家是否支持真正远程下发待确认。
P3

档口管理 → 菜品管理 现有

/restaurant/stall　→　/menu/dish?tab=info

在“档口管理”新增/编辑并启用承载售卖的档口；在“菜品管理 → 菜品信息”维护设备展示的商品、价格和启用状态，营养展示沿用“菜品营养配置”。

校验设备返回的商品名、价格必须与 P2 映射一致。
下一跳回到 P2 完成映射复核，再进入“餐厅设置”。
P4

餐厅设置 现有页面

/unified/restaurant-setting

复核当前餐厅可复用的消费账户、有效期和退款/冲正规则，不创建“咖啡”专属设置页。

动作按项目现网规则配置并记录扣款口径。
下一跳配置生效后进入设备试运行；变更规则时回到 P1/P2 再核验。
P5

订单管理 → 常规订单 现有接入补充

/order/regular　→　/order/detail?orderId=…

按订单号、档口、订单状态、扣款账户类型和日期筛选，点“查看”进入订单详情。

咖啡接入补充详情关联设备订单号、machid、轨道号、扣款状态、出货状态、errinfo。
下一跳出货成功即完成；收到 status=0 则转入退款/人工处理。
P6

订单退款 现有

/order/refund/index　→　/order/refund/detail?orderRefundId=…

对已生成售后单的出货异常，按订单号查询，进入“详情”，由有权限人员执行现有审核与处理动作。

边界是否自动建售后单/自动冲正须先确认现有消费系统能力。
返回结果处理结论回写订单，形成可查询的异常闭环。

PC 验收：一台启用设备与一个启用商品可完成映射；一笔设备订单能在“常规订单”查到；出货失败有“订单退款”或人工处理结果。

02　购买与设备回调（用户 + 咖啡机 + 我方消费体系）
用户在咖啡机选商品不增加小程序入口
→
咖啡机生成设备订单orderid、machid、trackno、价格
→
weburlA：获取付款码校验签名、设备映射、商品与价格；创建待扣款订单，返回 twocode
→
设备展示我方二维码twocode 是二维码数据，不是图片
→
用户扫码进入既有消费入口账户 / 餐卡 / 补贴扣款，具体账户待项目确认
→
weburlC：轮询扣款状态code=2 等待；code=1 成功；code=3/4 过期或关闭
→
咖啡机自行制作仅在 code=1 后执行
→
weburlB：上报出货结果status=1 成功；status=0 失败并带 errinfo

02-A　小程序 / 既有消费入口：只做确认扣款

此链路不新增“咖啡商城”“咖啡机”菜单。二维码来自设备，用户只进入现有消费确认能力；页面标题按最终投产的小程序或 H5 为准。

M1

咖啡机付款二维码页 设备端

用户用微信“扫一扫”或既有小程序扫码能力扫描设备显示的二维码。

用户操作不输入商品、金额或设备号。
下一跳二维码携带设备订单上下文，直接打开既有消费确认页。
M2

既有消费确认页 复用

用户核对商品、金额与可用账户/餐卡/补贴扣款方式后确认支付。

用户操作确认支付；余额不足、账户不可用或主动取消均保留现有失败提示。
下一跳支付成功进入 M3；失败、取消或过期进入 M4。
M3

既有支付成功页 复用

用户看到扣款成功，关闭页面后回到咖啡机等待制作。

后台联动咖啡机轮询得到 code=1 后才开始制作。
注意扣款成功不等于已出货，用户端不再点击“开始制作”。
M4

既有支付失败 / 已取消 / 已过期提示 复用

用户按当前提示返回或重新扫码；设备收到 code=3/4 后结束交易。

结果不制作、不把订单记为完成。
可选复用若当前小程序已有“订单/账单”，可用其查询；不是 V1 必须新增的页面。

小程序验收：用户只需“扫设备码 → 在既有消费页确认 → 看支付结果”三步；未付款、取消或过期绝不触发制作。

03　订单、售后与运营（管理员 / 运维）
常规订单查询设备订单、扣款状态与出货状态
→
出货成功订单完成；进入经营统计
出货失败记录 errinfo，进入异常处理
网络/重复回调以 orderid + machid 幂等；对账补偿
→
订单退款按既有退款/冲正规则或人工处理
→
设备管理 + 报表管理设备在线、故障、缺货、库存、交易与差异查询

03-A　咖啡机设备端：从选品到制作回传

下列是厂家固件必须呈现的交互状态，不是我方新建的 PC 或小程序页面；实际视觉和按钮以妙雀实机/固件为准。

D1

商品选择页 厂家固件

用户选择已配置商品/轨道；设备生成 orderid、machid、trackno、name、price。

校验前提设备传参必须与 PC 的 P2 映射一致。
下一跳进入订单确认并请求付款码。
D2

订单确认 / 请求付款码页 协议适配

设备调用 weburlA；我方校验签名、设备、轨道商品和价格，创建待扣款订单。

成功返回 twocode，进入扫码支付页。
失败展示可读原因并回商品选择页，不创建可扣款订单。
D3

扫码支付页 厂家固件

设备展示我方返回的 twocode 数据对应二维码，等待用户扫码。

约束设备不得自行生成或替换支付二维码。
下一跳跳到“等待支付页”，开始调用 weburlC。
D4

等待支付页 协议适配

按厂家约定频率轮询 weburlC：code=2 留在本页；code=1 才允许制作。

成功code=1 进入制作/出货中页。
失败code=3/4 进入交易结束页并禁止制作。
D5

制作 / 出货中页 → 完成页 厂家固件

咖啡机自行制作，成功后调用 weburlB(status=1)；设备展示完成并回商品选择页。

我方结果常规订单更新为出货成功，进入经营统计。
无需用户动作用户不再在小程序二次确认。
D6

制作失败 / 交易结束页 厂家固件

已支付但制作失败时调用 weburlB(status=0, errinfo)，给出重试或联系客服提示。

我方结果常规订单进入异常，导向退款/冲正或人工处理。
必备控制回调按 orderid + machid 幂等，并支持重试审计。

设备端验收：校验通过才展示付款码，只有 code=1 才制作；成功和失败都必须有一次可重试、可审计的 weburlB 回传。

V1 最小范围

  1. 补齐咖啡机设备与商品轨道的映射。
  2. 实现 `weburlA / weburlC / weburlB` 三段适配。
  3. 在常规订单关联设备订单、扣款、出货和失败原因。
  4. 出货失败转入既有订单退款或人工处理。
  5. 厂家库存、交易、设备状态查询作为后续对账与运维增强。

不应提前承诺

  • 远程下发咖啡机商品、价格或配方。
  • 后台远程控制咖啡机制作/出货。
  • 出货失败一定自动退款：须先确认现有消费系统冲正规则。
  • 厂家协议已在 318K 实机完全验证：仍需测试机与固件确认。