From 1f8d1ba3cf06a2e54f3a92907a66eda4c2f002cb Mon Sep 17 00:00:00 2001 From: zheng020 Date: Thu, 16 Apr 2026 17:44:43 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BB=BA=E7=AB=8B=20TopFans=20?= =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E6=9E=B6=E6=9E=84=E8=A7=84=E8=8C=83=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新建 docs/superpowers/specs/2026-04-16-system-architecture-design.md 作为平台级系统架构总览，整合所有已评审子系统规范 - 更新系统框架.md，同步完整架构信息 + 规范文档索引链接 - 涵盖: 服务架构、数据库模型、API 规范、9 大子系统概要 - 修正: 星册重构 spec 中"零额外 OSS 请求"表述错误 Co-Authored-By: Claude Opus 4.6 --- .../2026-04-16-system-architecture-design.md | 582 ++++++++++++++++++ 系统框架.md | 433 +++++++++++++ 2 files changed, 1015 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-16-system-architecture-design.md create mode 100644 系统框架.md diff --git a/docs/superpowers/specs/2026-04-16-system-architecture-design.md b/docs/superpowers/specs/2026-04-16-system-architecture-design.md new file mode 100644 index 0000000..c6c974a --- /dev/null +++ b/docs/superpowers/specs/2026-04-16-system-architecture-design.md @@ -0,0 +1,582 @@ +# 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 统一响应格式 + +```json +{ + "code": 200, + "message": "ok", + "data": {} +} +``` + +### 5.2 分页响应格式 + +```json +{ + "code": 200, + "message": "ok", + "data": { + "items": [], + "page": 1, + "page_size": 20, + "total": 100, + "has_more": false + } +} +``` + +所有列表查询统一使用 `page` + `page_size` 分页参数。 + +### 5.3 认证方式 + +- Header: `Authorization: Bearer ` +- 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](./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](./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](./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](./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](./2026-04-07-minimax-image-generation-design.md) | MiniMax 图生图 API 集成设计 | +| [2026-04-08-task-management-system-design.md](./2026-04-08-task-management-system-design.md) | 任务管理系统设计 | +| [2026-04-13-collection-asset-starbook-refactor.md](./2026-04-13-collection-asset-starbook-refactor.md) | 典藏/活动藏品体系 + 星册重构设计 | +| [2026-04-15-economic-system-design.md](./2026-04-15-economic-system-design.md) | 经济系统设计（水晶/经验/等级/铸造奖励） | +| 本文档 | 平台级系统架构总览 | + +--- + +*本文档为 TopFans 平台级系统架构规范，各子系统详细设计见上方规范文档索引。* diff --git a/系统框架.md b/系统框架.md new file mode 100644 index 0000000..27bba04 --- /dev/null +++ b/系统框架.md @@ -0,0 +1,433 @@ +# 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 星册重构
2026-04-07 MiniMax
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 ` +- 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 条 + +规范文档：[2026-04-13-collection-asset-starbook-refactor.md](./docs/superpowers/specs/2026-04-13-collection-asset-starbook-refactor.md) + +### 6.4 AI 图生图 + +前端传递参数 → 后端异步调用 MiniMax API → 前端 3 秒轮询任务状态 → 返回结果。Job 存储在内存 Map 中。 + +规范文档：[2026-04-07-minimax-image-generation-design.md](./docs/superpowers/specs/2026-04-07-minimax-image-generation-design.md) + +### 6.5 任务系统 + +- **每日任务**：每天 05:00 自动重置（PostgreSQL Advisory Lock），用户手动领取 +- **引导任务**：每用户仅可完成一次，阶段切换需检查前置任务 +- **展示收益**：展品到期后创建收益记录，每日 05:00 自动发放或手动领取 + +规范文档：[2026-04-08-task-management-system-design.md](./docs/superpowers/specs/2026-04-08-task-management-system-design.md) + +### 6.6 经济系统 + +- **水晶**：复式记账（balance_before + delta = balance_after），所有收入/消耗记流水 +- **经验/等级**：10 级满级，阈值存库带缓存，升级时记录等级变化 +- **铸造奖励**：基础返还 + 阶梯额外奖励，按 star_id 独立累计 +- **并发控制**：`SELECT FOR UPDATE` 悲观锁 + +规范文档：[2026-04-15-economic-system-design.md](./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) | 平台级系统架构规范（总览） | +| [2026-04-07-minimax-image-generation-design.md](./docs/superpowers/specs/2026-04-07-minimax-image-generation-design.md) | MiniMax 图生图 API 集成设计 | +| [2026-04-08-task-management-system-design.md](./docs/superpowers/specs/2026-04-08-task-management-system-design.md) | 任务管理系统设计 | +| [2026-04-13-collection-asset-starbook-refactor.md](./docs/superpowers/specs/2026-04-13-collection-asset-starbook-refactor.md) | 典藏/活动藏品体系 + 星册重构设计 | +| [2026-04-15-economic-system-design.md](./docs/superpowers/specs/2026-04-15-economic-system-design.md) | 经济系统设计（水晶/经验/等级/铸造奖励） |