Files

你的用户名 237c7802e5

Deploy / deploy (push) Has been cancelled

Details

Initial commit: Telegram Management System

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>

2025-11-04 15:37:50 +08:00

7.7 KiB

Raw Blame History

支付和计费系统

概述

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

系统架构

服务组件

Billing Service (services/billing-service/)
- 端口：3010
- 负责所有计费相关功能
- 集成 Stripe API
- 处理 Webhook 事件
API Gateway 集成
- 路由前缀：/api/v1/billing/
- 自动转发到 Billing Service
- 支持认证和限流
前端组件
- 计费仪表板
- 订阅管理
- 支付方式管理
- 账单历史

核心功能

1. 订阅管理

订阅计划

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

订阅功能

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

2. 支付方式

支持的支付类型

信用卡/借记卡
银行账户（ACH）

支付方式管理

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

3. 账单和发票

账单功能

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

账单状态

草稿（Draft）
待支付（Open）
已支付（Paid）
已作废（Void）
无法收回（Uncollectible）

4. 交易管理

交易类型

支付（Payment）
退款（Refund）
调整（Adjustment）
费用（Fee）

交易功能

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

数据模型

Subscription 模型

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

Invoice 模型

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

PaymentMethod 模型

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

Transaction 模型

{
  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 认证

配置

环境变量

# 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

计费配置

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

使用示例

创建订阅

const subscription = await createSubscription({
  plan: 'professional',
  billingCycle: 'monthly',
  paymentMethodId: 'pm_xxx'
});

记录使用量

await recordUsage(subscriptionId, {
  metric: 'messages',
  quantity: 1000
});

创建退款

const refund = await createRefund(transactionId, {
  amount: 50.00,
  reason: 'Customer request'
});

后台任务

系统运行以下定时任务：

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

故障排除

常见问题

支付失败
- 检查支付方式是否有效
- 确认账户余额充足
- 查看 Stripe 日志获取详细错误
Webhook 失败
- 验证 webhook 签名密钥
- 检查网络连接
- 查看 webhook 日志
订阅状态不同步
- 手动同步 Stripe 数据
- 检查 webhook 事件处理
- 验证数据库连接

最佳实践

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

未来改进

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

7.7 KiB Raw Blame History Unescape Escape