# 房间区域置顶

房间置顶是公共房间发现列表的运营排序能力。房间列表按 `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 业务时间下的剩余毫秒数。
