# 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`。存在未完结汇付订单时卸载会被拦截。