适用提交: 6c42f8f ｜ 最后验证: 2026-09-18 ｜ 何时会失效: payment_reconciliation_issue 的唯一键、app.payment.huifu.reconciliation.* 或 pending-after-minutes 的取值、或 HuifuSettlementRecordGateway 所用通道接口的契约发生变化

04 结算与对账

本文件回答三件事：出款现在由谁做、后台「结算记录」页的数据从哪来、以及支付与退款的后台兜底（对账）怎么跑。
一句话结论：**平台不再出款，也不再保存结算流水**——出款由斗拱按结算周期自动完成，结算记录每次都现场问通道；对账只做一件事：把本地没结论的资金事实与通道对齐。**【推断】**（逐条依据与置信档见下文各节）

本文件术语

正文严格使用根目录 CONTEXT.md 的术语，下表同时给出**禁用同义词**：

置信度四档（【官方原件】/【官方·外部】/【实测】/【推断】）的定义见 docs/huifu/README.md。
本文没有任何一条结论以汇付官方确认为依据；凡我方自测得到的结论一律标【实测】，并注明「自测结论，汇付侧未书面确认」。

1. 对账：定时扫描、退避与后台「立即对账」

flowchart TD
    SCH["PaymentReconciliationScheduler<br/>fixedDelay 默认 60000ms"] --> REC["reconcile(pendingAfterMinutes = 5)"]
    BTN["后台「立即对账」<br/>POST /api/admin/management/payment-reconciliation/run"] --> REC
    REC --> PAY["支付：本地未定局流水<br/>CREATED/PREPAY_CREATED/CREATE_UNKNOWN/CLOSING/CANCEL_UNCONFIRMED<br/>limit 100，按 last_reconciled_at 轮转"]
    REC --> RFD["退款：在途退款<br/>order_refund.refund_status=1，limit 100"]
    PAY --> LANE{"按状态分快慢车道"}
    LANE -->|"CLOSING / CANCEL_UNCONFIRMED，距创建与上次处理均满 1 分钟"| FAST["先问关单查询"]
    LANE -->|"其它未定局，距创建满 5 分钟"| SLOW["通道支付查询"]
    FAST --> FC{"关单查询说已关掉?"}
    FC -->|"是"| FOK["落 CLOSED + 结掉问题记录"]
    FC -->|"否"| FA{"已发起关单达到 3 次?"}
    FA -->|"否"| FAGAIN["再发一次关单；顺带确认是否已收款"]
    FA -->|"是"| FGIVE["只查不再关：给这次尝试终止<br/>订单取消 + 留 CANCEL_UNCONFIRMED"]
    SLOW --> SC{"通道答复"}
    SC -->|"成功: trans_stat=S 且业务码成功"| SOK["走与回调同一套结算规则<br/>落成已支付"]
    SC -->|"失败 / 23000001 交易不存在"| SFAIL["落 CREATE_FAILED"]
    SC -->|"处理中 / 读不出 / 查询失败"| SPEND["保持未定"]
    RFD --> RQ{"退款查询结果"}
    RQ -->|"仍在处理中"| RPEND["留在途"]
    RQ -->|"已终结"| ROK["结掉在途问题记录"]
    FOK --> ISSUE["payment_reconciliation_issue<br/>发现问题 upsert 成 open；有结论就 resolve"]
    FGIVE --> ISSUE
    SFAIL --> ISSUE
    SPEND --> ISSUE
    RPEND --> ISSUE

兜底说明：定时任务与后台按钮**调用同一个 reconcile()**，不存在「后台按钮走简化逻辑」这回事——这是 ADR-0004 的硬要求（禁止为了开发便利造捷径）。三条退避规则要记住：慢车道每行要「距创建满 pending-after-minutes（默认 5 分钟）」，快车道（CLOSING／CANCEL_UNCONFIRMED）只要「距创建与上次处理均满 1 分钟」（通道不允许关闭一分钟以内的订单，1 分钟同时也是最短重试间隔），且**每处理完一行就盖上 last_reconciled_at**，否则最久没被处理的一行会一直排最前面把后面的行饿死。**[实测]**（间隔/上限/退避都在 PaymentReconciliationService 与 PaymentSchedulingConfigurationTests 里被钉住；「注解默认值与 yml 必须一致」这一条是踩过坑后加的测试）

这里是支付与退款唯一的后台兜底：app.payment.huifu.reconciliation.enabled 在注解与 yml 两处的默认值都是 true——原先注解默认 false、只靠 yml 那一行打开，删掉那一行兜底就**静默消失**。**[实测]**
但长尾不在扫描里：PAYMENT_CLOSE_CONFLICT（关单回执说原交易已成功）之类只记问题记录交人工，没有任何自动消费它们的任务（见第 4 节）。**[推断]**

1.1 可调的三个参数与观察点

下表取值来自 application.yml 与 PaymentReconciliationScheduler / PaymentReconciliationAdminService，【推断】。

后台「立即对账」可传 pendingAfterMinutes（服务端收在 1~1440）。
观察点：payment_transaction.status / close_attempts / last_reconciled_at（这行最近被处理过吗）、order_refund.refund_status、payment_reconciliation_issue.status='open'（还有多少笔没有结论）。

对账只写结论，不写原文：台账里只落类型、业务号、期望值/实际值、金额与一句描述——不存回调原文、签名、OpenID、卡号或密钥。**[推断]**（PaymentIssueRecorder 的插入列即这些；合规要求见附录 A talent-card-server/docs/huifu-payment-integration.md 的验收清单）

2. 斗拱自动结算模型

• 出款方是斗拱，不是平台。 资金流：支付 → 延迟户（不可结算、不可取现）→ 核销成功时调**交易确认**分账到商户基本户 → 再由斗拱按 D1 结算周期自动结算到商户绑定的结算银行卡。支付即核销的到店消费订单不走延迟，支付成功即分账。**[实测]**（进件时 settle_config 打开为 settle_status=1、settle_cycle=D1、settle_pattern=P0、起结 0、留存 0，在真实商户详情里读回过这一组值）
• 平台不生成提现记录，也不主动取现；商户端只能看和换结算银行卡，不能发起提现或选金额。**[实测]**
• 本地没有结算记录表。 出款既然由通道做，本地就没有可查的流水；后台「结算记录」页每次打开都**逐商户现场向通道查询**（v2.merchant.basicdata.settlement.query），日期区间默认最近 30 天。**[推断]**（代码事实：HuifuSettlementRecordGateway 只读通道；V140 已把 merchant_withdrawal／merchant_withdrawal_order 删掉）
• 商户端看到的不是这份数据。 商户端「结算管理」读的是本地统计（/api/merchant/settlement-statistics/*，按订单维度聚合），与后台那张「通道真实结算流水」不同源；两者对不上时，以后台通道流水为准。**[推断]**
• 旧实现文档已失效：talent-card-server/docs/huifu-payment-integration.md 里「Automatic settlement」一节仍写着「本平台不再……」（方向正确），但同文件 Merchant payment readiness 一节仍写「自动结算必须关闭」与「调度器默认关闭」，这两句**已经过时**，别拿它当口径。**[推断]**（该文件是英文实现说明，本链路进入交接后未同步更新；冲突时以本套文档为准）

3. 结算记录页：pageSize 上限与查询条件

通道硬上限 pageSize <= 50（这是本页最有价值的教训）：斗拱结算记录查询传 51 或更大，直接回 00000003「基础参数校验失败:【pageSize-分页条数】……最大值为50」，而且**一条都不返回**（不是截断到 50）。此前后台默认传 100，于是「结算记录」页永远空白、而通道里其实有流水。实测：传 20 或 50 正常返回 2 条；传 51 或 100 一条不返回。**[实测]**（自测结论，汇付侧未书面确认）
现在的三道收敛：前端固定 size: 50 → 后端 min(max(size,1),50) → 网关 pageSizeWithinProviderLimit 兜底，越界值不会发到通道。**[推断]**（代码可核对）

查询条件分两处筛，因为两类条件属于两边：商家、联系电话、商家类型是**本地商户字段**，先筛掉不匹配的商户再去问通道（顺带少打几次通道）；状态是**通道流水的结算状态**（S 已结算 / F 失败 / P 处理中），只能等通道把流水给回来之后再过滤。日期栏是**结算日期的区间**（标签已从「申请时间」改对），不是商户申请时间。**[推断]**
这四条条件曾经**完全无效**：前端切到结算记录时只发日期与条数，四个条件根本没发出去，而状态下拉在该标签下还是空列表。**[实测]**

过期响应会覆盖已切走的表格：结算记录要逐商户问通道，是这一页最慢的请求；先切到「商户进件」标签时，结算的响应最后才落地，会把已经切过去的表格覆盖成结算流水——表头是进件的列、内容是结算记录，分页总数也变成结算的条数。修法是给 load() 加请求序号（latestRequest），只有最新那次允许写回表格（加载态也归最新那次管）。**[实测]**

还有四件与展示有关的事：

• 只问「通道侧收款能力正常」的商户：没开通好或在汇付被关停的商户，查过去也会被拒（实测被关闭的子商户回「客户与产品关系已关闭」），只会让页面每次打开都多一条失败提示。判定共用收款能力那套取值，不在本页另立一套。**[实测]**
• 逐商户失败不影响整页：单个商户查询失败只进 failures 列表，在页面底部提示；这是监控页，「看得到」优先。**[推断]**
• 没有真正的分页控件，且 total 会被截断：合并后的流水按结算日期倒序，total 是合并后（状态过滤后）的条数，但返回列表被截到 limit（最多 50）。所以「总数 80、只显示 50 条」是预期行为，不能当成丢数据。**[推断]**
• 卡号列直接取通道回执的 card_no：本地没有再脱敏一层，通道回的是明文还是掩码没有实测证据。**接手前先确认这一点**。[待确认：通道trans_log_result_list[].card_no是明文还是掩码；若是明文需要补脱敏]

4. 对账问题台账 payment_reconciliation_issue

V81 建表，列：issue_type、provider（值恒为 HUIFU）、business_no（支付流水号／退款单号）、order_no、expected_status、actual_status、amount、detail_message、status、detected_at、resolved_at、resolved_by。

• status 三态：**open（默认）／resolved／ignored**。后台可把一行改成 resolved 或 ignored——它**只改这一行的结论，不改支付或退款状态**，是一次审计动作。**[推断]**（代码与 PaymentReconciliationAdminService 可核对）
• 唯一键 (issue_type, provider, business_no, status) 把 status 也包了进去：同一笔业务同一类型只可能有一条 open，也各只有一条 resolved／ignored。写入走 on duplicate key update，所以重复发现同一问题只是刷新 detected_at 与描述，不会堆出一串重复行。**[推断]**
• 这个唯一键埋过一个坑：结掉一步会把 open 行改成 resolved，而同一笔业务先前可能已经有一条 resolved 行（对账每一轮都可能把同一条问题「关掉又开出来」），于是撞唯一键、整个对账台报错。修法是 resolve() 先删掉上一条结论行再落新结论，且删除是有条件的：只有确实存在一条 open 行（真的要更新结论）时才动它，人工写下的结论不会被一次无关的对账轮次抹掉。**[实测]**
• 见过的 issue_type：PAYMENT_PENDING_TIMEOUT、PAYMENT_PROVIDER_FAILED、PAYMENT_QUERY_FAILED、PAYMENT_QUERY_CONFLICT、PAYMENT_CLOSE_UNCONFIRMED、PAYMENT_CLOSE_CONFLICT、PAYMENT_AMOUNT_MISMATCH、PAYMENT_MERCHANT_MISMATCH、PAYMENT_MERCHANT_UNVERIFIED、PAYMENT_COLLECTOR_UNKNOWN、PAYMENT_ORDER_CANCELLED、REFUND_PENDING_TIMEOUT、REFUND_QUERY_FAILED、STRANDED_REFUND_REJECTED。**[推断]**（全仓 grep 常量；新增类型时同步补进 docs/huifu/06-踩坑清单.md）
• 它有接口但后台没有页面入口：GET/PATCH /api/admin/management/payment-reconciliation/issues 已实现，但 talent-card-admin 里只有「立即对账」按钮（src/api/admin.ts 的 runPaymentReconciliation，用在 src/views/OrderView.vue），**没有任何页面调用 issues 那两个接口**——目前只能查库或直接调接口看台账。这是接手人要补的可见性缺口。**[推断]**（grep -rn "payment-reconciliation" talent-card-admin/src 只命中 api/admin.ts 里那一条）

5. 硬规定：通道状态必须有不依赖回调的查询路径

规定（ADR-0004）：凡是需要通道推进的状态，都必须存在一条**不依赖回调**的路径；回调只用来缩短收敛时间，不承担「唯一能把状态推下去」的职责。原因是回调会丢、会重，在本地/内网环境**根本收不到**（回调地址都指向一个公网 IP，开发机不可达）。**每个新接入的通道能力都要回答一遍「它的查询对等物是什么」。**

各链路「由谁触发查询」是**逐链路分别定过**的，继续有效，不要互相套用：

对账在这条链路里的位置：它是支付与退款**唯一的后台兜底**——用户已经离开页面、也没有人再点「刷新支付状态」时，只有对账会把「通道其实收下了钱」落成已支付、把「关不掉但还活着的预支付单」继续盯下去、把在途退款收敛掉。它还承担发现问题的职责：任何对不上的成功事实（另一个商户、另一个金额、订单已取消、缺收款子商户）都记成 open 问题记录，**绝不静默丢弃、也绝不自动履约**。**[实测]**

配套的一条边界：不允许为了开发便利开「跳过真实通道、直接置为已支付」的捷径。开发环境如果需要更快收敛，就把定时间隔调短、并用后台「立即对账」触发**真实对账**，而不是伪造资金事实——自动退款与悬账判定都依赖「任何成功资金事实都能定位本地凭证」这条不变量。**[推断]**（ADR-0004 已把它写成规定；OrderService.pay 那个「只更新 order_status=1、不要求支付流水」的入口现在是否真的不存在，**没有找到证据**）
[待确认：后台「跳过真实支付直接置为已支付」的入口（审计 §7 的OrderService.pay）当前是否仍存在、是否已有独立的资金来源/凭证/审核流程]

6. 退役的平台提现链路（V133~V140）

平台曾经自己做出款：日汇总已核销订单 → 提交主动取现 → 收敛结果。**这条链路已经整体退役，代码已移除，不要再碰**：

（上表为逐份核对迁移文件的结果，【推断】；迁移动机另见 .scratch/huifu-handover/pitfall-checklist.md 的 F 组）

只写三件对现有链路仍有延续影响的事（其余细节随表一起作废）：

1. 资金边界按订单行串行化。 一个订单的核销、退款、悬账退款都要先锁 benefit_order 的同一行，因此它们按订单串行：不会出现「退了款又核销」「核销后被退款」；OrderFundBoundaryService.lock() 要求**调用方已经在事务里**（脱离事务直接失败，而不是静默失去串行化）。这条是提现时代为了「同一额度不能被冻结两次」立的，今天仍在守退款与核销的边界。**[实测]**（审计 §14 复现过「首笔部分退款后剩余金额永远退不了」，现规则改为按金额额度判定：已成功 + 处理中 < 实付）
2. 通道流水号不能被覆盖。 通道的退款流水号**只在发起退款的那次回执里有**，退款查询回执不带它；旧实现无条件覆盖，把唯一的通道凭证擦成空串，退款排查与对账失去定位依据。现在一律 coalesce(nullif(?,''), provider_refund_no)——**「只在某一次回执里出现的字段」不能无条件写回**。同类前例还有支付查询里的通道流水号字段是 org_hf_seq_id（hf_seq_id 只出现在异步通知里），取错会**静默写成 NULL**。**[实测]**
3. 失败结果必须收敛。 提现时代最贵的坑是「失败当天被当成已汇总，钱后来可取了也没有任何出账路径」。现在的口径是：任何失败或未知的资金结果都必须有出口——要么自动收敛，要么重试到有结论，要么落成一条看得见的问题记录交人工；**不允许只留在本地一条记录里等人发现**。**[实测]**

仍需人工收尾的遗留：

• merchant_withdrawal 已被 V140 删除，但**删表前库里已有的旧提现记录是否需要人工对账/归档**没有记录，也没有任何代码或脚本消费它。[待确认：merchant_withdrawal删除前的旧记录是否已完成人工收尾，是否需要从备份里取回核对]
• 后台补跑接口 POST /merchant-settlement/auto-withdrawal/run 在**当前代码里已不存在**（全仓 grep auto-withdrawal 零命中），但**是否还有外部脚本、运维文档或第三方调用方在打这个地址**无法从仓库判断。[待确认：该端点是否还有仓库外的调用方（脚本/文档/运维手册）]
• 旁证：rencaika_merchant/docs/pages/13-商户提现.md（最后更新 2026-09-10）仍在描述「只读展示待提现金额和系统自动提现记录」，MerchantSettlementView.vue 里也保留了 ?kind=withdrawals 的**旧链接兼容分支**（指向结算记录）。文档口径会不会误导运营，需要有人确认。[待确认：旧提现文档与旧链接是否要一并清理]

7. 本链路最容易再犯的 5 条坑

排序按「会动钱 > 卡死流程 > 体验」。每条都给全「现象 + 根因」。凡涉及通道行为的，**汇付侧均无书面确认**。

坑 1（会动钱）定时对账可能「静默消失」

现象：支付与退款唯一的后台兜底整个不跑了，而没有任何人发现。
根因：开关与间隔原先只写在 yml 里，注解上 enabled 的默认值是 false、间隔靠注解默认值——删掉 yml 里那一行，兜底就没了（配置与代码默认值不一致，是「看起来没问题」的那种故障）。现在注解与 yml 两处默认值一致（都开），并被 PaymentSchedulingConfigurationTests 钉住。
置信档：【实测】
接手提示：新增定时任务时，**注解默认值与 yml 必须一致并写测试**——同一个坑在本链路出现过，另一处（补偿任务的开关从未被读取、任务永远在跑）也是它。

坑 2（会动钱）回调丢了以后没有任何人推进状态

现象：订单一直停在待支付、悬账无人处理；对账要等到「距创建满 5 分钟」才会去问通道。
根因：只靠回调推进的状态在本地环境根本收不到（回调地址指向公网 IP，开发机不可达），生产上回调也会丢。真例：两笔小额订单的悬账根因就是回调没到达，最后靠对账补查才退回。
置信档：【实测】
接手提示：每接一个新通道能力，先回答「它的查询对等物是什么」（ADR-0004）；没有查询对等物的能力不要接。

坑 3（会动钱）把回调地址当「已经注册了」

现象：生产环境即使有公网也收不到绑卡（业务开通）回调。
根因：app.payment.huifu.merchant-business-notify-url 这类键原先**在 yml 里根本不存在**，靠 notify-url 推导出一个值——「通道侧到底注册了哪个地址」取决于另一个配置，缺一个也看不出来。现在五个回调地址都显式写出并有一层启动自检；但**通道控制台上实际注册了什么，仍然只能人工核对**。
置信档：【实测】
接手提示：部署/联调时逐条比对「yml 里的五个地址 ↔ 通道侧注册的地址」，并留档。[待确认：五个回调地址当前在通道侧各注册的是什么]

坑 4（卡死流程）结算记录页整页空白，而通道里其实有流水

现象：页面一条都不显示，也没有报错。
根因：pageSize 超过通道上限 50 时，接口直接回 00000003 且**一条都不返回**（不是截断）。后台默认传 100，于是永远空白。现在前端固定 50、后端收敛、网关兜底三层。
置信档：【实测】
接手提示：给通道接口加参数前，先确认它的**硬上限**（日期跨度、总条数也要一起核）；不要假定「超限会截断」。

坑 5（卡死流程）台账唯一键里的 status 会让「结掉又开出」直接报错

现象：对账台报错：同一笔业务被反复「结掉又开出」时撞唯一键 (issue_type, provider, business_no, status)。
根因：唯一键包含 status，于是同一业务可以同时存在一条 open 与一条 resolved；resolve() 直接把 open 行改成 resolved 时撞上已存在的 resolved 行。修法是先删掉上一条结论行再落新结论，且只在确实有 open 行时才删。
置信档：【实测】
接手提示：任何「状态进唯一键」的表都有这个形态；改台账写入逻辑前先想清楚「同一业务会不会同时有两条不同状态的行」。

8. 前端触点

• 后台（Vue）：talent-card-admin/src/views/MerchantSettlementView.vue（kind === 'settlements' 就是结算记录页；没有分页控件，日期栏标签是「结算日期」）、talent-card-admin/src/views/OrderView.vue（「立即对账」按钮）。
• 后台 api：talent-card-admin/src/api/admin.ts 的 getMerchantSettlements、getMerchantSettlement（进件/银行卡）、runPaymentReconciliation。**台账两个接口（issues 列表 / 关闭 issue）在前端没有封装、也没有页面**。
• 后台触发的端点：GET /api/admin/management/merchant-settlement/settlements（日期默认最近 30 天、size 默认 50）、POST /api/admin/management/payment-reconciliation/run、GET|PATCH /api/admin/management/payment-reconciliation/issues[/{id}]。
• 商户端（uvue）：rencaika_merchant/pages/settlement-management/settlement-management.uvue（结算管理，读**本地统计**；rencaika_merchant/services/settlement-statistics.uts → /api/merchant/settlement-statistics/*）——它**不是**通道结算流水，别把它当对账依据。
• 人才端（rencaika）：与本链路无直接触点；只在「已取消订单后来收到钱」这类悬账上通过退款被影响。

以上为**逐文件核对**结果（【推断】）——uvue 端没有可编译的反馈回路（本机没有 HBuilderX / uni CLI），
改商户端页面的展示口径之后必须真机验证；后台 Vue 页可在 talent-card-admin 里本机跑。

9. 先判断「是我们还是汇付的问题」

涉及通道行为的结论都是**自测结论，汇付侧未书面确认**。要拿它做新的对接依据，先向汇付要一条书面确认。