kknongchang_2506/AiWork/202506/101401-实现农场房屋排行榜功能.md

实现农场房屋排行榜功能

任务时间: 2025年06月10日 14:01
任务状态: ✅ 已完成
提交哈希: c17b007e

任务概述

实现农场房屋排行榜功能，允许玩家查看按房屋等级排序的排行榜，包括分页显示、用户自己的排名查询等功能。

完成内容

1. Handler层实现

1.1 创建RankHandler

• 文件: app/Module/AppGame/Handler/House/RankHandler.php
• 功能: 处理房屋排行榜请求，调用Farm模块的服务层获取排行榜数据
• 特点:
  • 支持分页参数处理
  • 异常处理和日志记录
  • 调用服务层并转换为Protobuf格式返回

2. Farm模块服务层扩展

2.1 扩展HouseService

• 文件: app/Module/Farm/Services/HouseService.php
• 新增方法: getHouseRankList() - 获取房屋排行榜数据
• 功能:
  • 调用逻辑层获取排行榜数据
  • 异常处理和日志记录
  • 返回DTO对象

3. Farm模块逻辑层实现

3.1 扩展HouseLogic

• 文件: app/Module/Farm/Logics/HouseLogic.php
• 新增方法:
  • getHouseRankList() - 实现排行榜查询逻辑
  • getUserHouseRank() - 获取用户排名
  • getTotalHouseRankCount() - 获取总数
• 功能:
  • 查询数据库，按房屋等级降序排序
  • 同等级按升级时间排序
  • 支持分页查询
  • 计算用户排名

4. DTO对象创建

4.1 HouseRankDto

• 文件: app/Module/Farm/Dtos/HouseRankDto.php
• 功能: 房屋排行榜数据传输对象
• 包含: 排行榜列表、用户排名、分页信息、赛季信息

4.2 HouseRankItemDto

• 文件: app/Module/Farm/Dtos/HouseRankItemDto.php
• 功能: 房屋排行榜项目数据传输对象
• 包含: 排名、房屋等级、用户ID、昵称、赛季信息
• 特点: 提供fromArray静态方法便于数据转换

5. Protobuf转换层

5.1 HouseRankDto转换类

• 文件: app/Module/AppGame/Proto/HouseRankDto.php
• 功能: 将DTO转换为Protobuf格式的响应数据
• 特点:
  • 正确处理分页信息转换
  • 处理nickname字段类型问题（protobuf中为int64）
  • 计算分页相关信息（最后一页、是否有更多等）

技术实现细节

1. 数据库查询优化

• 使用JOIN查询获取用户信息
• 按房屋等级降序排列，同等级按升级时间升序排列
• 支持分页查询，避免大量数据加载

2. 排名计算算法

• 计算用户排名：比用户等级高的用户数量 + 同等级但升级时间更早的用户数量 + 1
• 高效的SQL查询实现排名计算

3. Protobuf兼容性处理

• 发现并解决了protobuf中nickname字段类型问题（定义为int64而非string）
• 正确使用ResponsePage的方法名（setCurrentPage而非setPage）
• 完整的分页信息设置（包括hasMore、lastPage等）

测试验证

1. 功能测试

• ✅ 服务层排行榜数据获取测试
• ✅ Protobuf转换功能测试
  
• ✅ Handler完整流程测试
• ✅ 分页功能测试
• ✅ 用户排名计算测试

2. 测试结果

排行榜数据获取成功！
用户排名: 2
赛季: 1
排行榜列表:
排名: 1, 用户ID: 10006, 房屋等级: 12, 昵称: 13172187000
排名: 2, 用户ID: 10000, 房屋等级: 1, 昵称: 13172187523
排名: 3, 用户ID: 10001, 房屋等级: 1, 昵称: 13034634429
排名: 4, 用户ID: 10002, 房屋等级: 1, 昵称: 13034634428

分页信息:
Array
(
    [page] => 1
    [per_page] => 10
    [total] => 4
)

相关文件

新增文件

• app/Module/AppGame/Handler/House/RankHandler.php - 房屋排行榜Handler
• app/Module/AppGame/Proto/HouseRankDto.php - Protobuf转换类
• app/Module/Farm/Dtos/HouseRankDto.php - 排行榜DTO
• app/Module/Farm/Dtos/HouseRankItemDto.php - 排行榜项目DTO

修改文件

• app/Module/Farm/Logics/HouseLogic.php - 扩展排行榜逻辑
• app/Module/Farm/Services/HouseService.php - 扩展排行榜服务

任务状态

✅ 已完成 - 所有功能已实现并测试通过，代码已提交并推送到远程仓库。

API使用说明

请求格式

路由: house/rank
请求类型: RequestHouseRank
分页参数: RequestPage (page, per_page)

响应格式

响应类型: ResponseHouseRank
字段:
- page: 分页信息
- user_rank: 用户排名（0表示未上榜）
- reason: 赛季信息
- list: 排行榜列表（FarmRankItem数组）

排行榜项目格式

FarmRankItem:
- rank: 排名
- level: 房屋等级
- user_id: 用户ID
- nickname: 昵称ID（注意：protobuf中为int64类型）
- reason: 赛季信息

注意事项

1. nickname字段类型: protobuf中定义为int64，实际传递的是用户ID，客户端需要根据用户ID获取昵称
2. 排序规则: 按房屋等级降序，同等级按升级时间升序
3. 分页支持: 默认每页20条，最大100条
4. 性能考虑: 使用JOIN查询优化性能，避免N+1查询问题

下一步工作

建议进行以下后续工作：

1. 考虑添加排行榜缓存机制提升性能
2. 添加排行榜奖励功能
3. 考虑添加历史排行榜功能
4. 优化protobuf定义，将nickname字段改为string类型