🎨 #4087 【微信支付】兼容收付通旧版下单模型

Author: binarywang

docs/superpowers/plans/2026-08-08-legacy-ecommerce-api-compatibility.md

@@ -0,0 +1,60 @@
+# 收付通旧 API 过渡兼容层 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Restore the public e-commerce payment API removed by #4014 as deprecated adapters over the unified V3 API.
+
+**Architecture:** Deprecated legacy models remain in `bean.ecommerce`; `EcommerceService` exposes overloads with those legacy types. Each overload maps the input to the unified request/enums, invokes the existing unified method, and maps the response back, so transport and signature logic remain singular.
+
+**Tech Stack:** Java 8, Maven, TestNG, Gson, Lombok.
+
+## Global Constraints
+
+- Keep all new #4014 API signatures and behavior unchanged.
+- Mark every restored legacy public class and service method `@Deprecated` with migration Javadoc.
+- Do not recreate legacy HTTP, signing, or notification-verification implementations.
+- Remove the compatibility layer only in 5.0.
+
+---
+
+### Task 1: Restore legacy model surface
+
+**Files:**
+- Create: `weixin-java-pay/src/main/java/com/github/binarywang/wxpay/bean/ecommerce/{TransactionsResult,CombineTransactionsRequest,CombineTransactionsResult,CombineTransactionsNotifyResult,PartnerTransactionsRequest,PartnerTransactionsResult,PartnerTransactionsNotifyResult,PartnerTransactionsQueryRequest,PartnerTransactionsCloseRequest,SignatureHeader}.java`
+- Create: `weixin-java-pay/src/main/java/com/github/binarywang/wxpay/bean/ecommerce/enums/TradeTypeEnum.java`
+- Test: `weixin-java-pay/src/test/java/com/github/binarywang/wxpay/service/LegacyEcommerceApiCompatibilityTest.java`
+
+**Interfaces:**
+- Produces legacy types with their pre-#4014 fully qualified names and accessors.
+
+- [ ] **Step 1: Write a failing compilation test importing the old types.**
+- [ ] **Step 2: Run `mvn -pl weixin-java-pay -Dtest=LegacyEcommerceApiCompatibilityTest test` and confirm compilation fails because the old types do not exist.**
+- [ ] **Step 3: Restore the old model source and annotate each class `@Deprecated`.**
+- [ ] **Step 4: Re-run the focused Maven test and confirm compilation succeeds.**
+
+### Task 2: Add service-level adapters
+
+**Files:**
+- Modify: `weixin-java-pay/src/main/java/com/github/binarywang/wxpay/service/EcommerceService.java`
+- Create: `weixin-java-pay/src/main/java/com/github/binarywang/wxpay/service/LegacyEcommerceApiAdapter.java`
+- Test: `weixin-java-pay/src/test/java/com/github/binarywang/wxpay/service/LegacyEcommerceApiCompatibilityTest.java`
+
+**Interfaces:**
+- Consumes restored legacy models from Task 1 and current unified V3 APIs.
+- Produces deprecated overloads for `combine`, `combineTransactions`, notification parsing, query/close, partner order creation, query/close and notification parsing.
+
+- [ ] **Step 1: Write failing tests using legacy `EcommerceService` signatures and asserting delegation to the corresponding unified method.**
+- [ ] **Step 2: Run the focused Maven test and confirm each test fails because no legacy overload exists.**
+- [ ] **Step 3: Implement mapping helpers and `default` legacy overloads that delegate to current methods.**
+- [ ] **Step 4: Re-run the focused Maven test and confirm the legacy paths pass.**
+
+### Task 3: Regression verification and documentation
+
+**Files:**
+- Modify: `weixin-java-pay/src/test/java/com/github/binarywang/wxpay/service/LegacyEcommerceApiCompatibilityTest.java`
+- Modify: `docs/superpowers/specs/2026-08-08-legacy-ecommerce-api-compatibility-design.md`
+
+- [ ] **Step 1: Add tests proving current unified API calls still resolve to their current methods.**
+- [ ] **Step 2: Run `mvn -pl weixin-java-pay test` and verify the module builds successfully.**
+- [ ] **Step 3: Inspect `git diff --check` and `git diff` for accidental edits.**
+- [ ] **Step 4: Commit the implementation and tests with a Chinese message.**

docs/superpowers/specs/2026-08-08-legacy-ecommerce-api-compatibility-design.md

@@ -0,0 +1,35 @@
+# 收付通旧 API 过渡兼容层设计
+
+## 目标
+
+在保留 #4014 统一收付通 API 的前提下，恢复该 PR 删除的公开旧 API，使依赖 4.8.4 收付通模型和 `EcommerceService` 方法的应用能够升级到包含服务商电子发票能力的 4.8.5.x 版本。
+
+## 方案选择
+
+1. **仅恢复 `TransactionsResult`**：改动最少，但旧请求、枚举和服务方法仍无法编译，不能解决实际升级问题。
+2. **保留独立的旧实现**：兼容性最高，但会重新引入两套 HTTP、验签和签名逻辑，容易再次发生行为漂移。
+3. **废弃的适配层（采用）**：恢复旧模型及方法签名，由旧方法转换为统一模型后调用新 API。这样保留调用方兼容性，只有一套网络实现和业务行为。
+
+## 架构
+
+恢复的 `com.github.binarywang.wxpay.bean.ecommerce` 下模型均标记 `@Deprecated`。`EcommerceService` 对旧参数类型提供同名重载的 `default` 方法；这些方法使用一个包内适配器把旧请求、枚举和结果转换为新模型，然后委托新的统一方法。
+
+旧 API 与新 API 的参数类型位于不同包，因此可安全重载。新 API 的名称、签名和执行路径不变。兼容层覆盖 #4014 删除的下单、查询、关单和通知模型/入口，而不是只恢复一个结果类。
+
+## 行为与迁移
+
+- 旧调用方继续导入 `bean.ecommerce` 类型即可编译和运行。
+- 新调用方继续使用 `bean.request`、`bean.result`、`bean.notify` 的统一类型，不受兼容层影响。
+- 兼容层直接委托新 API；请求 JSON、验签和网络调用遵循当前统一实现。
+- 所有旧入口在 Javadoc 中给出新 API 的迁移目标，并标记为将在 5.0 移除。
+- 同时使用旧、新包的通配符导入可能引发同名类型歧义；用户应使用显式 import。
+
+## 测试
+
+为每个兼容入口增加测试，验证旧类型可调用、适配后委托至对应新 API，并验证返回模型中的核心字段和支付调起参数保持可用。测试同时覆盖新 API，确保新路径没有回归。
+
+## 非目标
+
+- 不恢复已删除的旧网络实现。
+- 不新增任何微信支付接口。
+- 不承诺 5.0 后继续保留旧模型。

weixin-java-pay/src/main/java/com/github/binarywang/wxpay/bean/ecommerce/CombineTransactionsNotifyResult.java

@@ -0,0 +1,30 @@
+package com.github.binarywang.wxpay.bean.ecommerce;
+
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.io.Serializable;
+
+/**
+ * 合单支付 通知结果
+ * <pre>
+ *   文档地址：https://pay.weixin.qq.com/wiki/doc/apiv3/wxpay/pay/combine/chapter3_7.shtml
+ * </pre>
+ */
+@Data
+@NoArgsConstructor
+@Deprecated
+public class CombineTransactionsNotifyResult implements Serializable {
+
+  private static final long serialVersionUID = -4710926828683593250L;
+  /**
+   * 源数据
+   */
+  private NotifyResponse rawData;
+
+  /**
+   * 解密后的数据
+   */
+  private CombineTransactionsResult result;
+
+}