telegram-management-system/marketing-agent/BILLING_SYSTEM.md

支付和计费系统

概述

本系统实现了完整的支付和计费功能，支持订阅管理、账单生成、支付处理和财务报表。集成了 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 模型

{
  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小时运行，发送催款通知
• 检查即将到期的支付方式：每日运行，提醒更新
• 处理失败的交易：每小时运行，重试失败的支付

故障排除

常见问题

1. 支付失败

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

2. Webhook 失败

   • 验证 webhook 签名密钥
   • 检查网络连接
   • 查看 webhook 日志

3. 订阅状态不同步

   • 手动同步 Stripe 数据
   • 检查 webhook 事件处理
   • 验证数据库连接

最佳实践

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

未来改进

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