574 lines
15 KiB
Markdown
574 lines
15 KiB
Markdown
# TopFans 产品需求文档 (PRD)
|
|
|
|
## 文档信息
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 项目名称 | TopFans |
|
|
| 版本 | V1.0 |
|
|
| 文档类型 | 产品需求文档 |
|
|
| 生成日期 | 2026-03-11 |
|
|
|
|
---
|
|
|
|
## 1. 项目概述
|
|
|
|
### 1.1 产品定位
|
|
|
|
TopFans 是一款基于 NFT 数字藏品技术的粉丝社交应用，连接明星与粉丝，提供藏品铸造、展馆展示、社交互动等核心功能。
|
|
|
|
### 1.2 目标用户
|
|
|
|
- 明星粉丝群体
|
|
- 数字藏品爱好者
|
|
- 社交娱乐用户
|
|
|
|
### 1.3 技术架构
|
|
|
|
#### 前端技术栈
|
|
| 技术 | 说明 |
|
|
|------|------|
|
|
| uni-app | 跨平台应用框架 |
|
|
| Vue 3 | 前端框架 |
|
|
| Vuex 4 | 状态管理 |
|
|
| HBuilderX | 构建工具 |
|
|
|
|
#### 后端技术栈
|
|
| 技术 | 说明 |
|
|
|------|------|
|
|
| Go 1.25.5 | 开发语言 |
|
|
| Gin | HTTP 网关 |
|
|
| Dubbo-go | 微服务框架 (Triple协议) |
|
|
| PostgreSQL | 数据库 |
|
|
| GORM | ORM框架 |
|
|
| JWT | 认证 |
|
|
| 阿里云 OSS | 对象存储 |
|
|
|
|
#### 微服务架构
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ Mobile App (uni-app) │
|
|
└─────────────────────────────────┬───────────────────────────────────────┘
|
|
│ HTTP
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ API Gateway (Gin :8080) │
|
|
│ • JWT认证 • 请求路由 • Swagger文档 │
|
|
└─────────┬──────────────────────┬───────────────────────┬───────────────┘
|
|
│ │ │
|
|
│ Dubbo RPC │ Dubbo RPC │ Dubbo RPC
|
|
▼ ▼ ▼
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ User Service │ │ Social Service │ │ Asset Service │
|
|
│ (:20000) │ │ (:20001) │ │ (:20003) │
|
|
│ │ │ │ │ │
|
|
│ • 注册/登录 │ │ • 好友管理 │ │ • 藏品铸造 │
|
|
│ • 粉丝身份 │ │ • 用户搜索 │ │ • OSS上传 │
|
|
│ • 密码管理 │ │ • 点赞功能 │ │ • 藏品查询 │
|
|
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
|
|
│ │ │
|
|
└─────────────────────┼──────────────────────┘
|
|
│ Dubbo RPC
|
|
▼
|
|
┌─────────────────────────┐
|
|
│ Gallery Service │
|
|
│ (:20004) │
|
|
│ │
|
|
│ • 展馆管理 │
|
|
│ • 展位管理 │
|
|
│ • 藏品展示 │
|
|
└─────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────┐
|
|
│ PostgreSQL │
|
|
│ + GORM │
|
|
└─────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 2. 功能模块总览
|
|
|
|
| 模块 | 核心功能 | 状态 |
|
|
|------|----------|------|
|
|
| 认证系统 | 注册、登录、Token管理 | ✅ 已实现 |
|
|
| 粉丝身份系统 | 身份选择、多身份切换 | ✅ 已实现 |
|
|
| 藏品系统 | 铸造、上传、详情、点赞 | ✅ 已实现 |
|
|
| 展馆系统 | 展位管理、藏品展示 | ✅ 已实现 |
|
|
| 社交系统 | 好友搜索、申请、删除 | ✅ 已实现 |
|
|
| 任务系统 | 任务列表、奖励领取 | 🔄 部分实现 |
|
|
| 新手引导 | 引导流程、状态管理 | 🔄 部分实现 |
|
|
|
|
---
|
|
|
|
## 3. 详细功能需求
|
|
|
|
### 3.1 认证系统 (Auth)
|
|
|
|
#### 3.1.1 用户注册
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/v1/auth/register |
|
|
| 认证 | 无需认证 |
|
|
| 请求参数 | uid(手机号), password, fan_identity_id, nickname |
|
|
| 返回 | access_token, user基础信息, 当前身份信息 |
|
|
| 说明 | 注册时必须选择一个粉丝身份(nickname唯一性?) |
|
|
|
|
#### 3.1.2 用户登录
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/v1/auth/login |
|
|
| 认证 | 无需认证 |
|
|
| 请求参数 | uid, password |
|
|
| 返回 | access_token, user基础信息 |
|
|
|
|
#### 3.1.3 获取当前用户
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/auth/me |
|
|
| 认证 | JWT Token |
|
|
| 返回 | uid, nickname, current_identity |
|
|
|
|
#### 3.1.4 修改密码
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/v1/account/password |
|
|
| 认证 | JWT Token |
|
|
| 请求参数 | old_password, new_password |
|
|
|
|
#### 3.1.5 退出登录
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/v1/auth/logout |
|
|
| 认证 | JWT Token |
|
|
|
|
#### 3.1.6 注销账号
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/user/delete-account |
|
|
| 认证 | JWT Token |
|
|
|
|
---
|
|
|
|
### 3.2 粉丝身份系统 (Fan Identity)
|
|
|
|
#### 3.2.1 获取可选粉丝身份列表
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/fan-identities |
|
|
| 认证 | 无需认证 |
|
|
| 查询参数 | keyword, page, page_size |
|
|
| 返回 | star_id, identity_id, name, tag |
|
|
|
|
#### 3.2.2 新增粉丝身份
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/v1/my/fan-identities |
|
|
| 认证 | JWT Token |
|
|
| 请求参数 | identity_id |
|
|
| 说明 | 最多绑定2个身份 |
|
|
|
|
#### 3.2.3 获取我的粉丝身份列表
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/my/fan-identities |
|
|
| 认证 | JWT Token |
|
|
|
|
#### 3.2.4 切换粉丝身份
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/v1/my/fan-identities/switch |
|
|
| 认证 | JWT Token |
|
|
| 请求参数 | new_star_id |
|
|
| 返回 | 新token, current_identity信息 |
|
|
|
|
---
|
|
|
|
### 3.3 个人信息 (Profile)
|
|
|
|
#### 3.3.1 获取个人信息
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/me/profile |
|
|
| 认证 | JWT Token |
|
|
| 返回 | uid, nickname, fan_identity, fan_level, starbook_limit, slot_limit, assets_num, crystal_balance |
|
|
|
|
#### 3.3.2 修改昵称
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | PUT /api/v1/me/nickname |
|
|
| 认证 | JWT Token |
|
|
| 请求参数 | nickname |
|
|
|
|
#### 3.3.3 更新头像
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | PUT /api/v1/me/avatar |
|
|
| 认证 | JWT Token |
|
|
| 请求参数 | avatar_url |
|
|
|
|
---
|
|
|
|
### 3.4 藏品系统 (Asset/Mint)
|
|
|
|
#### 3.4.1 获取OSS上传签名
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/assets/oss/signature |
|
|
| 认证 | JWT Token |
|
|
| 返回 | OSS上传所需的签名信息 |
|
|
|
|
#### 3.4.2 获取OSS预签名URL
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/assets/oss/presigned-url |
|
|
| 认证 | JWT Token |
|
|
| 请求参数 | object_key |
|
|
|
|
#### 3.4.3 创建铸造订单
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/v1/assets/mints |
|
|
| 认证 | JWT Token |
|
|
| 请求参数 | name, type, pic_url, material |
|
|
| 返回 | mint_id, status, asset_id |
|
|
|
|
#### 3.4.4 删除铸造订单
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | DELETE /api/v1/assets/mints/{orderId} |
|
|
| 认证 | JWT Token |
|
|
|
|
#### 3.4.5 获取我的藏品列表
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/assets/me/items |
|
|
| 认证 | JWT Token |
|
|
| 查询参数 | page, page_size |
|
|
| 返回 | asset_id, name, cover_url, like_count, mint_status, on_chain |
|
|
|
|
#### 3.4.6 获取藏品详情
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/assets/{assetId} |
|
|
| 认证 | 公开 |
|
|
| 返回 | asset_id, name, type, cover_url, owner_uid, owner_nickname, like_count, on_chain |
|
|
|
|
#### 3.4.7 点赞藏品
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/v1/social/assets/{assetId}/like |
|
|
| 认证 | JWT Token |
|
|
| 返回 | liked, like_count |
|
|
|
|
#### 3.4.8 取消点赞
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | DELETE /api/v1/social/assets/{assetId}/like |
|
|
| 认证 | JWT Token |
|
|
| 返回 | liked, like_count |
|
|
|
|
---
|
|
|
|
### 3.5 展馆系统 (Gallery)
|
|
|
|
#### 3.5.1 获取我的展馆
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/mygalleries |
|
|
| 认证 | JWT Token |
|
|
| 返回 | gallery_owner_id, slot_total, slots(含asset信息) |
|
|
|
|
#### 3.5.2 获取他人展馆
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/galleries/{targetUid} |
|
|
| 认证 | JWT Token |
|
|
| 返回 | 同上 |
|
|
| 说明 | 需校验粉丝身份一致才能访问 |
|
|
|
|
#### 3.5.3 展位展示藏品
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/v1/galleries/place |
|
|
| 认证 | JWT Token |
|
|
| 请求参数 | asset_id, gallery_owner_id, slot_id |
|
|
| 返回 | status, occupied_until, occupier_uid |
|
|
|
|
#### 3.5.4 下架展位藏品
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | DELETE /api/v1/galleries/slots/{slotId}/asset |
|
|
| 认证 | JWT Token |
|
|
|
|
---
|
|
|
|
### 3.6 社交系统 (Social)
|
|
|
|
#### 3.6.1 搜索用户
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/social/search-user |
|
|
| 认证 | JWT Token |
|
|
| 查询参数 | keyword |
|
|
| 返回 | uid, nickname, is_friend |
|
|
|
|
#### 3.6.2 获取好友列表
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/social/friends |
|
|
| 认证 | JWT Token |
|
|
| 查询参数 | page, page_size |
|
|
| 返回 | uid, nickname, fan_level |
|
|
|
|
#### 3.6.3 发送好友请求
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/v1/social/friend-requests |
|
|
| 认证 | JWT Token |
|
|
| 请求参数 | target_uid |
|
|
|
|
#### 3.6.4 获取已发送好友请求
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/social/friend-requests |
|
|
| 认证 | JWT Token |
|
|
| 查询参数 | type=sent |
|
|
|
|
#### 3.6.5 获取收到的好友请求
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/social/friend-requests |
|
|
| 认证 | JWT Token |
|
|
| 查询参数 | type=received |
|
|
|
|
#### 3.6.6 处理好友请求
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/v1/social/friend-requests/handle |
|
|
| 认证 | JWT Token |
|
|
| 请求参数 | request_id, action(accept/reject) |
|
|
|
|
#### 3.6.7 删除好友
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | DELETE /api/v1/social/friends |
|
|
| 认证 | JWT Token |
|
|
| 请求参数 | friend_uid |
|
|
|
|
---
|
|
|
|
### 3.7 任务系统 (Task)
|
|
|
|
#### 3.7.1 获取任务列表
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | GET /api/v1/tasks |
|
|
| 认证 | JWT Token |
|
|
| 返回 | task_id, title, status, reward |
|
|
|
|
#### 3.7.2 领取任务奖励
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 接口 | POST /api/v1/tasks/claim |
|
|
| 认证 | JWT Token |
|
|
| 请求参数 | task_id |
|
|
|
|
---
|
|
|
|
## 4. 数据库模型
|
|
|
|
### 4.1 核心数据表
|
|
|
|
| 表名 | 说明 |
|
|
|------|------|
|
|
| users | 用户表 |
|
|
| stars | 明星信息表 |
|
|
| fan_profiles | 粉丝档案表(用户-明星关联) |
|
|
| assets | 资产/藏品表 |
|
|
| mint_orders | 铸造订单表 |
|
|
| asset_likes | 点赞记录表 |
|
|
| friendships | 好友关系表 |
|
|
| friend_requests | 好友请求表 |
|
|
| booth_slots | 展位表 |
|
|
| exhibitions | 展品展示表 |
|
|
|
|
---
|
|
|
|
## 5. 用户界面结构
|
|
|
|
### 5.1 页面路由
|
|
|
|
| 路由 | 页面 | 说明 |
|
|
|------|------|------|
|
|
| /pages/login/login | 登录页 | 用户登录 |
|
|
| /pages/register/register | 注册页 | 用户注册 |
|
|
| /pages/profile/setNickname | 设置昵称 | 注册时设置昵称 |
|
|
| /pages/profile/selectRole | 选择角色 | 选择粉丝身份 |
|
|
| /pages/profile/profile | 个人中心 | 用户资料管理 |
|
|
| /pages/square/square | 广场首页 | 主页面 |
|
|
| /pages/exhibition/exhibition | 展馆页 | 展馆/展位管理 |
|
|
| /pages/castlove/success | 铸造成功 | 铸造成功展示 |
|
|
|
|
### 5.2 主要组件
|
|
|
|
| 组件 | 说明 |
|
|
|------|------|
|
|
| SquareContent | 广场主内容区(切换广场/好友/星册/铸爱/装扮) |
|
|
| FriendsContent | 好友列表与社交功能 |
|
|
| StarbookContent | 我的藏品/星册 |
|
|
| CastloveContent | 铸造功能 |
|
|
| DressupContent | 装扮功能 |
|
|
| NftCard | 藏品卡片 |
|
|
| NftDetailModal | 藏品详情弹窗 |
|
|
| Avatar | 头像组件 |
|
|
| Header | 顶部导航栏 |
|
|
| BottomNav | 底部导航栏 |
|
|
| TaskModal | 任务弹窗 |
|
|
|
|
---
|
|
|
|
## 6. 业务规则
|
|
|
|
### 6.1 粉丝身份隔离
|
|
|
|
- 每个用户可绑定最多2个粉丝身份
|
|
- 切换身份后，藏品、展馆、好友等数据按身份隔离
|
|
- Token中包含user_id和star_id
|
|
|
|
### 6.2 展馆规则
|
|
|
|
- 初始展位: 3个
|
|
- 可解锁/购买更多展位
|
|
- 可展示藏品到他人展馆空位
|
|
- 抢展位: 4小时后自动下架
|
|
|
|
### 6.3 好友规则
|
|
|
|
- 需双向确认才能成为好友
|
|
- 默认上限: 50个
|
|
- 可随等级解锁更多
|
|
|
|
### 6.4 铸造规则
|
|
|
|
- 支持平台素材或用户上传
|
|
- 需审核和AI生成封面
|
|
- 铸造后生成链上确权
|
|
|
|
---
|
|
|
|
## 7. 安全要求
|
|
|
|
### 7.1 认证
|
|
|
|
- JWT Token认证
|
|
- Token有效期: 7天
|
|
- 从Header提取: Authorization: Bearer \<token\>
|
|
|
|
### 7.2 响应格式
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "ok",
|
|
"data": {}
|
|
}
|
|
```
|
|
|
|
### 7.3 分页格式
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "ok",
|
|
"data": {
|
|
"items": [],
|
|
"page": 1,
|
|
"page_size": 20,
|
|
"total": 100
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 外部依赖
|
|
|
|
| 服务 | 说明 |
|
|
|------|------|
|
|
| 阿里云OSS | 藏品图片存储 |
|
|
| PostgreSQL | 数据持久化 |
|
|
| (区块链) | 数字藏品上链(待实现) |
|
|
|
|
---
|
|
|
|
## 9. 待实现功能
|
|
|
|
根据代码分析，以下功能标记为待实现或部分实现:
|
|
|
|
1. **广场推荐** - 广场小屋列表、TOP藏品展板
|
|
2. **任务系统** - 完整任务列表和奖励领取
|
|
3. **新手引导** - 引导流程和状态管理
|
|
4. **踢走占位** - 被占位者踢走占领者
|
|
5. **解锁展位** - 等级解锁或货币购买
|
|
6. **系统推荐好友** - 推荐好友列表
|
|
|
|
---
|
|
|
|
## 10. 附录
|
|
|
|
### 10.1 错误码定义
|
|
|
|
| 错误码 | 说明 |
|
|
|--------|------|
|
|
| 200 | 成功 |
|
|
| 401 | Token失效/未认证 |
|
|
| 400 | 请求参数错误 |
|
|
| 500 | 服务器内部错误 |
|
|
|
|
### 10.2 版本历史
|
|
|
|
| 版本 | 日期 | 说明 |
|
|
|------|------|------|
|
|
| V1.0 | 2026-03-11 | 初始版本(基于代码分析) |
|
|
|
|
---
|
|
|
|
*本文档基于代码分析自动生成，如需更新请参考实际实现。*
|