hyapp-server/docs/flutter对接/Agency资料与房间Flutter对接.md

Agency 资料与房间 Flutter 对接

基础约定

本地开发地址：

http://127.0.0.1:13000

所有接口都是登录接口，需要带登录 token。

请求头：

Header	必填	说明
Authorization	是	Bearer <access_token>。
X-App-Code	否	App 编码，默认 lalu；登录态接口最终以 token 内 app_code 为准。

成功和失败都使用统一 envelope：

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_xxx",
  "data": {}
}

客户端分支只判断 code，排查问题记录 request_id。

1. 查询用户所属 Agency 资料

地址：

GET /api/v1/agencies/profile

参数：

参数	位置	必填	类型	说明
user_id	query	是	string/int64	被查看的 host 用户 ID。

示例：

GET /api/v1/agencies/profile?user_id=10001
Authorization: Bearer <access_token>
X-App-Code: lalu

返回值：

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "agency": {
      "agency_id": "7001",
      "owner_user_id": "99",
      "region_id": 30,
      "parent_bd_user_id": "501",
      "name": "Yumi Star Agency",
      "avatar": "https://cdn.example/agency.png",
      "host_count": 20,
      "status": "active",
      "join_enabled": true,
      "created_by_user_id": "1",
      "created_at_ms": 1710000000000,
      "updated_at_ms": 1710000001000
    }
  }
}

没有 active host 身份，或没有 active agency 归属时：

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "agency": null
  }
}

字段说明：

字段	说明
agency_id	Agency ID，字符串。
owner_user_id	Agency 会长用户 ID，字符串。
name	Agency 自己的名称，不再读 owner 用户昵称。
avatar	Agency 自己的头像，不再读 owner 用户头像。
host_count	当前 active host 数量。
status	当前只展示 active。
join_enabled	是否允许用户申请加入。
created_at_ms / updated_at_ms	Unix epoch milliseconds。

2. 查询 Agency 下所有 host 的房间

地址：

GET /api/v1/agencies/rooms

参数：

参数	位置	必填	类型	默认	说明
user_id	query	是	string/int64	无	被查看的 host 用户 ID。
limit	query	否	int	20	每页数量，最大 50。
cursor	query	否	string	空	下一页 cursor。
tab	query	否	string	hot	hot 或 new。
query	query	否	string	空	搜索房间标题、房间 ID 或短号。

示例：

GET /api/v1/agencies/rooms?user_id=10001&tab=hot&limit=20
Authorization: Bearer <access_token>
X-App-Code: lalu

返回值：

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "agency_id": "7001",
    "rooms": [
      {
        "room_id": "room_101",
        "im_group_id": "room_101",
        "owner_user_id": "101",
        "title": "Agency Room",
        "cover_url": "https://cdn.example/room.png",
        "mode": "voice",
        "status": "active",
        "locked": false,
        "heat": 88,
        "online_count": 12,
        "seat_count": 8,
        "occupied_seat_count": 3,
        "visible_region_id": 30,
        "app_code": "lalu",
        "room_short_id": "M20",
        "country_code": "AE",
        "country_flag": "🇦🇪"
      }
    ],
    "next_cursor": "cursor_xxx"
  }
}

没有 active host 身份，或没有 active agency 归属时：

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "agency_id": "",
    "rooms": [],
    "next_cursor": ""
  }
}

字段说明：

字段	说明
agency_id	当前查询到的 Agency ID；无归属时为空字符串。
rooms	Agency 下所有 active host 的 active 房间。
next_cursor	下一页 cursor；为空表示没有下一页。
room_id	房间 ID。
im_group_id	腾讯云 IM 房间群 ID，进群使用这个字段。
owner_user_id	房主用户 ID，字符串。
title	房间名。
cover_url	房间封面。
locked	是否锁房。
heat	房间热度。
online_count	在线人数。
seat_count	麦位数量。
occupied_seat_count	已占用麦位数量。
room_short_id	房间短号。
country_code / country_flag	房主国家展示字段。

3. 修改 Agency 资料

地址：

POST /api/v1/agencies/profile/update

权限：

只有当前登录用户是 active Agency owner 时可以修改。普通 host、Agency 成员、BD、非 active owner 都不能修改。

参数：

参数	位置	必填	类型	说明
command_id	body	是	string	客户端生成的幂等 ID。
name	body	否	string	新 Agency 名称。
avatar	body	否	string	新 Agency 头像 URL。

name 和 avatar 至少传一个；传了就不能是空字符串。修改 Agency 资料不会修改 owner 用户昵称和头像。

示例：

POST /api/v1/agencies/profile/update
Authorization: Bearer <access_token>
X-App-Code: lalu
Content-Type: application/json

{
  "command_id": "cmd_agency_profile_001",
  "name": "New Agency Name",
  "avatar": "https://cdn.example/new-agency.png"
}

返回值：

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "agency": {
      "agency_id": "7001",
      "owner_user_id": "42",
      "region_id": 30,
      "name": "New Agency Name",
      "avatar": "https://cdn.example/new-agency.png",
      "host_count": 20,
      "status": "active",
      "join_enabled": true,
      "created_at_ms": 1710000000000,
      "updated_at_ms": 1710000005000
    }
  }
}

错误处理

失败返回：

{
  "code": "INVALID_ARGUMENT",
  "message": "invalid argument",
  "request_id": "req_abc"
}

HTTP 状态码	code	处理方式
400	INVALID_ARGUMENT	参数错误，例如 user_id 非法、tab 非法、limit 非法、缺少 command_id、name/avatar 都没传或传空。
401	UNAUTHORIZED	token 缺失、无效或过期，重新登录。
403	PROFILE_REQUIRED	用户资料未完成，跳转资料补全。
403	PERMISSION_DENIED	修改接口中当前用户不是 active Agency owner，不允许修改。
404	NOT_FOUND	修改接口中 Agency 事实不存在；刷新当前用户身份后再进入页面。
409	CONFLICT	command_id 与已有不同命令冲突；重新生成新的 command_id 再提交。
502	UPSTREAM_ERROR	服务暂不可用，可以提示稍后重试。

客户端处理规则：

1. 查询资料时，agency == null 是正常空状态，不弹错误。
2. 查询房间时，rooms == [] 是正常空列表，不弹错误。
3. 修改资料成功后，用返回的 data.agency 刷新页面，不要用 owner 用户资料覆盖。
4. 修改失败时保留本地未保存状态，让用户可以重试。
5. 所有失败日志记录 request_id。

相关 IM

无。Agency 资料修改和 Agency 房间列表不会下发新的 IM；房间卡片里的 im_group_id 只用于进入房间时加入腾讯云 IM 房间群。