URS推广模块

概述

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

主要功能

URS推荐关系管理：建立和维护URS用户间的直推和间推关系
URS关系缓存优化：多级推荐关系预计算缓存，提升查询性能
URS达人等级系统：根据团队规模和活跃度评定用户的URS达人等级
URS团队收益分成：计算和分配URS团队成员产生的收益分成
URS转账手续费配置：基于房屋等级和达人等级的差异化转入/转出手续费管理
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团队成员可完成特定任务

开发注意事项

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

开发文档

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

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

版本信息

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

联系方式

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

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

README.md 11 KB Histórico Raw