# 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 | 初始版本(基于代码分析) |

---

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