# 排行榜功能后端开发任务

## 任务概览

| 项目 | 内容 |
|------|------|
| 功能 | 热度排行榜、自制排行榜 |
| 状态 | 已完成 |
| 开始日期 | 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