# 批量付款到户有密 接入设计

日期：2026-08-25
状态：已与用户确认（2026-08-25）

## 1. 背景与目标

将支付宝邀测产品「**批量付款到户有密**」（批量转账到支付宝账户）接入 xjz-payment-platform。

**业务目标**：赋能企业客户批量付款 —— 平台代企业制单，企业财务在自己的支付宝端内输入一次支付密码确认，批量付款给外部支付宝账号（发薪、报销、佣金、供应商结算等）。资金**不经过平台账户**，付款方（企业）掌控资金，安全性高于现有记账本直付链路。

**与现有体系的关系**：现有资金链路是「支付宝安全发」（签约→进件→开通记账本→充值→单笔转账），与本产品是**两个独立产品**，并行共存，互不影响。

**接入角色**：付款方仅限平台入驻的企业客户（企业码场景）；平台以企业绑定的服务商 AppID 调用 API（沿用现有 `AlipayClientFactory.getClient(enterpriseId, bizType)` 模式，资金接口证书加签）。

**操作渠道**：PC 网页版（制单授权 channel=pc、支付页 PC 版），每批最多 1000 笔。

**收款方来源**：仅外部支付宝账号（手填或 Excel 导入），不关联平台员工体系。

## 2. 产品关键约束（来自支付宝邀测文档）

### 2.1 API 清单

| 环节 | 接口 | 用途 |
|---|---|---|
| 制单授权 | `alipay.fund.authorize.uni.apply` | 生成授权短链接（PC/小程序），付款方端内授权 |
| 授权查询 | `alipay.fund.authorize.uni.query` | 查询单一协议授权状态 |
| 授权通知 | `alipay.fund.authorize.status.notify` | 签约/解约异步通知（订阅 from 蚂蚁消息） |
| 批次下单 | `alipay.fund.batch.create` | 创建批量付款单据 |
| 渲染支付 | `alipay.fund.trans.render.pay` | 生成 PC/小程序支付页，付款方输密码完成 |
| 批次通知 | `alipay.fund.batch.order.changed` | 批次状态异步通知 |
| 批次查询 | `alipay.fund.batch.detail.query` | 批次+明细状态查询（兜底） |
| 批次关单 | `alipay.fund.batch.close` | 主动关闭未支付批次 |
| 电子回单（**二期**） | `alipay.data.bill.ereceiptagent.apply` / `alipay.data.bill.accountbookereceipt.query` | 申请/查询回单，本期不做

### 2.2 关键参数

**授权申请（uni.apply）**：
- `product_code` = `TRANSFER_API_STANDARD_AUTHORIZATION`（固定）
- `biz_scene` = `STANDARD_CREATE_FUND_ORDER`（固定）
- `authorize_link_type` = `SHORT_URL`（固定）
- `channel` = `pc`（PC 网页版）
- `principal_info.participant_id` = 付款方支付宝 uid；`participant_id_type` = `ALIPAY_USER_ID`
- 出参：`authorize_link`（短链接）

**批次下单（batch.create）**：
- `product_code` = `BATCH_API_TO_ACC`（固定）；`biz_scene` = `STANDARD_MESSAGE_BATCH_PAY`（固定）
- `out_batch_no` 商户唯一；`total_trans_amount`、`total_count`
- `order_title` 必填（展示在付款方账单）；`time_expire`（绝对时间，格式 `yyyy-MM-dd HH:mm`）
- `payer_info`：付款方 uid + `ext_info.agreement_no`（制单授权协议号，传则校验该协议）
- `trans_order_list[]`：每笔 `out_biz_no`（批内唯一）、`trans_amount`（≥1 元）、`payee_info`（identity + identity_type，LOGON_ID 时 name 必填且校验姓名一致）、`remark`
- **转账场景报备（26 年新接入商户必传）**：`transfer_scene_name` + `transfer_scene_report_infos[]`（`info_type` + `info_content`）
- 出参：`batch_trans_id`（支付宝批次号，有效期 30 天）

**渲染支付（render.pay）**：入参 `batch_trans_id`，出参支付 URL（PC 版浏览器打开）。

### 2.3 额度与限制

- 默认：单笔 5000 / 日 20000 / 月 600000 元；自助提额上限：单笔 50000 / 日 100000 / 月 1000000 元
- 每批最多 **1000 笔**（PC 渠道），明细金额 ≥1 元
- 部分明细因收款账户问题转账失败时，支付宝原路退回该明细金额（明细级别状态跟踪）

### 2.4 授权特性

- 授权一旦完成**永久生效**；终止只能付款方在支付宝 APP 端手动解约
- 授权链接**一次有效**，重新授权需换外部单号
- 同一付款方与平台间已存在授权协议则不允许重复新增
- 付款方和请求方一致时，跳过制单授权校验

### 2.5 接入前置条件

- 邀测产品，需联系支付宝业务人员开通「批量付款到户有密」；商家平台开通「商家转账」产品
- 应用网关：指向平台统一通知入口（现有 `/payment/notify`）
- 订阅 from 蚂蚁消息：`alipay.fund.authorize.status.notify`、`alipay.fund.batch.order.changed`
- 资金支出接口强制证书加签（现有服务商资金类客户端已是证书模式）
- 不支持服务商代开发 —— 由企业绑定服务商 AppID 模式接入（平台代持，已确认）

## 3. 业务流程

```
企业财务（PC）                     平台 (Java 后端)                        支付宝
   │                                  │                                     │
   │ ① 打开「制单授权」页面            │                                     │
   │◄─ 授权短链(PC) ──────────────────│─ fund.authorize.uni.apply ──────────►│
   │ 浏览器打开链接                    │                                     │
   │◄════════════ 支付宝授权页 ════════╪══════════════════════════════════════►│
   │ 输密码授权（永久生效，一次一链）   │                                     │
   │◄════════ 授权完成 ────────────────│─ status.notify 异步通知 ────────────►│
   │ ② 创建批次（≤1000笔外部账号）     │  fund.batch.create ─────────────────►│
   │◄─ 支付URL ────────────────────── │─ fund.trans.render.pay(PC) ─────────►│
   │ ③ 新窗口打开支付页                │                                     │
   │◄══════════ 支付宝端输一次密码 ════╪══════════════════════════════════════►│
   │ ④ 查批次列表/明细                 │◄─ fund.batch.order.changed 通知 ─────│
   │                                  │◄─ fund.batch.detail.query 兜底 ──────│
```

状态流转：批次 `INIT`（已受理）→ 支付后 `SUCCESS`（终态）/ 部分明细失败原路退回；`DISUSE`（关闭，终态，换外部单号重试）；批次创建后 30 天未支付自动关单（或 `time_expire` 控制）。

## 4. 数据模型（3 张新表）

沿用现有 base entity 体系（`PaymentEnterpriseBaseEntity`：tenant_id、enterprise_id 等）。

### 4.1 `pay_batch_authorize` — 制单授权记录

| 字段 | 类型 | 说明 |
|---|---|---|
| out_biz_no | varchar(64) | 授权外部单号（雪花），唯一 |
| enterprise_id | varchar(64) | 所属企业 |
| participant_id | varchar(64) | 付款方支付宝 uid |
| participant_id_type | varchar(16) | ALIPAY_USER_ID |
| agreement_no | varchar(64) | 制单授权协议号（授权完成后回填） |
| status | varchar(32) | AUTHING / AUTHED / UNBIND |
| authorize_link | varchar(512) | 生成的短链接 |
| authorize_expire_time | datetime | 链接超时时间 |

### 4.2 `pay_batch_order` — 批次主表

| 字段 | 类型 | 说明 |
|---|---|---|
| out_batch_no | varchar(32) | 商户批次唯一单号 |
| batch_trans_id | varchar(32) | 支付宝批次订单号（唯一索引） |
| total_amount | decimal(16,2) | 批次总金额 |
| total_count | int | 总笔数 |
| order_title | varchar(64) | 批次标题（账单展示） |
| status | varchar(32) | INIT / SUCCESS / DISUSE / FAIL |
| time_expire | datetime | 超时关单时间 |
| payer_uid | varchar(64) | 付款方 uid |
| agreement_no | varchar(64) | 制单授权协议号 |
| transfer_scene_name | varchar(64) | 转账场景（26 年新接入必传） |
| transfer_scene_report_infos | jsonb | 场景报备信息 [{info_type, info_content}] |
| remark | varchar(200) | 业务备注 |
| pay_url | varchar(1024) | render.pay 生成的支付 URL |
| receipt_file_id / receipt_status | — | 电子回单（二期可做） |
| error_code / error_msg | varchar | 错误信息 |

### 4.3 `pay_batch_detail` — 批次明细表

| 字段 | 类型 | 说明 |
|---|---|---|
| batch_id | bigint | 关联批次主键 |
| out_biz_no | varchar(64) | 明细外部单号（批内唯一） |
| amount | decimal(16,2) | 明细金额（≥1 元） |
| remark | varchar(100) | 转账备注（展示在收款方账单） |
| payee_identity | varchar(64) | 收款方账号（uid/账号/openid） |
| payee_identity_type | varchar(32) | ALIPAY_LOGON_ID / ALIPAY_USER_ID / ALIPAY_OPEN_ID |
| payee_name | varchar(256) | 收款方姓名（LOGON_ID 必填，校验姓名一致） |
| status | varchar(32) | INIT / SUCCESS / FAIL |
| error_code / error_msg | varchar | 明细级错误 |

## 5. 后端设计（Java，`module/payment/batch/` 新包）

### 5.1 `AlipayBatchPayService`

复用 `AlipayClientFactory.getClient(enterpriseId, "BATCH_PAY")`（服务商证书模式，bizType 走 `pay_service_provider_profile` 专属凭证，无专属配置回退服务商默认）。

- `authorizeApply(enterpriseId, participantId)` → 调 uni.apply，落授权记录，返回短链接
- `queryAuthorize(enterpriseId, outBizNo)` → 调 uni.query，更新授权状态
- `batchCreate(BatchCreateDTO)` → 校验（授权存在、笔数 ≤1000、金额 ≥1 元、场景报备）→ 调 batch.create → 落批次+明细
  - 幂等：`out_batch_no` 唯一；返回 `UNIQUE_VIOLATION` 时查询批次后再决定
- `renderPay(outBatchNo)` → 调 render.pay，回填 pay_url
- `batchQuery(outBatchNo)` → 调 batch.detail.query，同步批次+明细状态（定时/手动兜底，沿用现有 transferSyncAllService 定时同步模式）
- `batchClose(outBatchNo)` → 调 batch.close
- 通知处理（供 handler 调用）：授权状态更新、批次状态更新、明细逐笔更新

### 5.2 `BatchPayController` — `/payment/account/batch/*`（挂在现有资金账户模块下）

| 接口 | 权限 | 说明 |
|---|---|---|
| POST `/authorize/apply` | module_payment:account:authorize | 生成授权链接 |
| GET `/authorize/query` | module_payment:account:authorize | 查询授权状态 |
| GET `/authorize/list` | module_payment:account:transfer:list | 授权列表 |
| POST `/create` | module_payment:account:transfer | 创建批次 |
| POST `/pay` | module_payment:account:transfer | 生成支付 URL |
| GET `/list` | module_payment:account:transfer:list | 批次列表（分页/状态/时间筛选） |
| GET `/detail` | module_payment:account:transfer:detail | 批次详情+明细 |
| POST `/close` | module_payment:account:transfer | 关闭批次 |
| GET `/export` | module_payment:account:transfer:list | 导出（复用现有 transferExport 模式） |

### 5.3 异步通知（复用现有入口，零新增端点）

- `AlipayNotifyMethod` 枚举新增：`FUND_AUTHORIZE_STATUS_NOTIFY("alipay.fund.authorize.status.notify")`、`FUND_BATCH_ORDER_CHANGED("alipay.fund.batch.order.changed")`
- 新增 `BatchPayHandler extends BaseNotifyHandler`，注册上述两个 method，通过 `NotifyContext` 注入 batch mapper；处理：授权签约/解约更新授权表、批次状态更新 + 明细逐笔更新 + 记 `pay_alipay_notify_log`
- 验签沿用现有 `/payment/notify` 入口的验签机制（实现时确认 NotificationService 按 app_id 解析公钥的细节）
- 通知处理幂等：同一 notify_id / 终态不重复更新

## 6. 前端设计（资金账户模块新增「批量付款」）

- **制单授权页**：生成授权短链接（PC 复制/二维码），授权状态展示，重新授权按钮
- **批次列表页**：分页、状态筛选、时间筛选、导出；行操作：支付（打开支付 URL）、查看详情、关闭
- **创建批次页**：手填明细 / Excel 导入（模板下载：收款账号、类型、姓名、金额、备注）；转账场景选择（现金营销/企业退款/佣金报酬/二手回收/业务结算/公益补助/行政补贴退款/保险理赔）+ 报备信息录入
- **批次详情页**：批次信息 + 明细表格（逐笔状态）+ 支付按钮
- 支付页：`pay_url` 新窗口打开（支付宝 PC 支付页）

## 7. 错误处理与幂等

- 批次创建：`out_batch_no` 唯一索引；系统异常/未明确错误码时保持原单号重试；`UNIQUE_VIOLATION` → 查批次状态，已受理则不再重复创建
- 通知重复：以终态和 notify_id 判重
- 明细部分失败：支付宝原路退回，明细级状态跟踪，批次状态为 SUCCESS（部分明细 FAIL），列表展示明细级失败原因
- 授权链接过期/重复授权：提示重新生成（换 out_biz_no）
- 批次超时：`time_expire` 控制，DISUSE 终态提示换单重试

## 8. 测试

- **Java 单测**：`AlipayBatchPayService`（Mock 支付宝 SDK 响应）：授权申请/查询、批次创建幂等（UNIQUE_VIOLATION）、状态同步、通知处理幂等
- **前端 Playwright**：走通「生成授权链接 → 创建批次（导入明细）→ 生成支付 URL」链路，批次列表/详情渲染
- 通知 handler 单测：两个新 msg_method 分发正确

## 9. 前置条件与风险

- **邀测产品**：需联系支付宝业务人员开通；未开通前联调不可行 → 联调用沙箱/文档响应 Mock
- 转账场景报备为 26 年新接入必传 —— 前端录入 + 后端校验必填
- 服务商需配置应用网关 + 订阅 from 蚂蚁消息（运营操作，需与客户确认）
- 授权为永久性协议，平台不可解约 —— 授权管理页需明确提示
- 额度限制（单笔 5000 默认）可能导致大额批次失败 —— 页面提示查看/调整转账额度