kknongchang_2506/app/Module/Promotion

团队模块

概述

团队模块是开心农场系统的核心模块之一，负责管理用户之间的推荐关系、团队结构、达人等级和收益分成机制。该模块通过建立用户间的直推和间推关系，形成团队结构，并在团队成员产生收益时进行分成，鼓励用户发展团队，形成良性的社交生态。

主要功能

1. 推荐关系管理：建立和维护用户间的直推和间推关系
2. 达人等级系统：根据团队规模和活跃度评定用户的达人等级
3. 团队收益分成：计算和分配团队成员产生的收益分成
4. 团队数据统计：统计和展示团队规模、收益等数据
5. 推荐码生成：生成用户专属推荐码和推荐链接

目录结构

app/Module/Promotion/
├── AdminControllers/        # 后台管理控制器
├── Commands/                # 命令行工具
├── Databases/               # 数据库相关文件
│   └── createsql/          # 数据库创建SQL
├── Docs/                    # 详细文档目录
│   ├── README.md            # 文档索引
│   ├── 设计概述.md           # 模块整体设计
│   ├── 数据库设计.md         # 数据库表结构设计
│   ├── 模块接口.md           # 模块对外接口
│   └── 推荐关系系统.md        # 推荐关系系统设计
├── Enums/                   # 枚举类型定义
├── Events/                  # 事件类
├── Logics/                  # 业务逻辑类
├── Models/                  # 数据模型
├── Providers/               # 服务提供者
├── Repositorys/             # 数据仓库
└── Services/                # 开放服务类

核心概念

1. 推荐关系

• 直推关系：用户A直接推荐用户B注册，则用户A是用户B的直推上级
• 间推关系：用户A推荐用户B，用户B推荐用户C，则用户A是用户C的间推上级
• 团队成员：用户的所有直推和间推下级构成该用户的团队

2. 达人等级

团队系统设有达人等级，根据团队规模和活跃度评定：

达人等级	名称	升级条件	奖励权益
1	初级达人	直推5人且团队总人数≥10	团队收益1%分成
2	中级达人	直推10人且团队总人数≥30	团队收益1.5%分成
3	高级达人	直推20人且团队总人数≥50	团队收益2%分成
4	资深达人	直推30人且团队总人数≥100	团队收益2.5%分成
5	顶级达人	直推50人且团队总人数≥200	团队收益3%分成

3. 收益分成

• 直推分成：直推上级获得下级收益的5%
• 间推分成：间推上级根据达人等级获得下级收益的1%-3%
• 分成范围：间推分成仅对20代以内的团队成员有效
• 收益来源：主要来自团队成员播种收获的农作物收益

核心数据表

1. 用户推荐关系表 (promotion_user_referrals)

字段名	类型	说明
id	bigint	主键ID
user_id	bigint	用户ID
referrer_id	bigint	推荐人ID
level	tinyint	推荐层级(1=直推,2=间推)
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

2. 达人等级表 (promotion_user_talents)

字段名	类型	说明
id	bigint	主键ID
user_id	bigint	用户ID
talent_level	tinyint	达人等级(0-5)
direct_count	int	直推人数
promotion_count	int	团队总人数
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

3. 团队收益记录表 (promotion_profits)

字段名	类型	说明
id	bigint	主键ID
user_id	bigint	获得收益的用户ID
promotion_member_id	bigint	团队成员ID
source_id	bigint	收益来源ID
source_type	varchar	收益来源类型
profit_amount	int	分成收益数量
profit_rate	decimal	分成比例
created_at	timestamp	创建时间

核心服务

1. 推荐关系服务 (ReferralService)

• 建立推荐关系
• 获取用户的推荐人
• 获取用户的团队成员
• 验证推荐关系

2. 达人等级服务 (TalentService)

• 计算和更新达人等级
• 获取用户的达人信息
• 获取达人等级权益

3. 团队收益服务 (PromotionProfitService)

• 计算团队收益分成
• 记录收益分成
• 统计团队收益

4. 推荐码服务 (ReferralCodeService)

• 生成推荐码
• 验证推荐码
• 生成推荐链接

与其他模块的交互

1. 与User模块的交互

• 用户注册时接收推荐人ID
• 验证推荐人ID的有效性
• 建立推荐关系

2. 与Farm模块的交互

• 监听作物收获事件，计算农场收益分成
• 提供达人等级信息，影响农场产出

3. 与GameItems模块的交互

• 将团队分成收益添加到用户物品库
• 记录收益来源和分成比例

4. 与Task模块的交互

• 达人升级可触发任务完成
• 发展团队成员可完成特定任务

开发注意事项

1. 数据一致性：所有涉及多个操作的功能都应使用数据库事务
2. 性能优化：推荐关系查询和团队成员统计应考虑性能优化
3. 扩展性考虑：预留达人等级和分成比例的扩展空间
4. 安全验证：所有操作前验证用户权限和数据有效性
5. 日志记录：记录关键操作，便于问题排查和数据分析

开发文档

详细的开发文档请参考以下资源：

• 设计概述 - 模块的整体设计思路和架构
• 数据库设计 - 详细的数据库表结构和关系设计
• 模块接口 - 模块对外提供的服务接口
• 推荐关系系统 - 推荐关系系统的设计与实现