# 全球通用支付模块 (Universal Payment Module) v3.0

这是一个**配置驱动 (Configuration-Driven)**、**API 优先 (API-First)** 的全球支付解决方案包。
它通过标准化的协议和 AI 指令，让任何语言的项目都能在 5 分钟内接入支付宝、微信、PayPal、Stripe 和 USDT。

## 📂 模块结构 (Directory Structure)

\`\`\`
Universal_Payment_Module/
├── 1_核心设计_通用协议/           # [灵魂] 定义了支付的“法律”
│   ├── 标准配置模板.yaml        # [新增] 填空即可配置所有支付参数
│   ├── API接口定义.md           # [新增] 无论用什么语言，接口都长这样
│   ├── 业务逻辑与模型.md        # 数据库表结构设计 (Order/PayTrade)
│   └── 接口注册指南.md          # 申请 Key 的教程
│
├── 2_智能对接_AI指令/             # [工具] AI 编译器
│   └── 通用集成指令.md          # 发给 AI，自动生成代码
│
├── 3_逻辑参考_通用实现/           # [参考]
│   ├── 前端收银台Demo.html      # [新增] 原生 JS 实现的通用收银台
│   ├── 后端源码/                # PHP 参考实现
│   └── 前端模板/                # Twig 参考模板
│
└── README.md                     # 本说明文档
\`\`\`

## 🚀 极速对接 (Integration Guide)

### 第一步：配置 (Config)
1.  打开 `1_核心设计_通用协议/标准配置模板.yaml`。
2.  将文件内容复制到你项目的配置文件中（如 `.env` 或 `config.py`）。
3.  填入你申请到的 `APP_ID`, `PRIVATE_KEY` 等参数。

### 第二步：生成代码 (Generate)
1.  复制 `2_智能对接_AI指令/通用集成指令.md` 的内容。
2.  打开 AI 助手，发送指令：
    > "我的项目是用 **Python FastAPI** 写的。请根据上述文档，采用 **模式 A (嵌入式)** 为我集成支付功能。"
3.  AI 会为你生成：
    *   `pip install ...` 命令
    *   `models.py` (数据库模型)
    *   `payment_router.py` (API 接口)

### 第三步：前端接入 (Frontend)
1.  参考 `3_逻辑参考_通用实现/前端收银台Demo.html`。
2.  将其中的 `API_BASE` 替换为你后端实际的 API 地址。
3.  即可拥有一个支持 **扫码、跳转、加密货币支付** 的全功能收银台。

## 🌍 支持能力
| 渠道 | 能力 | 适用场景 |
| :--- | :--- | :--- |
| **Alipay / Wechat** | 扫码 / H5 / APP | 中国市场 (CNY) |
| **PayPal / Stripe** | 信用卡 / 订阅 | 全球市场 (USD/EUR...) |
| **USDT (TRC20)** | 链上转账 / 监听 | Web3 / 抗审查支付 |

## ✨ v3.0 优化亮点
*   **配置驱动**: 不再需要改代码里的硬编码，所有参数通过配置文件注入。
*   **API 契约**: 明确了输入输出格式，前后端对接不再扯皮。
*   **前端 Demo**: 提供了一个不依赖任何框架的原生 JS 收银台，复制即用。