233 lines
6.0 KiB
Markdown
233 lines
6.0 KiB
Markdown
# Stripe支付集成文档
|
||
|
||
## 1. 概述
|
||
|
||
本文档介绍了如何在DeotalandAi项目中集成Stripe支付功能，包括组件结构、支付流程、配置方法和测试步骤。
|
||
|
||
## 2. 项目结构
|
||
|
||
Stripe支付功能主要通过`StripePaymentForm.vue`组件实现，该组件位于`apps/frontend/src/components/`目录下。
|
||
|
||
## 3. 技术栈
|
||
|
||
- Vue 3 (Composition API)
|
||
- Stripe.js v3
|
||
- Element Plus (UI组件库)
|
||
- Vue I18n (国际化支持)
|
||
|
||
## 4. 组件功能详解
|
||
|
||
### 4.1 核心功能
|
||
|
||
- 信用卡支付处理
|
||
- 订单金额计算
|
||
- 优惠券应用
|
||
- 支付状态管理
|
||
- 响应式设计
|
||
- 暗色主题支持
|
||
- 中英文切换
|
||
|
||
### 4.2 组件结构
|
||
|
||
```
|
||
StripePaymentForm.vue
|
||
├── template
|
||
│ ├── 卡片输入区域
|
||
│ ├── 订单摘要
|
||
│ ├── 优惠券输入
|
||
│ ├── 支付按钮
|
||
│ └── 安全提示
|
||
├── script
|
||
│ ├── 初始化Stripe
|
||
│ ├── 计算税费和运费
|
||
│ ├── 应用优惠券
|
||
│ ├── 处理支付
|
||
│ └── 生命周期管理
|
||
└── style
|
||
├── 基础样式
|
||
├── 暗色主题适配
|
||
└── 响应式设计
|
||
```
|
||
|
||
## 5. 支付流程详解
|
||
|
||
### 5.1 初始化流程
|
||
|
||
1. 组件挂载时调用`initializeStripe()`函数
|
||
2. 加载Stripe.js库
|
||
3. 创建Stripe元素实例
|
||
4. 配置卡片输入样式
|
||
5. 挂载卡片输入元素到DOM
|
||
6. 计算初始税费和运费
|
||
|
||
### 5.2 支付处理流程
|
||
|
||
1. 用户输入信用卡信息
|
||
2. 系统验证卡片信息
|
||
3. 用户点击"立即支付"按钮
|
||
4. 调用`processPayment()`函数
|
||
5. 创建支付方式(Payment Method)
|
||
6. 发送支付请求到后端
|
||
7. 处理支付结果
|
||
8. 触发相应的事件回调
|
||
|
||
### 5.3 关键代码解析
|
||
|
||
```javascript
|
||
// 初始化Stripe
|
||
const initializeStripe = async () => {
|
||
try {
|
||
stripe.value = await loadStripe(STRIPE_PUBLISHABLE_KEY)
|
||
// ... 配置Stripe元素
|
||
} catch (error) {
|
||
console.error('Error initializing Stripe:', error)
|
||
}
|
||
}
|
||
|
||
// 处理支付
|
||
const processPayment = async () => {
|
||
// ... 验证Stripe实例
|
||
|
||
// 创建支付方式
|
||
const { error, paymentMethod: pm } = await stripe.value.createPaymentMethod({
|
||
type: 'card',
|
||
card: cardElement.value,
|
||
billing_details: { email: props.customerEmail }
|
||
})
|
||
|
||
// ... 发送支付请求到后端
|
||
// ... 处理支付结果
|
||
}
|
||
```
|
||
|
||
## 6. 配置和使用
|
||
|
||
### 6.1 Stripe API密钥配置
|
||
|
||
在组件中，Stripe公钥直接定义在代码中：
|
||
|
||
```javascript
|
||
const STRIPE_PUBLISHABLE_KEY = 'pk_test_51SRnUTG9Oq8PDokQxhKzpPYaf5rTFR5OZ8QqTkGVtL9YUwTZFgU4ipN42Lub6NEYjXRvcIx8hvAvJGkKskDQ0pf9003uZhrC9Y'
|
||
```
|
||
|
||
**生产环境建议**：将API密钥存储在环境变量中，通过`.env`文件加载。
|
||
|
||
### 6.2 组件使用
|
||
|
||
在父组件中引入并使用StripePaymentForm组件：
|
||
|
||
```vue
|
||
<template>
|
||
<StripePaymentForm
|
||
:amount="orderAmount"
|
||
:order-id="orderId"
|
||
:customer-email="userEmail"
|
||
@payment-success="handlePaymentSuccess"
|
||
@payment-error="handlePaymentError"
|
||
@cancel="handleCancel"
|
||
/>
|
||
</template>
|
||
|
||
<script setup>
|
||
import StripePaymentForm from './components/StripePaymentForm.vue'
|
||
|
||
// ... 其他代码
|
||
</script>
|
||
```
|
||
|
||
### 6.3 Props参数
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|
||
|--------|------|------|--------|------|
|
||
| amount | Number | 是 | - | 订单金额（分） |
|
||
| currency | String | 否 | 'usd' | 货币类型 |
|
||
| orderId | String | 是 | - | 订单ID |
|
||
| customerEmail | String | 否 | '' | 客户邮箱 |
|
||
|
||
### 6.4 事件
|
||
|
||
| 事件名 | 描述 | 回调参数 |
|
||
|--------|------|----------|
|
||
| payment-success | 支付成功时触发 | paymentResult对象 |
|
||
| payment-error | 支付失败时触发 | 错误对象 |
|
||
| cancel | 用户取消支付时触发 | - |
|
||
|
||
## 7. 测试和调试
|
||
|
||
### 7.1 测试卡号
|
||
|
||
Stripe提供了测试卡号，用于开发和测试：
|
||
|
||
- 成功支付：4242 4242 4242 4242
|
||
- 过期卡片：4000 0000 0000 0069
|
||
- 资金不足：4000 0000 0000 9995
|
||
|
||
### 7.2 测试流程
|
||
|
||
1. 确保前端项目正常运行
|
||
2. 进入支付页面
|
||
3. 输入测试卡号
|
||
4. 输入任意过期日期（未来日期）
|
||
5. 输入任意CVC码
|
||
6. 点击"立即支付"按钮
|
||
7. 观察支付结果
|
||
|
||
### 7.3 调试技巧
|
||
|
||
- 打开浏览器控制台查看日志
|
||
- 使用Stripe Dashboard查看支付记录
|
||
- 检查网络请求是否正常
|
||
- 验证后端API是否正确处理支付请求
|
||
|
||
## 8. 常见问题和解决方案
|
||
|
||
### 8.1 问题：Stripe初始化失败
|
||
|
||
**解决方案**：
|
||
- 检查Stripe公钥是否正确
|
||
- 确保网络连接正常
|
||
- 检查浏览器控制台是否有错误信息
|
||
|
||
### 8.2 问题：支付被拒绝
|
||
|
||
**解决方案**：
|
||
- 检查测试卡号是否正确
|
||
- 确保订单金额大于0
|
||
- 检查Stripe账户是否有足够的余额
|
||
|
||
### 8.3 问题：优惠券不生效
|
||
|
||
**解决方案**：
|
||
- 检查优惠券代码是否正确
|
||
- 验证优惠券是否在有效期内
|
||
- 检查优惠券使用条件是否满足
|
||
|
||
## 9. 支付流程优化建议
|
||
|
||
1. **添加支付方式选择**：支持更多支付方式，如Apple Pay、Google Pay等
|
||
2. **增强错误处理**：提供更详细的错误信息和解决方案
|
||
3. **添加支付进度提示**：提升用户体验
|
||
4. **实现支付结果页面**：统一处理支付成功和失败的情况
|
||
5. **添加支付记录查询**：方便用户查看历史支付记录
|
||
|
||
## 10. 安全注意事项
|
||
|
||
1. 不要在前端代码中暴露Stripe密钥
|
||
2. 所有支付请求必须经过后端验证
|
||
3. 定期更新Stripe库版本
|
||
4. 遵循PCI DSS安全标准
|
||
5. 加密敏感支付信息
|
||
|
||
## 11. 部署建议
|
||
|
||
1. 生产环境使用真实的Stripe API密钥
|
||
2. 配置Webhook接收Stripe事件通知
|
||
3. 实现幂等性处理，防止重复支付
|
||
4. 定期备份支付数据
|
||
5. 监控支付系统性能和错误率
|
||
|
||
## 12. 总结
|
||
|
||
Stripe支付集成是DeotalandAi项目中的重要功能，通过`StripePaymentForm.vue`组件实现了完整的支付流程。本文档详细介绍了组件结构、支付流程、配置方法和测试步骤，希望能帮助开发人员更好地理解和使用Stripe支付功能。
|
||
|
||
如需进一步了解Stripe支付API，请参考[Stripe官方文档](https://stripe.com/docs/api)。 |