📅 整理日期：2026-04-30
📦 适用版本：商赢龙腾 10.1（建议使用 **2026年1月发布的新版**）
⚠️ 25年11月拉取的 10.1 版本存在已知 bug，务必升级到 2601 新版

目录

  1. 版本升级注意事项
  2. H5码牌配置
  3. 分账配置
  4. 商铺子商户号配置
  5. 悦音箱（语音播报）配置
  6. 踩坑经验汇总

1. 版本升级注意事项

版本 说明
**2511 版本**（25年11月） ⚠️ 存在多个 bug，不建议直接使用
**2601 版本**（26年1月） ✅ 修复了已知 bug，推荐使用
**2511 版本已知问题：**
问题 影响
—— ——
海燕服务 bug 服务运行异常
order 包 bug 退货退款成功但前端报错
H5码牌 baseurl 错误 扫码无商铺名称
H5商户号不生效 H5码牌取小程序商户号

🔔 **强烈建议**：部署前先确认版本为 2601，避免排查已知问题浪费时间。

2. H5码牌配置

2.1 基本配置

配置项 值 说明
**主配置值** 域名 如 https://pay.example.com
**次配置值** /gwzx-h5pay/index.html?gid= H5支付入口路径（Nginx无特殊配置时使用默认值）

2.2 前端文件部署

H5码牌前端文件需部署在 **两个位置**，且保持一致：

部署位置 路径 内容
**海燕服务端** SERVICE\data\gwzx-h5pay-front\ index.html、image/、libs/、README.md
**Nginx 端** nginx\gwzx-h5pay-front\ index.html、image/、libs/、README.md

⚠️ 两处的 index.html 必须保持同步，修改后需确认两边文件日期一致。

2.3 ⚠️ 踩坑：扫码后不显示商铺名称

**现象：** 扫H5码牌后，页面打开但商铺名称为空。
**原因：** 两个 index.html 中的 **baseurl 配置不正确**。
**排查步骤：**

  1. 检查海燕服务端：SERVICE\data\gwzx-h5pay-front\index.html 中的 baseurl
  2. 检查Nginx端：nginx\gwzx-h5pay-front\index.html 中的 baseurl
  3. 确认两处 baseurl 均指向正确的域名地址
    **解决方案：**
  • ✅ 2601 版本已修复此问题，升级后自动正确
  • 2511 版本需手动修正两处 baseurl

3. 分账配置

3.1 开启分账（海燕 YAML 配置）

在海燕中配置支付参数，**必须将 netpay.settle 设为 true** 才能开启分账功能。
**YAML 配置模板：**

1
2
3
4
5
6
7
8
9
10
11
12
13
14
netpay:
settle: true # ⭐ 分账总开关（必须为 true）
config:
sha256Key: <分账签名密钥> # 分账签名密钥
apiUrl: https://api-mop.chinaums.com/v1/netpay/ # 网商支付接口地址
appId: <应用ID> # 应用ID
msgSrc: WWW.CCXYSGYL.COM # 消息来源
msgSrcId: <消息源ID> # 如 15WM
notifyUrl: <支付回调地址> # 支付结果通知地址
returnUrl: <支付返回页面> # 支付完成跳转页面
payChannel: '01' # 支付渠道
url:
host: <域名> # 如 https://yl.kldtoys.com
tid: <终端ID> # 终端号

**关键参数说明：**

参数 必填 说明
netpay.settle ✅ 分账总开关，必须为 true
netpay.config.sha256Key ✅ 分账签名密钥
netpay.config.apiUrl ✅ 网商支付接口，一般为固定值
netpay.config.appId ✅ 应用ID
netpay.config.msgSrc ✅ 消息来源标识
netpay.config.msgSrcId ✅ 消息源ID
netpay.config.notifyUrl ✅ 支付回调地址（需外网可访问）
netpay.config.returnUrl ✅ 支付完成后用户跳转页面
netpay.payChannel ✅ 支付渠道，'01' 为默认
url.host ✅ 项目域名
tid ✅ 终端号

💡 **提示**：notifyUrl 必须是外网可访问的地址，否则无法接收支付结果回调。

4. 商铺子商户号配置

4.1 配置位置

商铺详情 → 支付信息，包含两个字段：

字段 用途
**小程序商户号** 小程序支付使用的商户号
**H5商户号** H5码牌支付使用的商户号

4.2 ⚠️ 踩坑：2511版本H5商户号不生效

**现象：** H5码牌和小程序都只读取「小程序商户号」，「H5商户号」填了不生效。
**版本差异：**

版本 H5码牌取值 小程序取值
**2511** ⚠️ 小程序商户号（bug） 小程序商户号
**2601** ✅ H5商户号（独立） 小程序商户号
**配置示例：**
  • 商铺：0000-锦绣商业测试
  • H5商户号：898220100004729
  • 快速收银：已开启

    🔔 **注意**：升级到 2601 版本后，H5码牌和小程序各自独立取对应商户号，需分别配置。

5. 悦音箱（语音播报）配置

5.1 配置位置

在 **mediaconfig** 下进行悦音箱参数配置。

5.2 配置参数

参数 说明 示例/备注
cycleNum 打印联数 2
**pushTmplId** ⭐ **悦音箱推送实现ID** 需填写正确值（非占位符）
iotSendMessageUrl IoT消息发送接口地址 https://…
postoneAppId 应用ID —
postoneAppKey 应用密钥 —

⚠️ **重要**：pushTmplId 为关键参数，必须填写正确的悦音箱实现ID。

5.3 日志判断

**✅ 配置正确 — 成功日志：**

1
2
[INFO] [c.c.e.g.o.biz.cscanb.impl.MiniIotMessageService] - [op:sendMessageForIot] result = {"respDesc":"发送成功","respCode":"AU000000"}
[INFO] [c.c.e.g.o.biz.cscanb.task.IotPushMsgTaskRunnable] - rs = Response(respCode=SUCCESS, respDesc=响应成功, resultCode=SUCCESS, resultDesc=响应成功), responCode = SUCCESS

**❌ 配置错误 — 失败日志：**

1
[ERROR] [c.c.e.g.o.biz.cscanb.impl.MiniIotMessageService] - [op:sendMessageForIot] send iot err, result={"respCode":"SUCCESS","respDesc":"响应成功","resultCode":"99999","resultDesc":"缺少必要的参数,或参数为空!"}

⚠️ **注意区分**：失败时外层 respCode=SUCCESS 仅代表通信成功，实际业务失败需看 resultCode：

  • resultCode=99999 → 配置参数错误
  • resultCode=SUCCESS → 业务真正成功

5.4 ⚠️ 踩坑：报文成功但音箱不播报

**现象：** 日志显示 resultCode=SUCCESS “发送成功”，但悦音箱没有播报声音。
**排查步骤：**

步骤 操作 说明
1 检查配置参数 确认 pushImplId、postoneAppId、postoneApoKey 等值是否正确
2 检查配置是否生效 保存后可能未即时生效
3 ⚠️ 缓存问题 配置下发可能有缓存导致延时
4 ✅ **重新编辑保存** 保存成功后，**重新编辑再保存一次**，强制刷新缓存
5 联系悦音箱方老师 以上步骤都无效时，联系悦音箱厂商技术支持

💡 **经验**：缓存是最常见的原因，”保存 → 重新编辑 → 再保存” 可解决大部分不播报问题。

6. 踩坑经验汇总

序号 问题 版本 原因 解决方案
1 H5码牌扫码无商铺名称 2511 index.html baseurl 不正确 升级到 2601 或手动修正两处 baseurl
2 退款成功但前端报错 2511 order 包 bug 升级 order 包到 2601 版本
3 H5商户号不生效 2511 H5码牌取小程序商户号 升级到 2601 版本
4 分账不生效 通用 netpay.settle 未设为 true YAML 配置 netpay.settle: true
5 悦音箱配置报错 99999 通用 pushImplId 等关键参数为占位符 填写正确的参数值
6 悦音箱报文成功但不播报 通用 配置缓存未刷新 保存后重新编辑再保存一次

附录：版本升级 Checklist

部署 10.1 版本时，请按以下清单逐项确认：

  • 确认版本为 **2601**（非 2511）
  • 海燕服务已更新
  • order 包已更新
  • H5码牌前端文件（海燕端 + Nginx端）已同步部署
  • 两处 index.html baseurl 已确认正确
  • 分账配置 netpay.settle: true 已设置
  • 分账相关参数（sha256Key、appId 等）已正确填写
  • 商铺 H5商户号和小程序商户号已分别配置
  • 悦音箱 mediaconfig 参数已正确配置（非占位符）
  • 悦音箱配置保存后已重新编辑保存一次（刷新缓存）
  • 测试：H5码牌扫码 → 支付 → 语音播报 全流程验证