topfans/docs/superpowers/specs/2026-04-13-collection-asset-starbook-refactor.md

典藏/活动藏品体系 + 星册重构设计

日期：2026-04-13 状态：草稿，待评审 负责人：zheng020

---

一、背景与目标

1.1 现状问题

• StarbookContent.vue 混用通用 getMyAssetsApi，无法区分藏品类型（普通/典藏/活动）
• assets 表只有一套，没有类型区分字段
• 典藏藏品有子分类（category）需求，但目前表结构不支持
• 普通藏品有等级（grade）需求，但目前表结构不支持
• 活动藏品需要独立的生命周期管理
• 前端封面 URL 逐个解析（Promise.all + 多次 OSS 预签名调用），性能差
• 前端多重生命周期触发（onMounted + onActivated + onWatch + onShow），存在重复请求

1.2 重构目标

1. 建立普通藏品、典藏藏品、活动藏品三套并行的数据表结构
2. 普通藏品按 grade（1/2/3）分组展示，典藏按 category 子分类分组，活动按 activity_type 分组
3. 通过 asset_registry 统一索引表实现跨类型统一查询
4. 后端批量返回预签名封面 URL，前端零额外 OSS 请求
5. 星册页面按类型 + 子分类/等级分组展示，每组最多展示 6 条
6. "查看更多" 跳转独立页面，支持分页
7. 普通藏品（铸爱流程）、典藏藏品、活动藏品均可放入星册

---

二、数据模型

2.1 现有表（不变动）

表名	说明
assets	普通藏品（铸爱流程），结构不变

2.2 新建表

2.2.1 典藏藏品表 collection_assets

CREATE TABLE collection_assets (
    id                  BIGSERIAL PRIMARY KEY,
    asset_id            BIGINT UNIQUE NOT NULL,           -- 关联 assets 表主键
    owner_uid           BIGINT NOT NULL,
    star_id             BIGINT NOT NULL,
    name                VARCHAR(100) NOT NULL,
    cover_url           VARCHAR(500) NOT NULL,
    category            VARCHAR(50) NOT NULL,              -- 典藏子分类（动态值，示例：'limited', 'classic'）
    like_count          INT NOT NULL DEFAULT 0,
    status              SMALLINT NOT NULL DEFAULT 0,       -- 0=Pending, 1=Active
    metadata            JSONB,                             -- 预留扩展字段
    created_at          BIGINT NOT NULL,
    updated_at          BIGINT NOT NULL,

    CONSTRAINT uk_owner_star_name UNIQUE (owner_uid, star_id, name)
);

CREATE INDEX idx_collection_owner_star  ON collection_assets (owner_uid, star_id);
CREATE INDEX idx_collection_category   ON collection_assets (category);
CREATE INDEX idx_collection_asset_id    ON collection_assets (asset_id);

2.2.2 活动藏品表 activity_assets

CREATE TABLE activity_assets (
    id                  BIGSERIAL PRIMARY KEY,
    asset_id            BIGINT UNIQUE NOT NULL,
    owner_uid           BIGINT NOT NULL,
    star_id             BIGINT NOT NULL,
    activity_id         BIGINT NOT NULL,                   -- 所属活动 ID
    activity_type       VARCHAR(50) NOT NULL,             -- 活动类型（动态值，示例：'birthday', 'anniversary', 'concert'）
    name                VARCHAR(100) NOT NULL,
    cover_url           VARCHAR(500) NOT NULL,
    like_count          INT NOT NULL DEFAULT 0,
    status              SMALLINT NOT NULL DEFAULT 0,
    metadata            JSONB,
    created_at          BIGINT NOT NULL,
    updated_at          BIGINT NOT NULL,

    CONSTRAINT uk_owner_activity_name UNIQUE (owner_uid, activity_id, name)
);

CREATE INDEX idx_activity_owner        ON activity_assets (owner_uid, activity_id);
CREATE INDEX idx_activity_star        ON activity_assets (star_id, activity_id);
CREATE INDEX idx_activity_type        ON activity_assets (activity_type);
CREATE INDEX idx_activity_asset_id    ON activity_assets (asset_id);

2.2.3 统一索引表 asset_registry

CREATE TABLE asset_registry (
    id                  BIGSERIAL PRIMARY KEY,
    asset_id            BIGINT NOT NULL,
    asset_type          VARCHAR(20) NOT NULL,             -- 'regular' | 'collection' | 'activity'
    owner_uid           BIGINT NOT NULL,
    star_id             BIGINT NOT NULL,
    -- 普通藏品专属字段（其他类型时为 NULL）
    grade               SMALLINT,                          -- 普通藏品等级：1 / 2 / 3（仅 regular 时有效）
    -- 典藏专属字段（其他类型时为 NULL）
    collection_category VARCHAR(50),                        -- 典藏子分类（仅 collection 时有效）
    -- 活动专属字段（其他类型时为 NULL）
    activity_id         BIGINT,
    activity_type       VARCHAR(50),
    -- 公共字段
    status              SMALLINT NOT NULL DEFAULT 0,
    like_count          INT NOT NULL DEFAULT 0,
    created_at          BIGINT NOT NULL,
    updated_at          BIGINT NOT NULL,

    CONSTRAINT uk_asset_type_id          UNIQUE (asset_type, asset_id),
    CONSTRAINT uk_owner_star_type_asset  UNIQUE (owner_uid, star_id, asset_type, asset_id)
);

CREATE INDEX idx_registry_owner_star  ON asset_registry (owner_uid, star_id);
CREATE INDEX idx_registry_type_star  ON asset_registry (asset_type, star_id);
CREATE INDEX idx_registry_star_grade ON asset_registry (star_id, grade)
                                        WHERE asset_type = 'regular';
CREATE INDEX idx_registry_star_activity ON asset_registry (star_id, activity_id)
                                        WHERE asset_type = 'activity';

说明：

• asset_type='regular'（普通藏品）：grade 有效（1/2/3），collection_category 为 NULL
• asset_type='collection'（典藏）：collection_category 有效，grade 为 NULL
• asset_type='activity'（活动藏品）：activity_id / activity_type 有效，grade 为 NULL
• 同一 asset_id 只能属于一种 type，不能同时注册为 regular 和 collection

2.3 设计说明

1. 三种类型的区分方式：
   • regular（普通藏品）：grade 有效（1/2/3），由点赞数计算得出，预留升级接口
   • collection（典藏）：collection_category 有效（动态字符串），无 grade
   • activity（活动藏品）：activity_id / activity_type 有效，无 grade
2. category / activity_type 为动态字符串，不预设枚举值，应用层负责校验和展示名称映射
3. registry 表不自增 asset_id，由各类型表创建时写入，保证主从表一致性
4. UNIQUE 约束：owner_uid + star_id + asset_type + asset_id 保证用户每种类型下无重复藏品
5. 同一 asset_id 只能属于一种 type，普通藏品、典藏、活动藏品互斥，不能重复注册
6. grade 字段在数据库中为 NULL 表示非普通藏品，在 API 响应中统一转换为 0（由 Gateway 转换层处理）

2.4 星册槽位表 starbook_slots

新建独立表，与展馆（GalleryService）的 booth_slots 完全分离：

CREATE TABLE starbook_slots (
    id              BIGSERIAL PRIMARY KEY,
    owner_uid       BIGINT NOT NULL,
    star_id         BIGINT NOT NULL,
    slot_index      SMALLINT NOT NULL,                  -- 槽位序号（从 1 开始）
    asset_id        BIGINT,                              -- NULL 表示空槽位
    asset_type      VARCHAR(20),                         -- 'regular' | 'collection' | 'activity'，与 registry 对应
    placed_at       BIGINT NOT NULL,                     -- 放置时间（毫秒时间戳）
    created_at      BIGINT NOT NULL,
    updated_at      BIGINT NOT NULL,

    CONSTRAINT uk_owner_star_slot UNIQUE (owner_uid, star_id, slot_index),
    CONSTRAINT fk_starbook_asset FOREIGN KEY (asset_id, asset_type)
        REFERENCES asset_registry(asset_id, asset_type) ON DELETE SET NULL
);

CREATE INDEX idx_starbook_owner_star ON starbook_slots (owner_uid, star_id);
CREATE INDEX idx_starbook_asset ON starbook_slots (asset_id, asset_type);

说明：

• slot_index 从 1 开始，上限由 fan_profiles.starbook_limit 控制（动态，非写死）
• total_slots 从 fan_profiles.starbook_limit 动态读取，而非写死 15
• 槽位数量支持动态扩展（运营可调整 starbook_limit）
• 外键约束 asset_id + asset_type 关联 asset_registry，确保只有注册过的藏品才能放入星册
• 与 booth_slots 完全独立，星册槽位只用于星册页面展示

---

三、藏品创建流程

3.1 普通藏品（铸爱流程）

用户上传素材 → 铸造订单创建 → assets 表写入
→ 同时写入 asset_registry (type='regular', grade=1)  -- grade 初始为1，升级规则预留

说明：普通藏品（铸爱流程）纳入星册体系，创建时同步写入 registry，grade 初始为 1，后续按点赞数升级（规则待确认）。

3.2 典藏藏品

用户选择"典藏"类型 → 创建 assets 通用记录
→ 创建 collection_assets 专属记录（category）
→ 同时写入 asset_registry (type='collection')

3.3 活动藏品

用户参与活动并获得奖励 → 创建 assets 通用记录
→ 创建 activity_assets 专属记录（activity_id, activity_type）
→ 同时写入 asset_registry (type='activity')

3.4 写入一致性保障

建议在同一个事务内完成 assets 写入和 registry 写入，确保一致性。

---

四、普通藏品等级升级机制（预留接口）

grade 初始值为 1，升级规则待定（由团队讨论确认后实现）。设计上预留扩展接口：

// AssetService 或独立的 GradeService 预留方法
UpgradeGrade(assetID int64, fromGrade, toGrade int) error

// 升级条件判断后期实现，支持：
// - 点赞数阈值触发（如 grade1: ≥0, grade2: ≥100, grade3: ≥500）
// - 全网排名触发
// - 手动升级（运营操作）
// 升级后同步更新 asset_registry.grade

典藏藏品（collection）无 grade 字段，按 category 子分类区分。

---

五、API 设计

5.1 核心原则

• 后端批量返回预签名封面 URL，前端不单独调用 OSS 预签名接口
• 单次请求返回首页全量数据，避免前端多次请求

5.2 接口列表

接口	方法	说明
/api/v1/starbook/home	GET	星册首页，按 type → category → grade 分组，含普通/典藏/活动三种类型
/api/v1/starbook/items	GET	某分组的藏品列表（分页）
/api/v1/starbook/place	POST	放置藏品到星册槽位
/api/v1/starbook/slots/{slot_index}	DELETE	从槽位移除

5.3 详细接口定义

GET /api/v1/starbook/home

说明： 获取当前用户在当前 star 下的星册首页数据。total_slots 从 fan_profiles.starbook_limit 动态读取。

响应示例：

{
  "code": 200,
  "data": {
    "total_slots": 3,
    "slots": [
      {
        "slot_index": 1,
        "asset": null,
        "locked": false
      },
      {
        "slot_index": 2,
        "asset": {
          "asset_id": 101,
          "asset_type": "collection",
          "name": "限定典藏-1",
          "cover_url_signed": "https://oss-cn-shanghai.../signed",
          "like_count": 820,
          "category": "limited"
        },
        "locked": false
      }
    ],
    "groups": [
      {
        "type": "regular",
        "category": "castlove",
        "category_name": "典藏",
        "grades": [
          {
            "grade": 3,
            "items": [
              { "asset_id": 201, "name": "铸爱藏品-A", "cover_url_signed": "https://...", "like_count": 820, "category": "castlove", "grade": 3 }
            ],
            "total_count": 3,
            "has_more": false
          },
          {
            "grade": 2,
            "items": [
              { "asset_id": 202, "name": "铸爱藏品-B", "cover_url_signed": "https://...", "like_count": 450, "category": "castlove", "grade": 2 }
            ],
            "total_count": 8,
            "has_more": true
          }
        ]
      },
      {
        "type": "collection",
        "category": "limited",
        "category_name": "限定典藏",
        "items": [
          { "asset_id": 101, "name": "限定典藏-1", "cover_url_signed": "https://...", "like_count": 820, "category": "limited" }
        ],
        "total_count": 5,
        "has_more": true
      },
      {
        "type": "collection",
        "category": "classic",
        "category_name": "经典典藏",
        "items": [...],
        "total_count": 3,
        "has_more": false
      },
      {
        "type": "activity",
        "category": "birthday",
        "category_name": "生日会",
        "items": [...],
        "total_count": 2,
        "has_more": false
      }
    ]
  }
}

说明：

• total_slots：从 fan_profiles.starbook_limit 动态读取，非写死
• slots：星册槽位，当前展示的藏品直接返回预签名 URL，placed_at 为放置时间
• groups：三种类型的分组逻辑不同
  • type='regular'（普通藏品）：按 grade 分组（grade=1/2/3），category='castlove' 固定
  • type='collection'（典藏）：按 category 子分类分组，无 grade
  • type='activity'（活动藏品）：按 activity_type 分组，无 grade
• 每组最多返回 6 条，has_more=true 表示还有更多（点击"查看更多"跳转分页页）

GET /api/v1/starbook/items

Query 参数：

参数	类型	必填	说明
type	string	是	regular / collection / activity
category	string	否	子分类，不传则返回该类型全部（regular 时传 castlove）
grade	int	否	等级（仅 regular 时有效，1/2/3）
page	int	否	默认 1
page_size	int	否	默认 20

响应示例：

{
  "code": 200,
  "data": {
    "items": [
      {
        "asset_id": 201,
        "asset_type": "regular",
        "name": "铸爱藏品-A",
        "cover_url_signed": "https://oss-cn-shanghai.../signed",
        "like_count": 120,
        "category": "castlove",
        "grade": 2,
        "created_at": 1743004800000
      }
    ],
    "total": 15,
    "page": 1,
    "page_size": 20,
    "has_more": false
  }
}

说明：

• type='regular' 时 grade 取值 1/2/3，category='castlove' 固定
• type='collection' 时无 grade 字段，按 category 筛选
• type='activity' 时无 grade 字段，按 activity_type（即 category 参数）筛选

POST /api/v1/starbook/place

请求：

{
  "asset_id": 101,
  "asset_type": "collection",
  "slot_index": 1
}

说明： 增加 asset_type 字段，用于后端定位 registry 中的具体记录。

响应：

{
  "code": 200,
  "data": {
    "slot_index": 1,
    "asset": {
      "asset_id": 101,
      "asset_type": "collection",
      "name": "限定典藏-1",
      "cover_url_signed": "https://oss-cn-shanghai.../signed",
      "like_count": 820
    }
  }
}

DELETE /api/v1/starbook/slots/{slot_index}

说明： 从指定槽位移除藏品

响应：

{
  "code": 200,
  "data": {
    "slot_index": 1
  }
}

---

六、后端模块划分

6.1 Service 层

Service	职责
AssetService	现有流程改造：创建普通藏品时同步写 asset_registry (type='regular', grade=1)；预留 grade 升级接口
CollectionService（新建）	管理 collection_assets，典藏专属逻辑（含 category 子分类）
ActivityAssetService（新建）	管理 activity_assets，活动藏品专属逻辑
StarbookService（新建）	星册业务编排，管理 starbook_slots 表，调用各 Service，整合数据，统一生成预签名 URL

6.2 StarbookService 核心逻辑

1. 从 fan_profiles.starbook_limit 获取当前用户的槽位上限 total_slots
2. 从 starbook_slots 读取已放置的藏品，填充 slots 数组
3. 从 asset_registry 查询当前用户 + 当前 star 下的所有藏品（regular + collection + activity）
4. 按 type → 各自维度分组（regular 按 grade，collection 按 category，activity 按 activity_type）
5. 批量调用 OSS 生成预签名 URL（已有 generatePresignedURL 逻辑复用）
6. 返回结构化数据

6.3 Repository 层

Repository	表
CollectionRepository	collection_assets
ActivityAssetRepository	activity_assets
AssetRegistryRepository	asset_registry

---

七、Proto 文件变更

7.1 新建 starbook.proto

syntax = "proto3";

package topfans.starbook;

option go_package = "github.com/topfans/backend/pkg/proto/starbook;starbook";

import "proto/common.proto";
import "google/api/annotations.proto";

service StarbookService {
  // 星册首页
  rpc GetStarbookHome(GetStarbookHomeRequest) returns (GetStarbookHomeResponse) {
    option (google.api.http) = {
      get: "/api/v1/starbook/home"
    };
  }

  // 藏品列表（分页）
  rpc GetStarbookItems(GetStarbookItemsRequest) returns (GetStarbookItemsResponse) {
    option (google.api.http) = {
      get: "/api/v1/starbook/items"
    };
  }

  // 放置藏品到槽位
  rpc PlaceToSlot(PlaceToSlotRequest) returns (PlaceToSlotResponse) {
    option (google.api.http) = {
      post: "/api/v1/starbook/place"
      body: "*"
    };
  }

  // 从槽位移除
  rpc RemoveFromSlot(RemoveFromSlotRequest) returns (RemoveFromSlotResponse) {
    option (google.api.http) = {
      delete: "/api/v1/starbook/slots/{slot_index}"
    };
  }
}

message GetStarbookHomeRequest {}

message GetStarbookHomeResponse {
  topfans.common.BaseResponse base = 1;
  StarbookHomeData data = 2;
}

message StarbookHomeData {
  int32 total_slots = 1;
  repeated SlotInfo slots = 2;
  repeated AssetGroup groups = 3;
}

message SlotInfo {
  int32 slot_index = 1;
  bool locked = 2;
  SlotAsset asset = 3;
}

message SlotAsset {
  int64 asset_id = 1;
  string asset_type = 2;          // 'regular' / 'collection' / 'activity'
  string name = 3;
  string cover_url_signed = 4;
  int32 like_count = 5;
  string category = 6;             // regular: 'castlove' / collection: category / activity: activity_type
  int32 grade = 7;                // 仅 regular 时有效（1/2/3），其他类型为 0
  int64 placed_at = 8;            // 放置时间（毫秒时间戳）
}

message AssetGroup {
  string type = 1;                // 'regular' / 'collection' / 'activity'
  string category = 2;            // 'castlove'(regular) / collection_category / activity_type
  string category_name = 3;
  // regular 使用 grades 分组；collection/activity 使用 flat items 列表
  repeated GradeSection grades = 4;   // 仅 regular 时有效
  repeated AssetItem items = 5;        // collection / activity 使用
  int32 total_count = 6;
  bool has_more = 7;
}

message GradeSection {
  int32 grade = 1;                  // 仅 regular 时使用
  repeated AssetItem items = 2;
  int32 total_count = 3;
  bool has_more = 4;
}

message AssetItem {
  int64 asset_id = 1;
  string name = 2;
  string cover_url_signed = 3;
  int32 like_count = 4;
  int64 created_at = 5;
  string category = 6;       // regular: 'castlove' / collection: category / activity: activity_type
  int32 grade = 7;          // 仅 regular 时有效（1/2/3），其他类型为 0
}

message GetStarbookItemsRequest {
  string type = 1;                // 'regular' / 'collection' / 'activity'
  string category = 2;            // regular 时固定传 'castlove'
  int32 grade = 3;               // 仅 regular 时有效（1/2/3）
  int32 page = 4;
  int32 page_size = 5;
}

message GetStarbookItemsResponse {
  topfans.common.BaseResponse base = 1;
  AssetListData data = 2;
}

message AssetListData {
  repeated AssetItem items = 1;
  int64 total = 2;
  int32 page = 3;
  int32 page_size = 4;
  bool has_more = 5;
}

message PlaceToSlotRequest {
  int64 asset_id = 1;
  string asset_type = 2;        // 'regular' / 'collection' / 'activity'
  int32 slot_index = 3;
}

message PlaceToSlotResponse {
  topfans.common.BaseResponse base = 1;
  SlotInfo slot = 2;
}

message RemoveFromSlotRequest {
  int32 slot_index = 1;
}

message RemoveFromSlotResponse {
  topfans.common.BaseResponse base = 1;
}

---

八、前端重构

8.1 生命周期优化

问题： 当前 onMounted + onActivated + onShow + watch(isActive) 四处触发 loadAssetsList()

解决：

// 只保留 onShow + watch isActive，合并为单一加载逻辑
let lastLoadedAt = 0;

onShow(() => {
  if (props.isActive) {
    loadStarbookData();
  }
});

watch(() => props.isActive, (newVal) => {
  if (newVal) loadStarbookData();
});

// 限制频繁刷新：距离上次加载不足 1 秒则跳过
function loadStarbookData() {
  const now = Date.now();
  if (now - lastLoadedAt < 1000) return;
  lastLoadedAt = now;
  // ... 实际加载逻辑
}

8.2 数据流变更

变更前	变更后
调用 getMyAssetsApi（普通藏品）	调用 getStarbookHomeApi（统一，含 regular/collection/activity）
手动解析封面 URL（Promise.all 逐个调 OSS）	后端直接返回 cover_url_signed
前端硬编码 15 槽位	后端返回 total_slots（从 fan_profiles.starbook_limit 动态读取）
前端按 index 硬分组	后端按 type → category → grade 分组返回
普通藏品不展示在星册	普通藏品（type='regular'）纳入星册体系

8.3 页面路由

页面	路由	说明
星册主页	/pages/starbook/index	不变
查看更多	/pages/starbook/items?type=collection&category=limited&grade=3	新页面，接分页数据

8.4 数据结构（前端 TypeScript 类型）

interface StarbookHomeData {
  total_slots: number  // 从 fan_profiles.starbook_limit 动态读取
  slots: SlotInfo[]
  groups: AssetGroup[]
}

interface SlotInfo {
  slot_index: number
  locked: boolean
  asset: SlotAsset | null
}

interface SlotAsset {
  asset_id: number
  asset_type: 'regular' | 'collection' | 'activity'
  name: string
  cover_url_signed: string
  like_count: number
  category: string
  grade: number    // regular: 1/2/3，其他类型为 0
  placed_at: number  // 放置时间（毫秒时间戳）
}

interface AssetGroup {
  type: 'regular' | 'collection' | 'activity'
  category: string       // regular: 'castlove' / collection: 子分类 / activity: activity_type
  category_name: string
  // regular 按 grade 分组，collection/activity 直接用 items 列表
  grades?: GradeSection[]   // 仅 regular 时有效
  items?: AssetItem[]       // collection / activity 时有效
  total_count: number
  has_more: boolean
}

interface GradeSection {
  grade: number  // regular: 1/2/3
  items: AssetItem[]
  total_count: number
  has_more: boolean
}

interface AssetItem {
  asset_id: number
  name: string
  cover_url_signed: string
  like_count: number
  created_at: number
  category: string  // regular: 'castlove' / collection: 子分类 / activity: activity_type
  grade: number    // regular: 1/2/3，其他类型为 0
}

说明：

• type='regular'：grades[] 分组（按 grade），grade 取值 1/2/3，category='castlove' 固定
• type='collection'：items[] 列表（按 category 分组），grade=0（数据库存 NULL，API 转换层统一返回 0），category 为典藏子分类
• type='activity'：items[] 列表（按 activity_type 分组），grade=0（数据库存 NULL，API 转换层统一返回 0），category 为活动类型

---

九、性能保障

1. 后端批量预签名：单次请求一次性生成所有封面 URL 的预签名，前端零额外请求
2. Registry 单表索引：三条索引覆盖所有查询路径（owner+star, type+star, star+grade[regular]）
3. 首页按组截断：每 grade 组最多返回 6 条，has_more 标识是否还有更多
4. 前端防抖：1 秒内重复触发只执行一次加载
5. 分类动态扩展：category / activity_type 不写死枚举，应用层通过配置或枚举接口获取展示名

---

十、待确认事项

事项	状态	说明
典藏子分类（category）枚举值	待确认	动态字符串，设计已支持
活动类型（activity_type）枚举值	待确认	动态字符串，设计已支持
普通藏品 grade 升级规则	待确认	设计已预留 UpgradeGrade 接口
普通藏品 category 固定值	待确认	建议 category='castlove'

---

十一、影响范围

范围	变更内容
数据库	新建 4 张表（collection_assets, activity_assets, asset_registry, starbook_slots）
Proto	新建 starbook.proto
Gateway	新建 StarbookController，新增 4 个路由
Service 层	新建 CollectionService, ActivityAssetService, StarbookService
Repository 层	新建 CollectionRepository, ActivityAssetRepository, AssetRegistryRepository, StarbookSlotRepository
前端	StarbookContent.vue 重构，新增 /pages/starbook/items.vue
铸爱流程	受影响，普通藏品创建时需同步写入 asset_registry（type='regular', grade=1）