feat(huifu): 进件补采线下经营的三张门店材料（门头照/内景照/收银台）

yeg

2026-09-29 7a5303f5245e618422f32267c758dadb704487bb

 docs/huifu/02-进件与收款能力.md

@@ -25,6 +25,25 @@
术语表与 `CONTEXT.md` 的表述一致，但它本身是**仓库术语表**、不是官方文档；其中「延迟户不可结算、不可取现」这类**官方定义**目前只是转述（仓库内没有对应官方页面原件，属【官方·外部】）。
**本文没有任何一条结论以汇付官方确认为依据**（2026-09-18 全仓核查：仓库里不存在汇付官方回复的留档）：凡我方自测得到的结论一律标【实测】，并注明「自测结论，汇付侧未书面确认」。

**场景口径（2026-09-24 起）**：微信支付统一走**线下**——支付场景 `1/2/3`、业务开通类型 `02`、
费率规则号企业 `758`／个体户 `762`／小微 `770`、费率 `0.30%`、进件 `scene_type=OFFLINE`、
小微经营类型 `MICRO_TYPE_STORE`。这些都取自 `application.yml` 的 `app.payment.huifu.*`，**下发与判定同源**：
只改一处会让通道侧开通成功而本地阶段永远 `missing`（下游是收款闸门，会挡住商户收款）。成套口径与回退方式
见 `05` 第 18/19/19b 条，存量商户的迁移步骤见 `08` §9。

进件侧随之多两项要求：个人（小微）主体的**经营详细地址**成为必填（进件请求的 `detail_addr`，落
`merchant_onboarding_application.business_address`，**与证件地址 `legal_addr` 分开**——以前两者共用同一个值，
线下报备下会被通道驳回或留下错误信息，迁移 `V155`）；**门店材料从两张变三张**——门头照（F22）、内景照（F24）、
**收银台（F105）**，且**企业与个人主体都要交**（证明见下）。F22 的含义也从「店铺首页截图」变为「实体门头照」。

**门店材料是一组三张，且通道在进件这一步就核对【实测】**（2026-09-29）：进件请求被通道的「商户材料校验服务」
按 F-code 逐张核对，缺一张整笔驳回——报错原文
`调用商户材料校验服务返回，校验失败 缺失图片：F22-店铺门头照图片;F24-店铺内景图片;F105-店铺收银台`。
所以：商户端表单三类主体都收这三张（`storeHeaderUrl` / `storeIndoorUrl` / `storeCashierUrl`，迁移 `V156`），
进件请求发 `store_header_pic` / `store_indoor_pic` / `store_cashier_desk_pic`（字段名取自通道自己的报错），
业务开通再以 `extended_material_list` 的 F22/F24/F105 补一遍（`putMaterial` 跳过空值，某张确实没有时不下发残缺条目）。
**企业主体原先一张都不发**（`extended_material_list` 的下发条件写成「仅个人」），线下口径下就是在进件这一步被驳。

## 1. 进件时序：企业/个体双路径 + 通道回调 + 分阶段开通

```mermaid
@@ -37,14 +56,14 @@
    M->>S: POST /api/merchant/onboarding (X-Idempotency-Key)
    S->>S: 建进件(pending) + 银行卡(pending)；已有 active 进件则只补门店照
    alt 企业主体（含个体工商户）
        S->>H: v2.merchant.basicdata.ent（先传 F07/F02/F03/F13… 取 fileId）
        S->>H: v2.merchant.basicdata.ent（先传 F07/F02/F03/F13/F22/F24/F105… 取 fileId）
    else 个人（小微）主体
        S->>H: v2.merchant.basicdata.indv（先传 F40/F41/F13/F22）
        S->>H: v2.merchant.basicdata.indv（先传 F40/F41/F13/F22/F24/F105）
    end
    H-->>S: huifu_id + apply_no（同步响应即可推进下一步，不等 token_no）
    S->>H: v2.merchant.busi.open（wx_conf_list 场景 4/5/12、delay_flag=Y、forced_delay_flag=N）
    S->>H: v2.merchant.busi.open（wx_conf_list 场景 1/2/3（线下）、delay_flag=Y、forced_delay_flag=N）
    H-->>S: 90000000「审核中」＝已受理（不是失败）
    Note over S: 配置的闸门取通道证据：qry_wx_conf_list 里真的出现线上场景才发下一条
    Note over S: 配置的闸门取通道证据：qry_wx_conf_list 里真的出现配置的场景才发下一条
    S->>H: v2.merchant.busi.config（绑定人才端小程序 AppID）
    H-->>S: 00000000 或驳回
    H->>S: 回调 merchant-onboarding-notify / merchant-business-open-notify / merchant-wechat-config-notify
@@ -92,8 +111,8 @@
| `key`（`LABELS`） | 展示名 | 「已确认」的通道证据 |
| --- | --- | --- |
| `basic` | 基础审核 | `apply_status=Y` 且 `reg_status=S` |
| `wechat` | 微信支付 | `qry_wx_conf_list` 里 4/5/12 三场景齐全，且每场景 `fee_rate=0.70`、`fee_min_amt` **缺失或为 0**、`fee_charge_type=1`、`out_fee_flag=2`、`wx_mer_infos` 里有 `bank_mer_code` 且 `is_default=1` |
| `appId` | 人才端绑定 | `busi.config.query` 的 `atu_config_bo_list` 中 `fee_type=01` 的 `wx_config_list` 里出现人才端 AppID；`control_flag=Y` 记 `action_required` |
| `wechat` | 微信支付 | `qry_wx_conf_list` 里配置的三个支付场景（**线下默认 1/2/3**；线上 4/5/12）齐全，且每场景 `fee_rate=`配置值（**线下 0.30**、线上 0.70）、`fee_min_amt` **缺失或为 0**、`fee_charge_type=1`、`out_fee_flag=2`、`wx_mer_infos` 里有 `bank_mer_code` 且 `is_default=1`。场景与费率都取 `application.yml` 的配置，与下发同源 |
| `appId` | 人才端绑定 | `busi.config.query` 的 `atu_config_bo_list` 中 `fee_type=`配置值（**线下 02**、线上 01）的 `wx_config_list` 里出现人才端 AppID；`control_flag=Y` 记 `action_required` |
| `realname` | 实名与授权 | **只看 `authorize_stat`**：`=1` → `confirmed`；`APPLYMENT_STATE_REJECTED` → `failed`；`NOAPPLY/CANCELED` → `missing`；`EDITTING/WAITTING_FOR_AUDIT` → `pending`；其余 → `action_required` |
| `delay` | 延迟入账 | 商户详情 `delay_flag=Y` 且 `forced_delay_flag=N`；不满足时由 `v2.merchant.busi.modify` 发起（落 `merchant_onboarding_attempt`，`step='delay'`） |
| `settlement` | 自动结算 | `qry_settle_config_list` 恰好 1 条，且 `settle_status=1`、`settle_cycle=D1`、`settle_pattern=P0`、`min_amt=0`、`remained_amt=0` |
@@ -170,7 +189,7 @@
### 坑 4（卡死流程）微信小程序配置排在业务开通之前，任何新商户都开不出微信收款能力

**现象**：配置被驳「根据渠道号或微信子商户号未查到入驻记录」，紧接着微信支付、人才端绑定、实名全部连坐；商户永远停在 `not_started`。
**根因**：两层。①**顺序反了**：微信子商户号是业务开通创建的，配置必须先等它；配置一失败旧实现就 `return`，业务开通永远轮不到。②**闸门取错了依据**：业务开通被受理（`90000000`）不等于子商户号已可查——微信入驻是**异步**的，闸门必须取通道证据（`qry_wx_conf_list` 里真的出现线上场景），不能取本地状态。
**根因**：两层。①**顺序反了**：微信子商户号是业务开通创建的，配置必须先等它；配置一失败旧实现就 `return`，业务开通永远轮不到。②**闸门取错了依据**：业务开通被受理（`90000000`）不等于子商户号已可查——微信入驻是**异步**的，闸门必须取通道证据（`qry_wx_conf_list` 里真的出现配置的场景），不能取本地状态。
**置信档**：【实测】（新商户真实报文：配置驳回原因逐字如此；改成通道证据后受理成功）
**为什么以前没暴露**：只验证过存量/参考商户，它们的微信业务早就开通了，配置有东西可挂。

@@ -199,7 +218,7 @@
| 查询一律 `20002 数据权限认证失败` | 签名身份有没有该商户的数据权限；与商户层级（head 字段）**无关** | 我方凭据/权限。【实测】 |
| 业务开通回 `90000000` | 这是「审核中＝已受理」，**不是失败** | 我方判定（曾把它记成 `failed`）。【实测】 |
| `wx_conf_list格式错误` | 逐字段比对层级与类型：`wx_real_name_info` 是**嵌套对象**不是字符串；小微/个体工商户必须带 `mcc` | 我方报文。【实测】 |
| `微信费率规则号填写不正确` | CID 按「场景 × 业务类型 × **主体类型**」三维定位（企业 756 / 个体户 761 / 小微 775） | 我方配置。【官方原件】（官方 Excel 全表在 `docs/huifu/reference/official/wx-fee-rule-id.xlsx`） |
| `微信费率规则号填写不正确` | CID 按「场景 × 业务类型 × **主体类型**」三维定位（线下：企业 758 / 个体户 762 / 小微 770；线上：756 / 761 / 775） | 我方配置。【官方原件】（官方 Excel 全表在 `docs/huifu/reference/official/wx-fee-rule-id.xlsx`） |
| 阶段永远「未确认」而 `sync_error` 是空的 | 通道查询其实成功了，是**判定条件**没通过（典型：不设最低收费时通道**不返回** `fee_min_amt`，缺失必须按 0 处理） | 我方判定。【实测】（真实回执里该字段整个缺席） |
| 商户端没有授权二维码 | 通道回的是**裸 base64 的 JPEG**，别写死 PNG magic；官方示例却是 `data:image/png;base64,iVBOR…` | 我方解析．【实测】（通道回 `/9j/`）＋官方示例属【官方原件】（`reference/official/huifu-api_shjj_wxsmrzztcx.md`）——**两者不一致，不要照抄官方示例** |
| `authorize_stat=1` 却显示待办理 | 授权**只看 `authorize_stat`**；`APPLYMENT_STATE_FREEZED`（主体已完成过入驻）也可能是已授权成功 | 我方判定。【实测】 |