feat(huifu): 支持汇付进件通过后更换结算银行卡

- 用户端及后台管理端新增更换结算卡接口与页面交互
- 服务层实现换卡核心逻辑、参数校验及汇付接口调用
- 增加换卡异步通知处理与定时轮询补偿以同步审核状态
- 完善进件状态网关,补充换卡审核状态及驳回原因等字段
这个提交包含在:
可乐加冰
2026-11-15 00:52:59 +08:00
父节点 c264a7d30c
当前提交 abc40ef2a9
共有 19 个文件被更改,包括 1058 次插入 和 59 次删除

查看文件

@@ -91,6 +91,12 @@ class HuifuOnboardAdminView
'can_submit_huifu' => ($data['onboard_status'] ?? '') === 'draft',
'can_retry_huifu' => in_array($data['onboard_status'] ?? '', ['rejected', 'failed'], true),
'can_poll' => !in_array($data['onboard_status'] ?? '', ['draft', 'approved'], true),
'can_modify_card' => ($data['onboard_status'] ?? '') === 'approved' && !empty($data['huifu_id'])
&& (($payload['_card_modify']['status'] ?? '') !== 'pending'),
'card_modify_pending' => ($payload['_card_modify']['status'] ?? '') === 'pending',
'card_modify_reject_reason' => (string) (($payload['_card_modify']['status'] ?? '') === 'rejected'
? ($payload['_card_modify']['reject_reason'] ?? '')
: ''),
];
}
@@ -550,6 +556,7 @@ class HuifuOnboardAdminView
return null;
}
$form = array_merge(self::defaultFormData(), $payload);
unset($form['_card_modify']);
foreach ([
'id_card_front_url', 'id_card_back_url', 'bank_card_url', 'license_url',
'legal_id_front_url', 'legal_id_back_url', 'account_permit_url',

查看文件

@@ -0,0 +1,114 @@
<?php
namespace addons\shopro_huifu\library\onboard;
use addons\shopro_huifu\library\SdkLoader;
/**
* 用户业务入驻修改:仅更换结算卡(不改结算/取现费率)
*/
class HuifuOnboardBusiModify
{
protected $sdk;
public function __construct(HuifuOnboardSdk $sdk = null)
{
$this->sdk = $sdk ?: new HuifuOnboardSdk();
}
public function modifyCard($huifuId, array $form, array $fileMap)
{
SdkLoader::requireRequest('V2UserBusiModifyRequest.php');
$meta = $this->sdk->newReqMeta();
$request = new \BsPaySdk\request\V2UserBusiModifyRequest();
$request->setHuifuId($huifuId);
$request->setReqSeqId($meta['req_seq_id']);
$request->setReqDate($meta['req_date']);
$cardInfo = self::buildCardInfo($form);
$fileList = self::buildFileList($form, $fileMap);
$extend = [
'card_info' => json_encode($cardInfo, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
'async_return_url' => $this->sdk->getOnboardNotifyUrl(),
];
if ($fileList) {
$extend['file_list'] = json_encode($fileList, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
}
$request->setExtendInfo($extend);
$result = $this->sdk->getClient()->postRequest($request);
$data = $this->sdk->getClient()->parseResponse($result);
$applyNo = (string) ($data['apply_no'] ?? ($data['apply_id'] ?? ''));
return [
'req_date' => $meta['req_date'],
'req_seq_id' => $meta['req_seq_id'],
'apply_no' => $applyNo,
'resp' => $data,
];
}
public static function buildCardInfo(array $form)
{
// 系统 bank_account_type:0=对私,1=对公
// 汇付 card_type:0=对公,1=对私法人,2=对私非法人
$bankAccountType = (string) ($form['bank_account_type'] ?? '0');
$cardType = $bankAccountType === '1' ? '0' : '1';
$accountType = $form['account_type'] ?? 'indv';
$cardName = $form['card_name'] ?? '';
if ($accountType === 'indv') {
$cardName = $form['name'] ?? $cardName;
} elseif ($bankAccountType === '0') {
$cardName = $form['legal_name'] ?? $cardName;
}
$cardInfo = [
'card_type' => $cardType,
'card_name' => $cardName,
'card_no' => $form['card_no'],
'prov_id' => $form['prov_id'],
'area_id' => HuifuOnboardAreaHelper::toHuifuCityCode($form['area_id'] ?? ''),
'mp' => $form['mp'] ?? '',
];
if (!empty($form['branch_code'])) {
$cardInfo['branch_code'] = $form['branch_code'];
}
if (!empty($form['branch_name'])) {
$cardInfo['branch_name'] = $form['branch_name'];
}
if ($cardType === '1') {
$cardInfo['cert_type'] = '00';
$cardInfo['cert_no'] = $form['cert_no'];
$cardInfo['cert_validity_type'] = $form['cert_validity_type'];
$cardInfo['cert_begin_date'] = $form['cert_begin_date'];
if (($form['cert_validity_type'] ?? '') === '0' && !empty($form['cert_end_date'])) {
$cardInfo['cert_end_date'] = $form['cert_end_date'];
}
}
return $cardInfo;
}
public static function buildFileList(array $form, array $fileMap)
{
$bankAccountType = (string) ($form['bank_account_type'] ?? '0');
$cardType = $bankAccountType === '1' ? '0' : '1';
$fileList = [];
if (!empty($fileMap['F13'])) {
$fileList[] = [
'file_type' => 'F13',
'file_id' => $fileMap['F13'],
'file_name' => 'bank_card.jpg',
];
}
if ($cardType === '0' && !empty($fileMap['F08'])) {
$fileList[] = [
'file_type' => 'F08',
'file_id' => $fileMap['F08'],
'file_name' => 'account_permit.jpg',
];
}
return $fileList;
}
}

查看文件

@@ -118,11 +118,26 @@ class HuifuOnboardGate
// 仅历史 draft 残留时提示等待(正常已改为用户提交直连汇付)
$awaitAdmin = $required && $row && $row['onboard_status'] === Onboard::STATUS_DRAFT
&& in_array($agentStatus, ['pending', 'needinfo', 'reject'], true);
$cardModifyPending = false;
$cardModifyReject = '';
$canModifyCard = false;
if ($row && $row['onboard_status'] === Onboard::STATUS_APPROVED && $required) {
$payload = json_decode($row['payload'] ?? '', true);
$meta = is_array($payload) ? HuifuOnboardService::getCardModifyMeta($payload) : [];
$cardModifyPending = ($meta['status'] ?? '') === 'pending';
if (($meta['status'] ?? '') === 'rejected') {
$cardModifyReject = (string) ($meta['reject_reason'] ?? '');
}
$canModifyCard = !$cardModifyPending && !empty($row['huifu_id']);
}
if (!$row) {
return [
'required' => $required,
'can_submit' => $canSubmit,
'can_save_draft' => $canSaveDraft,
'can_modify_card' => false,
'card_modify_pending' => false,
'card_modify_reject_reason' => '',
'await_admin' => false,
'audit_first' => false,
'status' => null,
@@ -135,12 +150,17 @@ class HuifuOnboardGate
'required' => $required,
'can_submit' => $canSubmit,
'can_save_draft' => $canSaveDraft,
'can_modify_card' => $canModifyCard,
'card_modify_pending' => $cardModifyPending,
'card_modify_reject_reason' => $cardModifyReject,
'await_admin' => $awaitAdmin,
'audit_first' => false,
'status' => $row['onboard_status'],
'huifu_id' => $row['huifu_id'] ? substr($row['huifu_id'], 0, 4) . '****' . substr($row['huifu_id'], -4) : '',
'reject_reason' => $row['reject_reason'] ?? '',
'apply_no' => $row['apply_no'] ?? '',
'role_type' => $row['role_type'] ?? $roleType,
'role_ref_id' => intval($row['role_ref_id'] ?? $roleRefId),
'draft' => HuifuOnboardAdminView::clientFormFromRow($row),
];
}

查看文件

@@ -13,6 +13,7 @@ class HuifuOnboardService
protected $basic;
protected $basicEnt;
protected $busi;
protected $busiModify;
protected $query;
protected function sdk()
@@ -23,6 +24,7 @@ class HuifuOnboardService
$this->basic = new HuifuOnboardBasicIndv($this->sdk);
$this->basicEnt = new HuifuOnboardBasicEnt($this->sdk);
$this->busi = new HuifuOnboardBusiOpen($this->sdk);
$this->busiModify = new HuifuOnboardBusiModify($this->sdk);
$this->query = new HuifuOnboardQuery($this->sdk);
}
return $this->sdk;
@@ -230,23 +232,382 @@ class HuifuOnboardService
return $fileMap;
}
/**
* 已通过进件后更换结算银行卡(V2UserBusiModify,仅 card_info)
*/
public function modifySettleCard($userId, $roleType, $roleRefId, array $formData, $onboardId = 0)
{
if (!HuifuOnboardGate::isOnboardRequired()) {
throw new \RuntimeException('当前未开启汇付进件');
}
if (!in_array($roleType, ['promoter', 'regional_agent'], true)) {
throw new \InvalidArgumentException('无效角色类型');
}
$onboardId = intval($onboardId);
if ($onboardId > 0) {
$row = Onboard::get($onboardId);
if (!$row || intval($row['user_id']) !== intval($userId)) {
throw new \InvalidArgumentException('进件记录不存在');
}
} else {
$row = Onboard::findByRole($userId, $roleType, $roleRefId);
}
if (!$row || $row['onboard_status'] !== Onboard::STATUS_APPROVED) {
throw new \RuntimeException('仅进件已通过时可更换结算卡');
}
if (empty($row['huifu_id'])) {
throw new \RuntimeException('缺少汇付商户号,无法更换结算卡');
}
$payload = json_decode($row['payload'] ?? '', true);
if (!is_array($payload)) {
$payload = [];
}
$cardModify = self::getCardModifyMeta($payload);
if (($cardModify['status'] ?? '') === 'pending') {
throw new \RuntimeException('结算卡更换审核中,请稍后再试');
}
$form = HuifuOnboardValidator::validateCardModify($formData, $payload);
$oldCard = preg_replace('/\s+/', '', (string) ($payload['card_no'] ?? ''));
$newCard = preg_replace('/\s+/', '', (string) ($form['card_no'] ?? ''));
try {
$this->sdk();
$fileMap = $this->uploadCardModifyPictures($form, $payload, $oldCard !== $newCard);
$result = $this->busiModify->modifyCard($row['huifu_id'], $form, $fileMap);
$resp = is_array($result['resp'] ?? null) ? $result['resp'] : [];
$applyNo = (string) ($result['apply_no'] ?? '');
$pending = $this->isCardModifyPending($resp, $applyNo);
if ($pending) {
$payload['_card_modify'] = [
'status' => 'pending',
'apply_no' => $applyNo,
'req_seq_id' => (string) ($result['req_seq_id'] ?? ''),
'req_date' => (string) ($result['req_date'] ?? ''),
'pending_form' => $this->cardFieldsOnly($form),
'reject_reason' => '',
'updated_at' => time(),
];
$row->payload = json_encode($payload, JSON_UNESCAPED_UNICODE);
$row->resp_snapshot = json_encode($resp, JSON_UNESCAPED_UNICODE);
$row->save();
return $row;
}
if (!$this->isCardModifySyncSuccess($resp)) {
$msg = (string) ($resp['resp_desc'] ?? '更换结算卡失败');
throw new \RuntimeException(HuifuOnboardError::translate($msg));
}
return $this->commitCardModifySuccess($row, $payload, $form, $resp);
} catch (\RuntimeException $e) {
throw $e;
} catch (\Throwable $e) {
$friendly = HuifuOnboardError::translate($e->getMessage());
Log::error('[shopro_huifu] card modify fail uid=' . $userId . ' id=' . $row['id'] . ' ' . $e->getMessage());
throw new \RuntimeException($friendly, 0, $e);
}
}
public function handleNotify(array $data)
{
$huifuId = trim((string) ($data['huifu_id'] ?? ''));
$applyNo = trim((string) ($data['apply_no'] ?? ''));
if ($huifuId === '') {
return false;
}
$query = Onboard::where('huifu_id', $huifuId);
if ($applyNo !== '') {
$query->where('apply_no', $applyNo);
$auditInfo = $data['audit_info'] ?? null;
if (is_string($auditInfo)) {
$auditInfo = json_decode($auditInfo, true) ?: [];
}
$row = $query->order('id desc')->find();
if (!is_array($auditInfo)) {
$auditInfo = [];
}
$applyNo = trim((string) ($data['apply_no'] ?? ($auditInfo['apply_no'] ?? '')));
$reqSeqId = trim((string) ($data['req_seq_id'] ?? ''));
$row = Onboard::where('huifu_id', $huifuId)->order('id desc')->find();
if (!$row) {
return false;
}
if ($this->tryApplyCardModifyNotify($row, $data, $auditInfo, $applyNo, $reqSeqId)) {
return true;
}
// 原进件审核:优先按 apply_no 精确匹配,避免误更新其他记录
if ($applyNo !== '') {
$byApply = Onboard::where('huifu_id', $huifuId)->where('apply_no', $applyNo)->order('id desc')->find();
if ($byApply) {
$row = $byApply;
}
}
$this->sdk();
$this->query->pollAndUpdate($row);
return true;
}
/**
* 补偿:扫描换卡 pending,查单后更新(不改 onboard_status)
*/
public function pollCardModifyPending($limit = 50)
{
$list = Onboard::where('onboard_status', Onboard::STATUS_APPROVED)
->where('payload', 'like', '%"_card_modify"%')
->limit($limit)
->select();
if (!$list || count($list) === 0) {
return 0;
}
$this->sdk();
$count = 0;
foreach ($list as $row) {
try {
$payload = json_decode($row['payload'] ?? '', true);
if (!is_array($payload)) {
continue;
}
$meta = self::getCardModifyMeta($payload);
if (($meta['status'] ?? '') !== 'pending') {
continue;
}
$applyNo = trim((string) ($meta['apply_no'] ?? ''));
if ($applyNo === '' || empty($row['huifu_id'])) {
continue;
}
$status = $this->query->queryApply($row['huifu_id'], $applyNo);
$this->applyCardModifyRemoteStatus($row, $payload, $meta, $status);
$count++;
} catch (\Throwable $e) {
Log::error('[shopro_huifu] card modify poll fail id=' . $row['id'] . ' ' . $e->getMessage());
}
}
return $count;
}
protected function uploadCardModifyPictures(array $form, array $stored, $cardChanged)
{
$fileMap = [];
$needBankPic = $cardChanged || empty($stored['bank_card_url']) || (!empty($form['bank_card_url']) && ($form['bank_card_url'] !== ($stored['bank_card_url'] ?? '')));
if ($needBankPic && !empty($form['bank_card_url'])) {
$fileMap['F13'] = $this->picture->uploadByUrl('F13', $form['bank_card_url']);
}
if ((string) ($form['bank_account_type'] ?? '0') === '1' && !empty($form['account_permit_url'])) {
$oldPermit = (string) ($stored['account_permit_url'] ?? '');
if ($form['account_permit_url'] !== $oldPermit || empty($oldPermit)) {
$fileMap['F08'] = $this->picture->uploadByUrl('F08', $form['account_permit_url']);
}
}
return $fileMap;
}
protected function isCardModifyPending(array $resp, $applyNo)
{
$applyNo = trim((string) $applyNo);
if ($applyNo === '') {
return false;
}
// 有申请单号且绑卡结果未明确成功 → 审核中
if ($this->cardBusinessSucceeded($resp)) {
return false;
}
return true;
}
protected function isCardModifySyncSuccess(array $resp)
{
$code = (string) ($resp['resp_code'] ?? '');
if (!in_array($code, ['00000000', '00', '0000'], true) && $code !== '') {
// parseResponse 成功时通常已是业务成功码;若无码但有 token_no 也视为成功
if (empty($resp['token_no']) && !$this->cardBusinessSucceeded($resp)) {
return false;
}
}
if ($this->cardBusinessFailed($resp)) {
return false;
}
return true;
}
protected function cardBusinessSucceeded(array $resp)
{
$list = $resp['resp_business'] ?? [];
if (is_string($list)) {
$list = json_decode($list, true) ?: [];
}
if (!is_array($list) || !$list) {
return false;
}
foreach ($list as $item) {
if (!is_array($item)) {
continue;
}
if ((string) ($item['type'] ?? '') === '1' && strtoupper((string) ($item['code'] ?? '')) === 'S') {
return true;
}
}
return false;
}
protected function cardBusinessFailed(array $resp)
{
$list = $resp['resp_business'] ?? [];
if (is_string($list)) {
$list = json_decode($list, true) ?: [];
}
if (!is_array($list)) {
return false;
}
foreach ($list as $item) {
if (!is_array($item)) {
continue;
}
if ((string) ($item['type'] ?? '') === '1' && strtoupper((string) ($item['code'] ?? '')) === 'F') {
return true;
}
}
return false;
}
protected function commitCardModifySuccess(Onboard $row, array $payload, array $form, array $resp = [])
{
foreach ($this->cardFieldsOnly($form) as $key => $val) {
$payload[$key] = $val;
}
unset($payload['_card_modify']);
$row->payload = json_encode($payload, JSON_UNESCAPED_UNICODE);
if ($resp) {
$row->resp_snapshot = json_encode($resp, JSON_UNESCAPED_UNICODE);
}
// 保持 approved,不改 apply_no
$row->save();
return $row;
}
protected function cardFieldsOnly(array $form)
{
$keys = [
'bank_account_type', 'card_no', 'card_name', 'branch_code', 'branch_name',
'prov_id', 'area_id', 'district_id', 'shopro_province_id', 'shopro_city_id', 'shopro_district_id',
'mp', 'mobile_no', 'legal_mobile', 'bank_card_url', 'account_permit_url',
// normalize 可能同步的证件字段(对私)
'cert_no', 'cert_validity_type', 'cert_begin_date', 'cert_end_date', 'name',
];
$out = [];
foreach ($keys as $key) {
if (array_key_exists($key, $form)) {
$out[$key] = $form[$key];
}
}
return $out;
}
protected function tryApplyCardModifyNotify(Onboard $row, array $data, array $auditInfo, $applyNo, $reqSeqId)
{
$payload = json_decode($row['payload'] ?? '', true);
if (!is_array($payload)) {
return false;
}
$meta = self::getCardModifyMeta($payload);
if (($meta['status'] ?? '') !== 'pending') {
return false;
}
$metaApply = trim((string) ($meta['apply_no'] ?? ''));
$metaReq = trim((string) ($meta['req_seq_id'] ?? ''));
$matched = false;
if ($applyNo !== '' && $metaApply !== '' && $applyNo === $metaApply) {
$matched = true;
} elseif ($reqSeqId !== '' && $metaReq !== '' && $reqSeqId === $metaReq) {
$matched = true;
}
if (!$matched) {
return false;
}
$auditStatus = strtoupper(trim((string) (
$auditInfo['audit_status']
?? $data['audit_status']
?? $data['apply_status']
?? ''
)));
$auditDesc = (string) (
$auditInfo['audit_desc']
?? $data['audit_desc']
?? $data['sub_resp_desc']
?? $data['resp_desc']
?? ''
);
if (in_array($auditStatus, ['Y', 'S', 'SUCCESS', 'APPROVED', '1', '02', '2'], true)) {
$pendingForm = is_array($meta['pending_form'] ?? null) ? $meta['pending_form'] : [];
$this->commitCardModifySuccess($row, $payload, $pendingForm, $data);
return true;
}
if (in_array($auditStatus, ['N', 'F', 'FAIL', 'FAILED', 'REJECTED', '3', '03', '-1'], true)) {
$payload['_card_modify'] = [
'status' => 'rejected',
'apply_no' => $metaApply,
'req_seq_id' => $metaReq,
'pending_form' => $meta['pending_form'] ?? [],
'reject_reason' => $auditDesc ?: '结算卡更换被驳回',
'updated_at' => time(),
];
$row->payload = json_encode($payload, JSON_UNESCAPED_UNICODE);
$row->resp_snapshot = json_encode($data, JSON_UNESCAPED_UNICODE);
$row->save();
return true;
}
// 审核中:保持 pending
$payload['_card_modify']['updated_at'] = time();
$row->payload = json_encode($payload, JSON_UNESCAPED_UNICODE);
$row->resp_snapshot = json_encode($data, JSON_UNESCAPED_UNICODE);
$row->save();
return true;
}
protected function applyCardModifyRemoteStatus(Onboard $row, array $payload, array $meta, array $status)
{
if (!$status) {
return;
}
$stat = strtoupper(trim((string) (
$status['audit_status']
?? $status['apply_status']
?? $status['status']
?? ''
)));
$desc = (string) ($status['audit_desc'] ?? $status['apply_desc'] ?? $status['resp_desc'] ?? '');
if (in_array($stat, ['Y', 'S', 'SUCCESS', 'APPROVED', '1', '02', '2'], true)) {
$pendingForm = is_array($meta['pending_form'] ?? null) ? $meta['pending_form'] : [];
$this->commitCardModifySuccess($row, $payload, $pendingForm, $status);
return;
}
if (in_array($stat, ['N', 'F', 'FAIL', 'FAILED', 'REJECTED', '3', '03', '-1'], true)) {
$payload['_card_modify'] = [
'status' => 'rejected',
'apply_no' => (string) ($meta['apply_no'] ?? ''),
'req_seq_id' => (string) ($meta['req_seq_id'] ?? ''),
'pending_form' => $meta['pending_form'] ?? [],
'reject_reason' => $desc ?: '结算卡更换被驳回',
'updated_at' => time(),
];
$row->payload = json_encode($payload, JSON_UNESCAPED_UNICODE);
$row->resp_snapshot = json_encode($status, JSON_UNESCAPED_UNICODE);
$row->save();
}
}
public static function getCardModifyMeta(array $payload)
{
$meta = $payload['_card_modify'] ?? null;
return is_array($meta) ? $meta : [];
}
}

查看文件

@@ -43,6 +43,54 @@ class HuifuOnboardValidator
return self::normalize($data);
}
/**
* 已通过进件后仅更换结算卡:银行卡字段来自 patch,身份/执照沿用库内 stored
*/
public static function validateCardModify(array $patch, array $stored)
{
if (!$stored || !is_array($stored)) {
throw new \InvalidArgumentException('缺少原进件资料,无法更换结算卡');
}
$merged = $stored;
$bankKeys = [
'bank_account_type', 'card_no', 'card_name', 'branch_code', 'branch_name',
'prov_id', 'area_id', 'district_id', 'shopro_province_id', 'shopro_city_id', 'shopro_district_id',
'mp', 'mobile_no', 'legal_mobile', 'bank_card_url', 'account_permit_url',
];
foreach ($bankKeys as $key) {
if (!array_key_exists($key, $patch)) {
continue;
}
$val = $patch[$key];
if ($val === null || $val === '') {
continue;
}
$merged[$key] = $val;
}
$oldCard = preg_replace('/\s+/', '', (string) ($stored['card_no'] ?? ''));
$newCardRaw = preg_replace('/\s+/', '', (string) ($merged['card_no'] ?? ''));
// 前端若回显脱敏卡号且用户未改,沿用库内原卡号
if ($newCardRaw !== '' && strpos($newCardRaw, '*') !== false) {
$merged['card_no'] = $oldCard;
$newCardRaw = $oldCard;
}
HuifuOnboardAreaHelper::applyRegionCodes($merged);
self::resolveBranch($merged);
self::validateBank($merged);
if ($newCardRaw !== $oldCard && empty($merged['bank_card_url'])) {
throw new \InvalidArgumentException('更换银行卡号时请重新上传银行卡照片');
}
if ((string) ($merged['bank_account_type'] ?? '0') === '1' && empty($merged['account_permit_url'])) {
throw new \InvalidArgumentException('对公账户请上传开户许可证');
}
return self::normalize($merged);
}
protected static function validateIndividual(array $data)
{
foreach (['name', 'cert_no', 'mobile_no', 'reg_detail', 'id_card_front_url', 'id_card_back_url'] as $field) {