设计概述.md 18 KB
团队模块设计概述
1. 模块定位
团队模块是开心农场系统的核心模块之一，负责管理用户之间的推荐关系、团队结构、达人等级和收益分成机制。该模块通过建立用户间的直推和间推关系，形成团队结构，并在团队成员产生收益时进行分成，鼓励用户发展团队，形成良性的社交生态。
2. 设计目标
- 建立完整的用户推荐体系：支持直推和间推关系，形成多层级的团队结构
- 实现灵活的达人等级系统：根据团队规模和活跃度评定用户的达人等级
- 提供公平的收益分成机制：根据推荐关系和达人等级分配团队收益
- 支持多种收益来源：支持农场收获、任务完成等多种收益来源的分成
- 保证系统的可扩展性：预留达人等级、分成比例和收益来源的扩展空间
3. 架构设计
3.1 模块结构
团队模块采用分层架构设计，包括以下层次：
┌─────────────┐
│ Controller │ 控制器层：处理HTTP请求
└──────┬──────┘
│
▼
┌─────────────┐ ┌─────────────┐
│ Event │◄──┤ Service │ 服务层：对外提供服务接口
└─────────────┘ └──────┬──────┘
│
▼
┌─────────────┐
│ Logic │ 逻辑层：实现业务逻辑
└──────┬──────┘
│
▼
┌─────────────┐
│ Repository │ 仓库层：数据访问和持久化
└──────┬──────┘
│
▼
┌─────────────┐
│ Model │ 模型层：数据结构定义
└─────────────┘
3.2 核心组件
Service：对外提供服务接口，是模块的主要入口
- ReferralService：推荐关系服务
- TalentService：达人等级服务
- PromotionProfitService：团队收益服务
- ReferralCodeService：推荐码服务
Logic：实现业务逻辑，处理复杂的业务规则
- ReferralLogic：推荐关系逻辑
- TalentLogic：达人等级逻辑
- ProfitLogic：收益分成逻辑
Repository：数据访问和持久化，封装数据库操作
- UserReferralRepository：用户推荐关系仓库
- UserTalentRepository：用户达人等级仓库
- PromotionProfitRepository：团队收益记录仓库
Model：数据结构定义，对应数据库表
- UserReferral：用户推荐关系模型
- UserTalent：用户达人等级模型
- PromotionProfit：团队收益记录模型
Event：事件定义，用于模块间通信
- TalentLevelUpEvent：达人等级提升事件
- ReferralCreatedEvent：推荐关系创建事件
- PromotionProfitGeneratedEvent：团队收益生成事件
3.3 依赖关系
团队模块与其他模块的依赖关系：
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ User模块 │◄────►│ Promotion模块 │◄────►│ Farm模块 │
└─────────────┘ └──────┬──────┘ └─────────────┘
│
▼
┌─────────────┐
│GameItems模块│
└─────────────┘
- User模块：提供用户基本信息，接收推荐关系
- Farm模块：提供收获事件，接收团队收益分成
- GameItems模块：提供物品操作接口，处理收益物品的添加
4. 核心流程
4.1 推荐关系建立流程
┌─────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 用户 │ │ UserService │ │ReferralService│ │ReferralLogic│
└────┬────┘ └──────┬──────┘ └───────┬─────┘ └───────┬─────┘
│ │ │ │
│ 注册(推荐码) │ │ │
│────────────────►│ │ │
│ │ │ │
│ │ 验证推荐码 │ │
│ │───────────────────►│ │
│ │ │ │
│ │ │ 解析推荐人ID │
│ │ │───────────────────►
│ │ │ │
│ │ │ │
│ │ │◄───────────────────
│ │ │ │
│ │ │ 建立推荐关系 │
│ │ │───────────────────►
│ │ │ │
│ │ │ │
│ │ │◄───────────────────
│ │ │ │
│ │◄───────────────────│ │
│ │ │ │
│◄────────────────│ │ │
│ │ │ │
4.2 达人等级升级流程
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ReferralService│ │TalentService │ │ TalentLogic │
└───────┬─────┘ └───────┬─────┘ └───────┬─────┘
│ │ │
│ 建立推荐关系 │ │
│───────────────────┼───────────────────┼────►
│ │ │
│ 触发检查达人等级 │ │
│───────────────────► │
│ │ │
│ │ 获取团队规模 │
│ │───────────────────►
│ │ │
│ │ │
│ │◄───────────────────
│ │ │
│ │ 计算新达人等级 │
│ │───────────────────►
│ │ │
│ │ │
│ │◄───────────────────
│ │ │
│ │ 更新达人等级 │
│ │───────────────────►
│ │ │
│ │ │
│ │◄───────────────────
│ │ │
│ │ 触发等级提升事件 │
│ │───────────────────►
│ │ │
4.3 团队收益分成流程
┌─────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│Farm模块 │ │PromotionProfitService│ │ ProfitLogic │ │GameItems模块│
└────┬────┘ └───────┬─────┘ └───────┬─────┘ └───────┬─────┘
│ │ │ │
│ 收获事件 │ │ │
│─────────────────►│ │ │
│ │ │ │
│ │ 获取推荐关系 │ │
│ │───────────────────► │
│ │ │ │
│ │ │ │
│ │◄─────────────────── │
│ │ │ │
│ │ 计算分成比例 │ │
│ │───────────────────► │
│ │ │ │
│ │ │ │
│ │◄─────────────────── │
│ │ │ │
│ │ 记录分成收益 │ │
│ │───────────────────► │
│ │ │ │
│ │ │ │
│ │◄─────────────────── │
│ │ │ │
│ │ 添加收益物品 │ │
│ │───────────────────┼───────────────────►
│ │ │ │
│ │ │ │
│ │◄───────────────────┼───────────────────
│ │ │ │
5. 关键设计点
5.1 推荐关系存储
团队模块采用扁平化存储推荐关系，即直接存储用户与其所有上级（直推和间推）的关系，而不是仅存储直接推荐关系。这种设计有以下优点：
- 查询效率高：查询用户的所有上级或下级只需一次数据库查询
- 计算负担小：不需要在运行时递归计算多级关系
- 维护成本低：新增用户只需添加与其所有上级的关系记录
示例数据结构：
user_id | referrer_id | level
--------|------------|------
2 | 1 | 1 # 用户1直推了用户2
3 | 2 | 1 # 用户2直推了用户3
3 | 1 | 2 # 用户1间推了用户3
5.2 达人等级计算
达人等级计算采用定期更新和事件触发相结合的方式：
- 事件触发更新：当用户团队规模变化时（如新增团队成员），触发达人等级检查
- 定期批量更新：定时任务定期检查和更新所有用户的达人等级
- 缓存优化：缓存用户的达人等级信息，减少频繁查询
5.3 收益分成策略
收益分成采用灵活的策略模式设计：
- 来源适配器：为不同的收益来源（如农场收获、任务完成）提供适配器
- 分成规则引擎：根据推荐关系和达人等级计算分成比例
- 分成上限控制：设置分成总比例上限，确保系统可持续运营
5.4 事件驱动通信
模块间采用事件驱动的松耦合通信方式：
- 发布-订阅模式：模块发布事件，其他模块订阅并处理
- 异步处理：收益分成等耗时操作采用异步处理
- 失败重试：关键操作失败后支持重试机制
6. 扩展性设计
6.1 达人等级扩展
达人等级系统设计为可扩展的：
- 配置化等级：达人等级条件和权益通过配置表定义
- 动态权益：达人权益可动态配置，支持不同类型的权益
- 等级评定规则：支持扩展等级评定规则，如增加活跃度指标
6.2 收益来源扩展
收益分成系统支持多种收益来源：
- 来源注册机制：新的收益来源可通过注册机制接入
- 统一分成接口：提供统一的分成计算和处理接口
- 来源特定规则：支持为不同来源配置特定的分成规则
6.3 分成规则扩展
分成规则设计为可扩展的：
- 规则引擎：使用规则引擎处理复杂的分成逻辑
- 规则配置：分成比例和条件通过配置表定义
- 规则版本：支持规则版本管理，便于规则调整和升级
7. 安全性设计
7.1 数据验证
所有输入数据进行严格验证：
- 用户身份验证：验证操作用户的身份和权限
- 数据完整性验证：验证输入数据的完整性和有效性
- 业务规则验证：验证操作是否符合业务规则
7.2 防刷机制
防止恶意刷取团队收益：
- 操作频率限制：限制用户操作频率
- 异常行为检测：检测和阻止异常的团队行为
- 收益上限控制：设置单用户收益上限
7.3 数据隔离
确保数据安全和隔离：
- 用户数据隔离：用户只能访问自己的团队数据
- 权限分级：不同角色拥有不同的数据访问权限
- 敏感数据保护：加密存储敏感数据
8. 性能优化
8.1 数据库优化
优化数据库设计和查询：
- 索引设计：为常用查询字段建立合适的索引
- 分表策略：大表采用分表策略，提高查询效率
- 批量操作：使用批量插入和更新，减少数据库操作次数
8.2 缓存策略
合理使用缓存提高性能：
- 用户团队缓存：缓存用户的团队结构和达人信息
- 分成规则缓存：缓存分成规则和比例
- 统计数据缓存：缓存团队规模等统计数据
8.3 异步处理
耗时操作采用异步处理：
- 队列处理：收益分成等操作通过队列异步处理
- 批量处理：定期批量处理团队统计和达人升级
- 任务调度：使用任务调度系统管理异步任务
9. 与其他模块的交互
9.1 与User模块的交互
- 用户注册：接收用户注册事件，处理推荐关系
- 用户信息：获取用户基本信息，如昵称、头像等
- 用户状态：监听用户状态变更，如封禁、注销等
9.2 与Farm模块的交互
- 收获事件：监听作物收获事件，计算农场收益分成
- 达人权益：提供达人等级信息，影响农场产出
- 团队任务：支持团队协作完成农场任务
9.3 与GameItems模块的交互
- 物品操作：调用物品模块接口，添加收益物品
- 物品记录：记录收益物品的来源和分成信息
- 物品消耗：支持使用物品激活团队特权
9.4 与Task模块的交互
- 任务完成：触发团队相关任务的完成
- 任务奖励：计算团队任务奖励的分成
- 团队目标：支持设置和完成团队目标
10. 总结
团队模块作为开心农场系统的核心模块之一，通过建立用户间的推荐关系、团队结构、达人等级和收益分成机制，鼓励用户发展团队，形成良性的社交生态。模块设计注重灵活性、可扩展性和性能，采用分层架构和事件驱动通信，与其他模块保持松耦合关系。通过合理的数据结构设计和优化策略，确保系统在大规模用户场景下的稳定运行。