kknongchang_2506/app/Module/UrsPromotion/Docs/设计概述.md

URS推广模块设计概述 (三代推广版本)

1. 模块定位

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

1.1 版本更新 (v2.0.0)

主要变更：

• 推广关系从二代扩展为三代（直推、间推、三推）
• 收益类型分为两种：推广收益和种植收益
• 达人等级配置支持不同收益类型的分成比例
• 优化业务逻辑，提升系统性能

2. 设计目标

1. 建立完整的URS用户推荐体系：支持三代推荐关系（直推、间推、三推），形成多层级的URS团队结构
2. 实现灵活的URS达人等级系统：根据团队规模和活跃度评定用户的URS达人等级
3. 提供公平的URS收益分成机制：根据推荐关系和URS达人等级分配团队收益
4. 支持多种URS收益类型：支持推广收益和种植收益两种不同的收益分成
5. 保证系统的可扩展性：预留URS达人等级、分成比例和收益来源的扩展空间
6. 确保与现有模块的隔离性：与Promotion模块完全独立，避免数据和功能冲突

2.1 收益类型说明

推广收益 (promotion_reward)：

• 触发条件：下级用户进入农场时
• 分成对象：直推、间推、三推上级
• 分成比例：根据达人等级确定

种植收益 (planting_reward)：

• 触发条件：下级用户收获作物时
• 分成对象：直推、间推、三推上级
• 分成比例：根据达人等级确定

3. 架构设计

3.1 模块结构

URS推广模块采用分层架构设计，包括以下层次：

┌─────────────────────────────────────────────────────────────┐
│                    URS推广模块架构                            │
├─────────────────────────────────────────────────────────────┤
│  表现层 (Presentation Layer)                                │
│  ├── AdminControllers (后台管理控制器)                       │
│  └── Helper (辅助类)                                        │
├─────────────────────────────────────────────────────────────┤
│  服务层 (Service Layer)                                     │
│  ├── Services (对外服务接口)                                │
│  └── Events (事件定义)                                      │
├─────────────────────────────────────────────────────────────┤
│  业务层 (Business Layer)                                    │
│  ├── Logics (业务逻辑)                                      │
│  └── Listeners (事件监听器)                                 │
├─────────────────────────────────────────────────────────────┤
│  数据层 (Data Layer)                                        │
│  ├── Models (数据模型)                                      │
│  ├── Repositorys (数据仓库)                                 │
│  └── Enums (枚举定义)                                       │
└─────────────────────────────────────────────────────────────┘

3.2 核心组件

1. Service：对外服务接口，提供模块的核心功能

   • UrsUserMappingService：URS用户映射关系服务（核心基础服务）
   • UrsReferralService：URS推荐关系服务
   • UrsTalentService：URS达人等级服务
   • UrsProfitService：URS团队收益服务

2. Logic：业务逻辑处理，封装复杂的业务规则

   • UrsUserMappingLogic：URS用户映射关系逻辑
   • UrsReferralLogic：URS推荐关系逻辑
   • UrsTalentLogic：URS达人等级逻辑
   • UrsProfitLogic：URS团队收益逻辑

3. Repository：数据访问和持久化，封装数据库操作

   • UrsUserMappingRepository：URS用户映射关系仓库
   • UrsUserReferralRepository：URS用户推荐关系仓库
   • UrsUserTalentRepository：URS用户达人等级仓库
   • UrsProfitRepository：URS团队收益记录仓库

4. Model：数据结构定义，对应数据库表

   • UrsUserMapping：URS用户映射关系模型（核心基础模型）
   • UrsUserReferral：URS用户推荐关系模型
   • UrsUserTalent：URS用户达人等级模型
   • UrsProfit：URS团队收益记录模型

5. Event：事件定义，用于模块间通信

   • UrsTalentLevelUpEvent：URS达人等级提升事件
   • UrsReferralCreatedEvent：URS推荐关系创建事件
   • UrsProfitGeneratedEvent：URS团队收益生成事件

3.3 依赖关系

URS推广模块与其他模块的依赖关系：

┌─────────────┐      ┌─────────────────┐      ┌─────────────┐
│  User模块   │◄────►│ UrsPromotion模块 │◄────►│  Farm模块   │
└─────────────┘      └────────┬────────┘      └─────────────┘
                              │
                              ▼
                       ┌─────────────┐
                       │GameItems模块│
                       └─────────────┘

• User模块：提供用户基本信息，接收URS推荐关系
• Farm模块：提供收获事件，接收URS团队收益分成
• GameItems模块：提供物品操作接口，处理URS收益物品的添加

4. 核心流程

4.1 URS用户绑定关系建立流程

URS用户进入农场 → 检查映射关系 → 建立/验证映射 → 更新相关数据 → 触发相关事件

1. URS用户请求进入农场系统
2. 系统检查是否已存在映射关系
3. 如不存在，创建新的映射关系或自动创建农场用户
4. 如已存在，验证映射关系的有效性
5. 更新用户的达人等级和团队统计
6. 触发用户进入农场事件

4.2 URS推荐关系建立流程

用户注册 → 验证推荐码 → 建立推荐关系 → 更新团队统计 → 触发相关事件

1. 用户使用URS推荐码注册
2. 系统验证推荐码的有效性
3. 建立用户与推荐人的直推关系
4. 更新推荐人的团队统计数据
5. 触发推荐关系创建事件

4.2 URS达人等级升级流程

团队变化 → 检查升级条件 → 计算新等级 → 更新等级 → 触发升级事件

1. 监听团队成员变化事件
2. 检查用户是否满足升级条件
3. 计算用户的新达人等级
4. 更新用户的达人等级信息
5. 触发达人等级变更事件

4.4 URS收益分成流程

收益产生 → 获取团队关系 → 计算分成 → 发放收益 → 记录明细

1. 监听收益产生事件
2. 获取用户的所有上级关系
3. 根据关系类型和达人等级计算分成
4. 将分成收益发放给上级用户
5. 记录详细的分成明细

5. 数据设计

5.1 核心实体

1. URS用户映射关系：建立URS用户与农场用户的一对一映射关系（核心基础实体）
2. URS用户推荐关系：存储用户间的直接推荐关系（支持双ID系统）
3. URS用户达人等级：存储用户的达人等级和团队统计（支持双ID系统）
4. URS团队收益记录：记录所有的收益分成明细（支持双ID系统）
5. URS达人等级配置：配置各个达人等级的要求和权益

5.2 关系设计

• URS用户与农场用户：一对一（通过映射表建立关系，核心基础关系）
• 用户与推荐关系：一对一（每个用户只能有一个直接推荐人）
• 用户与达人等级：一对一（每个用户只有一个达人等级）
• 用户与收益记录：一对多（用户可以有多条收益记录）
• 映射关系与其他实体：一对多（一个映射关系对应多个推荐关系、达人等级、收益记录）

6. 技术特性

6.1 性能优化

1. 缓存策略：使用Redis缓存热点数据
2. 索引优化：为常用查询字段建立合适的索引
3. 分页查询：大数据量查询使用分页机制
4. 异步处理：收益分成等操作使用队列异步处理

6.2 数据一致性

1. 事务处理：关键操作使用数据库事务保证一致性
2. 乐观锁：并发更新使用乐观锁机制
3. 数据校验：严格的数据验证和约束
4. 日志记录：完整的操作日志便于问题排查

6.3 扩展性设计

1. 配置化：达人等级和分成规则支持配置化管理
2. 插件化：收益来源支持插件化扩展
3. 事件驱动：模块间通信使用事件机制
4. 接口标准化：统一的服务接口规范

7. 安全考虑

7.1 数据安全

1. 权限控制：严格的数据访问权限控制
2. 数据加密：敏感数据进行加密存储
3. 审计日志：完整的操作审计日志
4. 备份策略：定期数据备份和恢复机制

7.2 业务安全

1. 防刷机制：防止恶意刷取推荐关系
2. 循环检测：防止推荐关系形成循环
3. 限制机制：合理的业务限制和阈值
4. 监控告警：异常行为监控和告警

8. 与Promotion模块的区别

8.1 命名空间隔离

• 使用独立的命名空间App\Module\UrsPromotion
• 数据库表使用urs_promotion_前缀
• 路由使用urs-promotion前缀

8.2 业务定制化

• 针对URS业务场景的特殊需求
• 独立的达人等级配置和分成规则
• 支持URS特有的业务逻辑

8.3 数据独立性

• 完全独立的数据库表和数据空间
• 不与Promotion模块数据混合
• 支持独立的配置和管理

9. 总结

URS推广模块作为专门为URS业务场景设计的推广系统，通过建立用户间的推荐关系、团队结构、达人等级和收益分成机制，鼓励用户发展URS团队，形成良性的社交生态。模块设计注重灵活性、可扩展性和性能，采用分层架构和事件驱动通信，与其他模块保持松耦合关系，同时与现有Promotion模块完全隔离，确保业务的独立性和安全性。