hyapp-server/docs/房间区域置顶.md

房间区域置顶

房间置顶是公共房间发现列表的运营排序能力。房间列表按 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	取消房间置顶

创建请求：

{
  "roomId": "room_123",
  "weight": 100,
  "durationDays": 30
}

• roomId 可以是长房间 ID 或短房间 ID，最终落库使用长房间 ID。
• durationDays 不传时默认 30 天。
• 只能置顶当前 active 房间。

列表返回的 room 包含房间长短 ID、昵称、头像和区域；user 包含房主头像、长短 ID 和昵称；remainingMs 是当前 UTC 业务时间下的剩余毫秒数。