Update soul-content project

2025-12-29 14:01:37 +08:00
commit 087849d509
1112 changed files with 401606 additions and 0 deletions
--- a/addons/Universal_Payment_Module/.DS_Store
+++ b/addons/Universal_Payment_Module/.DS_Store
--- a/addons/Universal_Payment_Module/1_核心设计_通用协议/API接口定义.md
+++ b/addons/Universal_Payment_Module/1_核心设计_通用协议/API接口定义.md
@@ -0,0 +1,94 @@
+# 通用支付模块 API 接口定义 (Universal Payment API)
+
+无论后端使用何种语言（Python/Node/Go），请严格实现以下 RESTful 接口。
+
+## 1. 核心交易接口 (Core Transaction)
+
+### 1.1 创建订单
+*   **URL**: `POST /api/payment/create_order`
+*   **Description**: 业务系统通知支付模块创建一个待支付订单。
+*   **Request Body**:
+    ```json
+    {
+      "user_id": "u1001",           // 用户ID
+      "title": "VIP Membership",    // 订单标题
+      "amount": 99.00,              // 金额 (法币单位: 元 / 美元)
+      "currency": "CNY",            // 币种: CNY, USD
+      "product_id": "vip_01",       // 商品ID
+      "extra_params": {}            // 扩展参数
+    }
+    ```
+*   **Response**:
+    ```json
+    {
+      "code": 200,
+      "data": {
+        "order_sn": "202310270001", // 支付系统生成的唯一订单号
+        "status": "created"
+      }
+    }
+    ```
+
+### 1.2 发起支付 (收银台)
+*   **URL**: `POST /api/payment/checkout`
+*   **Description**: 用户选择支付方式后，获取支付参数。
+*   **Request Body**:
+    ```json
+    {
+      "order_sn": "202310270001",
+      "gateway": "alipay_qr",       // 支付方式: alipay_qr, wechat_jsapi, paypal, usdt, stripe
+      "return_url": "https://...",  // 支付成功后前端跳转地址
+      "openid": "..."               // 微信JSAPI支付必填
+    }
+    ```
+*   **Response**:
+    ```json
+    {
+      "code": 200,
+      "data": {
+        "type": "url",              // url (跳转), qrcode (扫码), json (SDK参数), address (USDT)
+        "payload": "https://...",   // 具体内容
+        "expiration": 1800          // 过期时间(秒)
+      }
+    }
+    ```
+
+### 1.3 查询订单状态
+*   **URL**: `GET /api/payment/status/{order_sn}`
+*   **Description**: 前端轮询使用。
+*   **Response**:
+    ```json
+    {
+      "code": 200,
+      "data": {
+        "status": "paid",           // created, paying, paid, closed
+        "paid_amount": 99.00,
+        "paid_at": "2023-10-27 10:00:00"
+      }
+    }
+    ```
+
+---
+
+## 2. 回调通知接口 (Webhook)
+
+### 2.1 统一回调入口
+*   **URL**: `POST /api/payment/notify/{gateway}`
+*   **Description**: 接收第三方支付平台的异步通知。
+*   **Path Params**:
+    *   `gateway`: `alipay`, `wechat`, `paypal`, `stripe`, `nowpayments`
+*   **Logic**:
+    1.  根据 gateway 加载对应驱动。
+    2.  验签 (Verify Signature)。
+    3.  幂等性检查 (Idempotency Check)。
+    4.  更新订单状态。
+    5.  返回平台所需的响应字符串 (e.g. `success`, `200 OK`).
+
+---
+
+## 3. 辅助接口
+
+### 3.1 获取汇率
+*   **URL**: `GET /api/payment/exchange_rate`
+*   **Params**: `from=USD&to=CNY`
+*   **Response**: `{"rate": 7.21}`
--- a/addons/Universal_Payment_Module/1_核心设计_通用协议/标准配置模板.yaml
+++ b/addons/Universal_Payment_Module/1_核心设计_通用协议/标准配置模板.yaml
@@ -0,0 +1,70 @@
+# 全球支付模块标准配置模板 (Standard Config)
+
+# 无论你使用 Python, Node.js, Go 还是 Java，请将此配置映射到你的环境（如 .env, config.py, config.js）
+
+# -------------------------------------------------------------------
+# 1. 基础环境 (Environment)
+# -------------------------------------------------------------------
+APP_ENV: "production"          # development / production
+APP_URL: "https://your-site.com" # 你的网站域名 (用于回调)
+
+# -------------------------------------------------------------------
+# 2. 数据库 (Database)
+# -------------------------------------------------------------------
+# 系统会自动生成 order 和 pay_trade 表
+DB_CONNECTION: "mysql"         # mysql / postgres / sqlite
+DB_HOST: "127.0.0.1"
+DB_PORT: "3306"
+DB_DATABASE: "payment_db"
+DB_USERNAME: "root"
+DB_PASSWORD: "password"
+
+# -------------------------------------------------------------------
+# 3. 支付宝 (Alipay) - CN
+# -------------------------------------------------------------------
+ALIPAY_ENABLED: true
+ALIPAY_APP_ID: "20210001..."
+ALIPAY_PRIVATE_KEY: "MIIETv..."  # 商户私钥
+ALIPAY_PUBLIC_KEY: "MIIBIj..."   # 支付宝公钥
+
+# -------------------------------------------------------------------
+# 4. 微信支付 (Wechat Pay) - CN
+# -------------------------------------------------------------------
+WECHAT_ENABLED: true
+WECHAT_APP_ID: "wx123456..."     # 公众号/小程序 AppID
+WECHAT_MCH_ID: "1234567890"      # 商户号
+WECHAT_API_V3_KEY: "abcdef..."   # APIv3 密钥 (32位)
+WECHAT_CERT_SERIAL: "45F59C..."  # 证书序列号
+WECHAT_PRIVATE_KEY_PATH: "./cert/apiclient_key.pem"
+WECHAT_CERT_PATH: "./cert/apiclient_cert.pem"
+
+# -------------------------------------------------------------------
+# 5. PayPal - Global
+# -------------------------------------------------------------------
+PAYPAL_ENABLED: true
+PAYPAL_MODE: "live"              # sandbox / live
+PAYPAL_CLIENT_ID: "Af7s8..."
+PAYPAL_CLIENT_SECRET: "EKd9..."
+
+# -------------------------------------------------------------------
+# 6. Stripe - Global
+# -------------------------------------------------------------------
+STRIPE_ENABLED: true
+STRIPE_PUBLIC_KEY: "pk_live_..."
+STRIPE_SECRET_KEY: "sk_live_..."
+STRIPE_WEBHOOK_SECRET: "whsec_..."
+
+# -------------------------------------------------------------------
+# 7. USDT (Crypto) - Web3
+# -------------------------------------------------------------------
+USDT_ENABLED: true
+USDT_GATEWAY_TYPE: "nowpayments" # nowpayments / native (原生监听)
+
+# 选项 A: NOWPayments (第三方网关)
+NOWPAYMENTS_API_KEY: "R1G..."
+NOWPAYMENTS_IPN_SECRET: "secret..."
+
+# 选项 B: Native (原生监听 - TRC20)
+TRON_NODE_API: "https://api.trongrid.io"
+TRON_WALLET_ADDRESS: "T9yD14Nj9..." # 你的收款地址
+TRON_CHECK_INTERVAL: 60             # 轮询间隔 (秒)
--- a/addons/Universal_Payment_Module/2_智能对接_AI指令/通用集成指令.md
+++ b/addons/Universal_Payment_Module/2_智能对接_AI指令/通用集成指令.md
@@ -0,0 +1,44 @@
+# 通用支付模块智能对接指令 (AI Integration Prompt) v3.0
+
+**角色设定**: 你是一位精通全球支付架构（Alipay/Wechat/PayPal/Stripe/USDT）的资深全栈架构师。
+
+**任务目标**:
+我提供了一个**完全配置驱动 (Configuration-Driven)** 的通用支付模块设计。
+请你根据我的目标项目环境，将此支付功能无缝集成进去。
+
+**核心资源 (Input)**:
+1.  **标准配置模板**: `1_核心设计_通用协议/标准配置模板.yaml` (所有支付参数的 Key)
+2.  **API 接口契约**: `1_核心设计_通用协议/API接口定义.md` (标准 RESTful 接口)
+3.  **核心业务模型**: `1_核心设计_通用协议/业务逻辑与模型.md` (数据库表结构)
+
+**集成模式 (选择一种)**:
+
+### 模式 A: 嵌入式集成 (Library Mode) - *推荐*
+适用于将支付功能直接写在现有的后端项目中 (如 Django app, NestJS module)。
+
+**步骤**:
+1.  **环境识别**: 检查我的项目语言 (Python/Node/Go/Java)。
+2.  **依赖安装**: 根据语言推荐 SDK (e.g. `alipay-sdk-python`, `stripe`).
+3.  **配置加载**: 创建代码读取 `标准配置模板.yaml` 中的环境变量。
+4.  **模型生成**: 根据 `业务逻辑与模型.md` 生成 ORM 代码 (User/Order/PayTrade)。
+5.  **接口实现**: 严格按照 `API接口定义.md` 实现 Controller/View。
+    *   *要求*: 使用工厂模式 (`PaymentFactory`) 管理不同网关。
+
+### 模式 B: 微服务集成 (Microservice Mode)
+适用于将支付功能独立部署为一个 Docker 容器。
+
+**步骤**:
+1.  **服务生成**: 用 Go (Gin) 或 Node.js (Express) 生成一个独立服务。
+2.  **Docker化**: 编写 `Dockerfile` 和 `docker-compose.yml`。
+3.  **网关代理**: 配置 Nginx 或 API Gateway 将 `/api/payment` 转发给此服务。
+
+---
+
+**给 AI 的执行指令 (Prompt)**:
+
+> "请读取 `Universal_Payment_Module` 目录下的所有设计文档。
+> 我的当前项目是基于 **[你的语言/框架]** 的。
+> 请采用 **[模式 A / 模式 B]** 为我集成支付功能。
+> 1. 首先生成依赖安装命令。
+> 2. 然后生成数据库模型代码。
+> 3. 最后实现符合 `API接口定义.md` 的核心接口代码。"
--- a/addons/Universal_Payment_Module/3_逻辑参考_通用实现/前端收银台Demo.html
+++ b/addons/Universal_Payment_Module/3_逻辑参考_通用实现/前端收银台Demo.html
@@ -0,0 +1,141 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>通用收银台 Demo</title>
+    <style>
+        /* 简单的内联样式，实际使用建议用 TailwindCSS */
+        body { font-family: -apple-system, sans-serif; background: #f5f5f7; padding: 20px; }
+        .container { max-width: 480px; margin: 0 auto; background: white; border-radius: 12px; padding: 24px; box-shadow: 0 4px 6px rgba(0,0,0,0.1); }
+        .order-info { margin-bottom: 24px; border-bottom: 1px solid #eee; padding-bottom: 16px; }
+        .amount { font-size: 32px; font-weight: bold; color: #333; }
+        .payment-methods { display: flex; flex-direction: column; gap: 12px; }
+        .method-btn { display: flex; align-items: center; justify-content: space-between; padding: 16px; border: 1px solid #ddd; border-radius: 8px; background: white; cursor: pointer; transition: all 0.2s; }
+        .method-btn:hover { border-color: #007aff; background: #f0f7ff; }
+        .method-btn.active { border-color: #007aff; box-shadow: 0 0 0 2px rgba(0,122,255,0.2); }
+        .btn-pay { width: 100%; background: #007aff; color: white; border: none; padding: 16px; border-radius: 8px; font-size: 16px; font-weight: bold; margin-top: 24px; cursor: pointer; }
+        .btn-pay:disabled { background: #ccc; }
+        .qrcode-area { text-align: center; margin-top: 20px; display: none; }
+        .qrcode-area img { width: 200px; height: 200px; }
+    </style>
+</head>
+<body>
+
+<div class="container">
+    <div class="order-info">
+        <div style="color: #666; font-size: 14px;">订单支付</div>
+        <div class="amount" id="displayAmount">¥ 99.00</div>
+        <div style="margin-top: 8px; font-size: 14px;">订单号: <span id="orderSn">202310270001</span></div>
+    </div>
+
+    <div class="payment-methods" id="paymentMethods">
+        <!-- 支付宝 -->
+        <div class="method-btn" onclick="selectMethod('alipay_qr')">
+            <span>🔵 支付宝 (Alipay)</span>
+            <input type="radio" name="method" value="alipay_qr">
+        </div>
+        <!-- 微信 -->
+        <div class="method-btn" onclick="selectMethod('wechat_scan')">
+            <span>🟢 微信支付 (Wechat)</span>
+            <input type="radio" name="method" value="wechat_scan">
+        </div>
+        <!-- PayPal -->
+        <div class="method-btn" onclick="selectMethod('paypal')">
+            <span>🅿️ PayPal (USD)</span>
+            <input type="radio" name="method" value="paypal">
+        </div>
+        <!-- USDT -->
+        <div class="method-btn" onclick="selectMethod('usdt')">
+            <span>🪙 USDT (TRC20)</span>
+            <input type="radio" name="method" value="usdt">
+        </div>
+    </div>
+
+    <div class="qrcode-area" id="qrcodeArea">
+        <img id="qrcodeImg" src="" alt="QRCode">
+        <p id="qrcodeText">请扫描二维码支付</p>
+    </div>
+
+    <button class="btn-pay" onclick="doPay()">确认支付</button>
+</div>
+
+<script>
+    let selectedMethod = null;
+    const API_BASE = '/api/payment'; // 你的后端接口地址
+
+    function selectMethod(method) {
+        selectedMethod = method;
+        document.querySelectorAll('.method-btn').forEach(el => el.classList.remove('active'));
+        event.currentTarget.classList.add('active');
+        document.querySelector(`input[value="${method}"]`).checked = true;
+        
+        // 如果选了USDT，可能需要先换算汇率（模拟）
+        if(method === 'usdt') {
+            document.getElementById('displayAmount').innerText = '₮ 13.88'; // 模拟 99 CNY -> USDT
+        } else if(method === 'paypal') {
+            document.getElementById('displayAmount').innerText = '$ 13.75'; // 模拟 99 CNY -> USD
+        } else {
+            document.getElementById('displayAmount').innerText = '¥ 99.00';
+        }
+    }
+
+    async function doPay() {
+        if (!selectedMethod) {
+            alert('请选择支付方式');
+            return;
+        }
+
+        const orderSn = document.getElementById('orderSn').innerText;
+
+        try {
+            // 调用后端通用接口
+            const response = await fetch(`${API_BASE}/checkout`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    order_sn: orderSn,
+                    gateway: selectedMethod,
+                    return_url: window.location.href
+                })
+            });
+            const result = await response.json();
+
+            if (result.data.type === 'url') {
+                // 跳转类 (PayPal, H5)
+                window.location.href = result.data.payload;
+            } else if (result.data.type === 'qrcode') {
+                // 扫码类 (Wechat, Alipay)
+                document.getElementById('qrcodeArea').style.display = 'block';
+                document.getElementById('qrcodeImg').src = `https://api.qrserver.com/v1/create-qr-code/?data=${encodeURIComponent(result.data.payload)}`;
+                startPolling(orderSn);
+            } else if (result.data.type === 'address') {
+                // 加密货币类
+                document.getElementById('qrcodeArea').style.display = 'block';
+                document.getElementById('qrcodeText').innerText = `请转账至: ${result.data.payload}`;
+                // 生成地址二维码...
+                startPolling(orderSn);
+            }
+
+        } catch (error) {
+            console.error('支付发起失败', error);
+            alert('支付发起失败，请查看控制台');
+        }
+    }
+
+    // 轮询查单
+    function startPolling(orderSn) {
+        const timer = setInterval(async () => {
+            const res = await fetch(`${API_BASE}/status/${orderSn}`);
+            const data = await res.json();
+            if (data.data.status === 'paid') {
+                clearInterval(timer);
+                alert('支付成功！');
+                window.location.reload();
+            }
+        }, 3000);
+    }
+</script>
+
+</body>
+</html>
--- a/addons/Universal_Payment_Module/README.md
+++ b/addons/Universal_Payment_Module/README.md
@@ -0,0 +1,58 @@
+# 全球通用支付模块 (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 收银台，复制即用。