soul-yongping/addons/Universal_Payment_Module copy/README.md

🌐 全球通用支付模块 (Universal Payment Module) v4.0

配置驱动 (Configuration-Driven) | API 优先 (API-First) | AI 智能对接

让任何语言的项目在 5 分钟内接入支付宝、微信支付、PayPal、Stripe 和 USDT

📂 模块结构

Universal_Payment_Module/
├── 1_核心设计_通用协议/           # [灵魂] 定义了支付的"法律"
│   ├── 标准配置模板.yaml        # 填空即可配置所有支付参数
│   ├── API接口定义.md           # 无论用什么语言，接口都长这样
│   ├── 业务逻辑与模型.md        # 数据库表结构设计 (Order/PayTrade)
│   └── 安全与合规.md            # 支付安全最佳实践
│
├── 2_智能对接_AI指令/             # [工具] AI 编译器
│   ├── 通用集成指令.md          # 发给 AI，自动生成代码
│   └── Cursor规则.md            # Cursor IDE 专用规则
│
├── 3_逻辑参考_通用实现/           # [参考] 可直接复用的代码
│   ├── 前端收银台Demo.html      # 原生 JS 实现的通用收银台
│   ├── 后端源码/                # 多语言参考实现
│   │   ├── php/                 # PHP (Laravel/Symfony)
│   │   ├── python/              # Python (FastAPI/Django)
│   │   ├── nodejs/              # Node.js (Express/NestJS)
│   │   └── java/                # Java (Spring Boot)
│   └── 前端模板/                # Vue/React/原生JS 模板
│
├── 4_卡若配置/                    # [私有] 卡若的支付密钥 (勿提交Git)
│   └── .env.example             # 配置示例
│
└── README.md                     # 本说明文档

🚀 极速对接 (3步完成)

第一步：配置 (Config)

# 1. 复制配置模板到你的项目
cp 1_核心设计_通用协议/标准配置模板.yaml your-project/.env

# 2. 填入你的支付密钥

第二步：生成代码 (Generate with AI)

发送给 Cursor/ChatGPT：
"请读取 Universal_Payment_Module 目录，我的项目是 Python FastAPI，
采用嵌入式集成，帮我生成支付模块代码。"

第三步：前端接入 (Frontend)

// 只需调用一个 API
const result = await fetch('/api/payment/checkout', {
  method: 'POST',
  body: JSON.stringify({ order_sn: '202401170001', gateway: 'wechat_jsapi' })
});

🌍 支持的支付渠道

渠道	能力	场景	状态
支付宝 Alipay	扫码/H5/APP/小程序	中国市场 (CNY)	✅ 已实现
微信支付 Wechat	JSAPI/Native/H5/APP/小程序	中国市场 (CNY)	✅ 已实现
PayPal	信用卡/订阅	全球市场 (USD/EUR)	✅ 已实现
Stripe	信用卡/订阅/Apple Pay	全球市场	✅ 已实现
USDT (TRC20)	链上转账/监听	Web3/抗审查	✅ 已实现

✨ v4.0 核心特性

1. 配置驱动 (Zero-Code Config)

• 所有密钥通过环境变量注入，无需改动代码
• 支持多环境切换 (development/production)

2. 工厂模式 (Payment Factory)

# 所有支付网关统一接口
payment = PaymentFactory.create('wechat')
result = payment.create_trade(order)

3. 幂等性保障 (Idempotency)

• 回调通知自动去重
• 订单状态机管理

4. AI 智能生成

• 提供 Cursor/Copilot 专用提示词
• 一键生成任意语言的完整实现

📖 快速参考

创建订单

POST /api/payment/create_order
Content-Type: application/json

{
  "user_id": "u1001",
  "title": "VIP会员",
  "amount": 99.00,
  "currency": "CNY",
  "product_id": "vip_monthly"
}

发起支付

POST /api/payment/checkout
Content-Type: application/json

{
  "order_sn": "202401170001",
  "gateway": "wechat_jsapi",
  "openid": "oXxx..."
}

支付状态查询

GET /api/payment/status/202401170001

🔐 安全须知

1. 密钥安全: 所有密钥存放在 .env，绝不提交到 Git
2. HTTPS 强制: 生产环境必须启用 HTTPS
3. 签名验证: 所有回调必须验签
4. 金额校验: 支付金额必须与订单金额匹配

📚 相关文档

• API 接口定义
• 数据库模型
• AI 集成指令
• Cursor 规则

---

作者: 卡若 | 联系: 28533368 (微信) | 更新: 2026-01-17