leeexin/license-manager

0 Fork 0

Files

T

wood911010 af76eaf1b1 feat: 添加支付模块，支持支付宝支付功能，包括订单创建、支付状态查询及支付历史记录管理

2026-01-09 19:21:40 +08:00

14 KiB

Raw Blame History

支付宝支付对接设计文档

概述

本系统需要对接支付宝支付功能，主要用于用户购买产品套餐的支付场景。系统采用模块化设计，支持后续扩展其他支付方式（如微信支付等）。

业务需求

用户购买产品套餐时支持支付宝支付
支持支付状态查询和回调处理
支付成功后自动激活用户套餐
支持支付记录查询和管理

技术架构

基于现有的Clean Architecture设计，使用支付宝官方Go SDK实现支付功能：

核心组件

支付SDK: github.com/smartwalle/alipay/v3 - 官方支付宝Go SDK
支付服务: 封装支付业务逻辑，集成官方SDK
支付仓储: 支付数据持久化
支付处理器: RESTful API接口

架构优势

官方维护: 使用官方SDK，确保兼容性和安全性
简化开发: 无需手动实现签名、验证等复杂逻辑
标准化: 遵循支付宝官方API规范
易扩展: 支持支付宝、微信等多支付方式

数据模型设计

通用支付设计：支付抽象与业务分离

采用最佳实践的支付抽象设计，支持多种支付方式和业务场景：

设计原则

支付抽象：payments表只包含支付相关的通用字段
业务关联：通过business_type和business_id关联具体业务
扩展性：支持支付宝、微信等多种支付方式
业务隔离：支付失败不影响业务数据

支付订单表 (payments)

CREATE TABLE payments (
    id SERIAL PRIMARY KEY,
    payment_no VARCHAR(64) UNIQUE NOT NULL COMMENT '支付单号',
    business_type VARCHAR(50) NOT NULL COMMENT '业务类型 (package_order-套餐购买)',
    business_id VARCHAR(36) NULL COMMENT '业务ID (关联cu_orders.id)',
    user_id INTEGER NOT NULL COMMENT '用户ID',
    amount DECIMAL(10,2) NOT NULL COMMENT '支付金额',
    currency VARCHAR(3) DEFAULT 'CNY' COMMENT '货币类型',
    payment_method VARCHAR(20) DEFAULT 'alipay' COMMENT '支付方式',
    payment_provider VARCHAR(20) DEFAULT 'alipay' COMMENT '支付提供商',
    status VARCHAR(20) NOT NULL DEFAULT 'pending' COMMENT '支付状态',
    trade_no VARCHAR(64) NULL COMMENT '第三方交易号',
    payment_time TIMESTAMP NULL COMMENT '支付完成时间',
    expire_time TIMESTAMP NOT NULL COMMENT '支付过期时间',
    payment_url TEXT NULL COMMENT '支付链接',
    notify_data JSONB NULL COMMENT '回调数据',
    extra_data JSONB NULL COMMENT '扩展数据',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

    FOREIGN KEY (user_id) REFERENCES users(id)
);

-- 索引
CREATE INDEX idx_payments_payment_no ON payments(payment_no);
CREATE INDEX idx_payments_business_type_id ON payments(business_type, business_id);
CREATE INDEX idx_payments_user_id ON payments(user_id);
CREATE INDEX idx_payments_status ON payments(status);
CREATE INDEX idx_payments_created_at ON payments(created_at);

业务类型枚举

package_order: 套餐购买订单
license_extend: 许可延期（预留）
service_upgrade: 服务升级（预留）

支付状态枚举

pending: 待支付
paid: 已支付
cancelled: 已取消
expired: 已过期
failed: 支付失败
refunded: 已退款

支付方式枚举

alipay: 支付宝
wechat: 微信支付（预留）
bank: 银行卡（预留）

官方SDK集成

SDK选择

使用 github.com/smartwalle/alipay/v3 官方Go SDK，原因：

官方维护: 支付宝官方团队维护，确保最新API支持
功能完整: 支持支付、退款、查询等所有功能
签名处理: 自动处理RSA签名和验证
类型安全: 强类型接口，避免手动构造参数
社区活跃: 有完整的文档和示例

核心用法

// 1. 创建客户端
client, err := alipay.New(appID, privateKey, false)

// 2. 创建支付请求
payRequest := alipay.TradePagePay{
    Trade: alipay.Trade{
        OutTradeNo:  "PAY20240101001",
        TotalAmount: "100.00",
        Subject:     "产品购买",
        ProductCode: "FAST_INSTANT_TRADE_PAY",
    },
}

// 3. 生成支付URL
payURL, err := client.TradePagePay(payRequest)

// 4. 处理回调
notification, err := client.GetTradeNotification(request)

集成优势

零配置: SDK自动处理签名和验证
错误处理: 完善的错误类型和处理机制
性能优化: 内部实现连接池和缓存
安全可靠: 官方审核，确保安全合规

API接口设计

1. 创建订单并支付

方案选择：兼容性修改现有接口

基于现有 POST /api/cu/orders 接口进行兼容性修改：

接口路径: POST /api/cu/orders（保持不变）

新增请求参数:

{
  "package_id": "basic",
  "license_count": 100,
  "payment_method": "alipay"  // 新增：支付方式，不传则为免费订单
}

响应格式变化:

免费订单（试用版）响应 - 保持原有格式：

{
  "code": "000000",
  "message": "成功",
  "data": {
    "order_id": "order_id_123",
    "order_no": "ORD202401010001",
    "total_amount": 0.00,
    "status": "paid",
    "authorization_code": "AC-240101-A1B2C3D4",
    "expired_at": "2024-01-25T23:59:59Z"
  }
}

付费订单响应 - 新增支付信息：

{
  "code": "000000",
  "message": "成功",
  "data": {
    "order_id": "order_id_456",
    "order_no": "ORD202401010002",
    "payment_no": "PAY202401010002",
    "total_amount": 24000.00,
    "status": "pending",
    "payment_url": "https://openapi.alipay.com/gateway.do?...",
    "expire_time": "2024-01-01T13:00:00Z"
  }
}

业务逻辑:

根据套餐类型和支付方式决定处理流程
免费订单：直接创建paid状态订单并生成授权码
付费订单：创建pending状态订单和支付单，返回支付链接

2. 查询订单状态

接口: GET /api/cu/orders/{order_no}/status（保持与现有API风格一致）

响应:

免费订单状态:

{
    "code": "000000",
    "data": {
        "order_no": "ORD202401010001",
        "status": "paid",
        "authorization_code": "AC-240101-A1B2C3D4",
        "expired_at": "2024-01-25T23:59:59Z"
    }
}

付费订单状态:

{
    "code": "000000",
    "data": {
        "order_no": "ORD202401010002",
        "status": "paid",
        "payment_status": "paid",
        "authorization_code": "AC-240102-B2C3D4E5",
        "payment_time": "2024-01-01T12:35:00Z"
    }
}

业务逻辑:

兼容现有查询接口
对于付费订单，额外返回支付相关信息

3. 支付回调处理

接口: POST /api/v1/payment/alipay/callback

支付宝服务器回调，系统验证签名后更新订单状态。

4. 获取支付历史

接口: GET /api/v1/payment/history

支持分页查询用户的支付记录。

支付流程设计

1. 支付流程图

用户选择套餐 → 创建业务订单(cu_orders, status=pending) → 创建支付单(payments, pending) → 跳转支付 → 用户支付 → 支付回调 → 更新payments为paid → 更新cu_orders为paid → 生成授权码

2. 详细流程

创建业务订单
- 前端调用创建订单接口，传入套餐ID和许可数量
- 后端验证套餐配置，计算价格和折扣
- 在cu_orders表创建记录，状态为pending，生成业务订单
- 创建对应的支付单，关联业务订单，状态为pending
- 调用支付接口生成支付链接
- 返回支付信息给前端
支付处理
- 用户跳转到支付页面完成支付
- 第三方支付平台处理支付并异步回调系统
回调处理
- 验证支付回调签名和数据
- 确认支付金额一致
- 在事务中执行：
  - 更新payments表状态为paid
  - 更新对应的cu_orders表状态为paid
  - 生成授权码
- 返回成功响应给支付平台
状态查询
- 前端可查询支付状态
- 返回支付状态和业务订单信息

安全设计

1. 支付验证

使用支付平台公钥验证回调签名
防止伪造回调请求
支持多种支付方式的签名验证

2. 金额防篡改

支付单金额在创建时计算并存储
支付回调时二次验证金额
业务数据与支付数据分离，确保一致性

3. 防重复支付

支付单状态机严格控制
第三方交易号唯一性验证
支付过期时间控制

4. 业务隔离

支付失败：只更新payments状态，业务订单保持pending
支付成功：事务中同时更新payments和业务订单状态
支持多种业务类型的支付处理

配置管理

在configs/config.yaml中添加统一的支付配置：

payment:
  # 默认支付方式
  default_method: alipay

  # 支付提供商配置
  providers:
    alipay:
      enabled: true
      app_id: "your_app_id"
      private_key: "your_private_key"
      public_key: "alipay_public_key"
      gateway_url: "https://openapi.alipay.com/gateway.do"
      notify_url: "https://your-domain.com/api/v1/payment/alipay/callback"
      return_url: "https://your-domain.com/payment/success"
      sign_type: "RSA2"
      charset: "utf-8"
      format: "json"

  # 通用支付配置
  expire_minutes: 30  # 支付过期时间（分钟）
  retry_times: 3      # 支付重试次数
  enable_log: true    # 启用支付日志

配置说明：

default_method: 默认支付方式，可设置为 alipay 或 wechat
providers: 各支付提供商的详细配置，支持动态开启/关闭
通用配置：支付过期时间、重试次数、日志开关等

错误处理

支付相关错误码

PAYMENT_ORDER_NOT_FOUND: 订单不存在
PAYMENT_ALREADY_PAID: 订单已支付
PAYMENT_EXPIRED: 订单已过期
PAYMENT_AMOUNT_MISMATCH: 支付金额不匹配
PAYMENT_SIGNATURE_VERIFY_FAILED: 签名验证失败

扩展性设计

1. 多支付方式支持

通过策略模式和工厂模式支持多种支付方式：

// 支付策略接口
type PaymentStrategy interface {
    CreatePayment(payment *Payment) (*PaymentResponse, error)
    QueryPayment(paymentNo string) (*PaymentStatus, error)
    HandleCallback(data map[string]interface{}) error
    ValidateSignature(data map[string]interface{}) bool
}

// 支付工厂
type PaymentFactory struct {
    strategies map[string]PaymentStrategy
}

func (f *PaymentFactory) GetStrategy(method string) PaymentStrategy {
    return f.strategies[method]
}

2. 支持的支付方式

支付宝：当前实现
微信支付：预留扩展
银行卡：预留扩展

3. 多业务场景支持

通过business_type支持不同业务场景：

const (
    BusinessTypePackageOrder = "package_order"  // 套餐购买
    BusinessTypeLicenseExtend = "license_extend" // 许可延期
    BusinessTypeServiceUpgrade = "service_upgrade" // 服务升级
)

4. 配置说明

详见配置管理章节，支持支付宝、微信等多支付方式统一配置。

测试策略

1. 单元测试

支付服务逻辑测试
支付宝接口mock测试
回调处理测试

2. 集成测试

完整支付流程测试
支付宝沙箱环境测试

3. 沙箱环境

使用支付宝提供的沙箱环境进行测试，避免真实资金操作。

数据迁移和兼容性

新增payments表

创建通用的支付表，支持多种支付方式和业务场景：

-- 创建payments表（见数据模型设计部分）
-- business_type + business_id 支持关联不同业务

API兼容性处理

现有接口修改策略

POST /api/cu/orders 接口变更：

向后兼容：不传payment_method参数时，保持原有免费订单逻辑
扩展功能：传入payment_method参数时，启用支付流程
响应差异：免费订单返回授权码，付费订单返回支付链接

迁移步骤

代码层面：

// 修改现有创建订单逻辑
func CreateOrder(req CreateOrderRequest) (*OrderResponse, error) {
    if req.PaymentMethod == "" {
        // 免费订单：直接创建并返回授权码
        return createFreeOrder(req)
    } else {
        // 付费订单：创建订单+支付单，返回支付信息
        return createPaidOrder(req)
    }
}

数据库层面：
- 新增payments表
- cu_orders表保持不变
- 通过关联关系连接
前端适配：
- 免费订单：无需修改，正常显示授权码
- 付费订单：跳转支付页面，支付完成后查询状态

错误处理兼容

保持现有的错误码体系，新增支付相关错误码：

cu_payment:
  "602001": "支付失败"
  "602002": "支付金额不匹配"
  "602003": "重复支付"
  "602004": "支付已过期"

部署注意事项

网络要求: 支付宝回调URL必须是公网可访问的HTTPS地址
密钥安全: 配置支付宝RSA私钥文件，严格控制访问权限
数据库: 确保payments表已创建，数据库连接池充足
日志监控: 支付相关日志级别设为INFO，配置告警监控支付成功率
SDK依赖: 确保 github.com/smartwalle/alipay/v3 已正确安装
配置验证: 部署前验证支付宝配置参数的正确性
业务隔离: 支付失败不影响业务订单，确保数据一致性

14 KiB Raw Blame History Unescape Escape