c4d60a25bd
feat(shopro_huifu): 新增股份制银行和城商行联行号导入功能 - 添加 joint 预设选项，支持导入招商、浦发、民生等股份制银行及常用城商行 - 更新命令行选项，增加 --preset=joint 参数说明 - 重构联行号导入过滤器，添加股份制银行关键词配置 - 优化 README 文档，更新导入命令使用说明 ```
170 行
8.1 KiB
Markdown
170 行
8.1 KiB
Markdown
# 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` 写入汇付；请固定站点根地址：
|
||
|
||
```sql
|
||
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` 是两套协议，不要混用。
|
||
|
||
## 定时任务
|
||
|
||
```bash
|
||
# 每 1-3 分钟：查单补偿（通知丢失时兜底）
|
||
php think shopro_huifu:compensate
|
||
|
||
# 单笔补救（汇付商户订单号 = req_seq_id）
|
||
php think shopro_huifu:compensate --order_sn=2026111111220944091001100
|
||
|
||
php think shopro_huifu:split-retry
|
||
```
|
||
|
||
## 安装验证
|
||
|
||
```bash
|
||
php think shopro_huifu:verify
|
||
```
|
||
|
||
检查插件文件、数据表、配置项、后台菜单、启用状态。
|
||
|
||
## 一键安装/修复（服务器必跑）
|
||
|
||
仅上传 `addons/shopro_huifu` 后，插件中心显示已安装但 verify 大量 FAIL 时：
|
||
|
||
```bash
|
||
php think shopro_huifu:install
|
||
```
|
||
|
||
会自动：复制后台文件 → 建表 → 扩展 `shopro_order.pay_type` → 写菜单 → 启用插件。
|
||
|
||
若 prepay 报 `Data truncated for column 'pay_type'`，说明订单表未升级，执行：
|
||
|
||
```bash
|
||
php think shopro_huifu:repair-menu
|
||
```
|
||
|
||
然后：
|
||
|
||
```bash
|
||
php think shopro_huifu:verify
|
||
```
|
||
|
||
执行后退出后台重新登录。
|
||
|
||
## 全国联行号导入
|
||
|
||
进件表单「开户银行支行」会先查数据库表 `shopro_huifu_bank_branch`，再回退到 `data/bank_branches.json` 种子库。全国约 15 万条联行号需导入数据库后，搜索才能覆盖全国。
|
||
|
||
```bash
|
||
# 1) 导入内置种子（约 120 条，主要城市 + 贵州/广东，无需下载）
|
||
php think shopro_huifu:import-bank-branch --seed
|
||
|
||
# 2) 下载 CSV 并导入（默认 main：四大行/农商行，约5万条）
|
||
php think shopro_huifu:import-bank-branch --download
|
||
|
||
# 3) 追加导入股份制/常用城商行（招商/浦发/民生等，约3万条，增量不清库）
|
||
php think shopro_huifu:import-bank-branch --file=addons/shopro_huifu/data/cnaps.csv --preset=joint
|
||
|
||
# 4) 手动下载后导入（下载失败时用）
|
||
# 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`。存在未完结汇付订单时卸载会被拦截。
|