# 游戏标签接口

---

商户在后台「游戏标签」维护的玩家端标签，经「站点内容配置 - 标签区块」摆放到**首页**与**游戏大厅**两个区块，用于对应页面按标签聚合展示游戏。

标签的摆放由【[站点配置](500_site_content.md#config)】的 `game_tag_ids`（首页）/ `lobby_game_tag_ids`（游戏大厅）字段下发：两者均为**已按摆放顺序排列的标签 ID 字符串数组**，不含标签内容。前端把区块的 ID 数组一次性传入本章节的【[标签详情（含游戏）](#tag_detail)】获取标签名称与嵌套的在架游戏后渲染区块；已删除 / 停用的标签 ID 会被服务端**静默跳过**，不在返回列表中占位。

---

## 标签详情（含游戏） {#tag_detail}

按标签 ID 批量返回各标签的元数据及其下嵌套的**全部**在架游戏，**无需登录**、无分页。

- `items` 按传入 `tag_ids` 顺序返回（重复 ID 去重）；不存在 / 已删除 / 已停用的标签**静默跳过不占位**。
- 每个标签的 `games` 按标签内排序下发（`sort_order` 升序，同值按加入标签时间先后），**仅包含当前在架的游戏**（已下架 / 被移出商户游戏库的游戏自动剔除），可能为空数组。
- `count` = `games` 长度，供「共 N」文案直接显示。
- 结果按商户 + 单标签缓存约 **5 分钟**（两区块同标签复用同一缓存），不做主动失效：标签内容 / 标签-游戏关系 / 游戏上下架的变更**最长 5 分钟后生效**，前端无需额外处理。

**URL:** `GET` /game/tag_detail

**Query:**

参数 | 类型 | 必填 | 说明
---|---|---|---
tag_ids | string | 是 | 标签 ID，多个用英文逗号分隔（单次最多 50 个），取自【[站点配置](500_site_content.md#config)】的 `game_tag_ids` / `lobby_game_tag_ids`

**输出:**

字段 | 类型 | 说明
---|---|---
items | list<object\> | 标签列表，按传入顺序；无效标签已跳过，元素结构见下表

**items 元素:**

字段 | 类型 | 说明
---|---|---
id | string | 标签 ID
name | string | 标签名称
sort_order | int | 商户侧排序值；**渲染顺序以站点配置 ID 数组顺序为准**，前端无需按此字段重排
count | int | 该标签实际下发的游戏数（= `games` 长度）
games | list<object\> | 标签下在架游戏列表，元素结构见下表

**games 元素:**

字段 | 类型 | 说明
---|---|---
id | string | 游戏 ID
provider_game_code | string | 游戏代码，可直接作为【[启动游戏](300_game.md#launch)】的 `internal_code`
game_name | string | 游戏名称
cover_url | string | 封面 URL
landscape_cover_url | string | 横版封面 URL，未配置时为空串
game_type | string | 游戏类型 code
provider_id | string | 厂商 ID
rtp | string | 标称 RTP（理论返还率，百分数，两位小数，如 `96.75`）；未配置时不返回该字段，仅供展示，不代表实际返奖

**示例:**

请求：`GET /game/tag_detail?tag_ids=7381296532185088001,7381296532185088002`

```json
{
  "items": [
    {
      "id": "7381296532185088001",
      "name": "Hot",
      "sort_order": 1,
      "count": 2,
      "games": [
        {
          "id": "7381300112233445501",
          "provider_game_code": "PG_fortune_tiger",
          "game_name": "Fortune Tiger",
          "cover_url": "https://cdn.example.com/games/fortune_tiger.png",
          "landscape_cover_url": "https://cdn.example.com/games/fortune_tiger_h.png",
          "game_type": "slots",
          "provider_id": "7381299001122334401"
        },
        {
          "id": "7381300112233445502",
          "provider_game_code": "PG_fortune_ox",
          "game_name": "Fortune Ox",
          "cover_url": "https://cdn.example.com/games/fortune_ox.png",
          "landscape_cover_url": "",
          "game_type": "slots",
          "provider_id": "7381299001122334401"
        }
      ]
    }
  ]
}
```

**错误情况:**

- `tag_ids` 中不存在 / 已删除 / 已停用的标签**不报错**，直接从 `items` 中缺席（站点配置中可能残留已删标签的 ID，属正常情况）；全部无效时 `items` 为空数组。
- 去重后超过 50 个 ID：返回业务错误 `单次最多查询 50 个标签`。

**与站点配置的配合流程:**

1. 调【[站点配置](500_site_content.md#config)】拿到 `game_tag_ids`（首页）或 `lobby_game_tag_ids`（游戏大厅）。
2. 把整个 ID 数组逗号拼接后一次调本接口，按 `items` 顺序渲染「标签名称 + 共 N + 游戏卡片」区块。
3. `games` 为空数组的标签建议不渲染该区块。