317 lines
9.3 KiB
Markdown
317 lines
9.3 KiB
Markdown
# 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 文档已修复，可以正常使用。
|