xionggeshop/addons/shopro_huifu/README.md

Shopro 汇付支付插件

汇付斗拱小程序微信支付 + 延时分账，可独立安装/启用/禁用/卸载。

安装

1. 将整个 addons/shopro_huifu/ 目录上传到服务器（截图站点 xgsc.gynhc.com 需同步部署）
2. 确认存在 Shopro_huifu.php（FastAdmin 识别用）和 ShoproHuifu.php（自动加载别名，二者缺一不可）
3. 后台 插件管理 → 本地插件，应出现 Shopro汇付支付，点击安装并启用
4. 也可 本地安装 上传 zip 包（zip 根目录需含 shopro_huifu/info.ini）
5. SDK 已 bundled 于 library/sdk/extracted/，也可 composer require huifurepo/dg-php-sdk:^2.0.30

配置

页面	路径
汇付支付配置	系统管理 → 商城配置 → 汇付支付配置
分账设置	系统管理 → 商城配置 → 支付分账 → 分账设置
分账接收方/规则/记录	系统管理 → 商城配置 → 支付分账 → 对应子菜单

直达链接：/admin/shopro_huifu/config、/admin/shopro/split/config

关键项：

• miniprogram_channel=huifu 切换小程序走汇付
• split_mode=huifu + delay_acct_enable=1 开启延时分账
• split_timing 三选一：payed / confirm / finish

通知地址

• 支付（推荐）：https://xgsc.gynhc.com/addons/shopro/pay/notifyhuifu
• 退款：https://xgsc.gynhc.com/addons/shopro/pay/notifyhuifurefund/platform/wxMiniProgram

务必 HTTPS 且公网可达。下单时会把 notify_url 写入汇付；请固定站点根地址：

INSERT INTO fa_shopro_huifu_config (`name`,`value`,`group`,`description`) VALUES
('site_base_url','https://xgsc.gynhc.com','basic','站点公网HTTPS根地址'),
('pay_notify_url','https://xgsc.gynhc.com/addons/shopro/pay/notifyhuifu','pay','支付通知URL')
ON DUPLICATE KEY UPDATE `value`=VALUES(`value`);

支付结果页也会调用 pay/syncHuifu 主动查单，不依赖 crontab；但异步 notify 仍应配置正确。

汇付控台/Webhook 与接口 notify_url 是两套协议，不要混用。

定时任务

# 每 1-3 分钟：查单补偿（通知丢失时兜底）
php think shopro_huifu:compensate

# 单笔补救（汇付商户订单号 = req_seq_id）
php think shopro_huifu:compensate --order_sn=2026111111220944091001100

php think shopro_huifu:split-retry

安装验证

php think shopro_huifu:verify

检查插件文件、数据表、配置项、后台菜单、启用状态。

一键安装/修复（服务器必跑）

仅上传 addons/shopro_huifu 后，插件中心显示已安装但 verify 大量 FAIL 时：

php think shopro_huifu:install

会自动：复制后台文件 → 建表 → 扩展 shopro_order.pay_type → 写菜单 → 启用插件。

若 prepay 报 Data truncated for column 'pay_type'，说明订单表未升级，执行：

php think shopro_huifu:repair-menu

然后：

php think shopro_huifu:verify

执行后退出后台重新登录。

全国联行号导入

进件表单「开户银行支行」会先查数据库表 shopro_huifu_bank_branch，再回退到 data/bank_branches.json 种子库。全国约 15 万条联行号需导入数据库后，搜索才能覆盖全国。

# 1) 导入内置种子（约 120 条，主要城市 + 贵州/广东，无需下载）
php think shopro_huifu:import-bank-branch --seed

# 2) 下载 CSV 并导入（默认 main：主要省市 + 四大行/农商行，约5万条）
php think shopro_huifu:import-bank-branch --download

# 3) 手动下载后导入（下载失败时用）
# https://hf-mirror.com/datasets/gweesin/CNAPS/resolve/main/cnaps.csv
php think shopro_huifu:import-bank-branch --file=addons/shopro_huifu/data/cnaps.csv

# 全国全量约15万（一般不需要）
php think shopro_huifu:import-bank-branch --file=addons/shopro_huifu/data/cnaps.csv --preset=full

# 校验库内重复
php think shopro_huifu:import-bank-branch --check

# 试跑（不写库）
php think shopro_huifu:import-bank-branch --file=addons/shopro_huifu/data/cnaps.csv --limit=100 --dry-run

导入完成后，小程序/后台搜索支行即可自动匹配联行号；仍搜不到时可手动填写 12 位联行号。

微信发货同步配合

支付成功通知会优先落库微信 transaction_id（wx_response.transaction_id / out_trans_id），供 shopro_wechat_trade 插件调用 upload_shipping_info。汇付流水仍保存在 shopro_huifu_pay_ext.hf_seq_id。

支付故障排查

报错	处理
openssl_sign / 验签失败	重新粘贴汇付商户私钥、汇付公钥（纯 base64 或完整 PEM 均可）
Data truncated for column 'pay_type'	php think shopro_huifu:repair-menu 扩展订单表 ENUM
汇付未返回 pay_info	见下方 checklist
RESP_SIGN_VERIFY_UNDO	env 与凭证环境不一致，或汇付公钥/商户私钥配错；跑 php think shopro_huifu:test-pay
RESP_SIGN_VERIFY_FAILED	汇付RSA公钥不是平台公钥（误填商户公钥）
22000005 入驻信息配置有误	跑 php think shopro_huifu:probe-wechat；核对 huifu_id/sys_id 层级、汇付侧 wx_applet_app_id、pay_scene(01线上/02线下或留空)
00000100 + trans_stat=P	汇付下单受理成功（用户支付中），非失败；插件需解析 pay_info 给小程序 requestPayment
prepay 返回 code:0, msg:""	旧版 Pay.php 会吞掉真实错误；请上传最新 Pay.php 后重试，响应 msg 会显示具体原因
汇付已成功、商城仍待付款	见下方「支付成功无回调」

pay_info 缺失 checklist（$huifu-pay-integration）：

1. 环境一致：后台 env=测试 必须配测试 sys_id/商户号；env=生产 配生产凭证（不能混用）
2. 网关：php think shopro_huifu:test-pay 确认 SDK PROD_MODE 与 env 一致
3. 小程序：sub_appid = 商城配置里 wxMiniProgram.app_id；sub_openid 须来自同一小程序授权
4. 通道：汇付控台已开通微信小程序支付；若填了 channel_no 必须同时填 pay_scene
5. 日志：runtime/log 搜索 [shopro_huifu] missing-pay_info 查看 resp_code/trans_stat

支付成功无回调（$huifu-pay-integration）

按 Skill 口径：前端 requestPayment 成功 ≠ 支付终态，必须以异步 notify_url 或查单补偿为准。

步骤	操作
1. 立即补救	php think shopro_huifu:compensate --order_sn=汇付商户订单号
2. 查日志	runtime/log 搜 [shopro_huifu] notify / notify verify fail / order not found
3. 验 URL	浏览器/ curl 访问 https://xgsc.gynhc.com/addons/shopro_huifu/pay/notify/platform/wxMiniProgram 应返回空 200（GET 无 sign 会 500 也正常，说明路由可达）
4. 固定 HTTPS	写入 pay_notify_url（见上方 SQL），避免 request()->root() 生成 http 或内网域名
5. 定时补偿	crontab 每 1-3 分钟：php think shopro_huifu:compensate

常见根因：

• notify 未到达：防火墙/WAF 拦截汇付 POST；notify_url 非 HTTPS 或域名不可公网访问
• 验签失败：notify verify fail — 汇付公钥错误；或 form 回调里 Base64 签名的 + 被 PHP 转成空格（需更新 HuifuNotifyParser.php 从原始 body 解析）
• 有 notify 但订单仍待付款：resp_data 可能是账务通知（acct_stat=I）无 trans_stat=S — 新版会在验签通过后查单二次确认
• payment_json 超长：Data too long for column 'payment_json' — Shopro 该列为 varchar(2500)，插件已改为写入精简快照，完整报文见 shopro_huifu_notify_log.payload
• 订单号对不上：汇付 req_seq_id 与商城 order_sn 不一致 — 日志 notify order not found；用 --order_sn=汇付侧商户订单号 补偿
• 回包不正确：必须 HTTP 200 + 响应体 RECV_ORD_ID_{req_seq_id}，否则汇付会重试

卸载

禁用插件会自动将 miniprogram_channel 回退为 yansongda。存在未完结汇付订单时卸载会被拦截。