237c7802e5
Some checks failed
Deploy / deploy (push) Has been cancelled
Full-stack web application for Telegram management - Frontend: Vue 3 + Vben Admin - Backend: NestJS - Features: User management, group broadcast, statistics 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
302 lines
7.7 KiB
Markdown
302 lines
7.7 KiB
Markdown
# 支付和计费系统
|
||
|
||
## 概述
|
||
|
||
本系统实现了完整的支付和计费功能，支持订阅管理、账单生成、支付处理和财务报表。集成了 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. **自动化催收**：智能催款流程 |