# TopFans 系统架构规范

> **创建日期：** 2026-04-16
> **更新日期：** 2026-04-16
> **项目：** TopFans 粉丝社交平台
> **状态：** 已评审通过
> **说明：** 本文档为 TopFans 平台级系统架构总览，各子系统的详细设计在对应规范文档中。
> **规范索引：** `docs/superpowers/specs/2026-04-16-system-architecture-design.md`

---

## 一、项目概述

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

### 技术栈

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

### 核心设计原则

1. **粉丝身份隔离**：所有业务数据按 `user_id + star_id` 联合隔离
2. **服务单一职责**：每个微服务职责单一，通过 Dubbo RPC 协作
3. **经济数据一致性**：经济类操作采用 `SELECT FOR UPDATE` 悲观锁
4. **OSS URL 直回**：后端直接返回 OSS 公共 URL，前端直接访问
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生成素材                        │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 三、服务清单与职责

### 后端微服务

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

### 服务间调用关系

```
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
```

---

## 四、数据库模型

### 核心数据表

| 表名 | 所属服务 | 说明 |
|------|---------|------|
| `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 | 水晶交易流水表 |
| `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 | 用户铸造累计表 |

详细表结构见各子系统规范文档（见第六章规范文档索引）。

### 粉丝身份隔离机制

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

---

## 五、API 架构

### 统一响应格式

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

### 分页响应格式

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

### 认证方式

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

### Swagger 文档

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

---

## 六、核心子系统概要

详见对应规范文档：`docs/superpowers/specs/2026-04-16-system-architecture-design.md`

### 6.1 认证系统

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

### 6.2 粉丝身份系统

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

### 6.3 藏品/星册体系

- **原创藏品**：铸爱流程，纳入星册体系，按 grade 分组展示
- **典藏藏品**：按 category 子分类分组
- **活动藏品**：按 activity_type 分组
- **统一索引**：`asset_registry` 表实现跨类型统一查询
- **OSS URL 直回**：后端直接返回 OSS 公共 URL，前端直接访问
- **星册首页**：一次请求返回全量数据，每组最多 6 条

规范文档：[典藏/活动藏品体系 + 星册重构设计](./docs/superpowers/specs/2026-04-13-collection-asset-starbook-refactor.md)

### 6.4 AI 图生图

前端传递参数 → 后端异步调用 MiniMax API → 前端 3 秒轮询任务状态 → 返回结果。Job 存储在内存 Map 中。

规范文档：[MiniMax 图生图 API 集成设计方案](./docs/superpowers/specs/2026-04-07-minimax-image-generation-design.md)

### 6.5 任务系统

- **每日任务**：每天 05:00 自动重置（PostgreSQL Advisory Lock），用户手动领取
- **引导任务**：每用户仅可完成一次，阶段切换需检查前置任务
- **展示收益**：展品到期后创建收益记录，每日 05:00 自动发放或手动领取

规范文档：[任务管理系统设计文档](./docs/superpowers/specs/2026-04-08-task-management-system-design.md)

### 6.6 经济系统

- **水晶**：复式记账（balance_before + delta = balance_after），所有收入/消耗记流水
- **经验/等级**：10 级满级，阈值存库带缓存，升级时记录等级变化
- **铸造奖励**：基础返还 + 阶梯额外奖励，按 star_id 独立累计
- **并发控制**：`SELECT FOR UPDATE` 悲观锁

规范文档：[经济系统设计文档](./docs/superpowers/specs/2026-04-15-economic-system-design.md)

### 6.7 展馆系统

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

### 6.8 社交系统

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

### 6.9 运营活动系统

应援活动（巴士应援、星演会、生日会等），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 自动重置
- 引导任务每个用户仅可完成一次，不重置
- 展示收益每日 05:00 自动发放或手动领取
- 奖励发放失败记录 failed 状态，对用户不可见

### 7.6 经济规则

- 水晶余额不允许为负数
- 经验只增不减，10 级满级
- 升级水晶奖励由调用方主动查询阈值后发放

---

## 八、前端页面结构

| 路由 | 页面 | 说明 |
|------|------|------|
| /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 | 欢迎页 | 首次打开引导 |

---

## 九、目录结构

### 后端目录

```
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/                # 数据库脚本
└── proto/                  # Proto 定义文件
```

### 前端目录

```
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-16-system-architecture-design.md](./docs/superpowers/specs/2026-04-16-system-architecture-design.md) | 平台级系统架构规范（总览） |
| [MiniMax 图生图 API 集成设计方案](./docs/superpowers/specs/2026-04-07-minimax-image-generation-design.md) | MiniMax 图生图 API 集成设计 |
| [任务管理系统设计文档](./docs/superpowers/specs/2026-04-08-task-management-system-design.md) | 任务管理系统设计 |
| [典藏/活动藏品体系 + 星册重构设计](./docs/superpowers/specs/2026-04-13-collection-asset-starbook-refactor.md) | 典藏/活动藏品体系 + 星册重构设计 |
| [经济系统设计文档](./docs/superpowers/specs/2026-04-15-economic-system-design.md) | 经济系统设计（水晶/经验/等级/铸造奖励） |