# 第三方游戏后台 API

仓库里原先没有单独的第三方游戏接口文档（`docs/` 下只有财务和在线/注册两份）。这份就是正式文档，顶部先写给前端的对照说明。

所有接口需要后台登录令牌：

```http
Authorization: Bearer <token>
```

POST 使用 `Content-Type: application/json`。统一响应：`code = 0` 成功，业务数据在 `data`；失败 `code != 0`，原因在 `msg`。

图片先调已有上传接口 `POST /admin/upload/uploadFile`，把返回的 `path` 写进 `logo` / `logo_pc` / `logo_h5`。
游戏目录静态资源统一由 `bot-28/public/static/img` 托管，接口返回后台 `APP_URL` 下的完整图片 URL。

---

## 给前端：对照设计稿改了什么

接口路径没变，还是这 5 个：

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/admin/egame/options` | 筛选项、大类、平台下拉 |
| GET | `/admin/egame/items` | 大类 / 平台 / 游戏列表 |
| POST | `/admin/egame/update` | 新增或修改（含排序、图片、名称） |
| POST | `/admin/egame/setStatus` | 启用 / 停用 |
| POST | `/admin/egame/delete` | 不支持删除，返回错误 |

### 页面怎么对接口

| 设计稿页面 | 请求 |
| --- | --- |
| 游戏大类 | `GET /admin/egame/items?item_type=category` |
| 游戏列表（平台，如 JDB / AG） | `GET /admin/egame/items?item_type=platform&platform_scope=category` |
| 平台修改弹窗 | 用列表行数据回填；保存 `POST /admin/egame/update` |
| 游戏管理内页（如 JDB 电子） | `GET /admin/egame/items?item_type=game&plat_type=jdb` |
| 修改游戏（含启用停用） | `POST /admin/egame/update`，开关也可走 `POST /admin/egame/setStatus` |
| 筛选下拉 | `GET /admin/egame/options` |

「序号」前端按分页自己算：`(page - 1) * limit + index + 1`。

### 字段对照

| 设计稿文案 | 接口字段 | 说明 |
| --- | --- | --- |
| 游戏大类 ID | `game_type` | 固定枚举，不是 1~5 连续号，见下表 |
| 游戏大类名称 | `name` | |
| 游戏说明 | `description` | 本次新增 |
| PC Logo / PC 游戏图片 | `logo` 或 `logo_pc` | 两个都会返回完整 URL；保存时推荐传 `logo_pc`，两个同时传以 `logo_pc` 为准 |
| H5/APP Logo / 图片 | `logo_h5` | 返回完整 URL；未配置时为空字符串 |
| 多语言游戏图片 | `logo_langs` | 游戏行返回语言到完整 URL 的映射；未配置时为 `null` |
| 平台 ID | `id` | 行主键。不要用稿子里的 `FL01` |
| 平台类型 | `plat_type` | `jdb` / `mg` / `pg` / `ag`，小写 |
| 显示名称 / 游戏名称 | `name` | 列表筛选也用 `name` |
| 游戏 ID | `game_code` | 如 `JDB001` |
| 支持终端类型 | `ingress` | `1` 电脑网页，`2` 手机网页，`3` 电脑/手机网页 |
| 支持终端（文案） | `ingress_name` | 后端已拼好，列表直接展示 |
| 支持网络 | `network` | 存库值：`mainland` / `hk` / `kr` / `jp` / `""`。空字符串 = 不限制。不要传中文 |
| 支持网络（实际生效） | `network_effective` | 自己没填时，游戏会继承「平台+大类」行，再继承平台总开关 |
| 支持网络（文案） | `network_name` | 大陆 / 香港 / 韩国 / 日本 / 不限制 |
| 启用状态 | `status` | `1` 启用，`0` 停用 |
| 启用状态（文案） | `status_name` | |
| 排序 | `sort` | **数字越大越靠前** |
| 游戏管理按钮 | `has_game_manage` | `true` 才显示「游戏管理」 |

`options` 里新增 `networks`，并改了文案：

- `statuses`：`开启/关闭` 改为 `启用/停用`
- `ingress`：`仅电脑/仅手机/通用` 改为 `电脑网页/手机网页/电脑/手机网页`

### 和设计稿不一致、按真实业务改掉的地方

1. **平台 ID 不用 FL01~FL05**  
   那是稿子里的假编号。同一平台会挂在多个大类下（JDB 电子、JDB 捕鱼），真正唯一的是行 `id`。平台类型用 `plat_type`。

2. **游戏大类 ID 不是 1~5**  
   三方约定是：

   | game_type | 名称 |
   | ---: | --- |
   | 1 | 视讯 |
   | 2 | 电子 |
   | 3 | 彩票 |
   | 4 | 体育 |
   | 5 | 电竞 |
   | 6 | 捕鱼 |
   | 7 | 棋牌 |

   稿子里捕鱼写成 3、体育写成 4，对不上。捕鱼是 `6`，棋牌是 `7`。请用 `game_type`，不要自己重排。

3. **保留「彩票」「电竞」两个大类**  
   稿子只画了 5 个。线上目录本身就有 7 个，列表要能展示，筛选也要有。

4. **游戏分类、平台类型不能改**  
   稿子「修改游戏」里这两个是下拉。它们是三方目录主键，改了会对不上。请做成禁用展示，可以回传当前值，改了后端会报 `目录标识不允许修改`。

5. **排序越大越靠前**  
   和后台其它模块一致。稿子里 1、2、3 只是示意，不要理解成「1 排最前」。改排序只传 `{ id, sort }`。

6. **有子游戏才出「游戏管理」**  
   请判断 `has_game_manage`（该 `plat_type` 下 `game_count > 0`）。没有子游戏就只显示「修改」。

7. **不能删除**  
   `POST /admin/egame/delete` 固定失败。停用走开关。

8. **不要写入示例游戏**  
   正式服目录已经有约 4499 条。迁移只加字段，不插 JDB001 这种假数据，也不改已有平台名称/开关/排序。

---

## 正式服已有 4499 条，怎么补「正确」数据

三方目录接口本身没有「支持网络」字段，后台不能根据 plat_type 猜韩国、日本。加列之后：

| 字段 | 已有 4499 条会变成 | 谁来填正确值 |
| --- | --- | --- |
| `network` | `""`（不限制） | 运营在后台改，或跑命令 |
| `logo_h5` | `""` | 后台上传 |
| `description` | 大类补了说明；平台/游戏仍为空 | 大类已自动回填；其它不用填 |
| `ingress` | **保持原值** | 同步进来的终端类型，不要整表覆盖 |
| `name` / `status` / `sort` / `logo` | **不动** | 已有数据就是正式数据 |

网络限制按「平台+大类」一行改，不要逐条改 4000 多条游戏。

### 后台保存（推荐）

改「游戏列表」里的 JDB电子 / PG电子 这一行：

```json
{
  "id": 88,
  "network": "mainland",
  "apply_to_games": true
}
```

`apply_to_games` 默认 `true`：一次把该平台该大类下全部游戏写成同一个网络。返回里带 `applied_game_count`。

不想动游戏、只改平台行，传 `"apply_to_games": false`。游戏自己没填时，列表仍会用 `network_effective` 显示平台的网络。

JDB 电子和 JDB 捕鱼可以设成不同网络，互不影响。

### 命令行（适合一批平台）

```bash
php artisan egame:set-network mainland --plat-type=jdb --game-type=2 --dry-run
php artisan egame:set-network mainland --plat-type=jdb --game-type=2
php artisan egame:set-network hk --plat-type=mg
php artisan egame:set-network none --plat-type=pt --force
```

- 默认只改当前为空的行，可重复跑
- `--force` 覆盖已经填过的
- `--dry-run` 只看会改多少条
- `none` = 不限制
- `--game-type` 不传 = 该平台所有大类

没有业务给的对照表，后端不会预置「JDB=大陆、MG=香港」。运营定规则后改平台行或跑上面的命令即可。

菜单加了 `egame/category`（游戏大类）、`egame/list`（游戏列表），挂在「第三方游戏」下面。

---

## 1. 筛选项

### GET `/admin/egame/options`

无参数。

```json
{
  "code": 0,
  "data": {
    "categories": [
      {
        "id": 1,
        "item_type": "category",
        "game_type": 1,
        "name": "视讯",
        "description": "真人视讯游戏",
        "logo": "https://admin-api.example.com/static/img/game-type/sx.png",
        "logo_pc": "https://admin-api.example.com/static/img/game-type/sx.png",
        "logo_h5": "",
        "status": 1,
        "sort": 70,
        "platform_count": 5,
        "game_count": 0
      }
    ],
    "platforms": [
      {
        "id": 20,
        "item_type": "platform",
        "plat_type": "jdb",
        "name": "夺宝",
        "platform_scope": "global",
        "category_count": 3,
        "game_count": 3,
        "has_game_manage": true
      }
    ],
    "statuses": [
      {"value": 1, "label": "启用"},
      {"value": 0, "label": "停用"}
    ],
    "ingress": [
      {"value": "1", "label": "电脑网页"},
      {"value": "2", "label": "手机网页"},
      {"value": "3", "label": "电脑/手机网页"}
    ],
    "networks": [
      {"value": "", "label": "不限制"},
      {"value": "mainland", "label": "大陆"},
      {"value": "hk", "label": "香港"},
      {"value": "kr", "label": "韩国"},
      {"value": "jp", "label": "日本"}
    ]
  }
}
```

下拉请直接用 `value` / `label`。`categories` 给「游戏分类」，`platforms` 给「平台类型」。

---

## 2. 列表

### GET `/admin/egame/items`

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `item_type` | 否 | `category` / `platform` / `game` |
| `platform_scope` | 否 | 只对平台有效：`global` 平台总开关，`category` 平台+大类（游戏列表页用这个） |
| `plat_type` | 否 | 平台代码，游戏管理内页必带 |
| `game_type` | 否 | 大类 |
| `game_code` | 否 | 游戏 ID，精确匹配 |
| `name` | 否 | 显示名称 / 游戏名称，模糊 |
| `keyword` | 否 | 同时模糊 `name` / `plat_type` / `game_code` |
| `status` | 否 | `1` / `0` |
| `ingress` | 否 | `1` / `2` / `3` |
| `network` | 否 | `mainland` / `hk` / `kr` / `jp` |
| `page` | 否 | 默认 `1` |
| `limit` | 否 | 默认 `15`，最大 `200` |

返回 `data.total`、`data.data`。

### 2.1 游戏大类

`GET /admin/egame/items?item_type=category`

主要字段：`game_type`、`name`、`description`、`logo` / `logo_pc`、`logo_h5`、`sort`、`status`。

### 2.2 游戏列表（平台）

`GET /admin/egame/items?item_type=platform&platform_scope=category&game_type=&plat_type=&name=&status=&ingress=&network=&page=1&limit=15`

一行是「某个平台在某个大类下」的配置，例如 JDB 电子。

```json
{
  "id": 88,
  "item_type": "platform",
  "platform_scope": "category",
  "plat_type": "jdb",
  "platform_name": "夺宝",
  "game_type": 2,
  "game_type_name": "电子",
  "name": "JDB电子",
  "ingress": "3",
  "ingress_name": "电脑/手机网页",
  "network": "",
  "network_effective": "",
  "network_inherited": false,
  "network_name": "不限制",
  "logo": "",
  "logo_pc": "",
  "logo_h5": "",
  "status": 1,
  "status_name": "启用",
  "sort": 12,
  "has_game_manage": true,
  "game_count": 120,
  "effective_status": 1,
  "disabled_by": null
}
```

`has_game_manage === true` 时显示「游戏管理」，点进去带上这一行的 `plat_type`（建议同时带 `game_type` 做筛选）。

`effective_status` 是算上父级之后的实际是否可见：大类关了、或平台总开关关了，这里会是 `0`，`disabled_by` 为 `category` / `platform` / `platform_category` / `game`。行上的开关仍绑定 `status`。

### 2.3 游戏管理内页

`GET /admin/egame/items?item_type=game&plat_type=jdb&game_code=&name=&status=&ingress=&network=`

```json
{
  "id": 201,
  "item_type": "game",
  "game_code": "JDB001",
  "name": "JDB夺宝",
  "plat_type": "jdb",
  "platform_name": "夺宝",
  "game_type": 2,
  "game_type_name": "电子",
  "ingress": "3",
  "ingress_name": "电脑/手机网页",
  "network": "",
  "network_effective": "mainland",
  "network_inherited": true,
  "network_name": "大陆",
  "logo": "",
  "logo_pc": "",
  "logo_h5": "",
  "sort": 30,
  "status": 1,
  "status_name": "启用"
}
```

---

## 3. 保存

### POST `/admin/egame/update`

有 `id` 就是改，没有或 `id=0` 就是按目录标识新增/补齐。普通修改只传要改的字段即可。

| 参数 | 说明 |
| --- | --- |
| `id` | 行 ID，修改必传 |
| `name` | 显示名称 / 游戏名称 / 大类名称 |
| `description` | 游戏说明，大类用 |
| `logo` / `logo_pc` | PC 图，二选一；两个同时传时用 `logo_pc`，避免旧 `logo` 覆盖新上传图片 |
| `logo_h5` | H5/APP 图 |
| `ingress` | 终端，平台和游戏可改；大类固定为 `3` |
| `network` | 网络，平台和游戏可改；大类忽略。传 `""` 表示不限制 |
| `apply_to_games` | 改平台+大类行的 `network` 时，是否同步该平台该大类下全部游戏。默认 `true` |
| `status` | 启用停用 |
| `sort` | 排序 |
| `item_type` / `plat_type` / `game_type` / `game_code` / `platform_scope` | 目录标识，修改时不要改 |

修改大类示例：

```json
{
  "id": 1,
  "name": "视讯",
  "description": "真人视讯游戏",
  "logo_pc": "https://cdn.example.com/sx-pc.png",
  "logo_h5": "https://cdn.example.com/sx-h5.png",
  "sort": 70,
  "status": 1
}
```

修改平台示例（对应「平台游戏修改」弹窗；改网络时默认同步该行下面全部游戏）：

```json
{
  "id": 88,
  "name": "JDB电子",
  "logo_pc": "https://cdn.example.com/jdb-pc.png",
  "logo_h5": "https://cdn.example.com/jdb-h5.png",
  "network": "mainland",
  "apply_to_games": true
}
```

返回里会多 `applied_game_count`。平台修改弹窗建议加「同步到该平台游戏」，默认勾选。

修改游戏示例（对应「修改游戏」，含启用停用）：

```json
{
  "id": 201,
  "name": "JDB夺宝",
  "logo_pc": "https://cdn.example.com/jdb001-pc.png",
  "logo_h5": "https://cdn.example.com/jdb001-h5.png",
  "status": 1
}
```

改排序只传：

```json
{ "id": 88, "sort": 910 }
```

成功返回该行最新数据，字段和列表一致。

---

## 4. 启用 / 停用

### POST `/admin/egame/setStatus`

列表开关、修改弹窗里的启用停用都走这里（也可以在 `update` 里带 `status`）。

```json
{ "id": 201, "status": 0 }
```

---

## 5. 删除

### POST `/admin/egame/delete`

目录由同步任务维护，不能删。请把状态设为停用。

```json
{ "code": -3, "msg": "第三方游戏目录由同步任务维护，不能删除，请将状态设为关闭" }
```

---

## 6. 菜单 uri

| 菜单 | 前端 uri |
| --- | --- |
| 第三方游戏 | `egame` |
| 游戏大类 | `egame/category` |
| 游戏列表 | `egame/list` |

按钮权限：`admin/egame/options`、`admin/egame/items`、`admin/egame/update`、`admin/egame/setStatus`、`admin/egame/delete`。