9.8-人民币结汇 POBO、锁汇与提现付款页面选项优化

1. 背景与目标

1.1 业务背景与问题

1. 人民币结汇 POBO。易宝人民币结汇接口同名付款必须先向通道报备付款人，且报备状态为成功后方可使用。当前平台未对接，商户无法以自己名义完成人民币端付款，收款方对账付款人名称与预期不符，产生退汇/驳回与人工核对成本。
2. 结汇汇率波动与 60 秒锁汇诉求。人民币结汇（外币兑人民币）交易受汇率实时波动影响大，商户在下单时需要明确锁定汇率并精准试算扣款或到账金额。上游已开放 60 秒询价锁汇能力（支持定额买与定额卖），当前系统未对接，商户无法锁汇下单，导致实际成交汇率与下单预期存在偏差。
3. 上游同名付款规则收紧。通过国际汇款（SWIFT）方式发起的所有交易，不再支持以平台付款人（Global Payment E-Commerce Limited）名义付款，仅支持以子商户注册企业主体名义付款——即 SWIFT 不再支持非同名付款。当前付款表单对 SWIFT 非同名组合不拦截，订单提交后被通道拒绝。
4. 提现页面缺少同名付款口径。同名付款选项仅存在于付款表单，提现（CNY 到账同样走人民币端付款）未同步，口径不一致。
5. 中间行费用承担方与清分方式不符。中间行费用仅存在于 SWIFT 电汇链路；当前表单在 Local（本地清分）账户下仍展示「中间行费用承担方」选项，误导商户选择无意义的承担方式。

1.2 目标与成功标准

1.3 不做的影响

若不对接：人民币端以商户主体名义付款（POBO）能力无法开放；结汇汇率波动造成商户成本不可控与对账纠纷；SWIFT 非同名订单持续被上游拒绝形成失败订单与客诉；提现与付款口径分裂。

2. 用户角色与场景

2.1 角色、权限与职责

2.2 核心业务场景

3. 功能范围

3.1 能力清单与发布状态

3.2 In Scope / Out of Scope

4. 页面/交互说明

4.1 F-01 / F-02 付款人报备链路（系统侧，无页面）

1. 纳入：商户 KYC 认证通过（终态成功）当刻自动进入待报备名单，商户无感知、无消息。
2. 报备：定时任务按批次汇总「待报备」商户，向通道提交付款人设置（入参仅 subMerchantId），提交后置「报备中」。
3. 查询：定时任务对「报备中」商户批量查询并回写：成功 / 失败（含失败原因）。查询返回注销（CLOSE）本期不做处理：忽略该返回、不回写、不重报，商户状态保持不变。
4. 无自动重试：报备失败后系统不做自动重试；状态保持「报备失败」，等待线下人工介入处置或运维手动 job 重新报备。
5. 告警机制（双触发，对接新 outbox 服务）：
   • 告警邮件统一通过系统新 outbox 服务发送，收件邮箱支持独立单独配置；
   • 1 次失败即告警：通道查询返回失败（FAILED）或提交通道失败时，立即发送告警邮件（含商户号、企业名称、失败原因、发生时间）；
   • 120 分钟超时告警：待报备/报备中累计停留超过 120 分钟仍未变更为 SUCCESS 终态，立即发送告警邮件（含商户号、企业名称、当前状态、停留时长）。
   • 报备成功后告警状态解除；同一故障生命周期内不重复触发同一类型告警。
6. 运维手动兜底：运维层手动报备 job 按单商户号立即发起一次报备（等同批次报备效果），结果仍走定时查询回写；job 仅在运维层使用，不处理记录；不影响自动链路。

报备/查询频率、批量大小、幂等与退避属研发设计；业务约束：批处理、全自动、商户无感知、即时告警、job 不处理记录。完整规则（含异常态）见 prd/9月迭代-R12-人民币结汇POBO付款人报备.md §4~§7。

4.2 F-03 / F-04 付款页与提现页「是否同名付款」选项（两页同构）

4.2.1 业务流程

进入付款/提现表单 → 选择币种 → 选择收款账户（供应商）/提现卡
    ↓
展示「是否同名付款」选项（是 / 否）：
    ├─ 「是（同名付款）」：可正常选择；**人民币结汇（到账 CNY）场景**提交时校验报备状态——
    │     报备成功 → 正常提交（结汇下单透传 appointPayerId）
    │     未成功（待报备/报备中/失败）→ 提交报错，按状态提示原因（文案 A/B）
    │     （报备仅影响人民币结汇；海外付款无论 SWIFT/Local 均不做报备校验）
    └─ 「否（非同名）」：按清分方式判定——
          SWIFT 账户 → 选项禁用不可选（F-05）
          Local 账户 → 可选，正常提交（本期不区分地区，见 Out of Scope）

图 4-1 商户端付款表单（对应 R-02~R-06：到账 CNY 时同名付款是/否均可选，未报备成功在提交时报错拦截，无承担方选项）

4.2.2 业务规则与联动

4.2.3 提现页差异与同构说明

提现页面与付款页在「其他信息」卡片布局、同名付款选项位置、SWIFT 禁非同名规则上完全同构；提现全部场景均不展示中间行费用承担方（固定记录 OUR）。

图 4-2 商户端提现表单（对应 R-07、R-15：同名付款选项位于「其他信息」卡片中，与付款页完全同构，是/否均可选，提现无承担方）

4.3 F-06 清分方式展示与承担方选项联动（仅外币 SWIFT 付款展示承担方；提现与其余场景无承担方）

承担方按业务场景呈现差异：

图 4-3 商户端付款表单（外币 SWIFT 场景：清分方式 SWIFT，同名付款仅支持“是”，展示「中间行费用承担方」选项 OUR/SHA，无 BEN）

图 4-4 商户端付款表单（外币 Local 场景：清分方式 LOCAL，同名付款是/否均可选，无中间行费用承担方）

图 4-5 商户端提现表单（外币 SWIFT 场景：清分方式 SWIFT，同名付款仅支持“是”，提现全场景无中间行费用承担方）

4.4 F-07 / F-08 人民币结汇 60 秒询价锁汇与下单交互说明

4.4.1 业务流程与锁汇时序

进入人民币结汇付款/提现表单 → 选择付款原币（USD/EUR等）与到账币种（CNY）
    ↓
选择交易方向并输入金额：
    ├─ 定额卖（CUSTOMER_SELL）：输入外币付款金额（系统内部统一按外扣 OUTER 计算手续费）
    └─ 定额买（CUSTOMER_BUY）：输入人民币到账金额（系统内部统一按外扣 OUTER 计算手续费）
    ↓
系统自动调用询价接口（/rest/v1.0/gpt/stdexc/inquiry，feeBear 固定传 OUTER）锁汇 60 秒：
    ├─ 返回询价令牌 inquiryToken、参考汇率 fxRate、手续费 feeAmount、出款金额 debitAmount、到账金额 paymentAmount
    ├─ 表单启动 60 秒锁汇倒计时，展示「锁汇汇率：1 USD = x.xxxx CNY（有效时间剩 xx 秒）」与试算明细
    ↓
商户操作与提交：
    ├─ 60 秒内点击「提交」：发起结汇下单（/rest/v1.0/gpt/stdexc/commit-order）——
    │     * 付款金额 amount 字段必填：严格取自锁汇返回的 debitAmount 进行上送！
    │     * 必传参数：inquiryToken、tradeSide、paymentAmount、paymentCurrency="CNY"、feeBear="OUTER"
    │     * 若勾选「是（同名付款）」，同时透传报备成功的 appointPayerId
    └─ 超过 60 秒未提交：锁汇令牌失效，提交按钮置灰/点击拦截提示「汇率已失效，请重新获取汇率」
          商户点击「刷新汇率」重新触发询价锁汇，重置 60 秒倒计时

4.4.2 锁汇与下单规则

5. 字段说明

5.1 关键业务字段

5.2 付款人报备状态枚举（商户级，唯一状态口径）

注销（CLOSE）本期不做处理：状态机不含注销态；查询返回 CLOSE 时忽略、不回写、不重报，商户保持原状态，页面与提交行为不变。上游 CLOSE 枚举与本地状态的映射仅保留 SUCCESS/PROCESSING/FAILED 三项。

6. 业务状态与服务支撑

6.1 业务状态流转

【付款人报备状态机】
（KYC 认证通过）→ 待报备 ─── 停留超 120 分钟 ───→ [outbox 服务发告警邮件至独立配置邮箱]
                     ↓
                   报备中 ─── 停留超 120 分钟 ───→ [outbox 服务发告警邮件至独立配置邮箱]
                     ├─成功→ 报备成功（终态，同名付款正常提交）
                     └─失败→ 报备失败（不做系统重试；1 次失败立即 [outbox 发告警邮件]；运维层 job 不处理记录处置）

【人民币结汇 60 秒锁汇状态机】
输入金额/切换条件 → 发起询价锁汇（feeBear=OUTER） → 锁汇成功（60s 倒计时中）
                                                     ├─ 60s 内点击提交 ──→ 下单 amount 严格取锁汇 debitAmount 上送下单成功
                                                     └─ 超过 60s 未提交 ─→ 锁汇失效（提交拦截，提示点击「刷新汇率」重新锁汇）

6.2 关联研发设计

• 上游接口与通知契约：
  1. 设置付款人（主动请求）：向通道设置同名付款人，请求参数仅 subMerchantId（子商户编号，string(32)，非必填），无额外明细字段；上游状态 PROCESSING/SUCCESS/FAILED/CLOSE 与 §5.2 枚举一一映射。
  2. 设置付款人信息结果通知（Webhook / Callback）：
     • 说明：下方为解密后的明文参数结构，解密过程和对接流程请参考：结果通知机制说明；
     • 通知类型：type 固定为 EXCHANGE_APPOINTPAYER_RESULT；
     • 通知参数表：

 - **通知接收与处理逻辑**：
   - 收到通知后按统一解密机制解密验签；
   - 根据 `merchantId` / `requestId` 匹配本地商户报备记录：
     - `status = SUCCESS`：本地回写状态为「报备成功」，持久化存储 `appointPayerId` 与 `appointPayerName`；
     - `status = FAILED`：本地回写状态为「报备失败」，持久化存储 `errorMsg`，并立即触发 outbox 服务发送失败告警邮件；
     - `status = CLOSE`：按本期规则忽略不回写，保持原状态；
     - `status = PROCESSING`：保持「报备中」。
   - 异步结果通知与主动定时查询任务（queryPayer）互为补充，任一通道先返回终态均可完成本地状态收敛。

1. 人民币结汇-询价：POST https://openapi.gptransfer.hk/yop-center/rest/v1.0/gpt/stdexc/inquiry，锁汇有效 60 秒，请求 feeBear 固定传 OUTER，返回 inquiryToken、validSeconds、fxRate、feeAmount、debitAmount、paymentAmount 等。
2. 人民币结汇-请求：POST https://openapi.gptransfer.hk/yop-center/rest/v1.0/gpt/stdexc/commit-order，付款金额字段 amount 必填且必须严格取自锁汇返回的 debitAmount；携带 inquiryToken、tradeSide、paymentAmount、paymentCurrency="CNY"、feeBear="OUTER"、appointPayerId（同名付款）发起结汇下单。
   • 系统服务与任务设计：
3. 批量报备、异步通知接收解析与定时查询补偿任务设计；
4. 邮件告警对接新 outbox 服务，告警收件邮箱通过独立配置项维护；
5. 运维层手动 job：仅限运维命令行工具，不处理审计与数据库记录；
6. 前端 60 秒倒计时组件与超时守卫拦截逻辑。

7. 异常/边界/权限

8. 验收标准