xiaoyu/topfans

Fork 0

zerosaturation 06f4038a75 提交后端代码

2026-04-07 22:29:48 +08:00

9.3 KiB

Raw Blame History

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）管理
- 粉丝身份列表和切换
- 密码管理

职责：好友关系管理、用户搜索、点赞功能
端口：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 设计：

{
  "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 生成命令

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 快速启动

cd backend
./start-all.sh

9.2 生成 Swagger 文档

cd backend
bash gen-swagger.sh

9.3 查看日志

tail -f logs/gateway.log
tail -f logs/*.log

十、待实现功能

10.1 任务系统

任务定义管理
任务进度跟踪
任务奖励发放

10.2 推荐系统

广场推荐小屋列表
TOP 藏品展板
推荐算法

10.3 区块链集成

真实上链功能
交易状态查询
链上数据同步

十一、总结

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

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

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

9.3 KiB Raw Blame History Unescape Escape