URS用户绑定关系增加userKey支持

任务时间: 2025年06月16日 17:00-17:30
任务类型: 功能扩展
模块: UrsPromotion

任务描述

为URS用户绑定关系表(urs_promotion_user_mappings)增加userKey字段支持，用于存储URS系统的用户凭证，优化登录流程和用户查找机制。

需求分析

业务背景

userKey是URS系统提供的用户登录凭证
用于向URS系统请求用户数据的标识符
通过userKey可以获取urs_user_id，进而建立推荐关系
需要在用户绑定关系中记录userKey，便于后续查找和验证

技术要求

在用户映射表中添加user_key字段
更新相关模型、服务层和DTO
优化登录流程，支持userKey存储
保持向后兼容性

实现方案

1. 数据库结构扩展

修改表: kku_urs_promotion_user_mappings

添加字段: user_key VARCHAR(255) NULL COMMENT 'URS用户凭证(userKey)'
添加索引: KEY idx_user_key (user_key)

2. 模型层更新

文件: app/Module/UrsPromotion/Models/UrsUserMapping.php

更新field注释，添加user_key字段说明
在$fillable中添加user_key字段
在$casts中添加user_key类型转换
新增userKey相关方法：
- setUserKey() - 设置用户凭证
- getUserKey() - 获取用户凭证
- hasUserKey() - 检查是否有用户凭证
- findByUserKey() - 根据userKey查找映射
- getFarmUserIdByUserKey() - 根据userKey获取农场用户ID
- getUrsUserIdByUserKey() - 根据userKey获取URS用户ID
- getMappingsByUserKeys() - 批量根据userKey获取映射

3. 服务层功能扩展

文件: app/Module/UrsPromotion/Services/UrsUserMappingService.php

更新createMapping()方法，支持userKey参数
更新getFarmUserId()方法，支持userKey参数
新增userKey专门处理方法：
- getFarmUserIdByUserKey() - 根据userKey获取农场用户ID
- getUrsUserIdByUserKey() - 根据userKey获取URS用户ID
- getMappingByUserKey() - 根据userKey获取映射详情
- batchGetMappingsByUserKeys() - 批量获取映射关系
- updateUserKey() - 更新用户映射的userKey
- userKeyExists() - 检查userKey是否已存在
- getFarmUserIdByUserKeyWithAutoCreate() - 根据userKey获取或创建农场用户ID

4. 登录流程集成

文件: app/Module/AppGame/Handler/Public/Login4uHandler.php

更新获取农场用户ID的逻辑
使用getFarmUserIdByUserKeyWithAutoCreate()方法
在登录时自动保存userKey到用户映射表

5. DTO对象更新

文件: app/Module/UrsPromotion/Dtos/UrsUserMappingDto.php

添加userKey属性
更新fromModel方法，包含userKey字段

实施进度

✅ 阶段一：数据库结构扩展（已完成）

创建数据库迁移脚本
执行ALTER TABLE添加user_key字段
添加索引优化查询性能
验证表结构修改

✅ 阶段二：模型层更新（已完成）

更新UrsUserMapping模型field注释
添加user_key到$fillable和$casts
实现userKey相关的访问器和查询方法
回滚错误的UrsUserReferral模型修改

✅ 阶段三：服务层功能扩展（已完成）

更新UrsUserMappingService现有方法
新增userKey专门处理方法
实现智能查找和自动创建功能
添加userKey存在性检查和更新功能

✅ 阶段四：登录流程集成（已完成）

更新Login4uHandler登录逻辑
集成userKey存储到登录流程
优化用户查找和创建机制

✅ 阶段五：DTO对象更新（已完成）

更新UrsUserMappingDto添加userKey字段
保持数据传输对象的一致性

✅ 阶段六：测试验证（已完成）

测试数据库userKey字段功能
验证根据userKey查询功能
确认索引正常工作

技术实现要点

1. 数据库设计

字段类型: VARCHAR(255)，支持较长的userKey
可空设计: 允许NULL，保持向后兼容
索引优化: 为userKey创建索引，提高查询性能

2. 服务层架构

向后兼容: 现有方法保持签名不变，通过可选参数扩展
智能查找: 优先根据userKey查找，其次根据ursUserId查找
自动创建: 支持在找不到映射时自动创建用户和映射关系

3. 错误处理

重复检查: 防止userKey重复使用
数据验证: 确保userKey和ursUserId的一致性
日志记录: 详细记录userKey相关操作的日志

使用示例

// 根据userKey获取农场用户ID
$farmUserId = UrsUserMappingService::getFarmUserIdByUserKey($userKey);

// 根据userKey获取或创建农场用户ID（推荐使用）
$farmUserId = UrsUserMappingService::getFarmUserIdByUserKeyWithAutoCreate($userKey, $ursUserId);

// 更新现有映射的userKey
$success = UrsUserMappingService::updateUserKey($ursUserId, $newUserKey);

// 检查userKey是否已存在
$exists = UrsUserMappingService::userKeyExists($userKey);

// 批量获取映射关系
$mappings = UrsUserMappingService::batchGetMappingsByUserKeys($userKeys);

文件清单

新增文件

app/Module/UrsPromotion/Database/add_user_key_fields.sql - 数据库迁移脚本

修改文件

app/Module/UrsPromotion/Models/UrsUserMapping.php - 添加userKey字段和方法
app/Module/UrsPromotion/Services/UrsUserMappingService.php - 扩展userKey相关服务
app/Module/AppGame/Handler/Public/Login4uHandler.php - 集成userKey存储
app/Module/UrsPromotion/Dtos/UrsUserMappingDto.php - 添加userKey字段
app/Module/UrsPromotion/Docs/DEV.md - 更新开发进度记录

回滚文件

app/Module/UrsPromotion/Models/UrsUserReferral.php - 回滚错误修改
app/Module/UrsPromotion/Services/UrsReferralService.php - 回滚错误修改

总结

本次功能扩展成功为URS用户绑定关系表增加了userKey支持，实现了：

数据存储: 在用户映射表中存储URS用户凭证
查询优化: 支持根据userKey快速查找用户映射关系
登录优化: 登录时自动保存userKey，提高后续查找效率
向后兼容: 保持现有功能不受影响
智能处理: 支持自动创建和更新userKey映射关系

该功能为URS系统与农场系统的集成提供了更好的用户标识和查找机制，提高了系统的可用性和性能。

161700-URS用户绑定关系增加userKey支持.md 6.3 KB Permalink History Raw