# 赛事直播子表与多线路播放设计

## 背景

当前赛事数据只在 `la_match.live_url` 中保存单个第三方直播链接，存在几个限制：

- 无法为同一场赛事维护多条直播线路
- 无法保存同一线路解析出的多种播放流地址
- 无法区分人工维护的入口链接和程序抓取的真实播放地址
- 前台比赛详情页只能展示单个直播入口，无法切换播放流

本次改造需要把“赛事直播”从主表单字段升级为“赛事 -> 直播线路子表”，同时保留 `la_match.live_url` 作为兼容字段。

## 目标

1. 新增赛事直播子表，一场赛事可维护多条直播线路。
2. 每条线路保存 4 个播放地址：
   - `play_url_flv`
   - `play_url_hd_flv`
   - `play_url_m3u8`
   - `play_url_hd_m3u8`
3. 直播抓取逻辑放到 `docker/crawler`，按现有 Python crawler 惯例接入。
4. 后台赛事列表改成“主表 + 展开子表”的直播线路管理方式。
5. 前台比赛详情页展示多条直播线路，并允许用户自由切换播放流。
6. 保留 `la_match.live_url`，自动回填为该赛事“最早新增的一条直播线路”的 `source_url`。

## 非目标

- 本轮不改 PC 前台直播 UI。
- 本轮不增加直播抓取历史日志表。
- 本轮不抽象多站点通用抓取框架，只先支持当前已知直播站解析。

## 当前现状

### 数据层

- 赛事主表：`la_match`
- 兼容直播字段：`la_match.live_url`
- 当前没有直播子表

### 后台

- `admin/src/views/match/lists/index.vue` 编辑弹窗中直接维护 `live_url`
- `server/app/adminapi/logic/match/MatchLogic.php` 允许编辑 `live_url`

### 前台

- `server/app/api/controller/MatchController.php::detail()` 返回单个 `live_url`
- `uniapp/src/pages/match_detail/match_detail.vue` 只渲染单个直播入口卡

### 调度

- Docker crawler 任务由 `docker/crawler/main.py` 注册 action
- `docker/crawler/config/crawler_tasks.yaml` 维护 Docker 内部 cron
- `la_dev_crontab` 仍保留任务记录，用于后台展示和沿用“已迁移到 Docker”惯例

## 总体设计

### 方案选型

采用“单子表保存当前线路状态”的方案，不新增抓取历史表。

每条直播线路在子表中保留当前最新抓取结果；抓取失败时保留旧值，不清空历史可用地址。

### 设计总览

1. 新增 `la_match_live` 子表。
2. 后端新增 `MatchLive` 模型、adminapi 线路管理接口、前台详情聚合返回。
3. 后台赛事列表新增展开子表，替换原单字段 `live_url` 手工编辑。
4. `docker/crawler` 新增 `match_live_stream` Python 任务，每分钟执行一次。
5. 比赛详情页新增多线路展示和播放流切换，默认使用 `play_url_m3u8`。

## 数据模型设计

### 新增数据表

表名：`la_match_live`

建议字段：

- `id` bigint unsigned，主键
- `match_id` int unsigned，关联 `la_match.id`
- `title` varchar(255)，直播标题
- `source_url` varchar(500)，指向网址
- `play_url_flv` varchar(1000)，标清 flv
- `play_url_hd_flv` varchar(1000)，高清 flv
- `play_url_m3u8` varchar(1000)，标清 m3u8
- `play_url_hd_m3u8` varchar(1000)，高清 m3u8
- `fetch_status` tinyint unsigned，抓取状态
  - `0` = pending
  - `1` = success
  - `2` = failed
- `fetch_error` varchar(500)，最近一次抓取错误信息
- `last_fetch_at` int unsigned，最近抓取时间
- `next_fetch_at` int unsigned，下次抓取时间
- `create_time` int unsigned
- `update_time` int unsigned
- `delete_time` int unsigned nullable

### 索引与约束

- 主键：`id`
- 唯一约束：`uk_match_source_url (match_id, source_url)`
- 普通索引：
  - `idx_match_id (match_id)`
  - `idx_next_fetch_at (next_fetch_at)`
  - `idx_fetch_status (fetch_status)`
  - `idx_match_create_time (match_id, create_time)`

### 模型约定

- 新增模型：`server/app/common/model/match/MatchLive.php`
- 继续沿用 `BaseModel`
- 使用 `create_time / update_time / delete_time` 与现有 `la_match` 保持一致

## 兼容规则

### `la_match.live_url`

保留 `la_match.live_url`，但不再允许后台人工直接维护。

自动回填规则：

- 若赛事存在直播线路，则回填“该赛事最早新增的一条直播线路”的 `source_url`
- 若赛事不存在直播线路，则将 `la_match.live_url` 置空

触发时机：

- 新增线路后
- 编辑线路 `source_url` 后
- 删除线路后
- 恢复已删除线路后（若后续有恢复能力）

### 前台兼容

`/api/match/detail` 继续返回：

- `live_url`：旧兼容字段
- `live_list`：新多线路列表

旧页面仍可只使用 `live_url`，新页面优先使用 `live_list`。

## 后台设计

### 页面交互

页面：`admin/src/views/match/lists/index.vue`

改造为：

- 赛事主表保留现有字段
- 新增展开列
- 展开后展示当前赛事的直播线路子表

子表字段：

- 直播标题
- 指向网址
- 主播放流（`play_url_m3u8`）
- 高清 m3u8（`play_url_hd_m3u8`）
- 标清 flv（`play_url_flv`）
- 高清 flv（`play_url_hd_flv`）
- 抓取状态
- 最近抓取时间
- 创建时间
- 更新时间

### 后台操作

子表提供：

- 新增线路
- 编辑线路
- 删除线路

人工可维护字段仅有：

- `title`
- `source_url`

以下字段只读：

- 4 个播放地址
- `fetch_status`
- `fetch_error`
- `last_fetch_at`
- `next_fetch_at`
- `create_time`
- `update_time`

### 旧字段替换

从赛事编辑弹窗中移除可编辑的 `live_url` 输入框。

可选保留只读展示：

- 字段名：`兼容主链接（自动）`
- 值：`la_match.live_url`

### adminapi 接口

新增控制器建议：

- `server/app/adminapi/controller/match/MatchLiveController.php`

新增接口：

- `GET /adminapi/match.matchLive/lists`
- `GET /adminapi/match.matchLive/detail`
- `POST /adminapi/match.matchLive/add`
- `POST /adminapi/match.matchLive/edit`
- `POST /adminapi/match.matchLive/delete`

新增对应层：

- `lists/match/MatchLiveLists.php`
- `logic/match/MatchLiveLogic.php`
- `validate/match/MatchLiveValidate.php`

`match.match/edit` 只维护赛事本身字段，不再接收人工写入的 `live_url`。

## 前台接口设计

### `/api/match/detail`

在现有赛事详情返回结构上新增 `live_list`。

`live_list` 单项字段：

- `id`
- `title`
- `source_url`
- `play_url_flv`
- `play_url_hd_flv`
- `play_url_m3u8`
- `play_url_hd_m3u8`
- `fetch_status`
- `last_fetch_at`
- `update_time`
- `default_play_url`
- `stream_options`

#### `default_play_url`

固定优先取值顺序：

1. `play_url_m3u8`
2. `play_url_hd_m3u8`
3. `play_url_flv`
4. `play_url_hd_flv`

当前业务上默认以 `play_url_m3u8` 作为主播放流。

#### `stream_options`

后端组装为可直接渲染的数组，顺序固定：

1. `M3U8` -> `play_url_m3u8`
2. `HD M3U8` -> `play_url_hd_m3u8`
3. `FLV` -> `play_url_flv`
4. `HD FLV` -> `play_url_hd_flv`

空值不返回。

## uniapp 页面设计

页面：`uniapp/src/pages/match_detail/match_detail.vue`

### 直播区域

将当前单个“直播详情”入口卡改造成“直播线路列表”。

每条线路展示：

- 直播标题
- 最近更新时间
- 抓取状态
- 默认播放流标识

### 播放行为

用户点击某条线路后：

- 进入独立播放页或播放器弹层
- 默认使用 `default_play_url`
- 播放流切换区展示 `stream_options`
- 用户可自由切换 4 条播放流

若某个流为空，则不展示该流的切换按钮。

### 兜底行为

- 若 `live_list` 不为空，优先渲染 `live_list`
- 若 `live_list` 为空但 `live_url` 有值，则保留旧入口卡
- 若两者都为空，则不显示直播区域

### 打开源网页

播放器区域保留“打开源网页”按钮，跳转 `source_url`，作为播放器兼容性兜底。

## Docker / Python 抓取设计

### 任务入口

新增文件：

- `docker/crawler/match_live_stream.py`

在 `docker/crawler/main.py` 注册 action：

- `match_live_stream`

### Docker 调度

在 `docker/crawler/config/crawler_tasks.yaml` 新增任务：

- `key: match_live_stream`
- `name: 赛事直播流抓取`
- `action: match_live_stream`
- `cron: "*/1 * * * *"`

### `la_dev_crontab` 记录

新增一条后台可见任务记录：

- `name`: 赛事直播流抓取
- `command`: `crawler`
- `params`: `match_live_stream`
- `expression`: `* * * * *`

这条记录沿用当前项目的“迁移到 Docker crawler”惯例：

- 后台可展示
- 真实执行由 Docker 调度
- PHP `crontab` 不直接执行抓取逻辑

## 抓取调度规则

### 选取规则

每分钟执行一次，从 `la_match_live` 中选择：

- `next_fetch_at <= now`
- 未删除

排序：

- `next_fetch_at asc`
- `id asc`

每轮限制 `20-50` 条，首版建议 `30` 条。

### 新线路 / 未完整抓取线路

判定为“未完整抓取”：

- 4 个播放地址中任意一个为空，或至少主流地址 `play_url_m3u8` 为空

行为：

- 新增或编辑 `source_url` 后立即置为 `fetch_status = 0`
- `next_fetch_at = now`
- 若抓取失败，`next_fetch_at = now + 60`

### 已抓到地址的线路

若线路已有可用播放地址：

- 抓取成功：`next_fetch_at = now + 600`
- 抓取失败：保留旧值，`next_fetch_at = now + 600`

### 解析来源

抓取入口为 `source_url`。

首版仅支持当前确认的直播站页面解析逻辑，不抽象成复杂通用框架。

### 播放地址回填

抓取成功后更新：

- `play_url_flv`
- `play_url_hd_flv`
- `play_url_m3u8`
- `play_url_hd_m3u8`
- `fetch_status = 1`
- `fetch_error = ''`
- `last_fetch_at = now`
- `next_fetch_at = now + 600`
- `update_time = now`

抓取失败后更新：

- `fetch_status = 2`
- `fetch_error = 最近错误`
- `last_fetch_at = now`
- `next_fetch_at = now + 60` 或 `now + 600`（视线路是否已有可用地址）
- `update_time = now`

## 稳定性设计

### 锁

`match_live_stream` action 增加跨进程锁，避免 Docker cron 重入。

### 超时

- 单条线路抓取需要超时
- 整个 action 在 `docker/crawler/main.py` 中配置 action 级别超时

### 失败保护

抓取失败时不得清空已有播放地址，避免前台线路因为一次失败整体不可用。

## 错误处理

- 页面结构变更导致解析不到 4 个地址时：
  - 新线路维持 `pending/failed`
  - 老线路保留旧地址
- 删除直播线路后，立即重新计算 `la_match.live_url`
- 后台人工编辑 `source_url` 后，播放地址字段只由 Python 任务刷新

## 代码改造范围

### server

- `server/app/common/model/match/MatchLive.php`
- `server/app/adminapi/controller/match/MatchLiveController.php`
- `server/app/adminapi/lists/match/MatchLiveLists.php`
- `server/app/adminapi/logic/match/MatchLiveLogic.php`
- `server/app/adminapi/validate/match/MatchLiveValidate.php`
- `server/app/adminapi/logic/match/MatchLogic.php`
- `server/app/api/controller/MatchController.php`

### admin

- `admin/src/api/match.ts`
- `admin/src/views/match/lists/index.vue`

### uniapp

- `uniapp/src/pages/match_detail/match_detail.vue`
- 如需独立播放页，再新增对应页面及路由注册

### docker/crawler

- `docker/crawler/match_live_stream.py`
- `docker/crawler/main.py`
- `docker/crawler/config/crawler_tasks.yaml`
- 对应测试文件

### docs/sql

- 新建 `create_match_live_table.sql`
- 新建 `insert_crontab_match_live_stream.sql`
- 如需停用旧逻辑，再补停用 SQL

## 验证方案

### 后端

- `php -l` 覆盖新增/修改的 PHP 文件
- 静态/最小回归脚本覆盖：
  - 直播线路新增、编辑、删除
  - `la_match.live_url` 自动回填
  - `/api/match/detail` 返回 `live_list`

### Python crawler

单测覆盖：

- 目标站解析出 4 个播放地址
- 失败时保留旧地址
- 新线路 1 分钟重试
- 已抓地址线路 10 分钟更新
- 互斥锁防重入

### 管理后台

- 展开子表展示
- 子表新增、编辑、删除
- 播放地址只读展示
- `npm run build`

### uniapp

- 比赛详情页展示多条直播线路
- 默认使用 `play_url_m3u8`
- 允许手动切换流
- 空流不展示切换按钮
- `npm run build:h5`

## 上线边界

本轮改造包含：

- `server`
- `admin`
- `uniapp`
- `docker/crawler`
- `docs/sql`

本轮不包含：

- PC 前台直播线路 UI
- 抓取历史日志表
- 多站点通用解析抽象

## 风险点

1. 第三方直播站页面结构可能变更，导致解析失败。
2. `m3u8` / `flv` 地址多为时效链接，抓取周期与前台展示需要允许“旧值短期继续可用”。
3. `uniapp` 不同平台对直链播放兼容性不同，因此必须保留 `source_url` 跳转兜底。
4. 后台一旦放开人工编辑播放地址，容易与爬虫更新冲突，因此必须禁止手改播放地址字段。

## 实施顺序建议

1. 建表 + 后端模型与逻辑
2. 后台子表接口与 UI
3. Python crawler 与 Docker 调度
4. 前台 `/api/match/detail` 聚合
5. uniapp 多线路播放 UI
6. SQL、回归测试、部署验证