kknongchang_2506/app/Module/UrsPromotion

URS推广模块

概述

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

主要功能

1. URS推荐关系管理：建立和维护URS用户间的直推和间推关系
2. URS关系缓存优化：多级推荐关系预计算缓存，提升查询性能
3. URS达人等级系统：根据团队规模和活跃度评定用户的URS达人等级
4. URS团队收益分成：计算和分配URS团队成员产生的收益分成
5. URS转账手续费配置：基于房屋等级和达人等级的差异化转入/转出手续费管理
6. URS团队数据统计：统计和展示URS团队规模、收益等数据

目录结构

app/Module/UrsPromotion/
├── AdminControllers/        # 后台管理控制器
│   └── Helper/             # 辅助类
├── Commands/                # 命令行工具
├── Databases/               # 数据库相关文件
│   ├── createsql/          # 数据库创建SQL
│   └── GenerateSql/        # 生成的SQL文件
├── Docs/                    # 详细文档目录
├── Enums/                   # 枚举类型定义
├── Events/                  # 事件类
├── Listeners/               # 事件监听器
├── Logics/                  # 业务逻辑类
├── Models/                  # 数据模型
├── Providers/               # 服务提供者
├── Repositorys/             # 数据仓库
└── Services/                # 开放服务类

核心概念

1. 分离映射关系设计

• 用户映射表：独立管理URS用户ID与农场用户ID的映射关系
• 推荐关系表：只存储URS用户ID之间的推荐关系
• 奖励发放逻辑：根据映射关系决定是否发放奖励，未进入农场的用户跳过

2. URS推荐关系

• 直推关系：用户A直接推荐用户B注册，A是B的直推上级
• 间推关系：用户A推荐用户B，用户B推荐用户C，A是C的间推上级
• 三推关系：用户A推荐用户B，用户B推荐用户C，用户C推荐用户D，A是D的三推上级
• 团队成员：用户的所有直推、间推和三推下级构成该用户的URS团队
• 跳过机制：上级未进入农场时跳过该层级，继续处理上上级
• 无推荐码：系统不使用推荐码机制，直接通过URS用户ID建立推荐关系

3. URS达人等级

URS达人等级分为6个级别：

• 0级：非达人（默认等级）
• 1级：URS初级达人
• 2级：URS中级达人
• 3级：URS高级达人
• 4级：URS资深达人
• 5级：URS顶级达人

4. URS收益分成

URS收益分成支持三代推广关系，包含两种收益类型：

3.1 推广收益

• 直推分成：下级进入农场时发放奖励，根据达人等级确定分成比例
• 间推分成：下级的下级进入农场时发放奖励，根据达人等级确定分成比例
• 三推分成：下级的下级的下级进入农场时发放奖励，根据达人等级确定分成比例

3.2 种植收益

• 直推分成：下级收获作物时发放奖励，根据达人等级确定分成比例
• 间推分成：下级的下级收获作物时发放奖励，根据达人等级确定分成比例
• 三推分成：下级的下级的下级收获作物时发放奖励，根据达人等级确定分成比例

3.3 分成范围

• 推广关系层级：支持三代推广关系（直推、间推、三推）
• 达人等级影响：不同达人等级享有不同的分成比例

5. URS转账手续费配置

URS转账手续费配置提供基于用户等级的差异化费率管理：

5.1 转账类型

• 转入(in)：用户向农场系统充值/存入资金的手续费
• 转出(out)：用户从农场系统提取/转出资金的手续费

5.2 费率计算规则

• 房屋等级优惠：房屋等级越高，手续费率越低
• 达人等级优惠：达人等级越高，手续费率越低
• 优先级匹配：系统自动匹配最高优先级的费率配置
• 智能缓存：费率计算结果缓存1小时，提升查询性能

5.3 费率特点

• 转入优惠：转入手续费通常较低或免费，鼓励用户充值
• 转出管控：转出手续费相对较高，控制资金流出
• 等级激励：通过差异化费率激励用户提升房屋等级和达人等级

核心数据表

1. URS用户映射关系表 (urs_promotion_user_mappings)

字段名	类型	说明
id	bigint	主键ID
urs_user_id	bigint	URS用户ID
user_id	bigint	农场用户ID
mapping_time	timestamp	映射建立时间（用户进入农场时间）
status	tinyint	状态:1有效,0无效

2. URS用户推荐关系表 (urs_promotion_user_referrals)

字段名	类型	说明
id	bigint	主键ID
urs_user_id	bigint	URS用户ID
urs_referrer_id	bigint	URS推荐人ID
referral_time	timestamp	推荐时间

3. URS达人等级表 (urs_promotion_user_talents)

字段名	类型	说明
id	bigint	主键ID
urs_user_id	bigint	URS用户ID
talent_level	tinyint	URS达人等级
direct_count	int	直推人数
indirect_count	int	间推人数
third_count	int	三推人数
promotion_count	int	团队总人数

4. URS团队收益记录表 (urs_promotion_profits)

字段名	类型	说明
id	bigint	主键ID
urs_user_id	bigint	获得收益的URS用户ID
urs_promotion_member_id	bigint	团队成员URS用户ID（产生收益的用户）
source_id	bigint	收益来源ID
source_type	varchar	收益来源类型
profit_type	varchar	收益类型：promotion_reward推广收益，planting_reward种植收益
relation_level	tinyint	推荐层级：1直推，2间推，3三推
profit_amount	decimal	分成收益数量
profit_rate	decimal	分成比例
farm_user_id	bigint	实际发放奖励的农场用户ID（冗余字段）
status	tinyint	状态：1正常，0取消，2跳过（用户未进入农场）

5. URS达人等级配置表 (urs_promotion_talent_configs)

字段名	类型	说明
id	bigint	主键ID
level	tinyint	达人等级
name	varchar	等级名称
direct_count_required	int	所需直推人数
promotion_count_required	int	所需团队总人数
promotion_reward_rates	json	推广收益分成比例配置
planting_reward_rates	json	种植收益分成比例配置

6. URS转账手续费配置表 (urs_promotion_transfer_fee_configs)

字段名	类型	说明
id	bigint	主键ID
house_level	int	房屋等级(0表示所有等级)
talent_level	int	达人等级(0表示所有等级)
transfer_type	enum	转账类型:in转入,out转出
fee_rate	decimal	手续费率(0-1之间的小数)
description	varchar	配置描述
priority	int	优先级(数值越大优先级越高)
status	tinyint	状态:1启用,0禁用

核心服务

1. URS用户映射服务 (UrsUserMappingService)

• 管理URS用户与农场用户的映射关系
• 用户进入农场时建立映射
• 提供双向ID查询功能
• 批量映射查询和状态管理
• 所有方法均为静态方法

2. URS推荐关系服务 (UrsReferralService)

• 建立URS推荐关系（只存储URS用户ID）
• 获取用户的URS推荐人和团队成员
• 推荐关系链查询和验证
• 防止循环推荐和团队统计更新
• 所有方法均为静态方法

3. URS达人等级服务 (UrsTalentService)

• 计算和更新URS达人等级
• 获取用户的URS达人信息和权益
• 升级条件检查和等级配置管理
• 达人排行榜和统计分析
• 所有方法均为静态方法

4. URS奖励分发服务 (UrsRewardDistributionService)

• 实现智能奖励分发逻辑
• 跳过未进入农场的用户
• 继续处理上级用户
• 记录分发结果和跳过原因
• 所有方法均为静态方法

5. URS转账手续费服务 (UrsTransferFeeService)

• 基于房屋等级和达人等级计算最优手续费率
• 支持转入和转出两种转账类型的差异化费率
• 智能匹配最高优先级的费率配置
• 缓存机制优化查询性能
• 事件监听自动应用最优费率
• 所有方法均为静态方法

与其他模块的交互

1. 与User模块的交互

• URS用户注册时建立推荐关系（只存储URS用户ID）
• 用户进入农场时建立映射关系
• 验证URS推荐人ID的有效性

2. 与Farm模块的交互

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

3. 与GameItems模块的交互

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

4. 与Task模块的交互

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

开发注意事项

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

开发文档

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

• 设计概述 - 模块的整体设计思路和架构
• 数据库设计 - 详细的数据库表结构和关系设计
• 达人等级逻辑 - 达人等级系统的详细逻辑和实现
• 用户绑定关系 - URS用户与农场用户映射关系的详细说明
• 转账手续费配置 - 转账手续费配置系统的详细说明和使用指南
• 服务层使用示例 - 服务层接口的使用方法和示例

版本信息

• 创建时间：2025年06月14日
• 当前版本：v1.0.0-dev
• 开发状态：开发中

联系方式

如有问题或建议，请联系开发团队。

---

注意：本模块专门为URS业务场景设计，与通用的Promotion模块完全独立，请勿混用。