# TopFans 项目总结文档

## 一、项目概述

**TopFans** 是一个基于微服务架构的粉丝社交平台，支持多明星身份、数字藏品（NFT）铸造、展馆展示、好友社交等功能。

### 核心特性
- 🎭 **多身份系统**：用户可以为不同明星创建粉丝身份，每个身份独立
- 🎨 **数字藏品**：支持铸造、展示、点赞数字藏品
- 🏛️ **展馆系统**：用户可以创建展馆展示藏品，支持展位管理
- 👥 **社交功能**：好友系统、点赞、随机推荐等
- 🔐 **JWT 认证**：基于 JWT 的认证系统，Token 中包含用户ID和明星ID

---

## 二、技术架构

### 2.1 架构模式
- **微服务架构**：采用领域驱动设计（DDD）拆分服务
- **API Gateway 模式**：Gateway 层作为统一入口，提供 REST API
- **服务间通信**：使用 Dubbo-go（Triple 协议，基于 gRPC）
- **数据存储**：PostgreSQL（主数据库）+ MinIO/S3（对象存储）

### 2.2 服务列表

#### 1. Gateway Service（API 网关）
- **职责**：统一入口、协议转换（REST → gRPC）、认证授权、请求路由
- **技术栈**：Gin + Swagger
- **端口**：8080
- **功能**：
  - REST API 接口
  - JWT Token 验证
  - Swagger 文档生成

#### 2. User Service（用户服务）
- **职责**：用户注册登录、JWT 生成、粉丝档案管理、身份切换
- **端口**：tri://127.0.0.1:20000
- **核心功能**：
  - 用户注册/登录
  - JWT Token 生成和验证
  - 粉丝档案（FanProfile）管理
  - 粉丝身份列表和切换
  - 密码管理

#### 3. Social Service（社交服务）
- **职责**：好友关系管理、用户搜索、点赞功能
- **端口**：tri://127.0.0.1:20001
- **核心功能**：
  - 好友申请/同意/拒绝/删除
  - 用户搜索（按 UID）
  - 随机用户推荐
  - 资产点赞

#### 4. Asset Service（资产服务）
- **职责**：数字藏品铸造、资产查询、素材管理
- **端口**：tri://127.0.0.1:20003
- **核心功能**：
  - 创建铸造订单
  - 资产查询和列表
  - 资产详情
  - OSS 上传签名生成
  - 上链状态查询

#### 5. Gallery Service（展馆服务）
- **职责**：展馆管理、展位管理、展品展示
- **端口**：tri://127.0.0.1:20004
- **核心功能**：
  - 我的展馆/他人展馆查询
  - 展位放置/移除藏品
  - 展位解锁/购买
  - 展位规则管理

---

## 三、核心业务逻辑

### 3.1 粉丝身份隔离机制

**设计原理**：
- 每个用户（user_id）可以为多个明星创建粉丝身份
- 每个粉丝身份（user_id + star_id）拥有独立的数据空间
- 所有业务数据都基于 `user_id + star_id` 进行隔离

**JWT Token 设计**：
```json
{
  "user_id": 10000001,
  "star_id": 123,
  "updated_at": 1704067200000,
  "iat": 1704067200,
  "exp": 1704672000
}
```

**数据库设计**：
- `users` 表：用户账号（user_id, mobile, password_hash）
- `fan_profiles` 表：粉丝档案（user_id, star_id, nickname, level, crystal_balance）- 联合主键
- 所有业务表都包含 `star_id` 作为隔离键

### 3.2 数字藏品铸造流程

```
1. 用户上传图片 → 获取 OSS 上传签名
2. 创建铸造订单 → 扣除水晶余额
3. 创建资产记录（链下）
4. 异步上链（模拟）
5. 更新资产状态
6. 更新用户资产数量
```

**关键点**：
- 铸造需要消耗水晶（CrystalBalance）
- 上链为异步机制（当前为模拟）
- 上链失败会进行退款

### 3.3 展馆系统

**展位规则**：
- 初始展位数：3 个
- 抢展位时长：4 小时（自动下架）
- 解锁条件：等级或水晶购买
- 规则存储在 PostgreSQL，启动时加载到内存

**展位状态**：
- `EMPTY`：空展位
- `OCCUPIED`：被占用
- `LOCKED`：未解锁

### 3.4 好友系统

**设计特点**：
- 基于粉丝身份隔离（同一明星身份下的好友）
- 双向关系（A 添加 B，B 自动成为 A 的好友）
- 请求-确认机制（发送请求 → 接受/拒绝）

**数据库表**：
- `friend_relations`：好友关系表
- `friend_requests`：好友申请表

---

## 四、API 设计

### 4.1 认证相关
- `POST /api/v1/auth/register` - 注册
- `POST /api/v1/auth/login` - 登录
- `GET /api/v1/auth/me` - 获取当前用户信息
- `POST /api/v1/auth/logout` - 登出
- `POST /api/v1/auth/refresh` - 刷新 Token

### 4.2 用户相关
- `GET /api/v1/users/:user_id` - 获取用户信息
- `GET /api/v1/fan-identities` - 获取可选粉丝身份列表
- `GET /api/v1/my/fan-identities` - 获取我的粉丝身份列表
- `POST /api/v1/my/fan-identities` - 添加粉丝身份
- `POST /api/v1/my/fan-identities/switch` - 切换粉丝身份

### 4.3 资产相关
- `GET /api/v1/assets/oss/signature` - 获取 OSS 上传签名
- `POST /api/v1/assets/upload` - 上传图片
- `POST /api/v1/assets/mints` - 创建铸造订单
- `GET /api/v1/assets/me/items` - 获取我的藏品列表
- `GET /api/v1/assets/:asset_id` - 获取资产详情

### 4.4 展馆相关
- `GET /api/v1/galleries/me` - 获取我的展馆
- `GET /api/v1/galleries/:target_uid` - 获取他人展馆
- `POST /api/v1/galleries/place` - 放置藏品
- `DELETE /api/v1/galleries/slots/:slot_id/asset` - 移除藏品
- `POST /api/v1/galleries/slots_unlock` - 解锁展位

### 4.5 社交相关
- `GET /api/v1/social/search-user` - 搜索用户
- `GET /api/v1/social/random-users` - 获取随机用户
- `POST /api/v1/social/friend-requests` - 发送好友请求
- `POST /api/v1/social/friend-requests/handle` - 处理好友请求
- `GET /api/v1/social/friends` - 获取好友列表
- `POST /api/v1/social/assets/:asset_id/like` - 点赞资产

---

## 五、数据存储

### 5.1 PostgreSQL（主数据库）
- 用户数据（users, fan_profiles）
- 资产数据（assets, mint_orders）
- 社交关系（friend_relations, friend_requests, asset_likes）
- 展馆数据（booth_slots, exhibitions）
- 规则表（task_definitions, gallery_rules）

### 5.2 MinIO/S3（对象存储）
- 图片资源（藏品封面、用户头像、素材）

### 5.3 区块链（链上存储）
- 资产确权（Token ID、交易哈希）

---

## 六、Swagger 文档

### 6.1 已修复的问题
- ✅ 修复了 Swagger UI 配置，使用 `ginSwagger.WrapHandler` 替代 `CustomWrapHandler`
- ✅ Swagger 文档已生成（`gateway/docs/` 目录）

### 6.2 访问方式
- **Swagger UI**：http://localhost:8080/swagger/index.html
- **Swagger JSON**：http://localhost:8080/swagger/doc.json

### 6.3 生成命令
```bash
cd backend
bash gen-swagger.sh
```

---

## 七、项目结构

```
TopFans/
├── backend/                    # 后端服务
│   ├── gateway/               # API 网关
│   │   ├── controller/       # 控制器层
│   │   ├── dto/              # 数据传输对象
│   │   ├── middleware/       # 中间件
│   │   ├── router/           # 路由配置
│   │   └── docs/             # Swagger 文档
│   ├── services/             # 微服务
│   │   ├── userService/      # 用户服务
│   │   ├── socialService/    # 社交服务
│   │   ├── assetService/     # 资产服务
│   │   └── galleryService/   # 展馆服务
│   ├── pkg/                  # 公共包
│   │   ├── database/         # 数据库连接
│   │   ├── logger/          # 日志
│   │   ├── jwt/             # JWT 工具
│   │   └── models/          # 数据模型
│   ├── proto/               # Proto 定义
│   └── docs/                # 项目文档
└── frontend/                 # 前端（Vue/uni-app）
```

---

## 八、关键设计决策

### 8.1 粉丝身份隔离
- **原因**：用户可以为多个明星创建身份，每个身份独立
- **实现**：所有业务表都包含 `star_id`，查询时使用 `user_id + star_id` 联合查询

### 8.2 JWT Token 设计
- **原因**：简化前端使用，Token 中包含所有必要信息
- **实现**：Token 中包含 `user_id` 和 `star_id`，前端可直接解析

### 8.3 规则管理
- **原因**：规则需要灵活配置，但查询频繁
- **实现**：规则存储在 PostgreSQL，服务启动时加载到内存

### 8.4 服务间通信
- **原因**：微服务需要高效通信
- **实现**：使用 Dubbo-go（Triple 协议，基于 gRPC）

---

## 九、开发指南

### 9.1 快速启动
```bash
cd backend
./start-all.sh
```

### 9.2 生成 Swagger 文档
```bash
cd backend
bash gen-swagger.sh
```

### 9.3 查看日志
```bash
tail -f logs/gateway.log
tail -f logs/*.log
```

---

## 十、待实现功能

### 10.1 任务系统
- 任务定义管理
- 任务进度跟踪
- 任务奖励发放

### 10.2 推荐系统
- 广场推荐小屋列表
- TOP 藏品展板
- 推荐算法

### 10.3 区块链集成
- 真实上链功能
- 交易状态查询
- 链上数据同步

---

## 十一、总结

TopFans 是一个设计良好的微服务架构项目，具有以下特点：

1. **清晰的职责划分**：每个服务职责明确，边界清晰
2. **灵活的身份系统**：支持多明星身份，数据隔离完善
3. **完整的业务功能**：涵盖用户、资产、展馆、社交等核心功能
4. **规范的 API 设计**：统一的响应格式，完整的 Swagger 文档
5. **良好的扩展性**：支持水平扩展，规则可配置

项目已经实现了核心功能，Swagger 文档已修复，可以正常使用。