pingpp-v2-payment

在现有 Java Spring Boot 项目中集成 Ping++ 合规分账产品。

使用时机

触发条件：

用户使用 /pingpp-v2-payment 触发
用户要求在项目中接入/对接/集成 Ping++ 合规分账
用户提到 "合规分账"、"pingpp"、"分账接入"、"Ping++ 集成" 并需要写代码

不触发条件：

用户只是讨论分账业务逻辑而不需要写代码
用户要求对接其他支付产品

前置条件

执行本 Skill 前，用户需提供：

| 准备项 | 说明 | |--------|------| | SDK jar | pingpp-sdk-x.x.x.jar（由 Ping++ 提供，用户须提供给 AI） | | API 接口文档 | 最新版本（由 Ping++ 提供，用户须提供给 AI） | | app_id | Ping++ 开户时提供 | | RSA 签名私钥 | PKCS#8 格式 PEM 文件 | | SM2 加密公钥 | PEM 文件，用于敏感字段加密 | | RSA 验签公钥 | PEM 文件，用于验证响应签名 |

关键规则

以下规则在整个 Skill 执行过程中必须遵守，违反将导致编译失败或运行时错误：

敏感字段必须加密 — password、银行卡号（bank_acct_no）、身份证号（id_no）、手机号（mobile_number）等字段必须先 Pingpp.encryptField(value) 再放入 params
SDK 全局配置通过静态方法 — Pingpp.setAppId()、Pingpp.setSignPrivateKeyPath() 等，在 Spring Bean @PostConstruct 调用
params key 使用下划线命名 — out_order_no、out_user_id，与 API 文档一致
响应类型必须使用 javap 输出的精确类名 — 不得推测/简化类名。例如：电子回单返回 ElectronicReceiptStoreResp（非 ~~ElectronicReceiptResp~~），余额流水返回 BalanceTxnListResp/BalanceTxnResp（非 ~~BalanceTransactionResp~~），短信返回 PersonalValidationSmsCodeResp/SmsCodeVerifyResp（非 ~~PersonalValidationResp~~）
文件上传走 Media 类 — Media.uploadImage(file, options) / Media.uploadFile(file, params, options)
RequestOptions 支持多租户 — 默认用 RequestOptions.getDefault()，需要时可按请求覆盖
方法签名必须通过 javap 验证后才能调用 — API 文档字段 ≠ SDK 实际方法签名，必须先 javap 反编译 jar 确认
SDK 版本可能变化 — 不硬编码版本号，每次通过 javap 动态确认当前 jar 的方法签名
禁止推测/编造 SDK 类名 — 所有 import、返回类型、变量类型必须来自 javap 输出的精确全限定类名。SDK 命名不规则（如 ElectronicReceiptStoreResp 而非 ElectronicReceiptResp，BalanceTxnResp 而非 BalanceTransactionResp），绝对不能凭直觉猜测
默认 Java 8 — 如果用户未明确指定 Java 版本，生成的代码必须兼容 Java 8（不使用 var、List.of()、Map.of()、text block、record、switch expression 等高版本语法）
必须使用带 RequestOptions 参数的方法重载 — SDK 中不带 RequestOptions 的 create(Map)、freeze(Map)、destroy(Map)、removeById()、uploadImage(File)、sendSmsCode(Map) 等方法均已标记 @Deprecated。生成代码时始终使用带 RequestOptions 的版本，传入 RequestOptions.getDefault()
每个写接口必须生成强类型 Request DTO — Service 方法的入参必须是自定义 Request 对象（如 PingppCreatePaymentRequest），禁止直接暴露 Map<String, Object> 作为 Service 方法签名参数。DTO 字段来源为 API 接口文档的请求参数表，字段使用驼峰命名、Lombok @Data，在 Service 内部将 DTO 字段转换为 Map<String, Object> 再传入 SDK。查询类接口如参数 ≥2 个也须定义 Query DTO

核心工作流程

第一步：前置确认

确认 SDK 和文档

确认用户已提供 SDK jar 文件和 API 接口文档。如未提供，提示用户联系 Ping++ 技术支持获取。

分析现有项目

扫描当前工作目录，了解：项目结构、构建工具（Maven/Gradle）、Spring Boot 版本、现有配置格式、代码风格。

如果当前目录不是 Java 项目，使用 AskUserQuestion 确认目标项目路径。

确认对接参数 [确认节点]

向用户确认：app_id、目标环境（测试/生产）、密钥文件路径、需要接入的接口列表。

核心接口（默认全选）：

用户管理：创建用户、查询用户
个人认证：认证申请、查询认证、修改个人信息
企业认证：查询受益人、认证申请、查询认证、修改企业信息、补充受益人
结算账户：新增、查询（按 ID/out_order_no/user）、删除、打款验证
场景账户：创建、查询、冻结/解冻、关闭、下载开户通知书
充值：创建充值、查询充值
余额消费：创建消费/转账、查询消费
退款：创建退款、查询退款
提现：创建提现、查询提现
分账：分账授权、创建分账、查询分账
电子回单：生成回单、查询回单
余额流水：查询余额流水
短信验证：发送验证码、验证验证码
文件上传：上传图片、上传文件
Webhook：事件回调处理

业务流程与接口依赖

① 创建用户(User.create) → out_user_id
② 个人/企业认证(CusApplication/MchApplication.create) → 认证状态
③ 新增结算账户(SettleAcct.create) → settle_acct_id
④ 创建场景账户(BalanceAcct.create) → balance_acct_id
⑤ 充值(Deposit.create) → deposit_id → 用户余额入账
⑥ 余额消费/转账(Payment.create) → payment_id
⑦ 退款(Refund.create) → refund_id
⑧ 提现(Withdrawal.create) → withdrawal_id
⑨ 分账授权(Allocation.auth) + 分账(Allocation.create) → allocation_id
⑩ 电子回单(ElectronicReceipt.create) → 下载回单
⑪ 余额流水(BalanceTransaction.retrieveList) → 对账
⑫ Webhook → 异步事件通知

| 接口 | 前置依赖 | 产出数据 | |------|----------|----------| | User.create | 无 | out_user_id | | CusApplication.create | out_user_id | cus_application_id | | MchApplication.create | out_user_id | mch_application_id | | SettleAcct.create | out_user_id | settle_acct_id | | BalanceAcct.create | out_user_id | balance_acct_id | | Deposit.create | out_user_id + acct_scene | deposit_id | | Payment.create | out_user_id + acct_scene + 余额 | payment_id | | Refund.create | payment_id | refund_id | | Withdrawal.create | out_user_id + acct_scene + 余额 | withdrawal_id | | Allocation.auth | balance_acct_id | allocation_auth_id | | Allocation.create | out_user_id + 余额 | allocation_id | | ElectronicReceipt.create | trade_id | electronic_receipt_id |

快速验证：查询类接口（retrieveById / retrieveByOutOrderNo）无需前置数据，用不存在的 ID 查询，只要抛 InvalidRequestException（404）而非 AuthenticationException（401）就说明签名通信正常。

第二步：集成 SDK

将用户提供的 SDK jar 安装到项目中。详见 sdk-integration.md。

第三步：SDK 验证（硬性门禁）

详见 sdk-reference.md 中的「javap 验证流程」

代码生成前的强制性验证步骤。 对用户提供的 SDK jar 执行 javap 反编译，确认所有目标接口的 Model 类方法签名和 Response 字段。

javap 反编译所有目标接口的 SDK Model 类

对每个目标接口对应的 SDK Model 类执行 javap，提取所有实际存在的方法签名：

javap -p -cp pingpp-sdk-x.x.x.jar com.pingxx.model.Payment

同时反编译对应的 Response 类（如 com.pingxx.resp.PaymentResp），确认响应字段。

交叉比对，生成「已验证方法清单」

将以下两者交叉比对，生成每个接口的已验证方法清单：

API 文档字段（用户提供的接口文档）→ 确认字段含义、必填性、请求参数和响应字段
javap 实际方法（第三步反编译结果）→ 确认方法是否存在、参数类型、精确返回类型类名

⛔ 如果文档字段在 javap 中找不到对应方法 → 记录到 TODO，不生成调用
⛔ 如果 javap 中存在文档未提及的方法 → 跳过，不使用
⛔ 返回类型必须逐字照抄 javap 输出 → 不得推测/简化/修改类名
   （SDK 命名不规则：ElectronicReceiptStoreResp、BalanceTxnListResp、MchApplicationStoreResp 等）

验证完成标志： 每个接口都有一个「已验证方法清单」，列明：哪些方法可以调用、参数类型（Map / String）、javap 输出的精确返回类型（如 ElectronicReceiptStoreResp 而非推测的 ElectronicReceiptResp）、是否有 RequestOptions 重载版本。清单作为第四步代码生成的唯一输入。

第四步：生成集成代码

详见 code-generation.md

硬性门禁：必须完成第三步验证后才能生成代码。 每一个 SDK 方法调用都必须能追溯到 javap 输出。

在现有项目包结构下生成分账模块代码（config/model/service/webhook/exception），遵循项目已有的包命名规范和代码风格。

必须生成的资源文件：

src/main/resources/keys/ 目录及 3 个占位 PEM 文件（详见 sdk-integration.md「必须创建密钥占位文件」章节）：
- pingpp_sign_private_key.pem — RSA PKCS#8 签名私钥占位
- pingpp_encrypt_public_key.pem — SM2 加密公钥占位
- pingpp_verify_public_key.pem — RSA 验签公钥占位
.gitignore 追加 src/main/resources/keys/*.pem（如尚未存在）
application.yml 中 pingpp 配置块（如尚未存在）

生成完毕后提醒用户：「请将 Ping++ 提供的实际密钥内容替换 keys/ 目录下的占位文件」。

第五步：编译与测试

编译与测试详见 testing-and-deployment.md

硬性要求：为本次接入的所有接口生成单元测试，且查询类测试必须通过。

Step 1: 建议用户执行 mvn clean compile              → 编译通过
Step 2: 为所有接口生成单元测试                        → 查询类启用，写入类/Webhook @Disabled
Step 3: 建议用户执行 mvn test                        → 查询类测试必须全部通过（硬性门禁）
Step 4: 向用户报告完整测试结果                        → 列出每个测试的状态和异常类型

查询类测试不通过 = 集成失败，必须排查后重跑。写入类/Webhook 生成框架代码标注 TODO，提醒用户替换数据后启用。

技术参考

sdk-reference.md — SDK 类路径、javap 验证流程、异常体系、错误排查
sdk-integration.md — Maven 配置、Spring Boot 集成、@PostConstruct 初始化
api-reference.md — 核心 API 接口文档、SDK 方法映射、Webhook 事件
code-generation.md — 代码结构、调用模式、DTO 命名规范
testing-and-deployment.md — 测试策略、通过判定、生产检查清单