143 lines
4.5 KiB
Markdown
143 lines
4.5 KiB
Markdown
|
# 🌐 全球通用支付模块 (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)
|
|||
|
|
```bash
|
|||
|
|
# 1. 复制配置模板到你的项目
|
|||
|
|
cp 1_核心设计_通用协议/标准配置模板.yaml your-project/.env
|
|||
|
|
|
|||
|
|
# 2. 填入你的支付密钥
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 第二步：生成代码 (Generate with AI)
|
|||
|
|
```
|
|||
|
|
发送给 Cursor/ChatGPT：
|
|||
|
|
"请读取 Universal_Payment_Module 目录，我的项目是 Python FastAPI，
|
|||
|
|
采用嵌入式集成，帮我生成支付模块代码。"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 第三步：前端接入 (Frontend)
|
|||
|
|
```javascript
|
|||
|
|
// 只需调用一个 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)
|
|||
|
|
```python
|
|||
|
|
# 所有支付网关统一接口
|
|||
|
|
payment = PaymentFactory.create('wechat')
|
|||
|
|
result = payment.create_trade(order)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 幂等性保障 (Idempotency)
|
|||
|
|
- 回调通知自动去重
|
|||
|
|
- 订单状态机管理
|
|||
|
|
|
|||
|
|
### 4. AI 智能生成
|
|||
|
|
- 提供 Cursor/Copilot 专用提示词
|
|||
|
|
- 一键生成任意语言的完整实现
|
|||
|
|
|
|||
|
|
## 📖 快速参考
|
|||
|
|
|
|||
|
|
### 创建订单
|
|||
|
|
```http
|
|||
|
|
POST /api/payment/create_order
|
|||
|
|
Content-Type: application/json
|
|||
|
|
|
|||
|
|
{
|
|||
|
|
"user_id": "u1001",
|
|||
|
|
"title": "VIP会员",
|
|||
|
|
"amount": 99.00,
|
|||
|
|
"currency": "CNY",
|
|||
|
|
"product_id": "vip_monthly"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 发起支付
|
|||
|
|
```http
|
|||
|
|
POST /api/payment/checkout
|
|||
|
|
Content-Type: application/json
|
|||
|
|
|
|||
|
|
{
|
|||
|
|
"order_sn": "202401170001",
|
|||
|
|
"gateway": "wechat_jsapi",
|
|||
|
|
"openid": "oXxx..."
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 支付状态查询
|
|||
|
|
```http
|
|||
|
|
GET /api/payment/status/202401170001
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🔐 安全须知
|
|||
|
|
|
|||
|
|
1. **密钥安全**: 所有密钥存放在 `.env`，**绝不提交到 Git**
|
|||
|
|
2. **HTTPS 强制**: 生产环境必须启用 HTTPS
|
|||
|
|
3. **签名验证**: 所有回调必须验签
|
|||
|
|
4. **金额校验**: 支付金额必须与订单金额匹配
|
|||
|
|
|
|||
|
|
## 📚 相关文档
|
|||
|
|
|
|||
|
|
- [API 接口定义](./1_核心设计_通用协议/API接口定义.md)
|
|||
|
|
- [数据库模型](./1_核心设计_通用协议/业务逻辑与模型.md)
|
|||
|
|
- [AI 集成指令](./2_智能对接_AI指令/通用集成指令.md)
|
|||
|
|
- [Cursor 规则](./2_智能对接_AI指令/Cursor规则.md)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**作者**: 卡若 | **联系**: 28533368 (微信) | **更新**: 2026-01-17
|