汇付商户进件集成

概述

汇付商户进件、用户开户与入驻

汇付官方资料的版权与使用边界见 references/shared-copyright-notice.md。

执行流程

1. 确定目标是支付商户还是分账/结算用户，再按当前任务确定主体、接口与技术栈。仅出现 huifu_id 不足以判定实体；有歧义只追问影响当前任务的实体/接口，其他明确部分继续。
2. 按下表读目标原子页；字段/代码任务补所属领域字段合同的目标章节，完整 DTO、响应或嵌套结构再补完整字段目录。代码任务再读对应SDK矩阵，不规定资料数量，不默认加载全部接口。
3. 按完整父路径和请求/同步/通知方向核对类型、长度、Y/N/C、枚举、默认值、互斥和外部资料。C按条件必填；String(JSON)逐层编码/解码，不按 *_list 名称猜数组，不把查询独有字段复制为请求。
4. 字段、示例、SDK或协议冲突标记 [需要官方确认]，附完整路径、具体疑点和官方地址。继续已明确实现，争议部分留 TODO/待填配置；不自动选择冲突一方、不把咨询答复作为整体开发前提。

字段审计或完整DTO任务：先按完整目录的接口标题定位，再分页读取目标请求、同步响应、异步通知及各父容器子表。按“方向+完整父路径”逐项核对已读范围；交付父容器的wire类型、条件、子字段、说明/示例冲突及表外注记，不以请求样例替代目录。声称完整前核对该接口所有目标方向；只展开部分时明确未展开范围。统计从机械目录复算并说明父/叶、方向及去重口径，搜索命中不代表完整读取。

商户与用户的DTO、ID和状态必须隔离：merchantHuifuId 不等于 userHuifuId。交易下单、退款、对账、checkout-js及支付终态交接给 $huifu-pay-integration。

精确路由

子账户配置属于商户管理；开户/绑卡审核/提现结算可用状态分开判断。余额、账务流水及汇总查询交接支付Skill，不能把用户开户ID当商户子账户的商户号。

官网账户管理五接口按当前职责拆分：本 Skill 负责创建子账户及修改结算/绑卡配置；支付 Skill 负责余额与资金流水读取。单纯查账交接支付 Skill，同时开户配置和查账时联用两者。商户详情、申请状态等管理查询仍归本 Skill，不能把所有“查询”一律交给支付。

接口选择与字段边界

• “补开”时同时确认具体能力/渠道和当前开通状态：银行卡、银联业务开通仍走 /v2/merchant/busi/open；微信、支付宝、抖音补开走 /v2/merchant/busi/modify。其他能力读两个原子页按适用范围判断。
• upper_huifu_id 与 sys_id 主体角色一致；渠道商/总部商户条件从目标接口取值，不全局强制。
• 图片 data.huifu_id 只接受已确认的直属商户号，用户开户ID不可填写。file_url 与文件流互斥；响应文件标识未知时不猜schema。
• 同名字段必须保留完整父路径和方向，特别是经营地区、结算卡地区和 material_card_info 补充账户；详细约束留在字段合同。
• 平台分配的 huifu_id 等ID作为不透明字符串原样传递，仍须核对实体角色，始终不补零、截断或转数字。长度列不能直接推出必须恰好18位；仅官网明确固定格式时做对应格式校验。
• 示例不作默认值，空说明/长度保留 —。外部资料命中时给出字段路径、触发条件、原始地址及相对地址解析结果；回调/下载/图片裸URL示例不作资料或默认地址。

SDK 与调用安全

常规接口真实请求都使用官方 Request/Client 入口。SDK没有专属Request/路由时先核对已验证的官方通用入口，逐项按字段合同构造；不冒称专属支持，不手写HTTP补位。

唯一例外是 /v2/supplementary/picture 的PHP/Python受控multipart适配，必须保持 data 加签、来源互斥、TLS和日志边界；Java图片仍使用官方SDK。能力缺陷与完整安全骨架见图片原子页及SDK矩阵。

Java调试在初始化/任何请求前全局关闭；PHP在加载任何SDK前固定 DEBUG=false，拒绝已启用DEBUG的进程和官方Demo/Composer调试入口。生成安全初始化骨架不要求用户先证明既有配置。

当前证据为2026-10-08官方固定提交/制品：Java3.0.41、PHP2.0.31、Python2.0.28。Java/Python默认TLS，PHP现有peer校验缺陷作非阻断提醒；不自动修改SDK、不新增关闭校验设置。实际安装版本不同则核对差异，明确部分继续，未知部分留TODO。

缺密钥、系统号、产品号或材料时可生成服务端配置占位和框架；真实调用前需有效配置与授权。明确非法输入、错误实体ID、验签失败、凭据泄露或未授权真实操作，停止受影响操作并说明原因，必要时标记 🔴 CHECKPOINT · HARD STOP。

状态与通知

返回商户/用户号及同步受理不代表审核、逐业务开通、银行账户或电子协议全部完成；各层状态按原子页分别判断。

商户逐业务通知包装仍待核对；业务开通修改存在 ord_id 时用该字段应答，不替换为 req_seq_id。审核/电子协议未知ACK、验签原文、HTTP语义、超时与重试留适配点，不套用支付或控台Webhook协议。

用户业务入驻已有公共通知合同：原始 data 免排序RSA验签、HTTP200与 RECV_ORD_ID_ + req_seq_id，完整超时、重试和wire矩阵必须读 references/user-onboarding-platform-contracts.md。该协议不能外推商户通知。

请求与交付

• 保留调用方日期、流水、申请号及角色ID，扩展不得覆盖声明字段；私钥、身份证、银行卡、手机号和图片使用安全配置/脱敏示例，不进入前端、日志或仓库。
• 本Skill实际参与时默认 hfms/1.1.0；支付也参与时为 hfps/1.5.0;hfms/1.1.0，顺序固定、一个英文分号且不加空格。仅安装未参与的不计入；显式合同值原样透传，不追加 sys_id，来源头不写业务 data。
• 直接回答当前问题，列出实际读取的 references。代码交付说明实体与目标接口、方向、配置/TODO和验证结果；只有后续涉及交易时才交接支付Skill。

当前版本

本Skill不提供进件沙箱端点。