# 金牌 Python 爬虫设计

## 目标

在当前 Python 仓库中新增一个符合 `base.spider.Spider` 接口的金牌爬虫，行为参考用户提供的 JS 版本，覆盖以下能力：

- 首页分类与筛选
- 首页推荐
- 分类浏览
- 搜索
- 详情解析
- 播放解析

实现形式遵循当前仓库的单文件 Spider 约定和离线单测约定，不引入新的公共基类。

## 范围

本次实现包含：

- 新增独立脚本 `py/金牌.py`
- 新增独立测试 `py/tests/test_金牌.py`
- 实现带签名头的匿名 API 请求
- 动态拉取分类与筛选
- 首页返回热门推荐
- 分类支持类型、剧情、地区、语言、年份、排序筛选
- 搜索支持分页与空关键词保护
- 详情组装基础元数据与单线路剧集
- 播放接口返回多清晰度直链列表

本次实现不包含：

- 修改 `base/` 公共层
- 引入新的第三方依赖
- 真实联网集成测试
- 站点探活、容灾切换或缓存
- 参考 JS 的 HTTP 路由包装层

## 方案选择

采用“单文件 Spider + helper + 单测”的直接适配方案，而不是抽象新的签名 API 基类。

原因如下：

- 当前仓库绝大多数站点都以单文件 Spider 交付，新增公共基类会放大本次范围
- 参考实现已经清晰给出了接口路径、签名算法和字段映射，直接适配风险最低
- 当前需求重点是完整还原站点能力，而不是为未知后续站点提前抽象

## 模块边界

新增 `py/金牌.py`，只在模块内部维护站点逻辑，不修改 `base/`。

对外实现以下接口：

- `init`
- `getName`
- `homeContent`
- `homeVideoContent`
- `categoryContent`
- `searchContent`
- `detailContent`
- `playerContent`

模块内部拆分以下 helper：

- `_obj_to_form`
  - 将请求参数按 `k=v&...` 拼接，忽略空值
- `_signed_headers`
  - 根据请求参数、`APP_KEY` 和时间戳生成签名头
- `_fetch_json`
  - 统一发起 GET 请求、校验状态码并解析 JSON
- `_map_vod`
  - 统一列表项字段映射
- `_build_filters`
  - 请求分类接口与筛选接口并组装首页筛选结构
- `_page_result`
  - 统一分类和搜索的分页返回结构
- `_build_play_id`
  - 将主视频 ID 与分集 ID 组合成短播放 ID
- `_parse_play_id`
  - 解析 `主ID@子ID` 形式的播放 ID

## 站点配置与签名策略

固定配置来自参考实现：

- 站点名：`金牌`
- 主站：`https://m.jiabaide.cn`
- 默认 UA：移动端 Chrome UA
- `Referer`：`${host}/`
- `APP_KEY`：`cb808529bae6b6be45ecfab29a4889bc`

签名规则保持与参考实现一致：

1. 取当前毫秒时间戳作为 `t`
2. 将请求参数与 `key=APP_KEY`、`t` 合并
3. 按 `k=v&...` 形式拼接
4. 先对拼接字符串做 `MD5`
5. 再对 `MD5` 结果做 `SHA1`
6. 将 `t` 和 `sign` 放入请求头

请求策略：

- 接口请求统一使用 `GET`
- 参数通过 query string 传递
- 请求头统一带 `User-Agent`、`Referer`、`t`、`sign`
- 若响应状态码不是 `2xx`，或业务 `code` 不是成功值，则返回空结果而非抛出未处理异常

## 分类与首页设计

`homeContent` 负责同时返回分类、筛选和首页推荐。

分类来源：

- `/api/mw-movie/anonymous/get/filer/type`

筛选来源：

- `/api/mw-movie/anonymous/v1/get/filer/list`

首页推荐来源：

- `/api/mw-movie/anonymous/home/hotSearch`

筛选字段映射遵循参考实现：

- `typeList -> key=type, name=类型`
- `plotList -> key=class, name=剧情`
- `districtList -> key=area, name=地区`
- `languageList -> key=lang, name=语言`
- `yearList -> key=year, name=年份`
- `serialList -> key=by, name=排序`

排序选项固定为：

- 最近更新 -> `1`
- 添加时间 -> `2`
- 人气高低 -> `3`
- 评分高低 -> `4`

每个筛选项都默认插入“全部”。

`homeVideoContent` 保持仓库现有习惯，返回：

- `{"list": []}`

## 列表与搜索设计

分类接口使用：

- `/api/mw-movie/anonymous/video/list`

请求参数如下：

- `type1`
  - 当前分类 ID
- `pageNum`
  - 当前页码
- `pageSize`
  - 固定 `30`
- `sort`
  - 由筛选项 `by` 映射，默认 `1`
- `sortBy`
  - 固定 `1`
- `type`
  - 子类型筛选
- `v_class`
  - 剧情筛选
- `area`
  - 地区筛选
- `lang`
  - 语言筛选
- `year`
  - 年份筛选

搜索接口使用：

- `/api/mw-movie/anonymous/video/searchByWordPageable`

请求参数如下：

- `keyword`
- `pageNum`
- `pageSize`

返回结构遵循当前仓库约定：

- `page`
- `limit`
- `total`
- `list`

其中：

- `limit` 固定为 `30`
- 默认不返回 `pagecount`
- 空关键词搜索直接返回空列表

## 列表字段映射

列表页与搜索页的单项统一映射为：

- `vod_id`
  - `vodId`
- `vod_name`
  - `vodName`
- `vod_pic`
  - `vodPic`
- `vod_remarks`
  - `vodRemarks` 与 `vodDoubanScore` 以 `_` 连接，空值自动忽略
- `vod_year`
  - 优先从 `vodPubdate` 提取年份
- `type_id`
  - `typeId`
- `type_name`
  - `typeName`

这样首页推荐、分类和搜索的列表结构保持一致。

## 详情设计

详情接口使用：

- `/api/mw-movie/anonymous/video/detail`

请求参数：

- `id`

详情返回只保留当前仓库需要的核心字段：

- `vod_id`
- `vod_name`
- `vod_pic`
- `type_name`
- `vod_remarks`
- `vod_year`
- `vod_area`
- `vod_lang`
- `vod_director`
- `vod_actor`
- `vod_content`
- `vod_play_from`
- `vod_play_url`

剧集列表来自 `episodeList`，每一集的播放 ID 设计为：

- `<vodId>@<nid>`

播放线路先收敛为单条：

- `金牌线路`

这样可以兼容仓库现有以 `vod_play_from` / `vod_play_url` 为核心的详情结构，同时避免把上游清晰度层级提前展开到详情页。

## 播放设计

播放接口使用：

- `/api/mw-movie/anonymous/v2/video/episode/url`

请求参数如下：

- `clientType=3`
- `id`
  - 主视频 ID
- `nid`
  - 分集 ID

播放页逻辑：

- 从 `主ID@子ID` 解析出 `id` 和 `nid`
- 请求上游接口拿到 `list`
- 将上游返回的多清晰度地址整理为播放器可消费的结果

播放器返回结构：

- `parse: 0`
- `playUrl: ""`
- `url`
  - 优先返回首个可用地址
- `header`
  - 至少包含移动端 `User-Agent`

不额外引入 `pagecount`、`urls` 或其他参考 JS 的扩展字段，优先保持与当前 Python 仓库播放器返回习惯一致。

同时，为了兼容仓库中部分站点会保留扩展信息，模块内部仍会保留原始清晰度列表的整理逻辑；若调用方仅消费 `url`，则使用首个可用地址即可。

异常策略：

- 播放 ID 不是 `主ID@子ID` 格式时，返回空 URL
- 上游返回空列表时，返回空 URL

## 错误处理

所有公开接口都以“尽量返回空结果”作为失败策略：

- `homeContent`
  - 失败时返回空分类、空筛选、空推荐
- `categoryContent`
  - 失败时返回 `page/limit/total/list` 的空结构
- `searchContent`
  - 失败时返回空分页结果
- `detailContent`
  - 失败时返回 `{"list": []}`
- `playerContent`
  - 失败时返回空 URL

不向上抛出未处理异常，保持与现有仓库 Spider 的容错风格一致。

## 测试设计

新增 `py/tests/test_金牌.py`，全部通过 mock 网络层验证离线行为。

至少覆盖以下测试：

1. `_signed_headers` 会写入 `t` 和正确的 `sign`
2. `homeContent` 能组合分类、筛选和首页推荐
3. `categoryContent` 能把 `by/class/area/lang/year/type` 正确映射到请求参数
4. `searchContent` 对空关键词直接返回空列表，对正常结果正确映射
5. `detailContent` 能输出基础元数据、单线路名与 `主ID@子ID` 剧集串
6. `playerContent` 能拆分播放 ID、请求上游并返回首个可用播放地址
7. 公开接口在上游异常或空数据时返回约定的空结构

测试原则：

- 不依赖真实网络
- 尽量验证最小行为单元
- 对签名和请求参数做精确断言，避免只测结果不测协议

## 风险与约束

主要风险如下：

- 上游匿名接口的业务 `code` 语义可能并不完全稳定，需要测试中明确覆盖成功与失败分支
- 参考 JS 的 `play` 返回了多清晰度数组，而仓库 Python Spider 通常以单个 `url` 为主，需要在实现中做兼容收敛
- 详情中的 `vodClass`、`vodYear`、`vodArea` 等字段可能出现缺失，需要统一空值兜底

对应约束如下：

- 优先保证仓库消费兼容性，而不是 1:1 复刻 JS 返回结构
- 不额外改动公共播放器约定
- 所有行为变化都必须由离线测试先定义再实现