井云服务中心算力点系统技术文档
1. 系统概述
井云服务中心算力点系统是一个独立的微服务模块，负责管理用户的算力点数生命周期，包括点数发放、消费、过期处理等核心功能。系统采用FIFO（先进先出）消费策略，确保点数按过期时间优先消费，同时支持多租户隔离和产品定价管理。
2. 核心功能特性
2.1 点数生命周期管理
- 点数发放: 支持多种来源的点数发放（购买、赠送、活动、退款）
- 点数消费: 采用FIFO策略，优先消费快过期的点数
- 点数过期: 自动处理过期点数并生成交易记录
- 交易记录: 完整的点数交易流水，支持审计和查询
2.2 多租户支持
- 租户隔离: 不同租户的点数完全隔离
- 产品定价: 支持租户按产品设定不同的点数消费价格
- 跨账本消费: 支持同一租户内跨账本的点数消费
2.3 智能消费策略
- FIFO算法: 优先消费快到期的点数
- 余额检查: 消费前验证用户总余额是否充足
- 部分消费: 支持从多个账本中组合消费以满足需求
- 原子操作: 确保消费操作的原子性和一致性
2.4 定时任务
- 过期处理: 每天凌晨2点自动处理过期点数
- 批量处理: 高效的批量过期处理机制
- 统计报告: 提供过期处理的详细统计信息
3. 数据模型设计
3.1 UserPointLedger (用户点数账本)
- Id: string (UUID/ULID)
- UserID: string (用户ID)
- TenantID: string (租户ID)
- Source: string (点数来源：PURCHASE/GIFT/PROMOTION/REFUND)
- InitialAmount: int64 (初始点数)
- Balance: int64 (当前余额)
- ExpiresAt: time.Time (过期时间)
- Status: enum (ACTIVE/EXPIRED/FULLY_CONSUMED)
- ExpiredAmount: int64 (过期金额)
- CreatedAt: time.Time
- UpdatedAt: time.Time
3.2 PointTransaction (点数交易记录)
- Id: string (UUID/ULID)
- UserID: string (用户ID)
- TransactionType: enum (ACCUMULATION/CONSUMPTION/EXPIRATION)
- Amount: int64 (交易金额，正数为增加，负数为减少)
- ReferenceID: string (关联ID，指向账本或消费记录)
- Description: string (交易描述)
- TenantID: string (租户ID)
- ProductID: string (产品ID)
- OccurredAt: time.Time (交易时间)
3.3 PointConsumptionRecord (点数消费记录)
- Id: string (UUID/ULID)
- UserID: string (用户ID)
- TenantID: string (租户ID)
- ProductID: string (产品ID)
- ConsumedAmount: int64 (消费总额)
- LedgerDeductions: bytes (账本扣款明细，JSON格式)
- Description: string (消费描述)
- CreatedAt: time.Time
3.4 ProductPricing (产品定价)
- TenantID: string (租户ID)
- ProductID: string (产品ID)
- ProductName: string (产品名称)
- PointsPerUnit: int64 (每单位产品消耗的点数)
- Unit: string (单位)
- Description: string (描述)
- IsActive: bool (是否启用)
4. 业务流程
4.1 点数发放流程
- 系统接收点数发放请求（购买、赠送等）
- 验证请求参数的有效性
- 创建用户点数账本记录
- 创建点数交易记录（ACCUMULATION类型）
- 返回账本ID和交易ID
4.2 点数消费流程（FIFO策略）
- 系统接收点数消费请求
- 获取用户所有活跃账本（按过期时间排序）
- 计算用户总余额是否充足
- 按FIFO策略从账本中扣减点数
- 创建消费记录和交易记录
- 更新相关账本余额
- 返回消费结果
4.3 点数过期处理流程
- 定时任务触发过期检查
- 查询所有已过期但未处理的账本
- 将过期账本状态更新为EXPIRED
- 创建过期交易记录（EXPIRATION类型）
- 统计过期处理结果
- 记录处理日志
5. API 接口定义
5.1 点数管理接口
POST /v1/points:grant- 发放点数POST /v1/points:consume- 消费点数GET /v1/users/{user_id}/points/overview- 获取用户点数总览GET /v1/users/{user_id}/points/transactions- 获取点数交易历史
5.2 产品定价接口
GET /v1/tenants/{tenant_id}/products/{product_id}/pricing- 获取产品定价POST /v1/tenants/{tenant_id}/products/{product_id}/pricing- 设置产品定价
5.3 定时任务接口
POST /v1/points:expire- 处理过期点数（定时任务调用）
6. FIFO消费算法详解
6.1 算法原理
FIFO（First In First Out）算法确保用户优先使用即将过期的点数，最大化点数利用率，减少用户损失。
6.2 实现步骤
- 获取活跃账本: 查询用户所有状态为ACTIVE的账本
- 按过期时间排序: 将账本按过期时间升序排列
- 逐个扣减: 从最早的账本开始扣减，直到满足需求或余额不足
- 更新状态: 对于余额为0的账本，状态更新为FULLY_CONSUMED
- 记录明细: 详细记录每个账本的扣减金额
6.3 代码实现示例
func (uc *PointUseCase) ConsumePoints(ctx context.Context, userID, tenantID, productID, description string, requiredAmount int64) (*PointConsumptionRecord, *PointTransaction, error) {
// 获取用户活跃账本（按过期时间排序）
ledgers, err := uc.userPointLedgerRepo.ListActiveUserPointLedgers(ctx, userID)
if err != nil {
return nil, nil, err
}
// 计算总余额
var totalBalance int64
for _, ledger := range ledgers {
totalBalance += ledger.Balance
}
// 检查余额是否充足
if totalBalance < requiredAmount {
return nil, nil, ErrorInsufficientBalance("余额不足")
}
// FIFO消费逻辑
remainingAmount := requiredAmount
var deductions []LedgerDeduction
for _, ledger := range ledgers {
if remainingAmount <= 0 {
break
}
deductionAmount := min(ledger.Balance, remainingAmount)
deductions = append(deductions, LedgerDeduction{
LedgerID: ledger.ID,
Amount: deductionAmount,
})
// 更新账本余额
newBalance := ledger.Balance - deductionAmount
status := UserPointLedgerStatusActive
if newBalance == 0 {
status = UserPointLedgerStatusFullyConsumed
}
err = uc.userPointLedgerRepo.UpdateBalance(ctx, ledger.ID, newBalance, status)
if err != nil {
return nil, nil, err
}
remainingAmount -= deductionAmount
}
// 创建消费记录和交易记录
// ...
}
7. 数据库设计
7.1 user_point_ledgers 表
- 存储用户点数账本信息
- 支持多租户隔离
- 包含过期时 间管理
- 状态管理确保数据一致性
7.2 point_transactions 表
- 存储所有点数交易记录
- 支持多种交易类型
- 提供完整的审计日志
- 按用户和时间建立索引
7.3 point_consumption_records 表
- 存储点数消费详情
- 记录跨账本消费明细
- 支持产品级别的消费统计
7.4 索引设计
user_point_ledgers: (user_id, expires_at), (user_id, status), (expires_at)point_transactions: (user_id), (occurred_at), (user_id, occurred_at), (transaction_type)point_consumption_records: (user_id), (tenant_id), (product_id)
8. 定时任务设计
8.1 过期处理任务
- 执行时间: 每天凌晨2点
- 处理逻辑: 批量处理已过期的点数账本
- 容错机制: 30分钟超时保护，失败重试
- 监控指标: 处理的账本数量、过期点数总数
8.2 任务实现
func (s *PointExpiryService) expirePoints() {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
defer cancel()
resp, err := s.pointClient.ExpirePoints(ctx, &pointpb.ExpirePointsRequest{})
if err != nil {
s.log.Errorf("Failed to expire points: %v", err)
return
}
s.log.Infof("Point expiry job completed: expired %d ledgers, total %d points",
resp.ExpiredLedgersCount, resp.TotalExpiredPoints)
}
9. 性能优化
9.1 查询优化
- 使用复合索引提高查 询效率
- 分页查询避免大量数据加载
- 缓存热点数据减少数据库访问
9.2 批量处理
- 过期处理采用批量操作
- 事务管理确保数据一致性
- 异步处理提高系统响应速度
9.3 并发控制
- 使用乐观锁防止并发冲突
- 分布式锁保证任务唯一性
- 连接池管理数据库连接
10. 监控与告警
10.1 关键指标
- 点数发放总额和笔数
- 点数消费总额和笔数
- 过期点数数量和比例
- 系统响应时间和错误率
10.2 告警规则
- 定时任务执行失败
- 点数余额异常变化
- 系统性能指标异常
- 数据库连接异常
11. 安全与权限
11.1 权限控制
- 用户只能操作自己的点数
- 租户间数据完全隔离
- 管理员权限分级管理
11.2 数据安全
- 敏感操作记录审计日志
- 交易数据加密存储
- 接口访问频率限制
12. 扩展性设计
12.1 水平扩展
- 无状态服务设计
- 数据库分片支持
- 缓存集群部署
12.2 功能扩展
- 支持更多点数来源类型
- 灵活的定价策略配置
- 多级过期策略支持
13. 运维指南
13.1 部署要求
- Go 1.25+ 运行环境
- PostgreSQL 数据库
- Redis 缓存（可选）
- 监控系统支持
13.2 配置管理
- 数据库连接配置
- 定时任务调度配置
- 日志级别和输出配置
- 监控和告警配置
13.3 故障处理
- 数据库连接失败处理
- 定时任务执行失败重试
- 异常数据修复工具
- 数据备份和恢复策略
14. 测试策略
14.1 单元测试
- 核心业务逻辑测试
- FIFO算法正确性验证
- 边界条件测试
- 异常情况处理测试
14.2 集成测试
- API接口集成测试
- 数据库操作测试
- 定时任务集成测试
- 多服务协作测试
14.3 性能测试
- 高并发消费测试
- 大量数据过期处理测试
- 系统压力测试
- 长时间运行稳定性测试
15. 最佳实践
15.1 开发规范
- 遵循Go语言编码规范
- 使用统一的错误处理机制
- 完善的日志记录
- 充分的单元测试覆盖
15.2 运维建议
- 定期检查过期处理结果
- 监控系统性能指标
- 及时处理异常告警
- 定期数据备份和验证
15.3 业务建议
- 合理设置点数过期时间
- 优化产品定价策略
- 定期分析用户消费行为
- 持续优化FIFO算法性能