topfans/docs/superpowers/specs/2026-04-16-system-architecture-design.md

TopFans 系统架构规范

创建日期： 2026-04-16 更新日期： 2026-04-16 项目： TopFans 粉丝社交平台 状态： 已评审通过 说明： 本文档为 TopFans 平台级系统架构总览，各子系统的详细设计在对应规范文档中，本文档仅做索引与概要。

---

一、项目概述

TopFans 是一个基于微服务架构的粉丝社交平台，支持多明星身份、数字藏品（NFT）铸造与展示、展馆管理、好友社交、AI 图生图、任务系统、经济系统等功能。

1.1 技术栈

层级	技术	说明
前端	uni-app + Vue 3 + Vuex 4	跨平台移动应用
后端	Go 1.25 + Gin + Dubbo-go	API Gateway + 微服务，Dubbo RPC 采用 Triple 协议（兼容 HTTP/gRPC）
数据库	PostgreSQL + GORM	共享数据库，各微服务按表隔离或共享
对象存储	阿里云 OSS / MinIO	藏品图片、用户头像、素材存储
服务通信	gRPC (Dubbo-go Triple)	微服务间 RPC 调用
认证	JWT	Token 包含 user_id 和 star_id
AI	MiniMax 图生图 API	AI 生成藏品图片

1.2 核心设计原则

1. 粉丝身份隔离：所有业务数据按 user_id + star_id 联合隔离，用户可为不同明星创建独立身份
2. 服务单一职责：每个微服务职责单一，通过 Dubbo RPC 协作
3. 经济数据一致性：经济类操作（水晶/经验）采用 SELECT FOR UPDATE 悲观锁，保证余额一致性
4. OSS URL 直回：后端直接返回 OSS 公共 URL，前端直接访问 OSS 资源查看封面
5. 定时任务全局协调：使用 PostgreSQL Advisory Lock 保证每日重置等定时任务在多实例下只执行一次

---

二、系统架构图

┌─────────────────────────────────────────────────────────────────────────┐
│                          Mobile App (uni-app)                           │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐             │
│  │  广场   │ │  星册   │ │  铸爱   │ │  星城   │ │  好友   │             │
│  │ Square  │ │Starbook │ │Castlove │ │Starcity │ │Friends  │             │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐                         │
│  │  任务   │ │  发现   │ │ 应援活动│ │ 个人中心│                         │
│  │  Tasks  │ │Discover │ │Support  │ │Profile  │                         │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘                         │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │ HTTP :8080
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       API Gateway (Gin) :8080                            │
│  • JWT 认证 • 请求路由 • 协议转换 REST→gRPC • Swagger 文档               │
└─────────┬───────────┬───────────┬───────────┬───────────┬─────────────┘
          │            │           │           │           │
          │ Dubbo RPC  │ Dubbo RPC │ Dubbo RPC │ Dubbo RPC │ Dubbo RPC
          │ (Triple)   │ (Triple)  │ (Triple)  │ (Triple)  │ (Triple)
          ▼            ▼           ▼           ▼           ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ User Service│ │Social Svc   │ │ Asset Svc   │ │Gallery Svc  │ │ Task Service│
│   :20000    │ │   :20001    │ │   :20003    │ │   :20004    │ │   :20005    │
│             │ │             │ │             │ │             │ │             │
│• 注册/登录  │ │• 好友管理   │ │• 藏品铸造   │ │• 展馆管理   │ │• 每日任务   │
│• 粉丝身份   │ │• 用户搜索   │ │• OSS上传    │ │• 展位管理   │ │• 引导任务   │
│• 档案/经济  │ │• 点赞功能   │ │• 图生图    │ │• 藏品展示   │ │• 展示收益   │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
                                                                      │
          ┌────────────────────────────────────────────────────────────┘
          │ Dubbo RPC (Triple)
          ▼
┌─────────────────────┐
│  activity-admin     │
│  (Python FastAPI)   │
│   :8090             │
│                     │
│• 任务定义管理       │
│• 每日/引导任务进度  │
│• 任务统计           │
│• 手动重置           │
└─────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         PostgreSQL + GORM                                │
│                                                                         │
│  用户/认证: users, stars, fan_profiles                                  │
│  藏品体系: assets, collection_assets, activity_assets, asset_registry    │
│  展馆: exhibitions, booth_slots                                         │
│  社交: friendships, friend_requests, asset_likes                         │
│  任务: task_definitions, user_daily_task_progress,                       │
│        user_onboarding_progress, user_onboarding_status,                │
│        onboarding_stage_config, exhibition_revenue_records,               │
│        task_reset_log                                                  │
│  经济: crystal_transaction_records, coin_transaction_records (预留),     │
│        exp_transaction_records, level_change_records,                    │
│        level_thresholds, mint_reward_config,                            │
│        mint_milestone_config, user_mint_count                           │
└─────────────────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         阿里云 OSS / MinIO S3                            │
│                   藏品图片 · 用户头像 · AI生成素材                        │
└─────────────────────────────────────────────────────────────────────────┘

2.1 服务间调用关系

Gateway ──RPC──▶ UserService
          ──RPC──▶ SocialService
          ──RPC──▶ AssetService
          ──RPC──▶ GalleryService
          ──RPC──▶ TaskService

TaskService ──RPC──▶ UserService (UpdateCrystalBalance, AddExperience)
GalleryService ──RPC──▶ TaskService (OnExhibitionCompleted)
AssetService ──RPC──▶ UserService (UpdateCrystalBalance)

activity-admin ──直连──▶ PostgreSQL (管理任务定义/统计)

---

三、服务清单与职责

3.1 后端微服务

服务	端口	语言	职责	规范文档
Gateway	:8080	Go	API 统一入口、认证、路由、协议转换	本文档
User Service	:20000	Go	用户注册登录、粉丝身份、JWT、水晶/经验/等级管理	本文档
Social Service	:20001	Go	好友关系、用户搜索、点赞	本文档
Asset Service	:20003	Go	藏品铸造、OSS 上传、图生图、铸造奖励	2026-04-13-collection-asset-starbook-refactor.md 2026-04-07-minimax-image-generation-design.md 2026-04-15-economic-system-design.md
Gallery Service	:20004	Go	展馆管理、展位管理、藏品展示、收益计算	本文档
Task Service	:20005	Go	每日任务、引导任务、展示收益、定时重置	2026-04-08-task-management-system-design.md
Activity Service	:20006	Go	运营活动（待完善）	本文档
activity-admin	:8090	Python	任务定义管理、统计、手动重置	2026-04-08-task-management-system-design.md

3.2 服务目录结构

backend/
├── gateway/                 # API 网关
│   ├── controller/         # 控制器层
│   ├── dto/                # 数据传输对象
│   ├── middleware/         # 中间件 (JWT)
│   ├── router/             # 路由配置
│   ├── config/             # 配置
│   ├── docs/               # Swagger 文档
│   └── main.go
├── services/               # 微服务
│   ├── userService/        # 用户服务
│   │   ├── config/
│   │   ├── repository/     # 数据层
│   │   ├── service/       # 业务层
│   │   ├── provider/      # Dubbo Provider
│   │   └── main.go
│   ├── socialService/      # 社交服务
│   ├── assetService/       # 资产服务
│   ├── galleryService/     # 展馆服务
│   ├── taskService/        # 任务服务
│   └── activityService/    # 活动服务
├── pkg/                    # 公共包
│   ├── database/           # 数据库连接
│   ├── logger/            # 日志 (Uber Zap)
│   └── jwt/               # JWT 工具
└── proto/                  # Proto 定义文件

---

四、数据库模型

4.1 核心数据表

表名	所属服务	说明
users	User Service	用户账号表
stars	User Service	明星信息表
fan_profiles	User Service	粉丝档案表 (user_id + star_id 联合主键)，含水晶余额、经验、等级
assets	Asset Service	原创藏品（铸爱流程）
collection_assets	Asset Service	典藏藏品（按 category 子分类）
activity_assets	Asset Service	活动藏品（按 activity_type 分组）
asset_registry	Asset Service	藏品统一索引表（跨类型统一查询）
mint_orders	Asset Service	铸造订单表
asset_likes	Social Service	藏品点赞表
friendships	Social Service	好友关系表
friend_requests	Social Service	好友申请表
exhibitions	Gallery Service	展品展示表
booth_slots	Gallery Service	展位表
task_definitions	Task Service	任务定义表
user_daily_task_progress	Task Service	每日任务进度表
user_onboarding_progress	Task Service	引导任务进度表
user_onboarding_status	Task Service	引导流程状态表
onboarding_stage_config	Task Service	引导阶段配置表
exhibition_revenue_records	Task Service	展示收益记录表
task_reset_log	Task Service	重置日志表
crystal_transaction_records	User Service	水晶交易流水表（复式记账）
coin_transaction_records	User Service	游戏币交易流水表（预留）
exp_transaction_records	User Service	经验变化记录表
level_change_records	User Service	等级变化记录表
level_thresholds	User Service	等级阈值配置表（10级满级）
mint_reward_config	Asset Service	铸造奖励配置表
mint_milestone_config	Asset Service	铸造阶梯奖励配置表
user_mint_count	Asset Service	用户铸造累计表

详细表结构及索引设计见各子系统规范文档：

• 经济系统表结构：2026-04-15-economic-system-design.md § 三
• 任务系统表结构：2026-04-08-task-management-system-design.md § 三
• 藏品/星册表结构：2026-04-13-collection-asset-starbook-refactor.md § 二

4.2 粉丝身份隔离机制

所有业务表均包含 star_id 字段，基于 user_id + star_id 联合主键进行数据隔离。用户可为不同明星创建独立身份，各身份下的藏品、好友、展馆、经济数据等互不影响。

---

五、API 架构

5.1 统一响应格式

{
  "code": 200,
  "message": "ok",
  "data": {}
}

5.2 分页响应格式

{
  "code": 200,
  "message": "ok",
  "data": {
    "items": [],
    "page": 1,
    "page_size": 20,
    "total": 100,
    "has_more": false
  }
}

所有列表查询统一使用 page + page_size 分页参数。

5.3 认证方式

• Header: Authorization: Bearer <JWT Token>
• Token 中包含 user_id 和 star_id
• star_id 从认证上下文获取，不在请求参数中显式传递

5.4 Swagger 文档

• 地址: http://localhost:8080/swagger/index.html
• JSON: http://localhost:8080/swagger/doc.json

5.5 Proto 定义文件位置

所有 Dubbo RPC 接口定义在 backend/proto/ 目录下，生成的 Go 代码在 backend/pkg/proto/ 下各服务目录中。

---

六、子系统规范索引

以下各子系统详细设计见对应的规范文档，本文档仅做概要说明与链接。

---

6.1 认证系统 (Auth)

概要： 手机号+密码注册/登录，返回 JWT Token。

功能	说明
注册	手机号+密码注册，需选择粉丝身份
登录	手机号+密码登录，返回JWT Token
登出	使Token失效
刷新Token	刷新认证Token

规范文档： 本文档现有内容

---

6.2 粉丝身份系统 (Fan Identity)

概要： 用户最多绑定 2 个粉丝身份，切换后 Token 自动携带新的 star_id，所有业务数据按身份隔离。

功能	说明
身份列表	获取可选明星身份列表
添加身份	为用户添加粉丝身份（最多2个）
切换身份	切换当前使用的粉丝身份
数据隔离	所有业务数据按 user_id + star_id 隔离

规范文档： 本文档现有内容

---

6.3 藏品/星册体系 (Asset & Starbook)

概要： 原创藏品、典藏藏品、活动藏品三轨并行。星册按类型 + 子分类/等级分组展示，后端直接返回 OSS 公共 URL。

设计要点：

• 三种类型通过 asset_registry 统一索引
• regular（原创）：按 grade 分组（grade 1/2/3...，大的在上）
• collection（典藏）：按 category 子分类分组
• activity（活动）：按 activity_type 分组
• 后端直接返回 OSS URL，前端直接访问（无需 OSS 预签名接口）
• 每组最多返回 6 条，首页一次请求返回全量数据

API：

• GET /api/v1/starbook/home — 星册首页（按 type → category/grade 分组）
• GET /api/v1/starbook/items — 藏品列表（分页）

规范文档： 2026-04-13-collection-asset-starbook-refactor.md

---

6.4 AI 图生图系统 (MiniMax)

概要： 前端传递参数 → 后端异步调用 MiniMax 图生图 API → 前端轮询任务状态 → 返回结果。

设计要点：

• 任务存储在内存 Map 中，Job ID 为 UUID
• 前端 3 秒轮询一次，超时 120 秒
• 图片压缩至最大边 1024px，格式统一为 JPEG(85%)
• subject_reference[].image_file 需 SSRF 校验（不允许私有IP/内网）

API：

• POST /api/v1/assets/mints/image/generation — 创建图生图任务（返回 202）
• GET /api/v1/assets/mints/image/generation/:job_id — 查询任务状态（轮询）

规范文档： 2026-04-07-minimax-image-generation-design.md

---

6.5 任务系统 (Task)

概要： 每日任务、引导任务、展示收益三大模块，使用 PostgreSQL Advisory Lock 保证每日 05:00 重置全局只执行一次。

设计要点：

• 每日任务：每天 05:00 Asia/Shanghai 自动重置，用户手动领取奖励
• 引导任务：每用户仅可完成一次，不重置，阶段切换需检查前置任务是否完成
• 展示收益：galleryService 展品到期后创建收益记录，每日 05:00 自动发放或用户手动领取
• 重置锁 key：pg_advisory_lock(YYYYMMDD)
• 奖励发放：统一调用 UserService 的 UpdateCrystalBalance + AddExperience，经济系统保证一致性

API：

• 每日任务：GET /api/tasks/daily、POST /api/tasks/report-event、POST /api/tasks/daily/claim、POST /api/tasks/daily/claim-all
• 引导任务：POST /api/tasks/guide/complete、GET /api/tasks/onboarding/status、POST /api/tasks/onboarding/advance-stage、POST /api/tasks/onboarding/claim-reward
• 展示收益：GET /api/tasks/exhibition-revenue、POST /api/tasks/exhibition-revenue/claim、POST /api/tasks/exhibition-revenue/claim-all

规范文档： 2026-04-08-task-management-system-design.md

---

6.6 经济系统 (Economy)

概要： 水晶（主要货币）、经验/等级、游戏币（预留）三大经济体系，采用复式记账（balance_before + delta = balance_after）保证审计一致性。

设计要点：

• 水晶：所有收入/消耗均记流水，支持 task_reward / mint_cost / mint_reward / exhibition_revenue / level_up_bonus / manual_adjust
• 经验/等级：10 级满级，阈值存 level_thresholds 表（带缓存 TTL 5分钟），升级时记 level_change_records
• 铸造奖励：每次铸造返水晶 + 阶梯额外奖励，按 star_id 独立累计
• 并发控制：SELECT FOR UPDATE 悲观锁，保证同一用户对同一偶像的余额操作串行
• 升级水晶奖励由调用方主动查询阈值后发放，AddExperience 本身不自动发放

API（UserService 提供）：

• UpdateCrystalBalance — 水晶增减（含流水写入）
• AddExperience — 经验增减（含等级计算，返回 newLevel + levelDelta）

规范文档： 2026-04-15-economic-system-design.md

---

6.7 展馆系统 (Gallery)

概要： 用户展馆展位管理，藏品上架展示，被好友参观可获得展示收益。

功能	说明
我的展馆	查看我的展馆和展位状态
他人展馆	查看好友展馆
放置藏品	将藏品放置到展位展示
下架藏品	从展位移除藏品（触发收益结算）
展位解锁	消耗水晶或等级解锁新展位

规范文档： 本文档现有内容

---

6.8 社交系统 (Social)

概要： 好友关系需双向确认，藏品可被点赞。

功能	说明
搜索用户	按UID或昵称搜索用户
随机推荐	获取随机用户推荐列表
发送好友请求	向目标用户发送好友申请
处理好友请求	接受/拒绝好友请求
好友列表	查看我的好友
删除好友	解除好友关系
点赞/取消点赞	对藏品进行点赞

规范文档： 本文档现有内容

---

6.9 运营活动系统 (Activity)

概要： 应援活动（巴士应援、星演会、生日会等），支持线上/线下活动参与，应援道具使用。

规范文档： 本文档现有内容（Activity Service 待完善）

---

七、业务规则汇总

7.1 粉丝身份规则

• 每个用户最多绑定 2 个粉丝身份
• 切换身份后 Token 自动携带新的 star_id
• 藏品、好友、展馆、经济数据等均按 user_id + star_id 隔离

7.2 展馆规则

• 初始展位数: 3 个
• 展位被占用后 4 小时自动下架
• 可通过等级或水晶解锁更多展位
• 展品下架时触发展示收益记录

7.3 好友规则

• 需双向确认才能成为好友
• 好友上限: 50 个（可随等级解锁）

7.4 铸造规则

• 支持平台素材或用户上传
• 铸造消耗水晶余额
• 铸造后生成链上确权信息（当前为模拟上链）
• 铸造成功可获得铸造奖励（基础+阶梯）

7.5 任务规则

• 每日任务每天 05:00 自动重置（PostgreSQL Advisory Lock 保证全局只执行一次）
• 引导任务每个用户仅可完成一次，不重置
• 展示收益每日 05:00 自动发放（claimable 状态的记录）
• 奖励发放失败记录 failed 状态，对用户不可见

7.6 经济规则

• 水晶余额不允许为负数（业务层校验）
• 经验只增不减，溢出部分在升级时已清零
• 10 级满级，超出阈值不再升级
• 升级水晶奖励由调用方主动查询 level_thresholds 后发放

---

八、前端页面结构

8.1 页面路由

路由	页面	说明
/pages/square/square	广场首页	主页面，展示推荐内容
/pages/starbook/index	星册	我的藏品列表（原创/典藏/活动三Tab）
/pages/starbook/items	查看更多	星册藏品分页列表
/pages/starcity/index	星城	展馆页面
/pages/exhibition/exhibition	展馆详情	展位管理
/pages/friends/index	好友	好友列表
/pages/castlove/index	铸爱首页	AI铸造入口
/pages/castlove/create	创建铸造	创建藏品
/pages/castlove/mall	铸爱商城	周边/道具购买
/pages/tasks/daily-tasks	每日任务	每日任务列表
/pages/tasks/guide	引导任务	新手引导
/pages/tasks/revenue	收益中心	收益展示
/pages/discover/discover	发现	AI生成页面
/pages/discover/generation-loading	生成中	图生图轮询页面
/pages/support-activity/index	应援活动	运营活动
/pages/profile/profile	个人中心	用户资料
/pages/login/login	登录	用户登录
/pages/register/register	注册	用户注册
/pages/welcome/index	欢迎页	首次打开引导

---

九、目录结构

9.1 后端目录

backend/
├── gateway/                 # API 网关 (Gin)
│   ├── controller/         # 控制器层
│   ├── dto/                # 数据传输对象
│   ├── middleware/         # 中间件 (JWT)
│   ├── router/             # 路由配置
│   ├── config/             # 配置
│   ├── docs/               # Swagger 文档
│   └── main.go
├── services/               # 微服务 (Dubbo-go)
│   ├── userService/        # 用户/经济服务
│   ├── socialService/      # 社交服务
│   ├── assetService/       # 资产/藏品服务
│   ├── galleryService/     # 展馆服务
│   ├── taskService/        # 任务服务
│   └── activityService/    # 活动服务
├── pkg/                    # 公共包
│   ├── database/           # 数据库连接
│   ├── logger/            # 日志 (Uber Zap)
│   └── jwt/               # JWT 工具
├── scripts/                # 数据库脚本
│   ├── v001_init.sql       # 初始建表
│   ├── 20260415_economic_tables.sql
│   └── 20260415_mint_reward_tables.sql
└── proto/                  # Proto 定义文件

9.2 前端目录

frontend/
├── pages/                  # 页面
│   ├── square/            # 广场
│   ├── starbook/          # 星册
│   ├── starcity/          # 星城
│   ├── exhibition/        # 展馆
│   ├── friends/           # 好友
│   ├── castlove/          # 铸爱/AI铸造
│   ├── tasks/             # 任务系统
│   ├── discover/          # 发现/AI生成
│   ├── support-activity/  # 应援活动
│   ├── profile/           # 个人中心
│   ├── login/             # 登录
│   ├── register/          # 注册
│   └── welcome/           # 欢迎页
├── components/            # 组件
├── store/                # Vuex 状态管理
├── utils/                # 工具函数
├── static/               # 静态资源
└── pages.json            # 路由配置

---

十、待完善功能

功能	状态	说明
真实区块链上链	待实现	目前为模拟上链
完整活动系统	部分实现	Activity Service 待完善
广场推荐算法	待实现	推荐小屋列表、TOP藏品
AI搭子系统	待实现	互动式对话、剧情陪伴
管理后台	部分实现	activity-admin 已实现任务管理，运营管理后台待建
流水分页查询 API	待实现	水晶/经验历史查询（当前只记录不查询）
游戏币 (Coin)	预留	当前 coin_balance 全为 0，等有实际用途时启用
原创藏品 grade 升级规则	待实现	设计已预留 UpgradeGrade 接口
典藏子分类枚举	待确认	动态字符串，应用层负责展示名映射
活动类型枚举	待确认	动态字符串，应用层负责展示名映射

---

十一、规范文档索引

文档	说明
2026-04-07-minimax-image-generation-design.md	MiniMax 图生图 API 集成设计
2026-04-08-task-management-system-design.md	任务管理系统设计
2026-04-13-collection-asset-starbook-refactor.md	典藏/活动藏品体系 + 星册重构设计
2026-04-15-economic-system-design.md	经济系统设计（水晶/经验/等级/铸造奖励）
本文档	平台级系统架构总览

---

本文档为 TopFans 平台级系统架构规范，各子系统详细设计见上方规范文档索引。