27c8fbf72c
feat(shopro): 实现汇付混合分账功能支持按人区分通道和钱包结算 - 新增汇付延时分账混合模式：已进件用户走支付通道，未进件用户入钱包 - 添加 shouldSettleHuifuPerReceiver 方法判断是否使用混合结算 - 实现 settleOrderHybridHuifuGatewayAndWallet 方法处理混合分账逻辑 - 新增 collectGatewaySplitUserIds 方法收集分账用户ID列表 - 添加 markCommissionOrderSettledIfDone 和 markRegionalOrderSettledIfDone 辅助方法 fix(shopro_huifu): 优化延时分账确认前置拦截逻辑 - 修复 getDelayTransBlockReason 方法参数传递问题 - 新增 getNonDelayAcctBlockReason 方法检查交易非延迟入账状态 - 添加 2300004 错误码拦截实时入账交易的延迟分账操作 docs(shopro_wechat_trade): 更新命令行工具文档 - 添加 resync-shipping 命令用于重新同步指定订单的配送信息 - 更新重传说明文档，明确 retry-failed 不会重试已成功的记录 ```
102 行
4.6 KiB
Markdown
102 行
4.6 KiB
Markdown
# Shopro 微信交易合规插件
|
||
|
||
微信小程序购物订单 + 发货信息同步（`upload_shipping_info` / `notify_confirm_receive`）。
|
||
|
||
## 运营前置（必做）
|
||
|
||
在小程序后台（AppID 与商城配置一致）完成：
|
||
|
||
1. 签署 **订单中心授权协议**（否则 `update_order_detail_path` 报错 `10060034`）
|
||
2. 开通 **发货信息管理服务**（支付与交易 → 订单管理 / 购物订单）
|
||
3. 满足实物交易类小程序运营规范
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
# 上传 addons/shopro_wechat_trade 后（推荐 SSH，不要只靠后台点启用）
|
||
php think shopro_wechat_trade:install
|
||
php think shopro_wechat_trade:verify
|
||
```
|
||
|
||
后台：**系统管理 → 商城配置 → 微信交易合规**
|
||
|
||
### 启用报 Permission denied / 过一阵又变关闭
|
||
|
||
常见两类原因：
|
||
|
||
1. **目录不可写**（截图里 `runtime/cache/... Permission denied`）
|
||
后台「启用插件」会写 `info.ini`、`application/extra/addons.php`、`public/assets/js/addons.js` 并清缓存。PHP 运行用户（宝塔多为 `www`）必须可写：
|
||
- `runtime/`（含 `cache/`、`log/`）
|
||
- `addons/shopro_wechat_trade/info.ini`
|
||
- `application/extra/addons.php`
|
||
- `public/assets/js/addons.js`
|
||
|
||
```bash
|
||
cd /www/wwwroot/xgsc.gynhc.com
|
||
chown -R www:www runtime addons application/extra public/assets/js/addons.js
|
||
chmod -R u+rwX runtime
|
||
php think shopro_wechat_trade:install
|
||
```
|
||
|
||
2. **代码部署覆盖 `info.ini`**
|
||
仓库里若 `state = 0`，每次 git/rsync 全量同步会把线上已启用状态盖回关闭。本仓库默认 `state = 1`；若你方部署脚本会覆盖 `addons/*/info.ini`，请在服务器保留 `state = 1` 或部署后执行 `php think shopro_wechat_trade:install`。
|
||
|
||
### 后台提示「文件冲突」
|
||
|
||
启用时若提示与 `application/admin/.../shopro_wechat_trade/*` 冲突，属正常：插件要把后台菜单/页面复制到主工程。仓库已含这些文件时选 **继续操作** 即可；更稳的是只用 CLI `shopro_wechat_trade:install` 修复，不必反复在插件中心开关。
|
||
|
||
## 汇付配合
|
||
|
||
若使用汇付小程序支付，需同步部署最新 `shopro_huifu`（支付通知会落库微信 `transaction_id`）。
|
||
|
||
## CLI
|
||
|
||
```bash
|
||
php think shopro_wechat_trade:init-path
|
||
php think shopro_wechat_trade:backfill
|
||
php think shopro_wechat_trade:retry-failed
|
||
php think shopro_wechat_trade:resync-shipping --sn=订单号
|
||
|
||
# 指定订单：商城确认收货 + 微信 confirm（截图里分账 FREEZE 的单可批量处理）
|
||
php think shopro_wechat_trade:confirm-orders --sn=202608500438103091004500,202606584688620091002100
|
||
# 商城已是「已收货」、只补微信：
|
||
php think shopro_wechat_trade:confirm-orders --sn=订单号 --skip-mall
|
||
# 自提/到店：未发货会自动先触发自提发货(logistics_type=4)，再商城确认+微信同步
|
||
php think shopro_wechat_trade:confirm-orders --sn=202606584688620091002100
|
||
```
|
||
|
||
## 微信发货一律按自提
|
||
|
||
后台 **微信交易合规 → 微信发货一律自提**（`shipping_force_self_pickup`，默认开启）：
|
||
|
||
- 调用 `upload_shipping_info` 时固定 **`logistics_type = 4`（用户自提）**
|
||
- 不再要求快递单号/快递公司，用订单号作 `tracking_no`
|
||
- **不改变**商城订单的配送方式（快递单仍可在后台照常发货）
|
||
|
||
已同步过「快递」的旧单若需按自提重传：`php think shopro_wechat_trade:resync-shipping --sn=订单号`（`retry-failed` 不会重试已是 success 的记录）。
|
||
|
||
已有库可执行：
|
||
|
||
```sql
|
||
INSERT IGNORE INTO fa_shopro_wechat_trade_config (`name`, `value`, `group`, `description`) VALUES
|
||
('shipping_force_self_pickup', '1', 'basic', '微信 upload_shipping_info 一律按用户自提(logistics_type=4)');
|
||
```
|
||
|
||
## 触发点
|
||
|
||
- `order_send_after` → 异步 `upload_shipping_info`
|
||
- `order_confirm_after`（全部 item 已收货）→ `notify_confirm_receive`（须已有 shipping 同步成功；`received_time` 为秒级时间戳）
|
||
|
||
微信错误 **47001 data format error** 多为确认收货 JSON 格式不符（勿用 RFC3339 字符串作为 `received_time`）。
|
||
|
||
## 小程序跳转
|
||
|
||
默认订单详情路径：`pages/order/detail?id=${商品订单号}`（微信官方示例用 `id` 传商户订单号）
|
||
|
||
### 安装报 10060035「无效的路径」
|
||
|
||
1. **先发布小程序**：微信会校验 path 是否存在于**当前线上版或提审版**代码中；未发布 `pages/order/detail` 时会报此错
|
||
2. **path 格式**：`pages/order/detail?id=${商品订单号}`（不要前导 `/`）
|
||
3. 发布后再执行：`php think shopro_wechat_trade:init-path`
|
||
4. 或在小程序后台 **支付与交易 → 订单管理** 手动填写相同 path
|