URS推广模块重构：分离映射关系设计

任务时间: 2025年06月15日 17:00
任务类型: 架构重构
模块: UrsPromotion
版本: v3.0.0

📋 问题分析

用户指出了之前双ID系统设计的逻辑问题：

原设计问题

数据冗余：在每个业务表中都存储双ID，造成数据冗余
映射管理混乱：没有统一的用户关系映射管理
奖励逻辑复杂：无法灵活处理用户未进入农场的情况
跳过机制缺失：上级未进入农场时无法跳过并继续处理上上级

用户需求

创建 urs_user_id 和 user_id 关系表来处理系统的用户关系;
上下级关系表只储存 urs_user_id 之间的关系;
发送奖励时如果urs_user_id 没有对应的 user_id 则跳过该人,继续处理其他人;比如上级没进入农场,但是上上级进入了要继续处理

🎯 重构方案

1. 分离映射关系设计

1.1 核心思想

独立映射表：创建专门的用户映射表管理URS用户ID与农场用户ID的关系
纯推荐关系：推荐关系表只存储URS用户ID之间的关系
智能跳过：奖励分发时根据映射关系决定是否跳过

1.2 表结构设计

用户映射表 (urs_promotion_user_mappings)

CREATE TABLE `kku_urs_promotion_user_mappings` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `urs_user_id` bigint unsigned NOT NULL COMMENT 'URS用户ID',
  `user_id` bigint unsigned NOT NULL COMMENT '农场用户ID',
  `mapping_time` timestamp NOT NULL COMMENT '映射建立时间（用户进入农场时间）',
  `status` tinyint NOT NULL DEFAULT '1' COMMENT '状态:1有效,0无效',
  UNIQUE KEY `uk_urs_user_id` (`urs_user_id`),
  UNIQUE KEY `uk_user_id` (`user_id`)
);

推荐关系表 (urs_promotion_user_referrals) - 简化版

CREATE TABLE `kku_urs_promotion_user_referrals` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `urs_user_id` bigint unsigned NOT NULL COMMENT 'URS用户ID',
  `urs_referrer_id` bigint unsigned NOT NULL COMMENT 'URS推荐人ID',
  `referral_code` varchar(32) DEFAULT NULL COMMENT '历史推荐码',
  `referral_time` timestamp NOT NULL,
  `status` tinyint NOT NULL DEFAULT '1',
  UNIQUE KEY `uk_urs_user_id` (`urs_user_id`)
);

2. 奖励分发逻辑重构

2.1 智能跳过机制

public function distributeReward($ursUserId, $sourceId, $sourceType, $profitType, $originalAmount, $rewardConfig)
{
    $referralChain = $this->getReferralChain($ursUserId, count($rewardConfig));
    
    $level = 1;
    foreach ($referralChain as $referrerUrsUserId) {
        $farmUserId = UrsUserMapping::getFarmUserIdByUrsUserId($referrerUrsUserId);
        
        if ($farmUserId === null) {
            // 跳过未进入农场的用户，记录跳过状态
            $this->recordSkippedReward(...);
        } else {
            // 发放奖励给已进入农场的用户
            $this->recordNormalReward(...);
        }
        
        $level++;
    }
}

2.2 状态管理

STATUS_NORMAL (1)：正常发放
STATUS_CANCELLED (0)：取消
STATUS_SKIPPED (2)：跳过（用户未进入农场）

🔧 技术实现

1. 新增模型类

UrsUserMapping模型

管理URS用户与农场用户的映射关系
提供双向ID查询功能
支持批量映射查询

UrsRewardDistributionService服务

实现智能奖励分发逻辑
处理跳过机制
记录分发结果和原因

2. 模型重构

UrsUserReferral模型

移除农场用户ID字段
只保留URS用户ID关系
通过映射表关联农场用户

UrsUserTalent模型

移除农场用户ID字段
简化为纯URS用户数据

UrsProfit模型

移除农场用户ID字段
新增farm_user_id冗余字段（便于查询）
新增STATUS_SKIPPED状态

3. 数据库迁移

创建了完整的迁移脚本：

备份现有数据
创建新的表结构
数据迁移和验证
清理备份数据

📊 架构优势

1. 数据结构优化

✅ 消除冗余：移除业务表中的双ID冗余
✅ 职责分离：映射关系与业务逻辑分离
✅ 扩展性强：便于后续功能扩展

2. 业务逻辑优化

✅ 智能跳过：自动跳过未进入农场的用户
✅ 连续处理：跳过后继续处理上级用户
✅ 状态追踪：完整记录奖励分发状态

3. 查询性能优化

✅ 索引优化：独立映射表提供高效查询
✅ 批量查询：支持批量ID映射查询
✅ 冗余字段：关键查询场景的性能优化

🚀 使用场景

1. 用户注册流程

URS用户注册 → 建立推荐关系（只存储URS ID）
用户进入农场 → 建立映射关系（URS ID ↔ 农场ID）

2. 奖励分发流程

产生收益 → 查找推荐链 → 检查映射关系 → 发放/跳过 → 记录结果

3. 数据查询场景

根据URS ID查询农场ID → 映射表查询
根据农场ID查询URS ID → 映射表查询
批量ID转换 → 批量映射查询

📝 文件变更

新增文件

create_urs_promotion_tables_v3.sql - 新版本表结构
UrsUserMapping.php - 用户映射模型
UrsRewardDistributionService.php - 奖励分发服务
migrate_to_separated_mapping_v3.sql - 迁移脚本

修改文件

UrsUserReferral.php - 移除农场用户ID字段
UrsUserTalent.php - 移除农场用户ID字段
UrsProfit.php - 重构字段结构，新增跳过状态
README.md - 更新架构说明和表结构文档

🎉 重构成果

架构清晰：分离映射关系，职责明确
逻辑完善：实现智能跳过机制，处理复杂业务场景
性能优化：独立映射表提供高效查询
扩展性强：为后续功能扩展奠定基础
向后兼容：保留历史数据，平滑迁移

任务状态: ✅ 已完成
完成时间: 2025年06月15日 17:00
版本: UrsPromotion v3.0.0 (分离映射关系版本)

151700-URS推广模块重构分离映射关系.md 5.9 KB Permalink History Raw