soul/addons/Universal_Payment_Module copy/2_智能对接_AI指令/通用集成指令.md

# 通用支付模块 AI 智能对接指令 (Integration Prompt) v4.0

> 发送此指令给 AI 助手 (Cursor/ChatGPT/Claude)，自动生成支付集成代码

---

## 🎯 角色设定

```
你是一位精通全球支付架构的资深全栈架构师，专注于：
- 支付网关集成 (Alipay/Wechat/PayPal/Stripe/USDT)
- 安全合规 (签名验证/HTTPS/PCI DSS)
- 高可用设计 (幂等性/状态机/分布式锁)
```

---

## 📋 任务目标

我提供了一个**配置驱动 (Configuration-Driven)** 的通用支付模块设计。
请根据我的项目环境，将此支付功能无缝集成。

---

## 📚 核心资源 (请先阅读)

1. **标准配置模板**: `1_核心设计_通用协议/标准配置模板.yaml`
2. **API 接口契约**: `1_核心设计_通用协议/API接口定义.md`
3. **数据模型**: `1_核心设计_通用协议/业务逻辑与模型.md`
4. **安全规范**: `1_核心设计_通用协议/安全与合规.md`

---

## 🔧 集成模式

### 模式 A: 嵌入式集成 (Library Mode) ⭐推荐

适用于将支付功能直接写在现有的后端项目中。

**执行步骤**:
1. **环境识别**: 检查项目语言 (Python/Node/Go/Java/PHP)
2. **依赖安装**: 推荐 SDK
3. **配置加载**: 读取环境变量
4. **模型生成**: 创建 ORM 模型 (Order/Trade/Refund)
5. **网关工厂**: 实现 PaymentFactory + 各网关 Driver
6. **接口实现**: 按 `API接口定义.md` 实现 Controller
7. **回调处理**: 实现回调验签和状态更新

---

### 模式 B: 微服务集成 (Microservice Mode)

适用于将支付功能独立部署为一个服务。

**执行步骤**:
1. **服务生成**: 创建独立的支付服务项目
2. **Docker化**: 编写 `Dockerfile` 和 `docker-compose.yml`
3. **网关代理**: 配置 `/api/payment/*` 路由转发

---

## 📝 给 AI 的标准执行指令

### 快速集成 (复制此内容发送给 AI)

```
请读取 `Universal_Payment_Module` 目录下的所有设计文档。

我的当前项目信息：
- 语言/框架: [Python FastAPI / Node.js Express / Java Spring Boot / Go Gin / PHP Laravel]
- 数据库: [MySQL / PostgreSQL / MongoDB]
- 集成模式: [模式 A 嵌入式 / 模式 B 微服务]

请执行以下任务：
1. 生成依赖安装命令
2. 生成数据库迁移/模型代码
3. 生成支付网关工厂类
4. 生成 API 接口代码 (严格按 API接口定义.md)
5. 生成回调处理代码
6. 生成配置读取代码

要求：
- 使用工厂模式管理支付网关
- 所有配置通过环境变量读取
- 包含完整的签名验证逻辑
- 包含幂等性处理
- 添加中文注释
```

---

## 🐍 Python FastAPI 示例指令

```
我的项目使用 Python FastAPI + SQLAlchemy + MySQL。

请根据 Universal_Payment_Module 文档，生成：

1. requirements.txt 依赖
2. app/models/payment.py - 数据模型
3. app/services/payment_factory.py - 支付网关工厂
4. app/services/gateways/alipay.py - 支付宝网关
5. app/services/gateways/wechat.py - 微信支付网关
6. app/routers/payment.py - API 路由
7. app/config/payment.py - 配置加载

特别要求：
- 使用 async/await 异步处理
- 集成 alipay-sdk-python 和 wechatpay-python-v3
- 回调接口支持 XML 和 JSON 格式
```

---

## 🟢 Node.js Express 示例指令

```
我的项目使用 Node.js Express + Prisma + PostgreSQL。

请根据 Universal_Payment_Module 文档，生成：

1. package.json 依赖
2. prisma/schema.prisma - 数据模型
3. src/services/PaymentFactory.ts - 支付网关工厂
4. src/services/gateways/AlipayGateway.ts
5. src/services/gateways/WechatGateway.ts
6. src/routes/payment.ts - API 路由
7. src/config/payment.ts - 配置加载

特别要求：
- 使用 TypeScript
- 使用 alipay-sdk 和 wechatpay-node-v3
- 实现完整的错误处理
```

---

## ☕ Java Spring Boot 示例指令

```
我的项目使用 Java Spring Boot + MyBatis + MySQL。

请根据 Universal_Payment_Module 文档，生成：

1. pom.xml 依赖
2. entity/ - 实体类
3. mapper/ - MyBatis Mapper
4. service/PaymentFactory.java - 支付网关工厂
5. service/gateway/AlipayGateway.java
6. service/gateway/WechatGateway.java
7. controller/PaymentController.java - API 控制器
8. config/PaymentConfig.java - 配置类

特别要求：
- 使用 alipay-sdk-java 和 wechatpay-java
- 使用 @Transactional 事务管理
- 实现统一异常处理
```

---

## 🐘 PHP Laravel 示例指令

```
我的项目使用 PHP Laravel + Eloquent + MySQL。

请根据 Universal_Payment_Module 文档，生成：

1. composer.json 依赖
2. database/migrations/ - 数据库迁移
3. app/Models/ - Eloquent 模型
4. app/Services/PaymentFactory.php - 支付网关工厂
5. app/Services/Gateways/AlipayGateway.php
6. app/Services/Gateways/WechatGateway.php
7. app/Http/Controllers/PaymentController.php
8. routes/api.php - 路由定义
9. config/payment.php - 配置文件

特别要求：
- 使用 alipay/aop-sdk 和 wechatpay/wechatpay
- 使用 Laravel 的服务容器
- 实现中间件验签
```

---

## 🔥 高级指令：前端收银台

```
请根据 Universal_Payment_Module 文档，生成前端收银台组件。

技术栈: [Vue 3 / React / 原生 JS]

要求：
1. 支持多种支付方式切换
2. 扫码支付显示二维码
3. 轮询支付状态
4. 适配移动端
5. 显示支付倒计时
6. 美观的 UI (可使用 TailwindCSS)
```

---

## 🔥 高级指令：Docker 部署

```
请为 Universal_Payment_Module 生成 Docker 部署配置。

要求：
1. Dockerfile (多阶段构建)
2. docker-compose.yml (包含 MySQL + Redis)
3. nginx.conf (反向代理 + HTTPS)
4. .env.example (环境变量模板)
5. deploy.sh (一键部署脚本)
```

---

## ⚠️ 注意事项

1. **密钥安全**: 生成的代码中不要硬编码任何密钥
2. **签名验证**: 必须实现完整的签名验证逻辑
3. **幂等处理**: 回调必须支持幂等
4. **金额校验**: 必须验证回调金额与订单金额匹配
5. **日志记录**: 关键操作必须记录日志

---

## 📞 支持

如有问题，请联系：
- 微信: 28533368
- 作者: 卡若