kiosk/docs/打印版与电子版接口修改说明.md

打印版 / 电子版：App 对接摘要

更新：2026-09-14。以后端交付的 OSCAR_PHOTO_PURCHASE.md 为准。人脸识别及最近照片流程使用 type=2；手机上传 type=1 保持原有格式。原打印页面和打印 ViewModel 未改动。

已对齐的协议

• verify-result、get-pay-url 的人脸照片请求显式发送 video_id=[]，照片 ID 去重。
• 报价分别使用 price_image / amount、price_electronic / amount_electronic。阶梯价格与总价以服务端为准，不在 App 计算。
• 本次后端不支持免费电子版。 电子版单价缺失、非正数或已选照片总额非正数时不可购买；空选可展示正数基础单价和零总额，但不能下单。
• get-pay-url 返回预选缓存、订单号和锁定金额，尚未创建实体订单或完成付款。App 保存该响应的订单金额；微信支付弹窗保持原 UI，仅显示标题、二维码和原扫码提示，不额外显示购买模式或金额。服务端保留员工 1 分钱优惠，实付金额以小程序为准。
• 新版支付链接要求 purchase_mode 匹配、金额有效、order_status=10 且 URL 非空。不能凭下单成功或 type=5 判定付款完成。
• HTTP pay-success-message 只有 order_status=30 才按购买成功处理；10 继续等待，40/50 显示取消/退款，其他状态不作为成功并显示服务端状态。
• WebSocket 新格式为 code=5 → data(type=5) → data(订单信息)，同时保留旧网关的扁平 data 解析。type=1 的 file_map 仍用于原上传打印流程。
• 完成消息需匹配订单号、来源、照片集合及购买模式，重复 HTTP / WebSocket 消息只处理一次。
• 选择照片或重新选择购买模式后清理旧支付二维码，重新取链接。业务错误显示服务端 msg；预选失效等查询错误关闭支付弹框、刷新报价，不继续使用旧链接。

完成与相册

verify-result → get-pay-url → 用户扫码建单支付
  → HTTP 补查 / WebSocket 完成消息
  → print：原打印与相册流程
  → electronic：独立完成页 → save-album-url

电子版完成页仅显示二维码及 90 秒返回倒计时，失败可重试。电子版不调用打印机、不扣纸、不调用 print-notify / print-complete，也不播放打印语音。

取得相册二维码不代表原图已转存完成。相册准备中由小程序展示，App 不再次要求付款；倒计时不影响购买权益。

旧版本兼容

• 旧 App 未传 purchase_mode：新后端默认 print。
• 新 App 遇到旧报价响应：保留打印，禁用缺失电子价的电子版。
• 旧打印支付响应同时缺少模式和金额时，保留原支付 URL 与报价显示；这种订单的完成消息允许省略模式。
• 电子版不得降级为打印版，新模式订单完成消息必须显式携带匹配模式。

验证边界

自动化验证使用本地网络拦截响应，覆盖正价购买、零价/未配置禁用、待付款不跳转、嵌套推送、重复/错误消息、预选失效、业务错误恢复及相册重试。真实微信支付、员工优惠、设备打印、FaceBox 转存和小程序下载仍需按后端文档进行部署后联调。