feat: support electronic photo purchases and download completion

2026-09-15 10:51:38 +08:00
parent 712f6154bc
commit b1cdc1fe06
33 changed files with 1488 additions and 218 deletions
@@ -0,0 +1,39 @@
+# 打印版 / 电子版：App 对接摘要
+
+更新：2026-09-14。以后端交付的 [OSCAR_PHOTO_PURCHASE.md](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`；预选失效等查询错误关闭支付弹框、刷新报价，不继续使用旧链接。
+
+## 完成与相册
+
+```text
+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 转存和小程序下载仍需按后端文档进行部署后联调。