1186 lines
33 KiB
Markdown
1186 lines
33 KiB
Markdown
# 展馆服务设计方案
|
||
|
||
## 📋 文档说明
|
||
|
||
本文档详细说明了展馆服务（Gallery Service）的设计方案，包括服务职责、API设计、数据库设计、业务规则、服务交互等。
|
||
|
||
**创建日期**: 2026-01-12
|
||
**维护者**: AI Assistant
|
||
**状态**: 🟡 设计方案
|
||
|
||
**重要说明**：
|
||
- 本文档中的 API 设计完全参考 `docs/HTTP REST API接口文档.md`
|
||
- 所有 API 路径、请求参数、响应格式均与 HTTP REST API 接口文档保持一致
|
||
- 如有不一致之处，以 HTTP REST API 接口文档为准
|
||
|
||
---
|
||
|
||
## 一、服务概述
|
||
|
||
### 1.1 服务定位
|
||
|
||
**Gallery Service（展馆服务）** 是负责用户展馆管理的核心微服务，包括：
|
||
- 展馆管理（我的展馆、他人展馆）
|
||
- 展位管理（槽位列表、解锁/购买展位）
|
||
- 展品展示（放置、下架、踢走占位）
|
||
- 展位规则管理（从PostgreSQL加载）
|
||
|
||
### 1.2 服务职责边界
|
||
|
||
**Gallery Service 负责：**
|
||
- ✅ 展馆的创建、查询、管理
|
||
- ✅ 展位的创建、解锁、管理
|
||
- ✅ 展品的放置、下架、踢走
|
||
- ✅ 展位规则的加载和管理
|
||
- ✅ 展位占用时长的计算和管理
|
||
|
||
**Gallery Service 不负责：**
|
||
- ❌ 资产信息管理（Asset Service）
|
||
- ❌ 用户信息管理（User Service）
|
||
- ❌ 粉丝档案管理（User Service）
|
||
- ❌ 水晶余额扣除（User Service，通过RPC调用）
|
||
- ❌ 任务进度更新（Task Service，通过事件触发）
|
||
|
||
---
|
||
|
||
## 二、核心功能设计
|
||
|
||
### 2.1 展馆管理
|
||
|
||
#### 2.1.1 获取我的展馆
|
||
|
||
**功能描述**：获取当前用户的展馆信息，包括所有展位及其状态。
|
||
|
||
**业务规则**：
|
||
- 每个用户（user_id + star_id）拥有一个展馆
|
||
- 展馆初始有3个展位（可配置）
|
||
- 展位可以解锁/购买（通过等级或水晶）
|
||
- 展位状态：EMPTY（空）、OCCUPIED（被占用）、LOCKED（未解锁）
|
||
|
||
**API设计**：
|
||
```
|
||
GET /api/mygalleries
|
||
```
|
||
|
||
**请求参数**：无（从JWT Token中获取user_id和star_id）
|
||
|
||
**响应数据**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"gallery_owner_id": 10000001,
|
||
"slot_total": 3,
|
||
"slots": [
|
||
{
|
||
"slot_id": 1,
|
||
"status": "OCCUPIED",
|
||
"asset": {
|
||
"asset_id": "asset_888",
|
||
"name": "藏品名称",
|
||
"cover_url": "https://...",
|
||
"like_count": 12,
|
||
"remain_time": 5000
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- 响应格式参考 HTTP REST API 接口文档
|
||
- `slot_id`：展位ID
|
||
- `status`：展位状态（EMPTY、OCCUPIED、LOCKED）
|
||
- `asset`：展品信息（仅当status为OCCUPIED时存在）
|
||
- `remain_time`：剩余时间（秒）
|
||
|
||
#### 2.1.2 获取他人展馆
|
||
|
||
**功能描述**：获取指定用户的展馆信息（用于广场/好友访问）。
|
||
|
||
**业务规则**：
|
||
- 只能查看同一明星（star_id）的展馆
|
||
- 需要验证粉丝身份一致性
|
||
- 返回数据与"我的展馆"相同，但某些操作不可用（如下架、踢走）
|
||
|
||
**API设计**：
|
||
```
|
||
GET /api/galleries/{target_uid}
|
||
```
|
||
|
||
**请求参数**：
|
||
- `target_uid` (path): 目标用户ID
|
||
|
||
**响应数据**：同"获取我的展馆"
|
||
|
||
---
|
||
|
||
### 2.2 展品展示
|
||
|
||
#### 2.2.1 在展位展示藏品
|
||
|
||
**功能描述**：在指定展位放置藏品（可以是自己的展馆或他人的展馆）。
|
||
|
||
**业务规则**：
|
||
- 只能放置自己拥有的资产
|
||
- 展位必须为空（EMPTY）且已解锁（is_enabled = true）
|
||
- 如果放置在他人的展馆，需要验证同一明星（star_id）
|
||
- 放置后，展位被占用，占用时长为4小时（可配置）
|
||
- 占用期间，展位所有者可以踢走占位
|
||
- 一个资产同时只能在一个展位展示
|
||
|
||
**API设计**：
|
||
```
|
||
POST /api/galleries/place
|
||
```
|
||
|
||
**请求参数**：
|
||
```json
|
||
{
|
||
"asset_id": "asset_888",
|
||
"gallery_owner_id": 10000001,
|
||
"slot_id": 1
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- 参考 HTTP REST API 接口文档，参数中 `slot_id` 在文档中写为 `slot_it`（可能是笔误），实际实现使用 `slot_id`
|
||
|
||
**响应数据**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"status": "OCCUPIED",
|
||
"occupied_until": "2025-12-30T10:00:00Z",
|
||
"occupier_uid": 18995036422
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- 响应格式参考 HTTP REST API 接口文档
|
||
- `occupied_until`：占用到期时间（ISO 8601格式）
|
||
- `occupier_uid`：占位者用户ID
|
||
|
||
**业务逻辑流程**：
|
||
1. 验证资产是否存在且属于当前用户（调用Asset Service）
|
||
2. 验证资产是否已在其他展位展示（查询exhibitions表）
|
||
3. 验证展位是否存在且为空（查询booth_slots表）
|
||
4. 验证展位是否已解锁（is_enabled = true）
|
||
5. 如果放置在他人的展馆，验证同一明星（star_id）
|
||
6. 创建展品展示记录（exhibitions表）
|
||
7. 更新展位状态（booth_slots表）
|
||
8. 更新资产的is_exhibited字段（调用Asset Service）
|
||
9. 发布事件：gallery.exhibit（通知Task Service）
|
||
|
||
#### 2.2.2 下架展位藏品
|
||
|
||
**功能描述**：主动下架展位中的藏品（只有放置者可以下架）。
|
||
|
||
**业务规则**：
|
||
- 只有放置者（occupier_uid）可以下架
|
||
- 下架后，展位变为空（EMPTY）
|
||
- 更新资产的is_exhibited字段
|
||
|
||
**API设计**：
|
||
```
|
||
POST /api/galleries/remove
|
||
```
|
||
|
||
**请求参数**：
|
||
```json
|
||
{
|
||
"asset_id": "asset_888",
|
||
"gallery_owner_uid": 10000001,
|
||
"slot_id": 1
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- 参考 HTTP REST API 接口文档，参数使用 `gallery_owner_uid`（不是 `gallery_owner_id`）
|
||
- 参数为可选（Body，可选）
|
||
|
||
**响应数据**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- 响应为空 data，参考 HTTP REST API 接口文档
|
||
|
||
**业务逻辑流程**：
|
||
1. 验证展品展示记录是否存在
|
||
2. 验证当前用户是否为放置者（occupier_uid）
|
||
3. 删除展品展示记录（exhibitions表）
|
||
4. 更新展位状态为EMPTY（booth_slots表）
|
||
5. 更新资产的is_exhibited字段（调用Asset Service）
|
||
6. 发布事件：gallery.remove（通知Task Service）
|
||
|
||
#### 2.2.3 踢走占位
|
||
|
||
**功能描述**：展位所有者踢走占位者（只有展位所有者可以操作）。
|
||
|
||
**业务规则**：
|
||
- 只有展位所有者（host_profile_id对应的user_id）可以踢走
|
||
- 踢走后，展位变为空（EMPTY）
|
||
- 更新资产的is_exhibited字段
|
||
|
||
**API设计**：
|
||
```
|
||
POST /api/galleries/me/slots/{slot_id}/kick
|
||
```
|
||
|
||
**请求参数**：
|
||
- `slot_id` (path): 展位ID
|
||
- `confirm` (body, optional): 确认操作
|
||
|
||
**响应数据**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"slot_id": 2,
|
||
"status": "EMPTY"
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务逻辑流程**：
|
||
1. 验证展位是否存在且属于当前用户
|
||
2. 验证展位是否被占用
|
||
3. 删除展品展示记录（exhibitions表）
|
||
4. 更新展位状态为EMPTY（booth_slots表）
|
||
5. 更新资产的is_exhibited字段（调用Asset Service）
|
||
|
||
---
|
||
|
||
### 2.3 展位管理
|
||
|
||
#### 2.3.1 解锁/购买新展位
|
||
|
||
**功能描述**：解锁或购买新的展位（通过等级或水晶）。
|
||
|
||
**业务规则**：
|
||
- 初始展位数：3个（可配置）
|
||
- 解锁方式：
|
||
- 等级解锁：达到指定等级即可解锁
|
||
- 水晶购买：消耗指定数量的水晶
|
||
- 解锁后，展位变为可用（is_enabled = true）
|
||
- 如果使用水晶购买，需要扣除水晶余额（调用User Service）
|
||
|
||
**API设计**：
|
||
```
|
||
POST /api/galleries/slots_unlock
|
||
```
|
||
|
||
**请求参数**：无（从JWT Token中获取user_id和star_id）
|
||
|
||
**响应数据**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"slot_total": 3,
|
||
"crystal_balance": 120
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- 参考 HTTP REST API 接口文档，响应包含：
|
||
- `slot_total`：展位总数
|
||
- `crystal_balance`：水晶余额（如果使用水晶购买，显示扣除后的余额）
|
||
- 解锁后的展位信息可以通过"获取我的展馆"接口查看
|
||
|
||
**业务逻辑流程**：
|
||
1. 查询当前用户的粉丝档案（获取等级、水晶余额）
|
||
2. 查询当前展位数和已解锁展位数
|
||
3. 查询下一个展位的解锁规则（从config中获取）
|
||
4. **优先检查等级解锁**：
|
||
- 如果用户等级达到要求，直接解锁（不消耗水晶）
|
||
- 创建新展位（booth_slots表），is_enabled = true
|
||
5. **如果等级不够，检查水晶购买**：
|
||
- 验证水晶余额是否足够
|
||
- 如果足够，扣除水晶余额（调用User Service）
|
||
- 创建新展位（booth_slots表），is_enabled = true
|
||
6. 如果等级不够且水晶不足，返回错误提示
|
||
|
||
---
|
||
|
||
## 三、数据库设计
|
||
|
||
### 3.1 展位表（booth_slots）
|
||
|
||
**表名**：`booth_slots`
|
||
|
||
**字段定义**：
|
||
```sql
|
||
CREATE TABLE booth_slots (
|
||
slot_id BIGSERIAL PRIMARY KEY,
|
||
host_profile_id BIGINT NOT NULL, -- 展馆所有者（fan_profiles表的id，联合主键）
|
||
user_id BIGINT NOT NULL, -- 用户ID（冗余字段，便于查询）
|
||
star_id BIGINT NOT NULL, -- 明星ID（冗余字段，便于查询）
|
||
slot_index INT NOT NULL, -- 展位序号（1, 2, 3, ...）
|
||
visibility VARCHAR(20) DEFAULT 'public', -- 可见性：public, private
|
||
is_enabled BOOLEAN DEFAULT false, -- 是否已解锁
|
||
unlock_type VARCHAR(20), -- 解锁方式：level, crystal, free
|
||
unlock_value INT, -- 解锁条件值（等级或水晶数量）
|
||
created_at BIGINT NOT NULL, -- 创建时间（毫秒时间戳）
|
||
updated_at BIGINT NOT NULL, -- 更新时间（毫秒时间戳）
|
||
|
||
-- 索引
|
||
UNIQUE KEY uk_host_slot (host_profile_id, slot_index),
|
||
INDEX idx_user_star (user_id, star_id),
|
||
INDEX idx_star_enabled (star_id, is_enabled)
|
||
);
|
||
```
|
||
|
||
**说明**：
|
||
- `host_profile_id`：展馆所有者，对应`fan_profiles`表的联合主键（user_id + star_id）
|
||
- `slot_index`：展位序号，从1开始递增
|
||
- `visibility`：可见性标志位，`public`（公有）或 `private`（私有），用于后续功能扩展
|
||
- `is_enabled`：是否已解锁，初始展位为true，后续展位为false
|
||
- `unlock_type`：解锁方式，level（等级）、crystal（水晶）、free（免费）
|
||
- `unlock_value`：解锁条件值，如等级5或水晶100
|
||
|
||
### 3.2 展品展示表（exhibitions）
|
||
|
||
**表名**：`exhibitions`
|
||
|
||
**字段定义**：
|
||
```sql
|
||
CREATE TABLE exhibitions (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
asset_id BIGINT NOT NULL, -- 资产ID
|
||
slot_id BIGINT NOT NULL, -- 展位ID（外键：booth_slots.slot_id）
|
||
host_profile_id BIGINT NOT NULL, -- 展馆所有者（冗余字段）
|
||
occupier_uid BIGINT NOT NULL, -- 占位者用户ID
|
||
occupier_star_id BIGINT NOT NULL, -- 占位者明星ID（冗余字段）
|
||
start_time BIGINT NOT NULL, -- 开始时间（毫秒时间戳）
|
||
expire_at BIGINT NOT NULL, -- 过期时间（毫秒时间戳）
|
||
created_at BIGINT NOT NULL, -- 创建时间（毫秒时间戳）
|
||
updated_at BIGINT NOT NULL, -- 更新时间（毫秒时间戳）
|
||
|
||
-- 外键约束
|
||
FOREIGN KEY (slot_id) REFERENCES booth_slots(slot_id) ON DELETE CASCADE,
|
||
|
||
-- 索引
|
||
UNIQUE KEY uk_asset (asset_id), -- 一个资产同时只能在一个展位
|
||
INDEX idx_slot (slot_id),
|
||
INDEX idx_host (host_profile_id),
|
||
INDEX idx_occupier (occupier_uid, occupier_star_id),
|
||
INDEX idx_expire (expire_at) -- 用于定时清理过期展品
|
||
);
|
||
```
|
||
|
||
**说明**：
|
||
- `asset_id`：资产ID，唯一约束，确保一个资产同时只能在一个展位
|
||
- `slot_id`：展位ID，外键关联`booth_slots`表
|
||
- `host_profile_id`：展馆所有者，冗余字段，便于查询
|
||
- `occupier_uid`：占位者用户ID
|
||
- `expire_at`：过期时间，用于定时清理过期展品
|
||
|
||
**注意**：
|
||
- 规则表（gallery_rules）暂不实现，规则直接硬编码在config文件中
|
||
- 后续版本会引入规则表进行统一规则配置
|
||
|
||
---
|
||
|
||
## 四、业务规则设计
|
||
|
||
### 4.1 展位初始化规则 ✅ **已确认：懒加载**
|
||
|
||
**规则**：
|
||
- 首次查询展馆时，自动创建初始展位（懒加载）
|
||
- 初始展位数量：3个（硬编码在config中）
|
||
- 初始展位全部解锁（is_enabled = true）
|
||
- 初始展位全部为公有（visibility = 'public'）
|
||
- 展位序号从1开始递增
|
||
|
||
**实现方式**：
|
||
- 在Gallery Service首次查询"获取我的展馆"时，检查是否存在展位
|
||
- 如果不存在，自动创建初始展位（3个）
|
||
- 使用事务确保原子性
|
||
|
||
**优势**：
|
||
- 解耦，不需要User Service调用Gallery Service
|
||
- 减少服务间依赖
|
||
- 按需创建，节省资源
|
||
|
||
### 4.2 展位解锁规则 ✅ **已确认：优先等级解锁**
|
||
|
||
**规则**：
|
||
- 第1-3个展位：免费解锁（初始展位）
|
||
- 第4个展位：等级5或水晶100
|
||
- 第5个展位：等级6或水晶200
|
||
- 第6个展位：等级7或水晶300
|
||
- ...（硬编码在config中，后续版本会引入规则表）
|
||
|
||
**解锁方式**：
|
||
- **优先等级解锁**：优先检查是否达到指定等级，如果达到则免费解锁，无需消耗水晶
|
||
- **水晶购买**：如果等级不够，可以使用水晶购买，消耗指定数量的水晶
|
||
|
||
**实现逻辑**：
|
||
1. 查询下一个展位的解锁规则（从config中获取）
|
||
2. 检查用户等级是否达到要求
|
||
3. 如果等级达到，直接解锁（不消耗水晶）
|
||
4. 如果等级不够，检查水晶余额是否足够
|
||
5. 如果水晶足够，扣除水晶并解锁
|
||
6. 如果都不满足，返回错误提示
|
||
|
||
### 4.3 展位占用规则
|
||
|
||
**规则**：
|
||
- 占用时长：4小时（可配置）
|
||
- 占用期间，展位所有者可以踢走占位
|
||
- 占用到期后，自动下架（需要定时任务）
|
||
- 一个资产同时只能在一个展位展示
|
||
|
||
**需要确认**：❓ 占用到期后的处理？
|
||
- 选项A：自动下架，展位变为空（需要定时任务）
|
||
- 选项B：保持占用，但标记为过期（需要前端显示过期状态）
|
||
|
||
### 4.4 展位放置规则 ✅ **已确认：可以放置到他人展馆**
|
||
|
||
**规则**：
|
||
- 只能放置自己拥有的资产
|
||
- 展位必须为空（EMPTY）且已解锁（is_enabled = true）
|
||
- **可以放置在他人的展馆**，但需要验证同一明星（star_id）
|
||
- 一个资产同时只能在一个展位展示
|
||
- 放置后，展位被占用，占用时长为4小时（硬编码在config中）
|
||
- 占用期间，展位所有者可以踢走占位
|
||
|
||
**实现逻辑**：
|
||
1. 验证资产是否存在且属于当前用户（调用Asset Service）
|
||
2. 验证资产是否已在其他展位展示（查询exhibitions表）
|
||
3. 验证展位是否存在且为空（查询booth_slots表）
|
||
4. 验证展位是否已解锁（is_enabled = true）
|
||
5. 如果放置在他人的展馆，验证同一明星（star_id）
|
||
6. 创建展品展示记录（exhibitions表）
|
||
7. 更新展位状态（booth_slots表）
|
||
8. 更新资产的is_exhibited字段（调用Asset Service）
|
||
9. 发布事件：gallery.exhibit（通知Task Service）
|
||
|
||
---
|
||
|
||
## 五、服务间交互
|
||
|
||
### 5.1 与 Asset Service 的交互
|
||
|
||
#### 5.1.1 验证资产是否存在且属于当前用户
|
||
|
||
**RPC接口**：
|
||
```protobuf
|
||
rpc GetAssetForRPC(GetAssetForRPCRequest) returns (GetAssetForRPCResponse);
|
||
```
|
||
|
||
**使用场景**：
|
||
- 放置资产前验证资产是否存在
|
||
- 验证资产是否属于当前用户
|
||
- 验证资产是否已在其他展位展示
|
||
|
||
**请求字段**：
|
||
- `asset_id`：资产ID
|
||
- `user_id`：用户ID
|
||
- `star_id`：明星ID
|
||
|
||
**响应字段**：
|
||
- `asset_id`：资产ID
|
||
- `owner_uid`：所有者用户ID
|
||
- `is_exhibited`：是否已在展位展示
|
||
|
||
#### 5.1.2 更新资产展馆状态
|
||
|
||
**RPC接口**：
|
||
```protobuf
|
||
rpc UpdateAssetExhibitionStatus(UpdateAssetExhibitionStatusRequest) returns (UpdateAssetExhibitionStatusResponse);
|
||
```
|
||
|
||
**使用场景**：
|
||
- 放置资产时，更新`is_exhibited = true`
|
||
- 下架资产时，更新`is_exhibited = false`
|
||
|
||
**请求字段**：
|
||
- `asset_id`：资产ID
|
||
- `is_exhibited`：是否在展位展示
|
||
|
||
### 5.2 与 User Service 的交互
|
||
|
||
#### 5.2.1 获取粉丝档案信息
|
||
|
||
**RPC接口**：
|
||
```protobuf
|
||
rpc GetFanProfile(GetFanProfileRequest) returns (GetFanProfileResponse);
|
||
```
|
||
|
||
**使用场景**：
|
||
- 解锁展位时，获取用户等级和水晶余额
|
||
- 验证用户权限
|
||
|
||
**请求字段**：
|
||
- `user_id`：用户ID
|
||
- `star_id`：明星ID
|
||
|
||
**响应字段**：
|
||
- `user_id`：用户ID
|
||
- `star_id`：明星ID
|
||
- `level`：等级
|
||
- `crystal_balance`：水晶余额
|
||
|
||
#### 5.2.2 扣除水晶余额
|
||
|
||
**RPC接口**：
|
||
```protobuf
|
||
rpc UpdateCrystalBalance(UpdateCrystalBalanceRequest) returns (UpdateCrystalBalanceResponse);
|
||
```
|
||
|
||
**使用场景**：
|
||
- 使用水晶购买展位时，扣除水晶余额
|
||
|
||
**请求字段**：
|
||
- `user_id`：用户ID
|
||
- `star_id`：明星ID
|
||
- `delta`：变化量（负数表示扣除）
|
||
|
||
### 5.3 与 Task Service 的交互
|
||
|
||
#### 5.3.1 发布事件（可选）
|
||
|
||
**事件类型**：
|
||
- `gallery.exhibit`：展品上架事件
|
||
- `gallery.remove`：展品下架事件
|
||
- `gallery.unlock`：展位解锁事件
|
||
|
||
**实现方式**：
|
||
- 直接RPC调用Task Service（推荐）
|
||
- 或使用消息队列（RocketMQ/Kafka/RabbitMQ）
|
||
|
||
**需要确认**：❓ 事件通知方式？
|
||
- 选项A：直接RPC调用（简单，推荐）
|
||
- 选项B：消息队列（解耦，但需要额外基础设施）
|
||
|
||
---
|
||
|
||
## 六、实现架构
|
||
|
||
### 6.1 服务结构
|
||
|
||
```
|
||
services/galleryService/
|
||
├── main.go # 主程序入口
|
||
├── go.mod # 依赖管理
|
||
├── go.sum # 依赖锁定
|
||
├── configs/
|
||
│ └── dubbo.yaml # Dubbo配置
|
||
├── config/
|
||
│ └── gallery_config.go # 展馆服务配置
|
||
├── repository/
|
||
│ ├── gallery_repository.go # 展馆数据访问层
|
||
│ ├── gallery_repository_test.go # Repository测试
|
||
│ └── README.md # Repository文档
|
||
├── service/
|
||
│ ├── gallery_service.go # 展馆业务逻辑
|
||
│ ├── slot_service.go # 展位业务逻辑
|
||
│ └── exhibition_service.go # 展品业务逻辑
|
||
├── client/
|
||
│ ├── asset_rpc_client.go # Asset Service RPC客户端
|
||
│ ├── user_rpc_client.go # User Service RPC客户端
|
||
│ └── task_rpc_client.go # Task Service RPC客户端（可选）
|
||
├── provider/
|
||
│ └── gallery_provider.go # RPC接口实现
|
||
└── IMPLEMENTATION_COMPLETE.md # 实现完成总结
|
||
```
|
||
|
||
### 6.2 配置层（Config）
|
||
|
||
**文件**：`config/gallery_config.go`
|
||
|
||
**配置项**：
|
||
```go
|
||
type GalleryConfig struct {
|
||
// 规则配置（硬编码，后续版本会引入规则表）
|
||
Rules *GalleryRules
|
||
|
||
// RPC客户端配置
|
||
AssetServiceURL string
|
||
UserServiceURL string
|
||
TaskServiceURL string
|
||
|
||
// 数据库配置
|
||
Database *DatabaseConfig
|
||
}
|
||
|
||
type GalleryRules struct {
|
||
// 初始展位数（默认：3）
|
||
InitialSlotCount int
|
||
|
||
// 抢展位时长（秒，默认：14400，即4小时）
|
||
GrabSlotDuration int64
|
||
|
||
// 按等级解锁成本（slot_index -> level）
|
||
// 例如：第4个展位需要等级5，第5个展位需要等级6
|
||
UnlockLevelBySlot map[int]int
|
||
|
||
// 按水晶解锁成本（slot_index -> crystal_cost）
|
||
// 例如：第4个展位需要水晶100，第5个展位需要水晶200
|
||
UnlockCrystalBySlot map[int]int
|
||
|
||
// 最大展位数（默认：10）
|
||
MaxSlotCount int
|
||
}
|
||
```
|
||
|
||
**配置示例**（参考其他service的实现方式）：
|
||
```go
|
||
// config/gallery_config.go
|
||
package config
|
||
|
||
var (
|
||
// GalleryRules 展馆规则配置（硬编码）
|
||
GalleryRules = &GalleryRulesConfig{
|
||
InitialSlotCount: 3,
|
||
GrabSlotDuration: 14400, // 4小时
|
||
|
||
// 按等级解锁：第4个展位需要等级5，第5个展位需要等级6，以此类推
|
||
UnlockLevelBySlot: map[int]int{
|
||
4: 5, // 第4个展位需要等级5
|
||
5: 6, // 第5个展位需要等级6
|
||
6: 7, // 第6个展位需要等级7
|
||
7: 8, // 第7个展位需要等级8
|
||
8: 9, // 第8个展位需要等级9
|
||
9: 10, // 第9个展位需要等级10
|
||
10: 11, // 第10个展位需要等级11
|
||
},
|
||
|
||
// 按水晶解锁：第4个展位需要水晶100，第5个展位需要水晶200，以此类推
|
||
UnlockCrystalBySlot: map[int]int{
|
||
4: 100, // 第4个展位需要水晶100
|
||
5: 200, // 第5个展位需要水晶200
|
||
6: 300, // 第6个展位需要水晶300
|
||
7: 400, // 第7个展位需要水晶400
|
||
8: 500, // 第8个展位需要水晶500
|
||
9: 600, // 第9个展位需要水晶600
|
||
10: 700, // 第10个展位需要水晶700
|
||
},
|
||
|
||
MaxSlotCount: 10,
|
||
}
|
||
)
|
||
```
|
||
|
||
### 6.3 Repository层
|
||
|
||
**职责**：
|
||
- 展馆数据访问（CRUD操作）
|
||
- 展位数据访问
|
||
- 展品展示数据访问
|
||
|
||
**主要方法**：
|
||
```go
|
||
// 展馆相关
|
||
GetGalleryByUser(userID, starID int64) (*Gallery, error)
|
||
CreateInitialSlots(userID, starID int64) error // 懒加载时创建初始展位
|
||
|
||
// 展位相关
|
||
GetSlotsByGallery(hostProfileID int64) ([]*BoothSlot, error)
|
||
GetSlotByID(slotID int64) (*BoothSlot, error)
|
||
CreateSlot(slot *BoothSlot) error
|
||
UpdateSlotStatus(slotID int64, status string) error
|
||
UnlockSlot(slotID int64) error
|
||
|
||
// 展品相关
|
||
GetExhibitionByAsset(assetID int64) (*Exhibition, error)
|
||
GetExhibitionBySlot(slotID int64) (*Exhibition, error)
|
||
CreateExhibition(exhibition *Exhibition) error
|
||
DeleteExhibition(exhibitionID int64) error
|
||
GetExpiredExhibitions(beforeTime int64) ([]*Exhibition, error)
|
||
```
|
||
|
||
**注意**：
|
||
- 规则配置硬编码在config文件中，不需要从数据库加载
|
||
- 后续版本会引入规则表，届时会添加规则加载方法
|
||
|
||
### 6.4 Service层
|
||
|
||
**职责**：
|
||
- 展馆业务逻辑
|
||
- 展位业务逻辑
|
||
- 展品业务逻辑
|
||
- 规则管理
|
||
|
||
**主要方法**：
|
||
```go
|
||
// 展馆服务
|
||
GetMyGallery(userID, starID int64) (*GalleryResponse, error)
|
||
GetUserGallery(targetUID, starID int64) (*GalleryResponse, error)
|
||
|
||
// 展位服务
|
||
UnlockSlot(userID, starID int64) (*UnlockSlotResponse, error)
|
||
|
||
// 展品服务
|
||
PlaceAsset(userID, starID int64, req *PlaceAssetRequest) (*PlaceAssetResponse, error)
|
||
RemoveAsset(userID, starID int64, req *RemoveAssetRequest) error
|
||
KickOccupier(userID, starID int64, slotID int64) error
|
||
```
|
||
|
||
### 6.5 Provider层
|
||
|
||
**职责**：
|
||
- 实现Proto定义的RPC接口
|
||
- 从Dubbo attachments提取用户信息
|
||
- 委托给Service层处理
|
||
|
||
**主要方法**：
|
||
```go
|
||
// 实现GalleryServiceHandler接口
|
||
GetMyGallery(ctx context.Context, req *pb.GetMyGalleryRequest) (*pb.GetMyGalleryResponse, error)
|
||
GetUserGallery(ctx context.Context, req *pb.GetUserGalleryRequest) (*pb.GetUserGalleryResponse, error)
|
||
PlaceAsset(ctx context.Context, req *pb.PlaceAssetRequest) (*pb.PlaceAssetResponse, error)
|
||
RemoveAsset(ctx context.Context, req *pb.RemoveAssetRequest) (*pb.RemoveAssetResponse, error)
|
||
KickOccupier(ctx context.Context, req *pb.KickOccupierRequest) (*pb.KickOccupierResponse, error)
|
||
UnlockSlot(ctx context.Context, req *pb.UnlockSlotRequest) (*pb.UnlockSlotResponse, error)
|
||
```
|
||
|
||
---
|
||
|
||
## 七、Proto接口定义
|
||
|
||
### 7.1 创建Proto文件
|
||
|
||
**文件**：`proto/gallery.proto`
|
||
|
||
**定义**：
|
||
```protobuf
|
||
syntax = "proto3";
|
||
|
||
package topfans.gallery;
|
||
|
||
import "google/api/annotations.proto";
|
||
import "common/common.proto";
|
||
|
||
option go_package = "github.com/topfans/backend/pkg/proto/gallery";
|
||
|
||
// 展馆服务
|
||
service GalleryService {
|
||
// 获取我的展馆
|
||
rpc GetMyGallery(GetMyGalleryRequest) returns (GetMyGalleryResponse) {
|
||
option (google.api.http) = {
|
||
get: "/api/mygalleries"
|
||
};
|
||
}
|
||
|
||
// 获取他人展馆
|
||
rpc GetUserGallery(GetUserGalleryRequest) returns (GetUserGalleryResponse) {
|
||
option (google.api.http) = {
|
||
get: "/api/galleries/{target_uid}"
|
||
};
|
||
}
|
||
|
||
// 在展位展示藏品
|
||
rpc PlaceAsset(PlaceAssetRequest) returns (PlaceAssetResponse) {
|
||
option (google.api.http) = {
|
||
post: "/api/galleries/place"
|
||
body: "*"
|
||
};
|
||
}
|
||
|
||
// 下架展位藏品
|
||
rpc RemoveAsset(RemoveAssetRequest) returns (RemoveAssetResponse) {
|
||
option (google.api.http) = {
|
||
post: "/api/galleries/remove"
|
||
body: "*"
|
||
};
|
||
}
|
||
|
||
// 踢走占位
|
||
rpc KickOccupier(KickOccupierRequest) returns (KickOccupierResponse) {
|
||
option (google.api.http) = {
|
||
post: "/api/galleries/me/slots/{slot_id}/kick"
|
||
body: "*"
|
||
};
|
||
}
|
||
|
||
// 解锁/购买新展位
|
||
rpc UnlockSlot(UnlockSlotRequest) returns (UnlockSlotResponse) {
|
||
option (google.api.http) = {
|
||
post: "/api/galleries/slots_unlock"
|
||
body: "*"
|
||
};
|
||
}
|
||
}
|
||
|
||
// 请求和响应消息定义
|
||
message GetMyGalleryRequest {}
|
||
|
||
message GetMyGalleryResponse {
|
||
topfans.common.BaseResponse base = 1;
|
||
GalleryData data = 2;
|
||
}
|
||
|
||
message GetUserGalleryRequest {
|
||
int64 target_uid = 1;
|
||
}
|
||
|
||
message GetUserGalleryResponse {
|
||
topfans.common.BaseResponse base = 1;
|
||
GalleryData data = 2;
|
||
}
|
||
|
||
message PlaceAssetRequest {
|
||
int64 asset_id = 1;
|
||
int64 gallery_owner_id = 2; // 注意：HTTP文档中使用 gallery_owner_id
|
||
int64 slot_id = 3; // 注意：HTTP文档中写为 slot_it（可能是笔误），实际使用 slot_id
|
||
}
|
||
|
||
message PlaceAssetResponse {
|
||
topfans.common.BaseResponse base = 1;
|
||
PlaceAssetData data = 2;
|
||
}
|
||
|
||
message RemoveAssetRequest {
|
||
int64 asset_id = 1;
|
||
int64 gallery_owner_uid = 2; // 注意：使用 gallery_owner_uid（不是 gallery_owner_id）
|
||
int64 slot_id = 3;
|
||
}
|
||
|
||
message RemoveAssetResponse {
|
||
topfans.common.BaseResponse base = 1;
|
||
}
|
||
|
||
message KickOccupierRequest {
|
||
int64 slot_id = 1;
|
||
bool confirm = 2;
|
||
}
|
||
|
||
message KickOccupierResponse {
|
||
topfans.common.BaseResponse base = 1;
|
||
KickOccupierData data = 2;
|
||
}
|
||
|
||
message UnlockSlotRequest {}
|
||
|
||
message UnlockSlotResponse {
|
||
topfans.common.BaseResponse base = 1;
|
||
UnlockSlotData data = 2;
|
||
}
|
||
|
||
// 数据模型
|
||
message GalleryData {
|
||
int64 gallery_owner_id = 1;
|
||
int32 slot_total = 2;
|
||
repeated SlotInfo slots = 3;
|
||
}
|
||
|
||
message SlotInfo {
|
||
int64 slot_id = 1;
|
||
int32 slot_index = 2;
|
||
string status = 3; // EMPTY, OCCUPIED, LOCKED
|
||
bool is_enabled = 4;
|
||
AssetInfo asset = 5;
|
||
int64 occupier_uid = 6;
|
||
int64 occupied_at = 7;
|
||
int64 expire_at = 8;
|
||
UnlockCondition unlock_condition = 9;
|
||
}
|
||
|
||
message AssetInfo {
|
||
int64 asset_id = 1;
|
||
string name = 2;
|
||
string cover_url = 3;
|
||
int32 like_count = 4;
|
||
int64 remain_time = 5; // 剩余时间（秒）
|
||
}
|
||
|
||
message UnlockCondition {
|
||
string type = 1; // level, crystal
|
||
int32 value = 2;
|
||
}
|
||
|
||
message PlaceAssetData {
|
||
string status = 1; // OCCUPIED
|
||
string occupied_until = 2; // ISO 8601格式
|
||
int64 occupier_uid = 3; // 占位者用户ID
|
||
}
|
||
|
||
message KickOccupierData {
|
||
string slot_id = 1; // 注意：返回字符串格式（如 "slot_2"）
|
||
string status = 2; // EMPTY
|
||
}
|
||
|
||
message UnlockSlotData {
|
||
int32 slot_total = 1; // 展位总数
|
||
int64 crystal_balance = 2; // 水晶余额（如果使用水晶购买，显示扣除后的余额）
|
||
// 注意：解锁后的展位信息可以通过"获取我的展馆"接口查看，此处不返回
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 八、需要确认的问题
|
||
|
||
### 8.1 展位初始化时机 ✅ **已确认：懒加载**
|
||
|
||
**决定**：首次查询时自动创建（懒加载）
|
||
|
||
**实现方式**：
|
||
- 在Gallery Service首次查询"获取我的展馆"时，检查是否存在展位
|
||
- 如果不存在，自动创建初始展位（3个）
|
||
- 使用事务确保原子性
|
||
|
||
**优势**：
|
||
- 解耦，不需要User Service调用Gallery Service
|
||
- 减少服务间依赖
|
||
- 按需创建，节省资源
|
||
|
||
---
|
||
|
||
### 8.2 解锁方式优先级 ✅ **已确认：优先等级解锁**
|
||
|
||
**决定**：优先使用等级解锁，如果等级不够，可以使用水晶购买
|
||
|
||
**实现逻辑**：
|
||
1. 查询下一个展位的解锁规则（从config中获取）
|
||
2. 检查用户等级是否达到要求
|
||
3. 如果等级达到，直接解锁（不消耗水晶）
|
||
4. 如果等级不够，检查水晶余额是否足够
|
||
5. 如果水晶足够，扣除水晶并解锁
|
||
6. 如果都不满足，返回错误提示
|
||
|
||
**优势**：
|
||
- 鼓励用户提升等级
|
||
- 提供灵活性，等级不够时可以使用水晶
|
||
|
||
---
|
||
|
||
### 8.3 占用到期后的处理 ❓
|
||
|
||
**问题**：展位占用到期后如何处理？
|
||
|
||
**选项A**：自动下架，展位变为空（需要定时任务）
|
||
- 优点：自动清理，展位可以重新使用
|
||
- 缺点：需要定时任务
|
||
|
||
**选项B**：保持占用，但标记为过期（需要前端显示过期状态）
|
||
- 优点：不需要定时任务
|
||
- 缺点：需要前端处理过期状态
|
||
|
||
**推荐**：选项A（自动下架）+ 选项B（前端显示过期状态，定时任务异步清理）
|
||
|
||
---
|
||
|
||
### 8.4 是否可以放置在他人的展馆 ✅ **已确认：可以放置**
|
||
|
||
**决定**：可以放置在他人的展馆（需要验证同一明星）
|
||
|
||
**实现逻辑**：
|
||
- 验证资产是否存在且属于当前用户
|
||
- 验证展位是否存在且为空
|
||
- 如果放置在他人的展馆，验证同一明星（star_id）
|
||
- 创建展品展示记录
|
||
|
||
**优势**：
|
||
- 增加社交互动
|
||
- 提升用户参与度
|
||
|
||
---
|
||
|
||
### 8.5 事件通知方式 ❓
|
||
|
||
**问题**：如何通知Task Service更新任务进度？
|
||
|
||
**选项A**：直接RPC调用（推荐）
|
||
- 优点：简单，不需要额外基础设施
|
||
- 缺点：服务间耦合
|
||
|
||
**选项B**：消息队列（RocketMQ/Kafka/RabbitMQ）
|
||
- 优点：解耦，异步处理
|
||
- 缺点：需要额外基础设施
|
||
|
||
**推荐**：选项A（直接RPC调用），参考Asset Service的实现
|
||
|
||
---
|
||
|
||
### 8.6 展位最大数量 ❓
|
||
|
||
**问题**：展位最大数量是多少？
|
||
|
||
**选项A**：10个（可配置）
|
||
**选项B**：20个（可配置）
|
||
**选项C**：无限制（可配置）
|
||
|
||
**推荐**：选项A（10个），后续可根据需求调整
|
||
|
||
---
|
||
|
||
### 8.7 展位占用时长 ❓
|
||
|
||
**问题**：展位占用时长是多少？
|
||
|
||
**选项A**：4小时（可配置）
|
||
**选项B**：24小时（可配置）
|
||
**选项C**：永久（可配置）
|
||
|
||
**推荐**：选项A（4小时），后续可根据需求调整
|
||
|
||
---
|
||
|
||
## 九、实现计划
|
||
|
||
### 9.1 阶段一：Proto接口定义和数据库设计
|
||
|
||
**任务**：
|
||
1. 创建`proto/gallery.proto`文件
|
||
2. 定义数据库表结构（booth_slots、exhibitions）
|
||
3. 创建数据库模型（`pkg/models/gallery.go`）
|
||
4. 编译Proto文件
|
||
|
||
**注意**：
|
||
- 暂不创建规则表（gallery_rules），规则硬编码在config文件中
|
||
- 后续版本会引入规则表
|
||
|
||
**预计工作量**：2-3小时
|
||
|
||
---
|
||
|
||
### 9.2 阶段二：Repository层实现
|
||
|
||
**任务**：
|
||
1. 实现`gallery_repository.go`
|
||
2. 实现展馆数据访问方法
|
||
3. 实现展位数据访问方法（包括懒加载创建初始展位）
|
||
4. 实现展品数据访问方法
|
||
5. 编写单元测试
|
||
|
||
**注意**：
|
||
- 暂不实现规则数据加载方法，规则硬编码在config文件中
|
||
- 懒加载逻辑：首次查询时自动创建初始展位
|
||
|
||
**预计工作量**：4-6小时
|
||
|
||
---
|
||
|
||
### 9.3 阶段三：Service层实现
|
||
|
||
**任务**：
|
||
1. 实现`gallery_service.go`
|
||
2. 实现`slot_service.go`
|
||
3. 实现`exhibition_service.go`
|
||
4. 实现业务逻辑和规则验证
|
||
5. 编写单元测试
|
||
|
||
**预计工作量**：6-8小时
|
||
|
||
---
|
||
|
||
### 9.4 阶段四：RPC客户端实现
|
||
|
||
**任务**：
|
||
1. 实现`asset_rpc_client.go`
|
||
2. 实现`user_rpc_client.go`
|
||
3. 实现`task_rpc_client.go`（可选）
|
||
4. 实现错误处理和日志记录
|
||
|
||
**预计工作量**：2-3小时
|
||
|
||
---
|
||
|
||
### 9.5 阶段五：Provider层实现
|
||
|
||
**任务**：
|
||
1. 实现`gallery_provider.go`
|
||
2. 实现所有RPC接口
|
||
3. 从Dubbo attachments提取用户信息
|
||
4. 委托给Service层处理
|
||
|
||
**预计工作量**：3-4小时
|
||
|
||
---
|
||
|
||
### 9.6 阶段六：主程序和配置
|
||
|
||
**任务**：
|
||
1. 实现`main.go`
|
||
2. 实现`config/gallery_config.go`（硬编码规则配置）
|
||
3. 配置`configs/dubbo.yaml`
|
||
4. 实现优雅关闭
|
||
|
||
**注意**：
|
||
- 规则配置硬编码在`config/gallery_config.go`中，参考其他service的实现方式
|
||
- 暂不实现规则加载机制（从数据库加载），后续版本会引入
|
||
|
||
**预计工作量**：2-3小时
|
||
|
||
---
|
||
|
||
### 9.7 阶段七：Gateway层集成
|
||
|
||
**任务**：
|
||
1. 实现`gateway/controller/gallery_controller.go`
|
||
2. 实现`gateway/dto/gallery_dto.go`
|
||
3. 实现`gateway/dto/gallery_converter.go`
|
||
4. 配置路由
|
||
5. 测试接口
|
||
|
||
**预计工作量**：3-4小时
|
||
|
||
---
|
||
|
||
### 9.8 阶段八：测试和优化
|
||
|
||
**任务**：
|
||
1. 单元测试
|
||
2. 集成测试
|
||
3. 性能测试
|
||
4. 优化和修复
|
||
|
||
**预计工作量**：4-6小时
|
||
|
||
---
|
||
|
||
**总预计工作量**：26-37小时（约3-5个工作日）
|
||
|
||
---
|
||
|
||
## 十、总结
|
||
|
||
### 10.1 设计要点
|
||
|
||
1. **服务职责清晰**：展馆服务专注于展馆、展位、展品的管理
|
||
2. **数据隔离**：使用`user_id + star_id`进行数据隔离
|
||
3. **规则硬编码**：展位规则硬编码在config文件中，与其他service实现方式一致
|
||
4. **服务间解耦**：通过RPC调用其他服务，不直接访问其他服务的数据库
|
||
5. **扩展性强**：支持后续功能扩展（如展位装饰、展品排序、私有/公有展位等）
|
||
6. **展位可见性**：展位支持私有/公有标志位，便于后续功能扩展
|
||
|
||
### 10.2 关键设计决策
|
||
|
||
1. **展位初始化**：✅ 懒加载方式，首次查询时自动创建
|
||
2. **解锁方式**：✅ 优先使用等级解锁，不够可以使用水晶购买
|
||
3. **他人展馆**：✅ 可以放置在他人的展馆，增加社交互动
|
||
4. **规则管理**：✅ 规则硬编码在config文件中，后续版本会引入规则表
|
||
5. **展位可见性**：✅ 展位支持私有/公有标志位（visibility字段）
|
||
6. **事件通知**：直接RPC调用Task Service，简单高效
|
||
|
||
### 10.3 下一步行动
|
||
|
||
1. **确认问题**：与产品/业务确认上述需要确认的问题
|
||
2. **细化设计**：根据确认结果，细化数据库设计和业务逻辑
|
||
3. **开始实现**：按照实现计划，逐步实现各个阶段
|
||
4. **测试验证**：完成实现后，进行充分的测试验证
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0
|
||
**最后更新**: 2026-01-12
|
||
**维护者**: AI Assistant
|