mp-java/docs/unified_payment_with_order_api.md

统一支付模块 - 订单创建与支付接口

🎯 新接口概述

新增了 POST /api/payment/create-with-order 接口，实现了：

1. 订单创建：完整的商品验证、库存扣减、价格计算
2. 支付发起：统一支付模块的支付创建
3. 数据一致性：事务保证订单和支付的一致性

📋 接口详情

请求地址

POST /api/payment/create-with-order

请求参数

{
  "paymentType": "WECHAT_NATIVE",
  "amount": 100.00,
  "subject": "网站建设服务订单",
  "description": "网站建设服务",
  "tenantId": 10398,
  "orderInfo": {
    "type": 0,
    "realName": "无",
    "address": "无",
    "addressId": 0,
    "deliveryType": 0,
    "channel": 0,
    "merchantId": null,
    "merchantName": null,
    "couponId": null,
    "comments": "网站建设服务订单",
    "goodsItems": [
      {
        "goodsId": 10004,
        "skuId": null,
        "quantity": 1,
        "specInfo": null
      }
    ]
  }
}

响应数据

{
  "code": 200,
  "message": "订单创建并发起支付成功",
  "data": {
    "success": true,
    "orderNo": "ORDER_1756547282147",
    "paymentType": "WECHAT_NATIVE",
    "paymentStatus": "PENDING",
    "amount": 100.00,
    "tenantId": 10398,
    "codeUrl": "weixin://wxpay/bizpayurl?pr=xxx",
    "currency": "CNY",
    "createTime": "2025-01-26T10:30:00"
  }
}

🔄 处理流程

1. 请求验证

• 用户登录状态验证
• 支付参数验证（金额、类型等）
• 订单参数验证（商品列表、收货信息等）

2. 订单创建

PaymentServiceImpl.createPaymentWithOrder()
    ↓
convertToOrderCreateRequest() - 转换请求格式
    ↓
orderBusinessService.createOrder() - 完整订单创建逻辑
    ↓
- 商品验证（存在性、状态、价格）
- 库存验证和扣减
- 优惠券处理
- 订单保存
- 订单商品保存
- 微信支付订单创建

3. 支付响应

• 返回微信支付二维码URL
• 包含订单号和支付状态
• 统一的响应格式

🆚 与现有接口对比

接口	功能	优势	适用场景
/api/payment/create	纯支付	简单快速	已有订单，只需支付
/api/shop/shop-order	纯订单	完整业务逻辑	创建订单，后续支付
/api/payment/create-with-order	订单+支付	一体化流程	推荐：预下单场景

🎯 兼容性处理

支持你的数据格式

你的原始数据：

{
  "addressId": 0,
  "comments": "网站建设服务订单",
  "deliveryType": 0,
  "payType": 102,
  "goodsItems": [{"goodsId": 10004, "quantity": 1}],
  "orderNo": "ORDER_1756547282147",
  "realName": "无"
}

转换为新格式：

{
  "paymentType": "WECHAT_NATIVE",
  "amount": 100.00,
  "subject": "网站建设服务订单",
  "tenantId": 10398,
  "orderInfo": {
    "type": 0,
    "realName": "无",
    "addressId": 0,
    "deliveryType": 0,
    "comments": "网站建设服务订单",
    "goodsItems": [{"goodsId": 10004, "quantity": 1}]
  }
}

✅ 优势总结

1. 架构统一

• 所有支付逻辑集中在统一支付模块
• 统一的错误处理和日志记录
• 统一的响应格式

2. 业务完整

• 复用现有的完整订单创建逻辑
• 商品验证、库存管理、优惠券处理
• 支付成功后的完整回调处理

3. 数据一致性

• 事务保证订单创建和支付的原子性
• 支付失败时订单状态正确
• 支付成功时自动更新订单状态

4. 扩展性好

• 支持多种支付方式（微信、支付宝、银联等）
• 支持复杂订单场景（多商品、多规格、优惠券等）
• 预留了通知和业务逻辑扩展接口

🚀 测试建议

1. 创建订单并支付

curl -X POST "http://127.0.0.1:9200/api/payment/create-with-order" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentType": "WECHAT_NATIVE",
    "amount": 100.00,
    "subject": "网站建设服务",
    "tenantId": 10398,
    "orderInfo": {
      "type": 0,
      "realName": "测试用户",
      "comments": "测试订单",
      "goodsItems": [{"goodsId": 10004, "quantity": 1}]
    }
  }'

2. 查询支付状态

curl "http://127.0.0.1:9200/api/payment/query?orderNo=ORDER_xxx&tenantId=10398&paymentType=WECHAT_NATIVE"

这个方案既保持了架构的统一性，又提供了完整的业务功能！