# Stripe 支付集成配置指南

本文档详细说明如何为 Prmbr 项目配置 Stripe 支付系统，实现订阅管理功能。

## 1. Stripe 账户设置

### 1.1 创建 Stripe 账户
1. 访问 [Stripe Dashboard](https://dashboard.stripe.com/)
2. 注册或登录 Stripe 账户
3. 完成账户验证（可能需要提供业务信息）

### 1.2 获取 API 密钥
在 Stripe Dashboard 中：
1. 进入 **Developers** → **API keys**
2. 复制以下密钥：
   - **Publishable key** (以 `pk_` 开头)
   - **Secret key** (以 `sk_` 开头)

## 2. 创建产品和价格

### 2.1 创建 Pro 订阅产品
1. 在 Stripe Dashboard 中，进入 **Products**
2. 点击 **Add product**
3. 填写产品信息：
   - **Name**: `Prmbr Pro Plan`
   - **Description**: `Professional plan with advanced features`
4. 添加价格：
   - **Price**: `$19.90`
   - **Billing period**: `Monthly`
   - **Currency**: `USD`
5. 保存产品并复制 **Price ID** (以 `price_` 开头)

### 2.2 配置产品元数据（可选）
为产品添加元数据以便识别：
- `plan_type`: `pro`
- `features`: `5000_prompts,10_versions,priority_support`

## 3. 环境变量配置

在项目根目录的 `.env.local` 文件中添加以下环境变量：

```bash
# Stripe 配置
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_your_publishable_key_here"
STRIPE_SECRET_KEY="sk_test_your_secret_key_here"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# Webhook 密钥（稍后配置）
STRIPE_WEBHOOK_SECRET="whsec_your_webhook_secret_here"
```

**注意**: 不再需要 `NEXT_PUBLIC_STRIPE_PRO_PRICE_ID` 环境变量，价格 ID 现在从数据库动态获取。

### 3.1 配置 Pro 套餐价格 ID

创建 Stripe 价格后，需要在数据库中更新 Pro 套餐的 `stripePriceId` 字段：

```sql
-- 在数据库中更新 Pro 套餐的 Stripe 价格 ID
UPDATE subscription_plans
SET "stripePriceId" = 'price_your_actual_pro_price_id_here'
WHERE name = 'pro';
```

或者使用管理员 API 更新：

```bash
curl -X PUT http://localhost:3000/api/admin/subscription-plans \
  -H "Content-Type: application/json" \
  -d '{
    "id": "pro",
    "stripePriceId": "price_your_actual_pro_price_id_here"
  }'
```

## 4. Webhook 配置

### 4.1 创建 Webhook 端点
1. 在 Stripe Dashboard 中，进入 **Developers** → **Webhooks**
2. 点击 **Add endpoint**
3. 设置端点 URL：
   - **开发环境**: `http://localhost:3000/api/webhooks/stripe`
   - **生产环境**: `https://yourdomain.com/api/webhooks/stripe`

### 4.2 选择监听事件
添加以下事件类型：
- `customer.subscription.created`
- `customer.subscription.updated`
- `customer.subscription.deleted`
- `invoice.payment_succeeded`
- `invoice.payment_failed`

### 4.3 获取 Webhook 签名密钥
1. 创建 webhook 后，点击进入详情页面
2. 在 **Signing secret** 部分，点击 **Reveal** 复制密钥
3. 将密钥添加到环境变量 `STRIPE_WEBHOOK_SECRET`

## 5. 客户门户配置

### 5.1 启用客户门户
1. 在 Stripe Dashboard 中，进入 **Settings** → **Billing** → **Customer portal**
2. 点击 **Activate** 启用客户门户
3. 配置门户设置：
   - **Business information**: 填写公司信息
   - **Customer information**: 允许客户更新邮箱和地址
   - **Subscriptions**: 允许客户取消订阅
   - **Payment methods**: 允许客户更新付款方式

### 5.2 自定义门户外观
1. 在 **Branding** 部分上传 Logo
2. 设置主题颜色以匹配您的品牌
3. 配置返回 URL: `https://yourdomain.com/subscription`

## 6. 测试配置

### 6.1 使用测试卡号
Stripe 提供测试卡号用于开发：
- **成功支付**: `4242 4242 4242 4242`
- **需要验证**: `4000 0025 0000 3155`
- **被拒绝**: `4000 0000 0000 0002`

### 6.2 测试订阅流程
1. 启动开发服务器: `npm run dev`
2. 访问价格页面: `http://localhost:3000/pricing`
3. 点击 "Upgrade to Pro" 按钮
4. 使用测试卡号完成支付
5. 验证用户订阅状态是否正确更新

## 7. 生产环境部署

### 7.1 切换到生产密钥
1. 在 Stripe Dashboard 右上角关闭 **Test mode**
2. 获取生产环境的 API 密钥
3. 更新环境变量为生产密钥

### 7.2 更新 Webhook URL
1. 创建新的生产环境 webhook 端点
2. 使用生产域名: `https://yourdomain.com/api/webhooks/stripe`
3. 更新 `STRIPE_WEBHOOK_SECRET` 为生产密钥

### 7.3 验证配置
- 确保所有环境变量正确设置
- 测试完整的订阅和取消流程
- 验证 webhook 事件正常接收和处理

## 8. 常见问题

### 8.1 Webhook 验证失败
- 检查 `STRIPE_WEBHOOK_SECRET` 是否正确
- 确保 webhook URL 可以从外网访问
- 验证请求头中的签名

### 8.2 订阅状态不同步
- 检查 webhook 事件是否正常接收
- 查看服务器日志中的错误信息
- 确保数据库连接正常

### 8.3 支付失败
- 检查 Stripe 密钥是否正确
- 验证产品和价格 ID 是否匹配
- 确保客户信息完整

## 9. 安全注意事项

1. **密钥安全**：
   - 永远不要在客户端代码中暴露 Secret Key
   - 使用环境变量存储敏感信息
   - 定期轮换 API 密钥

2. **Webhook 安全**：
   - 始终验证 webhook 签名
   - 使用 HTTPS 端点
   - 实现幂等性处理

3. **数据保护**：
   - 不要存储完整的信用卡信息
   - 遵循 PCI DSS 合规要求
   - 定期备份订阅数据

## 10. 监控和日志

### 10.1 Stripe Dashboard 监控
- 定期检查支付状态
- 监控失败的支付和订阅
- 查看客户活动日志

### 10.2 应用程序日志
- 记录所有 Stripe API 调用
- 监控 webhook 处理状态
- 设置错误告警

---

配置完成后，您的应用程序将具备完整的订阅管理功能，包括：
- 用户订阅 Pro 计划
- 自动处理订阅状态变更
- 客户自助管理订阅
- 安全的支付处理