feat(payment): 优化支付方式并确保系统平滑迁移

-将19种复杂支付方式简化为8种核心支付方式 - 更新PaymentType枚举，添加废弃支付方式的兼容处理 - 新增PaymentTypeCompatibilityUtil工具类，用于支付方式迁移 - 更新ShopOrder和ShopOrderParam的支付方式描述 - 修改ShopOrderServiceImpl中的支付处理逻辑 - 添加单元测试，验证支付方式优化后的功能正确性
2025-08-31 01:42:02 +08:00
parent b105936840
commit 61a5178e5a
7 changed files with 630 additions and 61 deletions
--- a/docs/支付方式优化迁移指南.md
+++ b/docs/支付方式优化迁移指南.md
@@ -0,0 +1,210 @@
+# 支付方式优化迁移指南
+
+## 📋 概述
+
+本文档说明如何将现有的复杂支付方式（19种）简化为8种核心支付方式，提高系统的可维护性和用户体验。
+
+## 🎯 优化目标
+
+- **简化支付方式**：从19种减少到8种核心支付方式
+- **提高可维护性**：减少代码复杂度和维护成本
+- **保持兼容性**：确保现有数据和业务逻辑正常运行
+- **改善用户体验**：简化支付选择，提高支付成功率
+
+## 📊 支付方式映射表
+
+### ✅ 保留的核心支付方式（8种）
+
+| 代码 | 名称 | 渠道 | 说明 |
+|------|------|------|------|
+| 0 | 余额支付 | balance | 用户账户余额扣减 |
+| 1 | 微信支付 | wechat | 包含JSAPI和Native两种模式 |
+| 2 | 支付宝支付 | alipay | 支付宝在线支付 |
+| 3 | 银联支付 | union_pay | 银联在线支付 |
+| 4 | 现金支付 | cash | 线下现金收款 |
+| 5 | POS机支付 | pos | 线下刷卡支付 |
+| 6 | 免费 | free | 免费商品或活动 |
+| 7 | 积分支付 | points | 用户积分兑换 |
+
+### ⚠️ 废弃的支付方式映射
+
+| 原代码 | 原名称 | 建议迁移到 | 迁移说明 |
+|--------|--------|------------|----------|
+| 2 | 会员卡支付 | 0 (余额支付) | 会员卡余额转为用户余额 |
+| 3 | 支付宝支付(旧) | 2 (支付宝支付) | 编号调整：3→2 |
+| 6 | VIP月卡 | 0 (余额支付) | VIP卡余额转为用户余额 |
+| 7 | VIP年卡 | 0 (余额支付) | VIP卡余额转为用户余额 |
+| 8 | VIP次卡 | 0 (余额支付) | VIP卡余额转为用户余额 |
+| 9 | IC月卡 | 0 (余额支付) | IC卡余额转为用户余额 |
+| 10 | IC年卡 | 0 (余额支付) | IC卡余额转为用户余额 |
+| 11 | IC次卡 | 0 (余额支付) | IC卡余额转为用户余额 |
+| 12 | 免费(旧) | 6 (免费) | 编号调整：12→6 |
+| 13 | VIP充值卡 | 0 (余额支付) | 充值卡余额转为用户余额 |
+| 14 | IC充值卡 | 0 (余额支付) | 充值卡余额转为用户余额 |
+| 15 | 积分支付(旧) | 7 (积分支付) | 编号调整：15→7 |
+| 16 | VIP季卡 | 0 (余额支付) | VIP卡余额转为用户余额 |
+| 17 | IC季卡 | 0 (余额支付) | IC卡余额转为用户余额 |
+| 18 | 代付 | 1 (微信支付) | 通过代付字段记录代付信息 |
+| 19 | 银联支付(旧) | 3 (银联支付) | 编号调整：19→3 |
+| 102 | 微信Native | 1 (微信支付) | 合并到微信支付，自动选择支付模式 |
+
+## 🔧 技术实现
+
+### 1. 枚举类更新
+
+已更新 `PaymentType.java`：
+- 保留8种核心支付方式
+- 废弃的支付方式标记为 `@Deprecated`
+- 添加兼容性方法：`isCorePaymentType()`, `isDeprecated()`
+
+### 2. 业务逻辑兼容
+
+已更新 `ShopOrderServiceImpl.java`：
+- 微信支付(1)自动根据openid选择JSAPI或Native模式
+- 保持对旧的微信Native(102)的兼容支持
+- 添加废弃支付方式的警告日志
+
+### 3. 实体类注释更新
+
+已更新相关实体类的Schema描述：
+- `ShopOrder.java`
+- `ShopOrderParam.java`
+
+## 📝 数据迁移SQL
+
+### 3.1 查看现有支付方式分布
+
+```sql
+-- 查看当前系统中各支付方式的使用情况
+SELECT 
+    pay_type,
+    COUNT(*) as order_count,
+    SUM(total_price) as total_amount
+FROM shop_order 
+WHERE pay_status = 1 
+GROUP BY pay_type 
+ORDER BY order_count DESC;
+```
+
+### 3.2 迁移废弃的支付方式
+
+```sql
+-- 第一步：调整编号映射（旧编号到新编号）
+UPDATE shop_order SET pay_type = 2, comments = CONCAT(IFNULL(comments, ''), ' [支付宝编号调整: 3→2]') WHERE pay_type = 3;
+UPDATE shop_order SET pay_type = 6, comments = CONCAT(IFNULL(comments, ''), ' [免费编号调整: 12→6]') WHERE pay_type = 12;
+UPDATE shop_order SET pay_type = 7, comments = CONCAT(IFNULL(comments, ''), ' [积分支付编号调整: 15→7]') WHERE pay_type = 15;
+UPDATE shop_order SET pay_type = 3, comments = CONCAT(IFNULL(comments, ''), ' [银联支付编号调整: 19→3]') WHERE pay_type = 19;
+
+-- 第二步：将会员卡类支付迁移为余额支付
+UPDATE shop_order
+SET pay_type = 0,
+    comments = CONCAT(IFNULL(comments, ''), ' [原支付方式: ',
+        CASE pay_type
+            WHEN 2 THEN '会员卡支付'
+            WHEN 6 THEN 'VIP月卡'
+            WHEN 7 THEN 'VIP年卡'
+            WHEN 8 THEN 'VIP次卡'
+            WHEN 9 THEN 'IC月卡'
+            WHEN 10 THEN 'IC年卡'
+            WHEN 11 THEN 'IC次卡'
+            WHEN 13 THEN 'VIP充值卡'
+            WHEN 14 THEN 'IC充值卡'
+            WHEN 16 THEN 'VIP季卡'
+            WHEN 17 THEN 'IC季卡'
+        END, ']')
+WHERE pay_type IN (2, 6, 7, 8, 9, 10, 11, 13, 14, 16, 17);
+
+-- 第三步：将微信Native支付迁移为微信支付
+UPDATE shop_order
+SET pay_type = 1,
+    comments = CONCAT(IFNULL(comments, ''), ' [原支付方式: 微信Native支付]')
+WHERE pay_type = 102;
+
+-- 第四步：处理代付支付方式
+UPDATE shop_order
+SET pay_type = IFNULL(friend_pay_type, 1),
+    comments = CONCAT(IFNULL(comments, ''), ' [原为代付支付]')
+WHERE pay_type = 18;
+```
+
+## ⚡ 部署步骤
+
+### 1. 预部署检查
+
+```bash
+# 1. 备份数据库
+mysqldump -u username -p database_name > backup_before_payment_migration.sql
+
+# 2. 检查当前支付方式分布
+mysql -u username -p -e "
+SELECT pay_type, COUNT(*) as count 
+FROM shop_order 
+GROUP BY pay_type 
+ORDER BY count DESC;"
+```
+
+### 2. 代码部署
+
+1. 部署更新后的代码
+2. 重启应用服务
+3. 验证支付功能正常
+
+### 3. 数据迁移
+
+1. 执行上述迁移SQL
+2. 验证数据迁移结果
+3. 清理废弃的支付配置
+
+### 4. 后续清理
+
+等待1-2个版本后，可以完全移除废弃的枚举值：
+
+```java
+// 最终版本的PaymentType枚举（移除所有@Deprecated项）
+public enum PaymentType {
+    BALANCE(0, "余额支付", "balance"),
+    WECHAT(1, "微信支付", "wechat"),
+    ALIPAY(3, "支付宝支付", "alipay"),
+    CASH(4, "现金支付", "cash"),
+    POS(5, "POS机支付", "pos"),
+    FREE(12, "免费", "free"),
+    POINTS(15, "积分支付", "points"),
+    UNION_PAY(19, "银联支付", "union_pay");
+}
+```
+
+## 🧪 测试建议
+
+### 1. 功能测试
+
+- [ ] 测试8种核心支付方式的正常流程
+- [ ] 测试废弃支付方式的兼容性
+- [ ] 测试支付回调处理
+- [ ] 测试退款功能
+
+### 2. 数据验证
+
+- [ ] 验证迁移后的订单数据完整性
+- [ ] 验证支付统计报表的准确性
+- [ ] 验证用户余额的正确性
+
+## 📈 预期收益
+
+1. **代码简化**：减少50%以上的支付相关代码复杂度
+2. **维护成本降低**：减少支付方式维护工作量
+3. **用户体验提升**：简化支付选择，提高转化率
+4. **系统稳定性**：减少支付相关的bug和异常
+
+## ⚠️ 注意事项
+
+1. **数据备份**：迁移前务必备份数据库
+2. **分步实施**：建议分阶段实施，先标记废弃，后续版本再移除
+3. **监控告警**：部署后密切监控支付成功率和异常情况
+4. **用户通知**：如有必要，提前通知用户支付方式的变更
+
+## 🔗 相关文件
+
+- `src/main/java/com/gxwebsoft/payment/enums/PaymentType.java` - 支付类型枚举
+- `src/main/java/com/gxwebsoft/shop/entity/ShopOrder.java` - 订单实体
+- `src/main/java/com/gxwebsoft/shop/service/impl/ShopOrderServiceImpl.java` - 订单服务实现
+- `src/main/java/com/gxwebsoft/payment/strategy/` - 支付策略实现目录