# Huwaa 首页房间筛选 Flutter 对接

## 地址

筛选目录：

```http
GET /api/v1/rooms/filters
Authorization: Bearer <access_token>
X-App-Code: huwaa
```

房间列表：

```http
GET /api/v1/rooms?tab=hot&region_id=1001
GET /api/v1/rooms?tab=hot&country_code=AE
```

目录接口要求用户已登录并完成资料。租户权威值是 access token claims 中的 `app_code`；`X-App-Code`/包名只参与请求入口解析，不能覆盖 token 或用来跨租户切换。Huwaa 返回本 App 的全部 active 区域和其中 enabled 国家；其他 App 只返回当前用户所在 active 区域及其国家。

## 参数

目录接口没有 query 参数。每个 option 都返回 `query_key` 和 `query_value`，Flutter 按下面规则调用房间列表：

- All：`query_key`、`query_value` 都为空，不传 `region_id` 和 `country_code`。
- 区域：把 option 的 `query_key=region_id`、`query_value` 原样放进 query。
- 国家：把 option 的 `query_key=country_code`、`query_value` 原样放进 query。
- `region_id` 与 `country_code` 不能同时传；切换筛选项时清空旧 cursor，再从第一页请求。
- 旧参数 `country` 继续兼容，新代码统一使用 `country_code`。

`parent_region_id` 只用于把国家展示在所属区域下。筛选国家时只传 `country_code`，不要把 `parent_region_id` 同时作为 `region_id` 传入。

## 返回值

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req-room-filters",
  "data": {
    "all": {
      "filter_type": "all",
      "query_key": "",
      "query_value": ""
    },
    "regions": [
      {
        "filter_type": "region",
        "query_key": "region_id",
        "query_value": "1001",
        "region_id": 1001,
        "region_code": "MIDDLE_EAST",
        "region_name": "Middle East",
        "sort_order": 10
      }
    ],
    "countries": [
      {
        "filter_type": "country",
        "query_key": "country_code",
        "query_value": "AE",
        "parent_region_id": 1001,
        "country_id": 971,
        "country_code": "AE",
        "country_name": "United Arab Emirates",
        "country_display_name": "UAE",
        "country_flag": "🇦🇪",
        "sort_order": 10
      }
    ]
  }
}
```

目录的数组顺序已经使用后台 `sort_order`。国家只在“国家 enabled 且所属区域 active”时下发，客户端不要自行拼接国家码或区域 ID。

`GET /api/v1/rooms` 响应中的旧 `data.countries` 字段继续保留，供旧版当前区域国家筛选使用；Huwaa 新版完整目录以本接口为准。

## 相关 IM/RTC

筛选目录和列表筛选不创建房间、不入腾讯云 IM 群，也不签发 RTC token。用户实际进入房间后，继续按现有 JoinRoom 流程处理 IM/RTC。