2026-04-07 22:28:50 +08:00

15 KiB

Raw Blame History

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.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 响应格式

{
  "code": 200,
  "message": "ok",
  "data": {}
}

7.3 分页格式

{
  "code": 200,
  "message": "ok",
  "data": {
    "items": [],
    "page": 1,
    "page_size": 20,
    "total": 100
  }
}

8. 外部依赖

服务	说明
阿里云OSS	藏品图片存储
PostgreSQL	数据持久化
(区块链)	数字藏品上链(待实现)

9. 待实现功能

根据代码分析，以下功能标记为待实现或部分实现:

广场推荐 - 广场小屋列表、TOP藏品展板
任务系统 - 完整任务列表和奖励领取
新手引导 - 引导流程和状态管理
踢走占位 - 被占位者踢走占领者
解锁展位 - 等级解锁或货币购买
系统推荐好友 - 推荐好友列表

10. 附录

10.1 错误码定义

错误码	说明
200	成功
401	Token失效/未认证
400	请求参数错误
500	服务器内部错误

10.2 版本历史

版本	日期	说明
V1.0	2026-03-11	初始版本(基于代码分析)

本文档基于代码分析自动生成，如需更新请参考实际实现。

15 KiB Raw Blame History

TopFans 产品需求文档 (PRD)

文档信息

1. 项目概述

1.1 产品定位

1.2 目标用户

1.3 技术架构

前端技术栈

后端技术栈

微服务架构

2. 功能模块总览

3. 详细功能需求

3.1 认证系统 (Auth)

3.1.1 用户注册

3.1.2 用户登录

3.1.3 获取当前用户

3.1.4 修改密码

3.1.5 退出登录

3.1.6 注销账号

3.2 粉丝身份系统 (Fan Identity)

3.2.1 获取可选粉丝身份列表

3.2.2 新增粉丝身份

3.2.3 获取我的粉丝身份列表

3.2.4 切换粉丝身份

3.3 个人信息 (Profile)

3.3.1 获取个人信息

3.3.2 修改昵称

3.3.3 更新头像

3.4 藏品系统 (Asset/Mint)

3.4.1 获取OSS上传签名

3.4.2 获取OSS预签名URL

3.4.3 创建铸造订单

3.4.4 删除铸造订单

3.4.5 获取我的藏品列表

3.4.6 获取藏品详情

3.4.7 点赞藏品

3.4.8 取消点赞

3.5 展馆系统 (Gallery)

3.5.1 获取我的展馆

3.5.2 获取他人展馆

3.5.3 展位展示藏品

3.5.4 下架展位藏品

3.6 社交系统 (Social)

3.6.1 搜索用户

3.6.2 获取好友列表

3.6.3 发送好友请求

3.6.4 获取已发送好友请求

3.6.5 获取收到的好友请求

3.6.6 处理好友请求

3.6.7 删除好友

3.7 任务系统 (Task)

3.7.1 获取任务列表

3.7.2 领取任务奖励

4. 数据库模型

4.1 核心数据表

5. 用户界面结构

5.1 页面路由

5.2 主要组件

6. 业务规则

6.1 粉丝身份隔离

6.2 展馆规则

6.3 好友规则

6.4 铸造规则

7. 安全要求

7.1 认证

7.2 响应格式

7.3 分页格式

8. 外部依赖

9. 待实现功能

10. 附录

10.1 错误码定义

10.2 版本历史

15 KiB

Raw Blame History