.claude/plan/2026-08-25-alipay-batch-pay-design.md

@@ -0,0 +1,214 @@
+# 批量付款到户有密 接入设计
+
+日期：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 默认）可能导致大额批次失败 —— 页面提示查看/调整转账额度

frontend/src/views/module_payment/apikey/index.vue

@@ -1280,7 +1280,9 @@ class SignatureGenerator
         $collect = [];
         foreach ($filteredData as $key => $value) {
             if (is_array($value)) {
-                $value = json_encode($value, JSON_UNESCAPED_SLASHES);
+                // 注意: 必须加 JSON_UNESCAPED_UNICODE, 否则中文会被转义为 \uXXXX,
+                // 与文档示例及后端验签的 UTF-8 原始编码不一致, 导致签名验证失败
+                $value = json_encode($value, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
             }
             $encodedValue = rawurlencode((string)$value);
             $collect[] = "{$key}={$encodedValue}";

java/src/main/java/com/payment/platform/core/security/TenantApiKeyAuthFilter.java

@@ -11,8 +11,11 @@ import com.payment.platform.module.payment.apikey.entity.TenantApiLogEntity;
 import com.payment.platform.module.payment.apikey.mapper.TenantApiKeyMapper;
 import com.payment.platform.module.payment.apikey.mapper.TenantApiLogMapper;
 import jakarta.servlet.FilterChain;
+import jakarta.servlet.ReadListener;
 import jakarta.servlet.ServletException;
+import jakarta.servlet.ServletInputStream;
 import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletRequestWrapper;
 import jakarta.servlet.http.HttpServletResponse;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -23,9 +26,10 @@ import org.springframework.security.core.context.SecurityContextHolder;
 import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
 import org.springframework.stereotype.Component;
 import org.springframework.web.filter.OncePerRequestFilter;
-import org.springframework.web.util.ContentCachingRequestWrapper;
-
+import java.io.BufferedReader;
+import java.io.ByteArrayInputStream;
 import java.io.IOException;
+import java.io.InputStreamReader;
 import java.nio.charset.StandardCharsets;
 import java.time.OffsetDateTime;
 import java.util.List;
@@ -123,7 +127,7 @@ public class TenantApiKeyAuthFilter extends OncePerRequestFilter {
         long startTime = System.currentTimeMillis();
 
         // 包装 request 以便可以多次读取 body (Python L87-90 中读了一次 JSON body)
-        ContentCachingRequestWrapper wrappedRequest = wrapRequest(request);
+        CachedBodyRequestWrapper wrappedRequest = wrapRequest(request);
 
         // ---- 1. 提取 Authorization header (Python L37-41) ----
         String apiKey = extractApiKey(wrappedRequest);
@@ -174,6 +178,16 @@ public class TenantApiKeyAuthFilter extends OncePerRequestFilter {
         //     Python: TenantApiKeyService.verify_signature(api_key_obj.api_secret, request_data, signature)
         //     → SignatureGenerator.verify_signature(api_secret, request_data, signature)
         if (!SignatureGenerator.verifySignature(keyEntity.getApiSecret(), requestData, signature)) {
+            // 诊断日志: 记录后端实际收到的请求体与两端签名, 用于联调定位 (不记录 apiSecret)
+            try {
+                log.error("OpenAPI签名验证失败: apiKey={}, tenantId={}, 收到Signature={}, 期望签名={}, requestData={}",
+                        apiKey, keyEntity.getTenantId(), signature,
+                        SignatureGenerator.generateSignature(keyEntity.getApiSecret(), requestData),
+                        objectMapper.writeValueAsString(requestData));
+            } catch (Exception e) {
+                log.error("OpenAPI签名验证失败: apiKey={}, 收到Signature={} (记录请求体失败: {})",
+                        apiKey, signature, e.getMessage());
+            }
             // Python L106: "Invalid Signature"
             logApiCall(keyEntity.getId(), keyEntity.getTenantId(), request, response, 401, startTime);
             writeAuthError(response, ErrorCode.AUTH_FAILED.getCode(),
@@ -251,8 +265,8 @@ public class TenantApiKeyAuthFilter extends OncePerRequestFilter {
      * 读取请求体 JSON — 对应 Python L87-90
      *   request_data = await request.json()
      */
-    private Map<String, Object> readRequestBody(ContentCachingRequestWrapper request) {
-        byte[] content = request.getContentAsByteArray();
+    private Map<String, Object> readRequestBody(CachedBodyRequestWrapper request) {
+        byte[] content = request.getCachedBody();
         if (content.length == 0) {
             return Map.of();
         }
@@ -343,10 +357,77 @@ public class TenantApiKeyAuthFilter extends OncePerRequestFilter {
 
     // ========================= 工具 =========================
 
-    private ContentCachingRequestWrapper wrapRequest(HttpServletRequest request) {
-        if (request instanceof ContentCachingRequestWrapper) {
-            return (ContentCachingRequestWrapper) request;
+    private CachedBodyRequestWrapper wrapRequest(HttpServletRequest request) {
+        if (request instanceof CachedBodyRequestWrapper) {
+            return (CachedBodyRequestWrapper) request;
+        }
+        try {
+            return new CachedBodyRequestWrapper(request);
+        } catch (IOException e) {
+            // 读取 body 失败(连接中断等): 记录日志, 返回无 body 的包装(验签会失败, 由后续逻辑处理)
+            log.warn("缓存请求体失败: {}", e.getMessage());
+            return new CachedBodyRequestWrapper(request, new byte[0]);
+        }
+    }
+
+    // ========================= 请求体缓存 wrapper (支持多次读取) =========================
+
+    /**
+     * 构造时一次性读入请求体, getInputStream()/getReader() 基于缓存的 byte[] 返回新流,
+     * 因此 filter 验签消费后, Controller 的 @RequestBody 仍可正常读取。
+     *
+     * 不能使用 ContentCachingRequestWrapper: 其 getInputStream() 只返回同一个流,
+     * 被消费后即 EOF, Controller 再读会得到空 body → HttpMessageNotReadableException
+     * "Required request body is missing"。
+     */
+    static class CachedBodyRequestWrapper extends HttpServletRequestWrapper {
+        private final byte[] body;
+
+        CachedBodyRequestWrapper(HttpServletRequest request) throws IOException {
+            super(request);
+            try (ServletInputStream is = request.getInputStream()) {
+                this.body = is.readAllBytes();
+            }
+        }
+
+        CachedBodyRequestWrapper(HttpServletRequest request, byte[] body) {
+            super(request);
+            this.body = body;
+        }
+
+        byte[] getCachedBody() {
+            return body;
+        }
+
+        @Override
+        public ServletInputStream getInputStream() {
+            ByteArrayInputStream bais = new ByteArrayInputStream(body);
+            return new ServletInputStream() {
+                @Override
+                public int read() {
+                    return bais.read();
+                }
+
+                @Override
+                public boolean isFinished() {
+                    return bais.available() == 0;
+                }
+
+                @Override
+                public boolean isReady() {
+                    return true;
+                }
+
+                @Override
+                public void setReadListener(ReadListener listener) {
+                    // 非异步读取, 无需回调
+                }
+            };
+        }
+
+        @Override
+        public BufferedReader getReader() {
+            return new BufferedReader(new InputStreamReader(getInputStream(), StandardCharsets.UTF_8));
         }
-        return new ContentCachingRequestWrapper(request);
     }
 }

java/src/test/java/com/payment/platform/core/security/TenantApiKeyAuthFilterTest.java

@@ -0,0 +1,39 @@
+package com.payment.platform.core.security;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockHttpServletRequest;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+/**
+ * 回归测试: CachedBodyRequestWrapper 必须支持多次读取请求体。
+ * 认证 filter 验签时要读一次 body, Controller 的 @RequestBody 还要再读一次,
+ * 若 wrapper 只支持读一遍, Controller 会收到空 body →
+ * HttpMessageNotReadableException "Required request body is missing"。
+ */
+class TenantApiKeyAuthFilterTest {
+
+    @Test
+    void cachedBodyCanBeReadByFilterThenByController() throws IOException {
+        String json = "{\"amount\":\"0.10\",\"remark\":\"完整签名复测\"}";
+        MockHttpServletRequest req = new MockHttpServletRequest("POST",
+                "/api/v1/payment/openapi/account/transfer");
+        req.setContentType("application/json;charset=UTF-8");
+        req.setContent(json.getBytes(StandardCharsets.UTF_8));
+
+        TenantApiKeyAuthFilter.CachedBodyRequestWrapper wrapped =
+                new TenantApiKeyAuthFilter.CachedBodyRequestWrapper(req);
+
+        // 第一次读: 模拟 filter 验签消费 body
+        assertEquals(json, new String(wrapped.getInputStream().readAllBytes(), StandardCharsets.UTF_8));
+
+        // 第二次读: 模拟 Controller 的 @RequestBody (Jackson 通过 getInputStream 读)
+        assertEquals(json, new String(wrapped.getInputStream().readAllBytes(), StandardCharsets.UTF_8));
+
+        // getReader 路径也应可读 (部分 MVC 配置走 reader)
+        assertEquals(json, new String(wrapped.getReader().readLine()));
+    }
+}