# 团队模块

## 概述

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

## 主要功能

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. **日志记录**：记录关键操作，便于问题排查和数据分析

## 开发文档

详细的开发文档请参考以下资源：
- [设计概述](Docs/设计概述.md) - 模块的整体设计思路和架构
- [数据库设计](Docs/数据库设计.md) - 详细的数据库表结构和关系设计
- [模块接口](Docs/模块接口.md) - 模块对外提供的服务接口
- [推荐关系系统](Docs/推荐关系系统.md) - 推荐关系系统的设计与实现