FruitServer/docs/plans/2026-10-19-K25.md

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

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

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