Initial commit: Telegram Management System
Some checks failed
Deploy / deploy (push) Has been cancelled
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>
This commit is contained in:
你的用户名
302
marketing-agent/BILLING_SYSTEM.md
Normal file
302
marketing-agent/BILLING_SYSTEM.md
Normal file
@@ -0,0 +1,302 @@
|
||||
# 支付和计费系统
|
||||
|
||||
## 概述
|
||||
|
||||
本系统实现了完整的支付和计费功能，支持订阅管理、账单生成、支付处理和财务报表。集成了 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. **自动化催收**：智能催款流程
|
||||
Reference in New Issue
Block a user