跳到主要内容

井云服务中心分销系统技术文档

1. 系统概述​

井云服务中心分销系统是一个基于多级分销模式的佣金计算与管理功能模块，支持直推佣金和间推佣金的自动计算、用户分销等级管理、佣金记录管理、提现管理等功能。

2. 核心功能特性​

2.1 分销等级管理​

  • 创建分销等级: 支持设置等级名称、描述、最小消费金额、最小下线人数、直推佣金比率、间推佣金比率
  • 更新分销等级: 支持动态调整分销等级的各个参数
  • 查询分销等级: 支持获取单个等级信息或等级列表
  • 删除分销等级: 支持删除指定的分销等级

2.2 佣金计算与管理​

  • 自动佣金计算: 订单支付成功后自动计算并生成佣金记录
  • 多级佣金: 支持直推佣金（一级）和间推佣金（二级）
  • 佣金记录管理: 支持佣金记录的查询和状态管理

2.3 提现管理​

  • 提现申请: 用户可申请提现佣金余额
  • 提现审批: 支持管理员处理提现申请
  • 提现记录: 管理用户提现历史记录

2.4 用户分销信息​

  • 分销信息查询: 获取用户当前的分销等级、下线数量、佣金余额等信息
  • 佣金记录查询: 查询用户的佣金明细记录
  • 交易历史查询: 查询用户的交易历史

3. 数据模型设计​

3.1 DistributionLevel (分销等级)​

- Id: int64
- Name: string (等级名称)
- Description: string (等级描述)
- MinConsumptionAmount: string (最小消费金额)
- MinDownlineCount: int (最小下线人数)
- DirectCommissionRate: string (直推佣金比率)
- IndirectCommissionRate: string (间推佣金比率)
- CreatedAt: time.Time
- UpdatedAt: time.Time

3.2 CommissionRecord (佣金记录)​

- Id: int64
- OrderID: int64 (订单ID)
- BeneficiaryID: int64 (受益人ID)
- ContributorID: int64 (贡献者ID)
- CommissionAmount: string (佣金金额)
- CommissionRate: string (佣金比率)
- CommissionLevel: int (佣金等级 - 1为直推，2为间推)
- Status: string (状态)
- Description: string (佣金说明)
- CreatedAt: time.Time
- UpdatedAt: time.Time

3.3 WithdrawalRecord (提现记录)​

- Id: int64
- UserID: int64 (用户ID)
- Amount: string (提现金额)
- Fee: string (手续费)
- ActualAmount: string (实际到账金额)
- Status: string (状态)
- PaymentMethod: string (支付方式)
- PaymentAccount: string (支付账户)
- ProcessedBy: int64 (处理人ID)
- ProcessedAt: *time.Time (处理时间)
- Remark: string (备注)
- CreatedAt: time.Time
- UpdatedAt: time.Time

3.4 User (用户表扩展)​

- DistributionLevelID: int64 (分销等级ID)
- CommissionBalance: string (佣金余额)

4. 业务流程​

4.1 分销等级设置流程​

  1. 管理员创建分销等级，设置佣金比率等参数
  2. 用户满足条件后被分配相应的分销等级
  3. 不同等级享受不同的佣金比率

4.2 佣金计算流程​

  1. 用户A购买商品，订单支付成功
  2. 系统查询用户A的直接邀请人B
  3. 根据B的分销等级计算直推佣金，生成佣金记录
  4. 系统查询用户A的间接邀请人C
  5. 根据C的分销等级计算间推佣金，生成佣金记录
  6. 累计佣金并更新用户佣金余额

4.3 提现流程​

  1. 用户申请提现，填写金额和支付方式
  2. 系统验证用户余额是否充足
  3. 扣减用户佣金余额，创建提现申请记录
  4. 管理员审核提现申请
  5. 审核通过后处理提现，更新记录状态

5. API 接口定义​

5.1 分销等级管理接口​

  • POST /user/distribution/level - 创建分销等级
  • PUT /user/distribution/level/{id} - 更新分销等级
  • GET /user/distribution/levels - 获取分销等级列表
  • DELETE /user/distribution/level/{id} - 删除分销等级

5.2 用户分销接口​

  • GET /user/distribution/my-info - 获取我的分销信息
  • GET /user/distribution/commission-records - 获取佣金记录列表
  • POST /user/distribution/user-level - 设置用户分销等级
  • GET /user/distribution/downlines - 获取下线用户列表

5.3 提现管理接口​

  • POST /user/distribution/withdrawal - 申请提现
  • GET /user/distribution/withdrawal-records - 获取提现记录
  • GET /user/distribution/pending-withdrawals - 获取待处理提现
  • POST /user/distribution/process-withdrawal - 处理提现申请

5.4 交易历史接口​

  • GET /user/distribution/transaction-history - 获取交易历史

6. 佣金计算逻辑​

6.1 直推佣金计算​

当用户B购买商品时，其直接邀请人A将获得直推佣金：

直推佣金 = 订单金额 × (直推佣金比率 / 100)

6.2 间推佣金计算​

当用户C购买商品时，其间接邀请人A将获得间推佣金：

间推佣金 = 订单金额 × (间推佣金比率 / 100)

6.3 佣金计算实现​

在 DistributionUsecase.calculateCommissions 方法中实现：

  1. 获取购买用户的直接邀请人和间接邀请人
  2. 查询各自分销等级，获取相应佣金比率
  3. 计算佣金金额并创建佣金记录
  4. 更新用户佣金余额

7. 数据库设计​

7.1 distribution_levels 表​

  • 存储分销等级配置信息
  • 包含佣金比率、升级条件等字段

7.2 commission_records 表​

  • 存储佣金记录
  • 关联订单、受益人、贡献者等信息

7.3 withdrawal_records 表​

  • 存储提现记录
  • 包含提现状态、支付方式等信息

7.4 users 表扩展​

  • 添加 distribution_level_id 字段关联分销等级
  • 添加 commission_balance 字段存储佣金余额

8. 安全与权限​

8.1 权限控制​

  • 分销等级管理功能仅限管理员使用
  • 用户只能查看和操作自己的分销信息
  • 提现功能需要验证用户身份和余额

8.2 数据安全​

  • 佣金计算和余额更新使用事务确保数据一致性
  • 提现申请需要审核机制防止恶意操作
  • 所有敏感操作记录日志便于审计

9. 扩展性设计​

9.1 多级分销扩展​

当前系统支持二级分销，可通过修改 calculateCommissions 方法扩展至更多级

9.2 佣金比率动态调整​

支持不同分销等级设置不同佣金比率，便于精细化运营

9.3 提现方式扩展​

支持多种提现方式（微信、支付宝、银行卡等），便于后续扩展

10. 监控与维护​

10.1 佣金统计​

  • 提供用户佣金统计功能
  • 支持按时间、等级等维度统计

10.2 异常处理​

  • 佣金计算失败时记录错误日志
  • 提现失败时及时通知用户和管理员

10.3 性能优化​

  • 佣金记录支持分页查询
  • 合理使用索引提升查询性能

10.4 定时任务​

  • 每日分销等级检查: 系统每晚凌晨3点自动检查当日有支付的用户和新注册用户的邀请人分销等级
  • 自动升级机制: 对于满足更高等级条件的用户，系统将自动升级其分销等级
  • 智能更新范围: 只检查当天有支付的用户和新注册用户的邀请人，而非全量用户，提高效率

11. API 接口扩展​

11.1 定时任务接口​

  • rpc CheckDistributionLevels(CheckDistributionLevelsRequest) returns (CheckDistributionLevelsReply) - 供定时任务调用的分销等级检查接口