# K25 计划：客户端详情页 + 播放器对齐设计稿

日期：2026-10-19
基线：`ReelShort/develop` = `4553606`
分支：`feature/flutter-k25-detail-player`

## 一、范围

只改详情页与 `homeMode=false` 的播放器：

- 详情页：16:9 hero、玻璃导航、元数据、简介展开、CTA、选集 chips、2 列剧集卡。
- 卡片播放器：顶部导航、9:10 视频框、进度条、三按钮行、精选评论卡。
- `homeMode=true` 的 K24 首页沉浸 feed 保持现状。

不改：后端接口/模型字段、首页、发现页、我的页、登录页、`playback_session`/ticket 协议。

## 二、设计口径

沿用 K24 Obsidian Flare token、Outfit/Plus Jakarta Sans、`GlassPanel`。

详情页结构：

1. 16:9 hero（当前模型只有 `posterUrl`，作为 hero 图；无 `coverUrl` 字段）。
2. 左侧玻璃返回，右侧分享/收藏/更多（举报在更多菜单）。
3. 集数 pill、24px 标题、Season 副标题、viewCount、题材标签。
4. 16px 简介卡，2 行 + More/Less。
5. 橙色全宽 CTA + 48×48 收藏/下载，续看进度与错误重试保留。
6. Episodes 标题 + 范围 chip（无区间数据时显示 All）+ 46×44 横向集数 chips。
7. 2 列剧集预览卡：缩略图 96×64、Free/Coin、时长、锁态、下载/播放入口。

播放器结构（`homeMode=false`）：

1. 顶部返回、剧名 + Ep.x、更多（下载/PiP）。
2. 9:10 圆角 16 视频框，Auto-Next/1.0x pill、中心橙色播放、右侧点赞/全屏。
3. 1.5px 进度条，白色缓冲、橙色播放、白色 thumb；保留拖动 seek。
4. Episodes / Comments / Next Ep 三按钮；末集 Next Ep 置灰。
5. 精选评论卡复用 `CommentController`，无评论隐藏；VIP/总评论数字段缺失时隐藏。

## 三、TDD 顺序

1. 详情 widget 测试：hero 16:9、CTA 行、简介展开、集数 chips、2 列剧集卡。
2. 详情实现：先复用现有 `DramaDetailLogic`，只重排视图和控件。
3. 播放器 widget 测试：卡片模式结构、三按钮行、进度条颜色/thumb、末集禁用。
4. 播放器实现：新增卡片布局，保留原全屏 feed；复用 ticket/session/queue。
5. 回归：PiP、票据错误、进度、收藏、下载、举报、评论、自动连播。

## 四、数据缺口

| 设计字段 | 模型状态 | 处理 |
| --- | --- | --- |
| coverUrl | 无（只有 posterUrl） | hero 使用 posterUrl |
| 评分 | 无 | 隐藏 |
| 完结状态 | 无 | 隐藏 |
| Top 排名 | 无 | 隐藏 |
| Trailer/4K | 无 | 隐藏 |
| VIP | 无 | 隐藏 |
| 剧级点赞/评论总数 | 无 | 只显示文案/已加载数量，不伪造 |
| 场景标签 | 无 | 隐藏 |
| 集数范围 | 无 | 显示 All chip |
| 倍速能力 | 无播放速率接口 | 显示 1.0x，不伪造切换能力 |

## 五、风险

- 卡片播放器切换全屏时复用同一 `PageController`；只在二者之一挂载，避免控制器绑定两个 PageView。
- 自动连播依赖 PageController 动画，卡片模式保留 PageView 作为视频底层。
- 评论卡新增一次评论首屏请求；无评论/失败时直接隐藏，不影响播放。
- 详情页 hero、2 列剧集卡在小屏下需自适应缩略图宽度，避免溢出。

## 六、门禁与 Git

```bash
dart analyze lib test
flutter test
flutter build apk --debug
```

完成后 `--no-ff` 合并回 `develop` 并 push；作者/提交者
`Zhou Weidong <502333560@qq.com>`。真机验收由用户执行。