topfans/docs/Tasks-Rankings.md

排行榜功能后端开发任务

任务概览

项目	内容
功能	热度排行榜、自制排行榜
状态	已完成
开始日期	2026-03-12

---

任务清单

Phase 1: 数据模型准备

序号	任务	服务	状态
1.1	在 Asset 表新增 is_original 字段	AssetService	✅ 已完成
1.2	编写数据库迁移脚本	AssetService	✅ 已完成

Phase 2: Proto 定义

序号	任务	状态
2.1	新增 ranking.proto 定义排行榜接口	✅ 已完成
2.2	编译 proto 生成 Go 代码	✅ 已完成

Phase 3: 排行榜逻辑实现

序号	任务	服务	状态
3.1	实现热度排行榜查询逻辑 (displaying)	AssetService	✅ 已完成
3.2	实现热度排行榜查询逻辑 (month)	AssetService	✅ 已完成
3.3	实现热度排行榜查询逻辑 (total)	AssetService	✅ 已完成
3.4	实现自制排行榜查询逻辑	AssetService	✅ 已完成
3.5	实现"我的排名"查询逻辑	AssetService	✅ 已完成

Phase 4: Gateway 接口

序号	任务	状态
4.1	新增排行榜路由配置	✅ 已完成
4.2	实现排行榜 Controller	✅ 已完成
4.3	添加 Swagger 文档	✅ 已完成

Phase 5: 测试与优化

序号	任务	状态
5.1	单元测试	✅ 已完成
5.2	API 联调测试	✅ 已完成
5.3	性能优化 (Redis 缓存)	⬜ 待开始

---

新增文件清单

文件	说明
backend/proto/ranking.proto	Proto 定义
backend/scripts/add_is_original_column.sql	数据库迁移脚本
backend/services/assetService/repository/ranking_repository.go	排行榜 Repository
backend/services/assetService/repository/ranking_repository_test.go	排行榜单元测试
backend/services/assetService/service/ranking_service.go	排行榜 Service
backend/services/assetService/provider/ranking_provider.go	排行榜 Provider
backend/services/assetService/main.go	更新：注册 Ranking Service
backend/gateway/controller/ranking_controller.go	排行榜 Controller
backend/gateway/router/router.go	更新：添加排行榜路由

---

API 接口

方法	路径	说明
GET	/api/v1/rankings/hot	获取热度排行榜
GET	/api/v1/rankings/original	获取自制排行榜

API 参数说明

参数	类型	必填	说明
dimension	string	否	统计维度: displaying(展示中), month(本月), total(全部)，默认 total
star_id	int64	否	粉丝身份ID，不传则使用当前身份
page	int	否	页码，默认 1
page_size	int	否	每页数量，默认 10

---

进度记录

日期	完成任务	备注
2026-03-12	Phase 1 数据模型	is_original 字段 + 迁移脚本
2026-03-12	Phase 2 Proto	ranking.proto + 编译
2026-03-12	Phase 3 逻辑	Repository + Service + Provider
2026-03-12	Phase 4 Gateway	Controller + 路由配置
2026-03-12	Phase 5.1 单元测试	ranking_repository_test.go
2026-03-12	Phase 5.2 API 联调	全部 API 测试通过

---

技术依赖

• AssetService (20003) - 藏品和点赞数据
• Exhibition 表 - 展示中藏品判定
• AssetLike 表 - 本月点赞统计
• Redis - 排行榜缓存（待实现）

---

注意事项

1. 排行榜按粉丝身份 (star_id) 隔离
2. "我的排名"返回用户点赞最高的藏品
3. 取消点赞不实时扣除点赞数
4. 分页默认 10 条，Top N 默认 100