```

feat(wallet): 用户提交时直连汇付API优化流程 - 移除数据库事务包装汇付API调用，避免长耗时锁表问题 - 用户提交申请时直接连接汇付服务，不再仅保存草稿等待后台处理 - 修改汇付重提交方法名为resubmit以明确区分不同操作 - 更新异常处理机制，增加Throwable捕获确保错误正确处理 - 调整提交成功后的消息提示内容，准确反映当前处理状态 fix(agent): 代理申请流程汇付集成优化 - 统一汇付进件提交失败的消息提示文本 - 优化代理申请状态判断逻辑，根据汇付载荷存在性决定提交方式 - 更新区域代理申请成功提示，区分已提交汇付和待提交场景 - 修复业务审核通过后的汇付提交触发机制 docs(huifu): 更新汇付进件相关文档说明 - 修改后台管理界面描述，体现用户直连汇付的新流程 - 更新业务审核状态下的操作指引说明 - 调整汇付网关类的方法注释，明确各方法职责变化 - 修正canSaveHuifuDraft方法注释，说明字段兼容性和新功能 ```
2026-10-08 21:03:04 +08:00
--- a/addons/shopro/controller/UserWalletApply.php
+++ b/addons/shopro/controller/UserWalletApply.php
@@ -105,19 +105,19 @@ class UserWalletApply extends Base
        $resubmit = false;

        try {
-            \think\Db::transaction(function () use ($bindings, $userId, $form, $service, &$did, &$resubmit) {
-                foreach ($bindings as $binding) {
-                    $huifu = $binding['huifu_onboard'];
-                    if (!empty($huifu['can_submit'])) {
-                        $service->submit($userId, $binding['role_type'], $binding['role_ref_id'], $form);
-                        $did = true;
-                        $resubmit = true;
-                    } elseif (!empty($huifu['can_save_draft'])) {
-                        $service->saveDraft($userId, $binding['role_type'], $binding['role_ref_id'], $form);
-                        $did = true;
-                    }
+            // 汇付 API 不放在 DB 事务内，避免长耗时锁表
+            foreach ($bindings as $binding) {
+                $huifu = $binding['huifu_onboard'];
+                if (!empty($huifu['can_submit'])) {
+                    $service->resubmit($userId, $binding['role_type'], $binding['role_ref_id'], $form);
+                    $did = true;
+                    $resubmit = true;
+                } elseif (!empty($huifu['can_save_draft'])) {
+                    // 用户提交即直连汇付（不再只存 draft 等后台/定时任务）
+                    $service->submit($userId, $binding['role_type'], $binding['role_ref_id'], $form);
+                    $did = true;
                }
-            });
+            }
        } catch (\InvalidArgumentException $e) {
            $this->error($e->getMessage());
        } catch (\RuntimeException $e) {
@@ -125,6 +125,11 @@ class UserWalletApply extends Base
                ? \addons\shopro_huifu\library\onboard\HuifuOnboardError::translate($e->getMessage())
                : $e->getMessage();
            $this->error($msg);
+        } catch (\Throwable $e) {
+            $msg = class_exists('\\addons\\shopro_huifu\\library\\onboard\\HuifuOnboardError')
+                ? \addons\shopro_huifu\library\onboard\HuifuOnboardError::translate($e->getMessage())
+                : $e->getMessage();
+            $this->error($msg ?: '提交汇付进件失败');
        }

        if (!$did) {
@@ -133,7 +138,7 @@ class UserWalletApply extends Base

        $msg = $resubmit
            ? '汇付进件已重新提交，请耐心等待审核'
-            : '进件资料已提交，请等待后台审核；审核通过后将自动提交汇付';
+            : '已提交汇付进件，请耐心等待审核';
        $this->success($msg, $this->resolveWalletOnboard($userId));
    }

--- a/addons/shopro/controller/commission/Agent.php
+++ b/addons/shopro/controller/commission/Agent.php
@@ -289,7 +289,7 @@ class Agent extends Commission
                try {
                    \think\Hook::listen('shopro_commission_apply_after', $hookParams);
                } catch (\Throwable $e) {
-                    $failMsg = $huifuResubmit ? '汇付进件提交失败' : '进件资料保存失败';
+                    $failMsg = '汇付进件提交失败';
                    $this->error($e->getMessage() ?: $failMsg);
                }
            }
@@ -297,13 +297,13 @@ class Agent extends Commission

        if ($huifuResubmit) {
            $msg = '汇付进件已重新提交，请耐心等待审核';
-        } elseif ($canSaveHuifuDraft && !$applyStatus) {
-            $msg = '进件资料已保存，请等待后台审核；审核通过后将自动提交汇付';
+        } elseif (!empty($huifuPayload)) {
+            $msg = '申请已提交，汇付进件已同步提交，请耐心等待审核';
        } else {
            $msg = '申请已提交，请等待后台审核';
            if (class_exists('\\addons\\shopro_huifu\\library\\onboard\\HuifuOnboardGate')
                && \addons\shopro_huifu\library\onboard\HuifuOnboardGate::isOnboardRequired()) {
-                $msg = '申请已提交，请等待后台审核；审核通过后请到「提现」页绑定进件资料';
+                $msg = '申请已提交，请等待后台审核；通过后请到「提现」页完成汇付进件';
            }
        }
        $this->success($msg, null);
--- a/addons/shopro/controller/regional_agent/Agent.php
+++ b/addons/shopro/controller/regional_agent/Agent.php
@@ -119,11 +119,16 @@ class Agent extends RegionalAgent

        if ($status === AgentModel::STATUS_PENDING) {
            $msg = $huifuRequired
-                ? '申请已提交，请等待后台审核；审核通过后请到「提现」页绑定进件资料'
+                ? (!empty($huifuOnboard)
+                    ? '申请已提交，汇付进件已同步提交，请耐心等待审核'
+                    : '申请已提交，请等待后台审核；通过后请到「提现」页完成汇付进件')
                : '申请已提交，请等待后台审核';
        } else {
            $msg = '申请已通过，您已成为该区域公司';
-            if ($huifuRequired && class_exists('\\addons\\shopro_huifu\\library\\onboard\\HuifuOnboardGate')) {
+            if ($huifuRequired && !empty($huifuOnboard)) {
+                $msg = '申请已通过，汇付进件已同步提交，请耐心等待审核';
+            } elseif ($huifuRequired && class_exists('\\addons\\shopro_huifu\\library\\onboard\\HuifuOnboardGate')) {
+                // 无随申请提交资料时，兜底尝试提交历史 draft
                \addons\shopro_huifu\library\onboard\HuifuOnboardGate::submitOnBusinessApproved(
                    $userId,
                    'regional_agent',
--- a/addons/shopro_huifu/application/admin/view/shopro_huifu/onboard/index.html
+++ b/addons/shopro_huifu/application/admin/view/shopro_huifu/onboard/index.html
@@ -21,7 +21,7 @@
    <div class="panel panel-default panel-intro">
        <div class="panel-heading">
            汇付个人进件
-            <span class="text-muted" style="font-size:12px;margin-left:12px;">业务审核通过后由定时任务自动提交汇付；失败满 24 小时自动重提（可手动「提交汇付/重提」）</span>
+            <span class="text-muted" style="font-size:12px;margin-left:12px;">用户提交资料后直连汇付；失败可手动「重提」，可选定时任务兜底重试</span>
        </div>
        <div class="panel-body">
            <div style="margin-bottom:12px;">
@@ -85,7 +85,7 @@
            </el-descriptions>

            <div class="biz-tip" v-if="detailData.business.status === 'pending'">
-                该用户业务身份仍为「待审核」，请先在{{ detailData.business.type_text }}管理中审核通过；通过后将自动提交汇付进件。
+                该用户业务身份仍为「待审核」，请先在{{ detailData.business.type_text }}管理中审核；若进件仍为草稿可手动「提交汇付」。
                <el-button type="text" size="mini" @click="goAudit(detailData.business.audit_url)">前往业务审核</el-button>
            </div>
            <div class="biz-tip" v-else-if="detailData.record.onboard_status === 'draft' && detailData.business.status === 'normal'">
--- a/addons/shopro_huifu/library/onboard/HuifuOnboardGate.php
+++ b/addons/shopro_huifu/library/onboard/HuifuOnboardGate.php
@@ -48,7 +48,8 @@ class HuifuOnboardGate
    }

    /**
-     * 后台业务审核通过后触发汇付进件（先审后汇付）
+     * 后台业务审核通过后的兜底：若仍有未提交的 draft，则补提交汇付
+     * （正常路径已由用户提交时直连汇付）
     */
    public static function submitOnBusinessApproved($userId, $roleType, $roleRefId)
    {
@@ -83,7 +84,7 @@ class HuifuOnboardGate
    }

    /**
-     * 用户端是否可保存/更新进件草稿（不调用汇付 API）
+     * 用户端是否可首次提交进件资料到汇付（字段名 can_save_draft 兼容旧前端）
     */
    public static function canSaveHuifuDraft($userId, $roleType, $roleRefId, $agentStatus = '')
    {
@@ -101,6 +102,7 @@ class HuifuOnboardGate
        ], true)) {
            return false;
        }
+        // 已有 draft 且业务侧仍待审/驳回时，不允许反复改资料占坑（历史规则保留）
        if ($row && $row['onboard_status'] === Onboard::STATUS_DRAFT
            && in_array($agentStatus, ['pending', 'needinfo', 'reject'], true)) {
            return false;
@@ -113,6 +115,7 @@ class HuifuOnboardGate
        $required = self::isOnboardRequired();
        $canSubmit = $required && $userId && self::canSubmitOnboard($userId, $roleType, $roleRefId, $agentStatus);
        $canSaveDraft = $required && $userId && self::canSaveHuifuDraft($userId, $roleType, $roleRefId, $agentStatus);
+        // 仅历史 draft 残留时提示等待（正常已改为用户提交直连汇付）
        $awaitAdmin = $required && $row && $row['onboard_status'] === Onboard::STATUS_DRAFT
            && in_array($agentStatus, ['pending', 'needinfo', 'reject'], true);
        if (!$row) {
@@ -121,7 +124,7 @@ class HuifuOnboardGate
                'can_submit' => $canSubmit,
                'can_save_draft' => $canSaveDraft,
                'await_admin' => false,
-                'audit_first' => true,
+                'audit_first' => false,
                'status' => null,
                'huifu_id' => '',
                'reject_reason' => '',
@@ -133,7 +136,7 @@ class HuifuOnboardGate
            'can_submit' => $canSubmit,
            'can_save_draft' => $canSaveDraft,
            'await_admin' => $awaitAdmin,
-            'audit_first' => true,
+            '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'] ?? '',
--- a/addons/shopro_huifu/library/onboard/HuifuOnboardService.php
+++ b/addons/shopro_huifu/library/onboard/HuifuOnboardService.php
@@ -29,7 +29,7 @@ class HuifuOnboardService
    }

    /**
-     * 用户申请时仅保存进件资料，待后台业务审核通过后再提交汇付
+     * 仅保存进件资料（后台代录 / 兼容旧路径）；用户端已改为 submit 直连汇付
     */
    public function saveDraft($userId, $roleType, $roleRefId, array $formData, $onboardId = 0, $force = false)
    {
--- a/addons/shopro_huifu/listener/CommissionApplyHook.php
+++ b/addons/shopro_huifu/listener/CommissionApplyHook.php
@@ -25,9 +25,10 @@ class CommissionApplyHook
            if (!HuifuOnboardGate::canSubmitOnboard($userId, 'promoter', $userId)) {
                throw new \RuntimeException('当前状态不可重新提交汇付进件');
            }
-            $service->submit($userId, 'promoter', $userId, $form);
+            $service->resubmit($userId, 'promoter', $userId, $form);
            return;
        }
-        $service->saveDraft($userId, 'promoter', $userId, $form);
+        // 申请时一并提交汇付，不再只存草稿
+        $service->submit($userId, 'promoter', $userId, $form);
    }
 }
--- a/addons/shopro_huifu/listener/RegionalAgentApplyHook.php
+++ b/addons/shopro_huifu/listener/RegionalAgentApplyHook.php
@@ -22,6 +22,7 @@ class RegionalAgentApplyHook
            throw new \RuntimeException('请填写汇付进件资料');
        }
        $service = new HuifuOnboardService();
-        $service->saveDraft($userId, 'regional_agent', $agentId, $form);
+        // 申请时一并提交汇付，不再只存草稿
+        $service->submit($userId, 'regional_agent', $agentId, $form);
    }
 }
--- a/application/admin/view/shopro_huifu/onboard/index.html
+++ b/application/admin/view/shopro_huifu/onboard/index.html
@@ -21,7 +21,7 @@
    <div class="panel panel-default panel-intro">
        <div class="panel-heading">
            汇付个人进件
-            <span class="text-muted" style="font-size:12px;margin-left:12px;">业务审核通过后由定时任务自动提交汇付；失败满 24 小时自动重提（可手动「提交汇付/重提」）</span>
+            <span class="text-muted" style="font-size:12px;margin-left:12px;">用户提交资料后直连汇付；失败可手动「重提」，可选定时任务兜底重试</span>
        </div>
        <div class="panel-body">
            <div style="margin-bottom:12px;">
@@ -85,7 +85,7 @@
            </el-descriptions>

            <div class="biz-tip" v-if="detailData.business.status === 'pending'">
-                该用户业务身份仍为「待审核」，请先在{{ detailData.business.type_text }}管理中审核通过；通过后将自动提交汇付进件。
+                该用户业务身份仍为「待审核」，请先在{{ detailData.business.type_text }}管理中审核；若进件仍为草稿可手动「提交汇付」。
                <el-button type="text" size="mini" @click="goAudit(detailData.business.audit_url)">前往业务审核</el-button>
            </div>
            <div class="biz-tip" v-else-if="detailData.record.onboard_status === 'draft' && detailData.business.status === 'normal'">