跳到主要内容

井云服务中心算力点系统技术文档

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 点数发放流程

  1. 系统接收点数发放请求(购买、赠送等)
  2. 验证请求参数的有效性
  3. 创建用户点数账本记录
  4. 创建点数交易记录(ACCUMULATION类型)
  5. 返回账本ID和交易ID

4.2 点数消费流程(FIFO策略)

  1. 系统接收点数消费请求
  2. 获取用户所有活跃账本(按过期时间排序)
  3. 计算用户总余额是否充足
  4. 按FIFO策略从账本中扣减点数
  5. 创建消费记录和交易记录
  6. 更新相关账本余额
  7. 返回消费结果

4.3 点数过期处理流程

  1. 定时任务触发过期检查
  2. 查询所有已过期但未处理的账本
  3. 将过期账本状态更新为EXPIRED
  4. 创建过期交易记录(EXPIRATION类型)
  5. 统计过期处理结果
  6. 记录处理日志

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 实现步骤

  1. 获取活跃账本: 查询用户所有状态为ACTIVE的账本
  2. 按过期时间排序: 将账本按过期时间升序排列
  3. 逐个扣减: 从最早的账本开始扣减,直到满足需求或余额不足
  4. 更新状态: 对于余额为0的账本,状态更新为FULLY_CONSUMED
  5. 记录明细: 详细记录每个账本的扣减金额

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算法性能