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`

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

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

```sql
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` 完全分离：

```sql
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，升级规则待定（由团队讨论确认后实现）。设计上预留扩展接口：

```go
// 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` 动态读取。

**响应示例：**

```json
{
  "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 |

**响应示例：**

```json
{
  "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

**请求：**

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

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

**响应：**

```json
{
  "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}

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

**响应：**

```json
{
  "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

```protobuf
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()`

**解决：**

```js
// 只保留 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 类型）

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