docs: 设计收付通旧 API 兼容层

Author: binarywang

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 后继续保留旧模型。