47 lines
1.9 KiB
Markdown
47 lines
1.9 KiB
Markdown
# 房间区域置顶
|
||
|
||
房间置顶是公共房间发现列表的运营排序能力。房间列表按 `visible_region_id` 隔离，所以置顶也按区域生效：后台选择一个房间后，后端使用该房间当前 `visible_region_id` 建立 `room_region_pins` 记录。
|
||
|
||
## 边界
|
||
|
||
- `room-service` 仍然是房间状态 owner；置顶不进入 Room Cell、snapshot 或 command log。
|
||
- 置顶只影响 `GET /api/v1/rooms?tab=hot/new` 的排序，不影响进房权限。
|
||
- 有效置顶条件为 `status=active` 且 `expires_at_ms > now_ms`。
|
||
- 房间改区域后，旧区域置顶不会自动迁移到新区域；后台需要取消旧置顶并在新区域重新置顶。
|
||
|
||
## 排序
|
||
|
||
同一区域公共列表排序：
|
||
|
||
1. 有效置顶房间排在普通房间之前。
|
||
2. 置顶房间按 `weight DESC, expires_at_ms DESC, room_id ASC`。
|
||
3. 非置顶房间保留原排序：`hot` 按 `sort_score DESC`，`new` 按 `created_at_ms DESC`。
|
||
|
||
列表 cursor 包含置顶分区、权重、过期时间和原列表排序键，跨页时不会重复返回置顶房间。
|
||
|
||
## 后台接口
|
||
|
||
后台接口使用后台登录 token 和 `/api/v1` 前缀。
|
||
|
||
| 方法 | 路径 | 权限 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `GET` | `/api/v1/admin/rooms/pins` | `room-pin:view` | 查询房间置顶列表，默认只返回有效置顶 |
|
||
| `POST` | `/api/v1/admin/rooms/pins` | `room-pin:create` | 新增或恢复房间置顶 |
|
||
| `DELETE` | `/api/v1/admin/rooms/pins/{pin_id}` | `room-pin:cancel` | 取消房间置顶 |
|
||
|
||
创建请求：
|
||
|
||
```json
|
||
{
|
||
"roomId": "room_123",
|
||
"weight": 100,
|
||
"durationDays": 30
|
||
}
|
||
```
|
||
|
||
- `roomId` 可以是长房间 ID 或短房间 ID，最终落库使用长房间 ID。
|
||
- `durationDays` 不传时默认 30 天。
|
||
- 只能置顶当前 `active` 房间。
|
||
|
||
列表返回的 `room` 包含房间长短 ID、昵称、头像和区域；`user` 包含房主头像、长短 ID 和昵称；`remainingMs` 是当前 UTC 业务时间下的剩余毫秒数。
|