# 支付和计费系统

## 概述

本系统实现了完整的支付和计费功能，支持订阅管理、账单生成、支付处理和财务报表。集成了 Stripe 作为支付处理器，支持信用卡和银行账户支付。

## 系统架构

### 服务组件

1. **Billing Service** (`services/billing-service/`)
   - 端口：3010
   - 负责所有计费相关功能
   - 集成 Stripe API
   - 处理 Webhook 事件

2. **API Gateway 集成**
   - 路由前缀：`/api/v1/billing/`
   - 自动转发到 Billing Service
   - 支持认证和限流

3. **前端组件**
   - 计费仪表板
   - 订阅管理
   - 支付方式管理
   - 账单历史

## 核心功能

### 1. 订阅管理

#### 订阅计划
- **免费版**：基础功能，限制使用量
- **入门版**：$29/月，适合小团队
- **专业版**：$99/月，高级功能
- **企业版**：$299/月，无限制使用

#### 订阅功能
- 创建和升级订阅
- 取消和恢复订阅
- 试用期管理
- 使用量跟踪
- 优惠券和折扣

### 2. 支付方式

#### 支持的支付类型
- 信用卡/借记卡
- 银行账户（ACH）

#### 支付方式管理
- 添加和删除支付方式
- 设置默认支付方式
- 支付方式验证
- 账单地址管理

### 3. 账单和发票

#### 账单功能
- 自动生成月度账单
- 手动创建账单
- 账单支付和退款
- PDF 账单下载
- 邮件通知

#### 账单状态
- 草稿（Draft）
- 待支付（Open）
- 已支付（Paid）
- 已作废（Void）
- 无法收回（Uncollectible）

### 4. 交易管理

#### 交易类型
- 支付（Payment）
- 退款（Refund）
- 调整（Adjustment）
- 费用（Fee）

#### 交易功能
- 交易历史查询
- 交易汇总报表
- 导出功能（CSV、PDF、Excel）
- 退款处理

## 数据模型

### Subscription 模型
```javascript
{
  tenantId: ObjectId,           // 租户ID
  customerId: String,           // 客户ID
  plan: String,                 // 订阅计划
  status: String,               // 状态
  currentPeriodStart: Date,     // 当前周期开始
  currentPeriodEnd: Date,       // 当前周期结束
  trialEnd: Date,              // 试用期结束
  usage: Object,               // 使用量跟踪
  metadata: Object             // 元数据
}
```

### Invoice 模型
```javascript
{
  tenantId: ObjectId,          // 租户ID
  invoiceNumber: String,       // 账单号
  customerId: String,          // 客户ID
  status: String,              // 状态
  lineItems: Array,            // 行项目
  subtotal: Number,            // 小计
  tax: Object,                 // 税费
  total: Number,               // 总计
  amountDue: Number,           // 应付金额
  dueDate: Date               // 到期日
}
```

### PaymentMethod 模型
```javascript
{
  tenantId: ObjectId,          // 租户ID
  customerId: String,          // 客户ID
  type: String,                // 类型（card/bank_account）
  card: Object,                // 卡片信息
  bankAccount: Object,         // 银行账户信息
  isDefault: Boolean,          // 是否默认
  status: String              // 状态
}
```

### Transaction 模型
```javascript
{
  tenantId: ObjectId,          // 租户ID
  transactionId: String,       // 交易ID
  type: String,                // 类型
  status: String,              // 状态
  amount: Number,              // 金额
  currency: String,            // 货币
  fee: Number,                 // 手续费
  net: Number,                 // 净额
  processedAt: Date           // 处理时间
}
```

## API 端点

### 订阅 API
- `GET /api/v1/billing/subscriptions` - 获取订阅列表
- `POST /api/v1/billing/subscriptions` - 创建订阅
- `PATCH /api/v1/billing/subscriptions/:id` - 更新订阅
- `POST /api/v1/billing/subscriptions/:id/cancel` - 取消订阅
- `POST /api/v1/billing/subscriptions/:id/reactivate` - 恢复订阅
- `POST /api/v1/billing/subscriptions/:id/usage` - 记录使用量

### 账单 API
- `GET /api/v1/billing/invoices` - 获取账单列表
- `POST /api/v1/billing/invoices` - 创建账单
- `GET /api/v1/billing/invoices/:id` - 获取账单详情
- `POST /api/v1/billing/invoices/:id/pay` - 支付账单
- `GET /api/v1/billing/invoices/:id/pdf` - 下载账单 PDF

### 支付方式 API
- `GET /api/v1/billing/payment-methods` - 获取支付方式列表
- `POST /api/v1/billing/payment-methods` - 添加支付方式
- `DELETE /api/v1/billing/payment-methods/:id` - 删除支付方式
- `POST /api/v1/billing/payment-methods/:id/default` - 设为默认

### 交易 API
- `GET /api/v1/billing/transactions` - 获取交易列表
- `POST /api/v1/billing/transactions/:id/refund` - 创建退款
- `GET /api/v1/billing/transactions/summary/:period` - 获取汇总
- `GET /api/v1/billing/transactions/export/:format` - 导出交易

## Webhook 集成

### Stripe Webhook 事件
系统监听以下 Stripe webhook 事件：
- `customer.subscription.created` - 订阅创建
- `customer.subscription.updated` - 订阅更新
- `customer.subscription.deleted` - 订阅删除
- `invoice.payment_succeeded` - 支付成功
- `invoice.payment_failed` - 支付失败

### Webhook 端点
```
POST /api/v1/billing/webhooks/stripe
```

## 安全性

### 支付安全
- 使用 Stripe.js 进行安全的支付信息收集
- 不存储完整的信用卡号或银行账户信息
- 所有支付数据通过 HTTPS 传输
- PCI DSS 合规

### 访问控制
- 租户隔离：每个租户只能访问自己的计费数据
- 角色权限：管理员才能访问计费设置
- API 认证：所有端点需要 JWT 认证

## 配置

### 环境变量
```env
# Stripe 配置
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# 计费服务配置
BILLING_URL=http://localhost:3010
BILLING_PORT=3010

# 数据库
MONGODB_URI=mongodb://localhost:27017/billing
```

### 计费配置
```javascript
{
  currency: 'USD',           // 默认货币
  taxRate: 0,               // 税率
  trialDays: 14,            // 试用期天数
  gracePeriodDays: 7,       // 宽限期天数
  dunningAttempts: 3,       // 催款尝试次数
  dunningIntervalDays: 3    // 催款间隔天数
}
```

## 使用示例

### 创建订阅
```javascript
const subscription = await createSubscription({
  plan: 'professional',
  billingCycle: 'monthly',
  paymentMethodId: 'pm_xxx'
});
```

### 记录使用量
```javascript
await recordUsage(subscriptionId, {
  metric: 'messages',
  quantity: 1000
});
```

### 创建退款
```javascript
const refund = await createRefund(transactionId, {
  amount: 50.00,
  reason: 'Customer request'
});
```

## 后台任务

系统运行以下定时任务：
- **检查即将到期的订阅**：每日运行，发送续订提醒
- **检查逾期账单**：每6小时运行，发送催款通知
- **检查即将到期的支付方式**：每日运行，提醒更新
- **处理失败的交易**：每小时运行，重试失败的支付

## 故障排除

### 常见问题

1. **支付失败**
   - 检查支付方式是否有效
   - 确认账户余额充足
   - 查看 Stripe 日志获取详细错误

2. **Webhook 失败**
   - 验证 webhook 签名密钥
   - 检查网络连接
   - 查看 webhook 日志

3. **订阅状态不同步**
   - 手动同步 Stripe 数据
   - 检查 webhook 事件处理
   - 验证数据库连接

## 最佳实践

1. **定期对账**：每月对比 Stripe 和本地数据
2. **监控失败率**：跟踪支付失败和退款率
3. **优化重试策略**：根据失败原因调整重试时间
4. **保持合规**：遵守 PCI DSS 和数据保护法规
5. **文档维护**：及时更新账单模板和条款

## 未来改进

1. **多币种支持**：支持更多货币类型
2. **更多支付方式**：支持 PayPal、支付宝等
3. **发票定制**：自定义发票模板和品牌
4. **高级报表**：收入预测和财务分析
5. **自动化催收**：智能催款流程