kknongchang_2506/app/Module/UrsPromotion/Docs/用户绑定关系.md

URS推广模块 - 用户绑定关系详细文档

1. 概述

用户绑定关系是URS推广模块的核心基础功能，负责建立和管理URS系统用户与农场系统用户之间的映射关系。该功能实现了分离映射关系设计，使得URS推广系统可以独立于农场用户系统存在，同时保持两个系统之间的数据关联。

1.1 设计原则

• 分离映射关系：URS推广关系只存储URS用户ID，通过映射表关联农场用户
• 一对一映射：一个URS用户只能映射一个农场用户，反之亦然
• 自动创建机制：支持在建立映射关系时自动创建农场用户
• 状态管理：支持映射关系的启用和禁用状态管理
• 数据完整性：确保映射关系的数据完整性和一致性

1.2 核心功能

1. 映射关系建立：用户进入农场时建立URS用户与农场用户的映射关系
2. 双向查询：支持根据URS用户ID查询农场用户ID，或反向查询
3. 批量操作：支持批量查询和处理映射关系
4. 状态管理：支持映射关系的启用、禁用状态管理
5. 自动创建：不存在映射关系时自动创建新用户并建立映射
6. 后台管理：提供完整的后台管理界面进行映射关系管理

2. 数据结构

2.1 用户映射表 (urs_promotion_user_mappings)

字段名	类型	说明
id	bigint	主键ID
urs_user_id	bigint	URS用户ID（核心标识）
user_id	bigint	农场用户ID（对应users表）
mapping_time	timestamp	映射建立时间（用户进入农场时间）
status	tinyint	状态:1有效,0无效
is_active	tinyint	是否活跃:1活跃,0不活跃
last_activity_check	timestamp	最后活跃检查时间
active_days_count	int	活跃天数统计
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

2.2 状态定义

// 映射状态
const STATUS_INVALID = 0; // 无效
const STATUS_VALID = 1;   // 有效

// 活跃状态
const ACTIVE_NO = 0;  // 不活跃
const ACTIVE_YES = 1; // 活跃

2.3 活跃用户定义

• 活跃用户：最近15天内有活动记录的用户（基于last_activity_time字段）
• 活跃检查：每日定时任务自动检查和更新用户活跃状态
• 活跃统计：用于达人等级升级条件判断

2.3 索引设计

• 主键索引：PRIMARY KEY (id)
• 唯一索引：UNIQUE KEY uk_urs_user_id (urs_user_id) - 确保URS用户唯一映射
• 唯一索引：UNIQUE KEY uk_user_id (user_id) - 确保农场用户唯一映射
• 普通索引：KEY idx_mapping_time (mapping_time) - 支持时间查询
• 普通索引：KEY idx_status (status) - 支持状态筛选

3. 服务层接口

3.1 UrsUserMappingService 核心方法

3.1.1 创建映射关系

/**
 * 创建用户映射关系（用户进入农场时调用）
 * @param int $ursUserId URS用户ID
 * @param int $farmUserId 农场用户ID
 * @return UrsUserMappingDto
 */
public static function createMapping(int $ursUserId, int $farmUserId): UrsUserMappingDto

3.1.2 获取农场用户ID

/**
 * 根据URS用户ID获取农场用户ID
 * @param int $ursUserId URS用户ID
 * @return int|null 农场用户ID，如果未找到返回null
 */
public static function getFarmUserId(int $ursUserId): ?int

3.1.3 获取URS用户ID

/**
 * 根据农场用户ID获取URS用户ID
 * @param int $farmUserId 农场用户ID
 * @return int|null URS用户ID，如果未找到返回null
 */
public static function getUrsUserId(int $farmUserId): ?int

3.1.4 检查用户是否已进入农场

/**
 * 检查URS用户是否已进入农场
 * @param int $ursUserId URS用户ID
 * @return bool
 */
public static function hasEnteredFarm(int $ursUserId): bool

3.1.5 自动创建用户并建立映射

/**
 * 获取或创建农场用户ID（不存在时自动创建）
 * @param int $ursUserId URS用户ID
 * @return int|null 农场用户ID，创建失败返回null
 */
public static function getOrCreateFarmUserId(int $ursUserId): ?int

3.1.6 批量查询映射关系

/**
 * 批量获取URS用户ID对应的农场用户ID
 * @param array $ursUserIds URS用户ID数组
 * @return array 映射关系数组 [urs_user_id => farm_user_id]
 */
public static function batchGetFarmUserIds(array $ursUserIds): array

3.2 状态管理方法

3.2.1 禁用映射关系

/**
 * 禁用用户映射关系
 * @param int $ursUserId URS用户ID
 * @return bool
 */
public static function disableMapping(int $ursUserId): bool

3.2.2 启用映射关系

/**
 * 启用用户映射关系
 * @param int $ursUserId URS用户ID
 * @return bool
 */
public static function enableMapping(int $ursUserId): bool

3.3 统计和查询方法

3.3.1 获取映射统计信息

/**
 * 获取映射统计信息
 * @return array
 */
public static function getMappingStats(): array

3.3.2 获取映射详情

/**
 * 获取用户映射详情
 * @param int $ursUserId URS用户ID
 * @return UrsUserMappingDto|null
 */
public static function getMappingDetail(int $ursUserId): ?UrsUserMappingDto

4. 业务流程

4.1 用户进入农场流程

graph TD
    A[URS用户进入农场] --> B{检查是否已有映射关系}
    B -->|已存在| C{检查映射的农场用户ID是否匹配}
    C -->|匹配| D[返回现有映射关系]
    C -->|不匹配| E[抛出异常：已映射到其他用户]
    B -->|不存在| F{检查农场用户ID是否已被映射}
    F -->|已被映射| G[抛出异常：农场用户已被映射]
    F -->|未被映射| H[创建新映射关系]
    H --> I[记录操作日志]
    I --> J[返回映射关系DTO]

4.2 自动创建用户流程

graph TD
    A[获取或创建农场用户] --> B{检查是否已有映射关系}
    B -->|已存在| C[返回现有农场用户ID]
    B -->|不存在| D[生成用户名: urs-{ursUserId}]
    D --> E[生成随机密码]
    E --> F[调用UserService创建用户]
    F --> G{用户创建是否成功}
    G -->|失败| H[记录错误日志并返回null]
    G -->|成功| I[创建用户映射关系]
    I --> J[记录成功日志]
    J --> K[返回农场用户ID]

5. 使用示例

5.1 基础使用示例

use App\Module\UrsPromotion\Services\UrsUserMappingService;

// 用户进入农场时建立映射关系
$ursUserId = 1001;
$farmUserId = 2001;

try {
    $mapping = UrsUserMappingService::createMapping($ursUserId, $farmUserId);
    echo "映射关系建立成功，ID: " . $mapping->id;
} catch (\Exception $e) {
    echo "建立失败: " . $e->getMessage();
}

// 查询映射关系
$farmUserId = UrsUserMappingService::getFarmUserId(1001);
$ursUserId = UrsUserMappingService::getUrsUserId(2001);

// 检查用户是否已进入农场
$hasEntered = UrsUserMappingService::hasEnteredFarm(1001);

5.2 自动创建用户示例

// 获取或自动创建农场用户
$ursUserId = 1002;
$farmUserId = UrsUserMappingService::getOrCreateFarmUserId($ursUserId);

if ($farmUserId) {
    echo "农场用户ID: " . $farmUserId;
} else {
    echo "创建失败";
}

5.3 批量操作示例

// 批量获取映射关系
$ursUserIds = [1001, 1002, 1003];
$mappings = UrsUserMappingService::batchGetFarmUserIds($ursUserIds);

foreach ($mappings as $ursUserId => $farmUserId) {
    echo "URS用户 {$ursUserId} 映射到农场用户 {$farmUserId}";
}

// 获取已进入农场的URS用户列表
$enteredUsers = UrsUserMapping::getEnteredFarmUrsUserIds($ursUserIds);

6. 后台管理功能

6.1 管理界面功能

• 列表页面：显示所有用户映射关系，支持筛选和排序
• 详情页面：显示映射关系的详细信息
• 状态管理：支持启用/禁用映射关系
• 关联查询：提供到推荐关系和达人等级的快速链接
• 操作日志：记录所有映射关系的操作历史

6.2 筛选功能

• URS用户ID筛选
• 农场用户ID筛选
• 状态下拉选择筛选
• 绑定时间范围筛选
• 创建时间范围筛选

6.3 自定义操作

• 同步信息：同步用户信息到映射关系
• 验证映射：验证映射关系的有效性
• 查看推荐关系：跳转到用户的推荐关系页面
• 查看达人等级：跳转到用户的达人等级页面

7. 错误处理

7.1 常见异常

• 重复映射异常：URS用户已映射到其他农场用户
• 农场用户被占用异常：农场用户已被其他URS用户映射
• 用户创建失败异常：自动创建农场用户时失败
• 数据库操作异常：数据库连接或操作失败

7.2 异常处理示例

try {
    $mapping = UrsUserMappingService::createMapping($ursUserId, $farmUserId);
} catch (\Exception $e) {
    Log::error('用户映射创建失败', [
        'urs_user_id' => $ursUserId,
        'farm_user_id' => $farmUserId,
        'error' => $e->getMessage()
    ]);
    
    // 根据异常类型进行不同处理
    if (strpos($e->getMessage(), '已映射') !== false) {
        // 处理重复映射异常
    }
}

8. 性能优化

8.1 缓存策略

• 使用Redis缓存热点映射关系
• 缓存用户是否已进入农场的状态
• 批量查询时使用缓存减少数据库访问

8.2 数据库优化

• 合理使用索引提高查询性能
• 批量操作时使用批量查询方法
• 定期清理无效的映射关系记录

9. 监控和日志

9.1 操作日志

所有映射关系的关键操作都会记录详细日志：

• 映射关系创建
• 映射关系状态变更
• 自动用户创建
• 异常情况记录

9.2 统计监控

• 每日新增映射关系数量
• 映射关系状态分布
• 自动创建用户成功率
• 异常情况统计

10. 最佳实践

1. 事务处理：关键操作使用数据库事务确保数据一致性
2. 异常处理：合理处理各种异常情况，提供友好的错误信息
3. 日志记录：记录详细的操作日志便于问题排查
4. 性能优化：使用批量操作和缓存提高性能
5. 数据验证：严格验证输入参数，确保数据完整性
6. 状态管理：合理使用状态字段管理映射关系的生命周期