xiaoyu/topfans
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
confirmmodal
topfans/backend/PROJECT_SUMMARY.md
zerosaturation 06f4038a75 提交后端代码
2026-04-07 22:29:48 +08:00

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

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 设计：

{
  "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 访问方式

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 是一个设计良好的微服务架构项目，具有以下特点：

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

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