支付链路交接文档

适用提交: 6c42f8f ｜最后验证: 2026-09-18 ｜何时会失效: 见 §5「维护契约」的触发器表

这套文档交付的是 2026-09-11 ~ 2026-09-18 完成的汇付天下/斗拱支付链路：**企业/个人进件 → 微信收款能力 → 支付 → 资金确认 → 结算**。

1. 给谁、怎么用

给接手支付链路维护的后端开发。目标不是「读完就懂」，而是**遇到问题时能自己判断「这是我们还是汇付的问题」，不必回头问人**——包括将来继续做汇付侧对接（新增支付方式、接新的能力开通）。

三条使用建议：

你只有 30 分钟	你要改支付/退款	你要接手排查线上问题
`01`（尤其 §1 图和 §4 硬规定）	`01` → `03` → `06` §1 必读 15 条	`07` → `06` §10 待确认清单

哪个问题该查哪份：

问题	权威文档
「这个字段/返回码官方是怎么规定的？」	`05` §2 + `reference/official/` 原件。不要引我方归纳
「通道为什么这么怪？」	`05` §3 的 28 条
「我们代码在哪、我该改哪？」	`01` §2 §3
「这条规矩为什么不能破？」	`01` §4 六条硬规定 + `docs/adr/`
「这个现象以前踩过吗、根因是什么？」	`06`（自包含，不必翻 git）
「线上这个症状怎么查？」	`07`
「怎么把环境跑起来 / 怎么上线？」	`08`（测试库细节在 `docs/agents/testing.md`，不在这里重复）
「这块的实现细节？」	`talent-card-server/docs/huifu-payment-integration.md`（英文，附录 A，冲突时以它为准）
「当初为什么这么决定？」	`docs/adr/0001`~`0004`

2026-09-18 全仓检索确认：没有客服对话、邮件、工单编号或官方口头结论。因此这套文档**不出现「已与汇付确认」这种说法**。凡是试出来的，一律标【实测】并注明「自测结论，汇付侧未书面确认」。

要引用「汇付是这么规定的」，只能引 reference/official/ 下的原件或官方 URL。

档	含义	你该怎么对待
【官方原件】	官方文档写了，且本地有原件可引	可以直接依赖
【官方·外部】	官方写了，但仓库内无原件	依赖前先联网复核
【实测】	我们在真实通道/真实库上验证过（有真实回执或库内数据）	可以依赖，但汇付侧没书面确认；照它做新对接被拒时，去找汇付要依据
【推断】	只有代码逻辑可推	当线索用，不要当结论

术语表在根目录 CONTEXT.md，它是唯一权威。 本套文档严格遵守其中每条的 _Avoid_ 禁用同义词——这些禁用词不是洁癖，是因为它们会和别的概念混同，混了就会写错代码。

最容易写错的几个：

用	不要用	为什么
预支付单	预订单、支付单	「支付单」会与本地订单混同。预支付单是通道侧的一张可付款凭证
支付尝试	支付流水、支付次数量词	「支付流水」是记账视角。支付尝试描述的是「一笔订单向通道发起的一次请求」
关单	取消、关闭订单	关单的对象是预支付单，取消的对象是订单——两者是不同层级的事
支付结果不确定	支付中、支付确认中	前者描述「没结论」，后者听起来像「有进度」
关单中	取消失败	「关单中」是「暂时没结论且必须重试到有结论」，不是失败
悬账	差错、异常单	悬账特指「通道确认收到、但本地订单已取消」的钱，它必须有出口

CONTEXT.md 在 2026-09-18 增量补了 3 条术语（**关单查询**、**渠道商**、**差错台账**），其余原有的都已覆盖这条链路。

谁改支付链路，谁更新对应文档。 下列事件一旦发生，必须同步改：

每份文档头部的 最后验证 字段在你确认过内容仍然成立后更新，并写明**何时会失效**。

事项	去哪
`application.yml` 四个明文凭据键改占位、私钥轮换	`.scratch/huifu-handover/issues/01-plaintext-credentials-in-application-yml.md`（独立工单，本次不动手）
`06` §10 那 16 条待确认项	各条里写明了该找谁确认
其他业务域（家属卡、洗车、停车、票券包、权益规则、资讯）	按 `AGENTS.md` 的域划分，不属于本套文档