439 lines
10 KiB
Markdown
439 lines
10 KiB
Markdown
# TopFans 排行榜功能需求文档
|
||
|
||
## 1. 功能概述
|
||
|
||
### 1.1 产品背景
|
||
|
||
排行榜功能旨在提升用户活跃度和参与度，通过展示热门藏品和自制佳作榜单，激励用户创作和互动。
|
||
|
||
### 1.2 排行榜类型
|
||
|
||
| 排行类型 | 统计维度 | 数据来源 |
|
||
|----------|----------|----------|
|
||
| 热度排行 | 展示中 / 本月 / 全部 | 藏品点赞数 |
|
||
| 自制排行 | 展示中 / 本月 / 全部 | 自制藏品点赞数 |
|
||
|
||
> **注意**: 活动排行榜功能待后续单独设计
|
||
|
||
---
|
||
|
||
## 2. 数据模型设计
|
||
|
||
### 2.1 现有数据分析
|
||
|
||
**Asset (藏品表)**
|
||
- `LikeCount` - 点赞数（累计）
|
||
- `OwnerUID` - 拥有者ID
|
||
- `StarID` - 粉丝身份ID
|
||
- `CreatedAt` - 创建时间
|
||
|
||
**AssetLike (点赞记录表)**
|
||
- `AssetID` - 藏品ID
|
||
- `UserID` - 点赞用户ID
|
||
- `CreatedAt` - 点赞时间（用于本月统计）
|
||
|
||
**Exhibition (展品展示表)**
|
||
- `AssetID` - 展品ID
|
||
- `StartTime` - 开始展示时间
|
||
- `ExpireAt` - 过期时间（用于"展示中"判定）
|
||
|
||
### 2.2 新增数据模型
|
||
|
||
#### 2.2.1 藏品表扩展
|
||
|
||
在 Asset 表中增加 `IsOriginal` 字段（true=自制藏品）：
|
||
|
||
```go
|
||
type Asset struct {
|
||
// ... 现有字段
|
||
IsOriginal bool `gorm:"default:false;column:is_original"` // 是否自制藏品
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. API 接口设计
|
||
|
||
### 3.1 通用响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"items": [],
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total": 100
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 热度排行榜
|
||
|
||
#### 3.2.1 获取热度排行榜
|
||
|
||
**接口**: GET /api/v1/rankings/hot
|
||
|
||
**认证**: 需认证 (JWT Token)
|
||
|
||
**Query 参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| dimension | string | 是 | 统计维度: `displaying`(展示中) / `month`(本月) / `total`(全部) |
|
||
| star_id | int64 | 否 | 粉丝身份ID筛选，不传则返回当前身份数据 |
|
||
| page | int | 否 | 页码，默认1 |
|
||
| page_size | int | 否 | 每页数量，默认10 |
|
||
|
||
**返回示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"my_ranking": {
|
||
"rank": 5,
|
||
"asset_id": 1005,
|
||
"asset_name": "我的藏品",
|
||
"cover_url": "https://...",
|
||
"like_count": 88,
|
||
"status": "ranked"
|
||
},
|
||
"items": [
|
||
{
|
||
"rank": 1,
|
||
"asset_id": 1001,
|
||
"asset_name": "战战生贺",
|
||
"cover_url": "https://...",
|
||
"owner_uid": 12345,
|
||
"owner_nickname": "爱战战",
|
||
"like_count": 999,
|
||
"is_original": false
|
||
},
|
||
{
|
||
"rank": 2,
|
||
"asset_id": 1002,
|
||
"asset_name": "肖战同框",
|
||
"cover_url": "https://...",
|
||
"owner_uid": 12346,
|
||
"owner_nickname": "小飞侠",
|
||
"like_count": 888,
|
||
"is_original": true
|
||
}
|
||
],
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total": 100
|
||
}
|
||
}
|
||
```
|
||
|
||
**我的排名返回说明**:
|
||
|
||
| 状态 | rank | 说明 |
|
||
|------|------|------|
|
||
| 上榜 | 5 | 在 Top N 内，显示具体排名 |
|
||
| 未上榜 | null | 不在 Top N 内，显示差距 |
|
||
|
||
**上榜返回示例 (my_ranking)**:
|
||
|
||
```json
|
||
{
|
||
"my_ranking": {
|
||
"rank": 5,
|
||
"asset_id": 1005,
|
||
"asset_name": "我的藏品",
|
||
"cover_url": "https://...",
|
||
"like_count": 88,
|
||
"status": "ranked"
|
||
}
|
||
}
|
||
```
|
||
|
||
**未上榜返回示例 (my_ranking)**:
|
||
|
||
```json
|
||
{
|
||
"my_ranking": {
|
||
"rank": null,
|
||
"asset_id": 1005,
|
||
"asset_name": "我的藏品",
|
||
"cover_url": "https://...",
|
||
"like_count": 50,
|
||
"status": "unranked",
|
||
"diff_to_rank": 50
|
||
}
|
||
}
|
||
```
|
||
|
||
**统计逻辑**:
|
||
|
||
| 维度 | 说明 |
|
||
|------|------|
|
||
| `displaying` | 统计当前正在展示的藏品的点赞数（Exhibition.ExpireAt > Now()） |
|
||
| `month` | 统计当前自然月内（2026年3月1日-3月31日）获得的点赞数 |
|
||
| `total` | 统计藏品累计点赞数 |
|
||
|
||
**多藏品处理**:
|
||
|
||
- 用户有多个藏品时，返回排行最高的那个藏品排名
|
||
|
||
**分页规则**:
|
||
|
||
- 每次返回 10 条（page_size 默认 10）
|
||
- 榜单最多显示前 100 名（可配置）
|
||
|
||
---
|
||
|
||
### 3.3 自制排行榜
|
||
|
||
#### 3.3.1 获取自制排行榜
|
||
|
||
**接口**: GET /api/v1/rankings/original
|
||
|
||
**认证**: 需认证 (JWT Token)
|
||
|
||
**Query 参数**:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| dimension | string | 是 | 统计维度: `displaying`(展示中) / `month`(本月) / `total`(全部) |
|
||
| star_id | int64 | 否 | 粉丝身份ID筛选，不传则返回当前身份数据 |
|
||
| page | int | 否 | 页码，默认1 |
|
||
| page_size | int | 否 | 每页数量，默认10 |
|
||
|
||
**返回示例**:
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"my_ranking": {
|
||
"rank": 3,
|
||
"asset_id": 1002,
|
||
"asset_name": "自制海报",
|
||
"cover_url": "https://...",
|
||
"like_count": 666,
|
||
"status": "ranked"
|
||
},
|
||
"items": [
|
||
{
|
||
"rank": 1,
|
||
"asset_id": 1002,
|
||
"asset_name": "自制海报",
|
||
"cover_url": "https://...",
|
||
"owner_uid": 12346,
|
||
"owner_nickname": "小飞侠",
|
||
"like_count": 888,
|
||
"material_url": "https://...",
|
||
"is_original": true
|
||
}
|
||
],
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total": 50
|
||
}
|
||
}
|
||
```
|
||
|
||
**统计逻辑**:
|
||
|
||
- 仅统计 `is_original = true` 的自制藏品
|
||
- 其他维度逻辑同热度排行榜
|
||
|
||
---
|
||
|
||
## 4. 前端界面设计
|
||
|
||
### 4.1 排行榜入口
|
||
|
||
在首页广场添加"排行榜"Tab，或在个人中心添加入口。
|
||
|
||
### 4.2 排行榜页面结构
|
||
|
||
```
|
||
┌─────────────────────────────┐
|
||
│ 排行榜 │
|
||
├─────────────────────────────┤
|
||
│ [热度] [自制] │ ← Tab 切换
|
||
├─────────────────────────────┤
|
||
│ │
|
||
│ 🥇 用户A 999 赞 │
|
||
│ [图片] │
|
||
│ │
|
||
│ 🥈 用户B 888 赞 │
|
||
│ [图片] │
|
||
│ │
|
||
│ 🥉 用户C 777 赞 │
|
||
│ [图片] │
|
||
│ │
|
||
├─────────────────────────────┤
|
||
│ [展示中] [本月] [全部] │ ← 维度切换
|
||
└─────────────────────────────┘
|
||
```
|
||
|
||
### 4.3 我的排名吸底展示
|
||
|
||
**上榜状态**:
|
||
|
||
```
|
||
┌─────────────────────────────┐
|
||
│ 排行榜 │
|
||
│ ... │
|
||
│ 8. 用户H 100 赞 │
|
||
│ [图片] │
|
||
│ 9. 用户I 99 赞 │
|
||
│ [图片] │
|
||
│ 10. 用户J 98 赞 │
|
||
│ [图片] │
|
||
├─────────────────────────────┤
|
||
│ 🏆 我的排名: 第5名 │
|
||
│ ❤️ [图片] 我的藏品 88赞 │
|
||
└─────────────────────────────┘
|
||
```
|
||
|
||
**未上榜状态**:
|
||
|
||
```
|
||
┌─────────────────────────────┐
|
||
│ 排行榜 │
|
||
│ ... │
|
||
│ 98. 用户H 60 赞 │
|
||
│ [图片] │
|
||
│ 99. 用户I 59 赞 │
|
||
│ [图片] │
|
||
│ 100. 用户J 58 赞 │
|
||
│ [图片] │
|
||
├─────────────────────────────┤
|
||
│ 😢 未上榜 │
|
||
│ 距离上榜还差 8 热度 │
|
||
│ [图片] 我的藏品 50赞 │
|
||
└─────────────────────────────┘
|
||
```
|
||
|
||
**空状态**:
|
||
|
||
```
|
||
┌─────────────────────────────┐
|
||
│ 排行榜 │
|
||
├─────────────────────────────┤
|
||
│ │
|
||
│ 暂无数据，快去创作吧 │
|
||
│ │
|
||
│ [去铸造] │
|
||
└─────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 数据库变更
|
||
|
||
### 5.1 藏品表扩展
|
||
|
||
```sql
|
||
ALTER TABLE assets ADD COLUMN is_original BOOLEAN DEFAULT FALSE;
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 性能优化
|
||
|
||
### 6.1 缓存策略
|
||
|
||
| 数据 | 缓存策略 | 过期时间 |
|
||
|------|----------|----------|
|
||
| 热度排行榜 | Redis ZSet | 5分钟 |
|
||
| 自制排行榜 | Redis ZSet | 5分钟 |
|
||
|
||
### 6.2 定时任务
|
||
|
||
1. **排行榜定时刷新** - 每5分钟更新一次排行榜缓存
|
||
2. **排名计算** - 每日凌晨重新计算精确排名
|
||
|
||
---
|
||
|
||
## 7. 业务流程
|
||
|
||
### 7.1 点赞时更新排行榜
|
||
|
||
```
|
||
用户点赞藏品
|
||
↓
|
||
AssetLike 表新增记录 (记录点赞时间用于本月统计)
|
||
↓
|
||
Asset.LikeCount +1
|
||
↓
|
||
更新 Redis 热度/自制排行 ZSet
|
||
```
|
||
|
||
### 7.2 展示中藏品统计
|
||
|
||
```
|
||
定时任务扫描 Exhibition 表
|
||
↓
|
||
筛选 ExpireAt > Now() 的记录
|
||
↓
|
||
关联 Asset 表获取点赞数
|
||
↓
|
||
更新 Redis 展示中排行 ZSet
|
||
```
|
||
|
||
### 7.3 本月统计
|
||
|
||
```
|
||
用户查询本月排行时
|
||
↓
|
||
计算当月起始时间戳 (2026-03-01 00:00:00)
|
||
↓
|
||
筛选 AssetLike.CreatedAt >= 月起始时间
|
||
↓
|
||
按 AssetID 分组统计点赞数
|
||
↓
|
||
返回排行结果
|
||
```
|
||
|
||
### 7.4 我的排名计算
|
||
|
||
```
|
||
用户请求排行榜
|
||
↓
|
||
获取用户在该粉丝身份下所有藏品
|
||
↓
|
||
找出点赞数最高的藏品
|
||
↓
|
||
查询该藏品在榜单中的排名
|
||
↓
|
||
如果不在 Top 100，计算与第100名差距
|
||
↓
|
||
返回 my_ranking 信息（含 cover_url）
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 待确认问题
|
||
|
||
1. **粉丝身份隔离**: 排行榜是否需要按粉丝身份隔离？
|
||
- ✅ 已确认：按当前用户的 star_id 过滤
|
||
|
||
2. **展示中判定**: 展位被占后4小时自动下架，如何处理？
|
||
- ✅ Exhibition.ExpireAt > Now() 即为展示中
|
||
|
||
3. **本月统计**: 自然月切换时（如3月1日），是否需要清理缓存？
|
||
- 待定：建议跨月时刷新缓存
|
||
|
||
4. **Top N 默认值**: 默认显示前多少名？
|
||
- ✅ 已确认：默认 100
|
||
|
||
---
|
||
|
||
## 9. 版本历史
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| V1.0 | 2026-03-11 | 初始版本 |
|
||
| V1.1 | 2026-03-12 | 移除活动排行榜，补充我的排名、差距计算、分页规则 |
|
||
| V1.2 | 2026-03-12 | my_ranking 补充 cover_url 字段 |
|