# 🌐 全球通用支付模块 (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