docs(plans): 记录 K25 详情页与播放器

2026-10-19 15:17:34 +08:00
1 parent f21a334ca8
commit c69327062b
@@ -0,0 +1,79 @@
+# 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>`。真机验收由用户执行。
+
@@ -20,7 +20,7 @@

 ---

-## [待处理] 2026-10-19 | K25 客户端详情页 + 播放器对齐设计稿
+## [已完成·待用户验收] 2026-10-19 | K25 客户端详情页 + 播放器对齐设计稿

 **用户指令（2026-10-19）**：「开始实现详情页和播放器」。
 > 设计权威：`docs/design/screens/03-detail.html`、`04-player.html`（origin/main 或 `/tmp/specs-design/docs/design/screens/`）。
@@ -4945,3 +4945,66 @@ ReelShort `develop` 与 `feature/flutter-k24-design-system` 已推送。
   清空恢复；有观看记录时显示 Continue Watching，无记录时不显示。
 4. 点 Me，确认账号内容与 History/Watchlist/Liked 在同一页；切回 Home 播放进度与收藏状态保留。
 5. 深色/浅色系统、320×568 与 390×844 小屏检查无溢出、文字不截断。
+
+### K25 客户端详情页 + 播放器（2026-10-19）
+
+范围：详情页与 `homeMode=false` 卡片播放器；`homeMode=true` 首页沉浸 feed 保持 K24 现状。
+
+详情页：
+
+- 16:9 hero（当前模型只有 `posterUrl`）、底部渐变、玻璃返回/分享/收藏/更多。
+- 集数 pill、24px 标题、Season 副标题、`viewCount`、题材标签；评分/完结/榜单项无字段隐藏。
+- 16px 玻璃简介卡，2 行 + More/Less。
+- 橙色全宽 Start Watching/继续观看 + 48×48 收藏/下载；举报保留在更多菜单。
+- Episodes 标题 + All 范围 chip；46×44 横向集数 chips，锁定项紫色；2 列剧集卡，
+  390 宽下缩略图实测 96×64，含 Free/Coin、时长、锁态与下载入口。
+
+播放器（从详情进入）：
+
+- 顶部返回、剧名 + Ep.x、更多（下载/PiP）。
+- 9:10 圆角 16 视频框、Auto-Next/1.0x pill、中心橙色播放、右侧 36px 点赞/全屏。
+- 1.5px 进度条：白色 30% 缓冲、`#FF5B3D` 播放段、白色 thumb；左中右时间/集数信息，保留拖动 seek。
+- Episodes / Comments / Next Ep 三按钮；末集 Next 置灰。
+- `PlayerFeaturedComment` 复用 `CommentController`，无评论隐藏；VIP/总数无字段不显示。
+- 保留票据三态、自动连播、PiP、下载、点赞/收藏/评论与播放会话协议。
+
+数据缺口：`coverUrl`、评分、完结、Top 排名、Trailer/4K、VIP、剧级点赞/评论总数、场景标签、
+集数范围、倍速能力均无模型字段；按 INBOX 隐藏或不伪造。
+
+门禁原始输出：
+
+```text
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+
+$ flutter test
+00:30 +352: All tests passed!
+
+$ flutter build apk --debug
+Running Gradle task 'assembleDebug'...                             26.3s
+✓ Built build/app/outputs/flutter-apk/app-debug.apk
+```
+
+构建说明：主工作区仍有用户侧 `flutter run`，因此在 `/tmp/reelshort-k25-final`
+独立 worktree 执行 `flutter pub get` 与 `flutter build apk --debug`，避免并发占用 `build/`。
+
+Git：
+
+```text
+ec163f9 feat(detail): 重做详情页视觉结构
+689063a feat(player): 新增卡片式播放器
+04fddce merge: K25 客户端详情页与播放器
+```
+
+提交与合并 author/committer 均为 `Zhou Weidong <502333560@qq.com>`。
+ReelShort `develop` 与 `feature/flutter-k25-detail-player` 已推送。
+
+真机验收步骤（设备侧取证由用户执行）：
+
+1. 从首页/发现进入详情，检查 16:9 hero、玻璃按钮、集数/播放量/题材、简介展开。
+2. 点 Start Watching，确认进入卡片播放器：9:10 视频框、进度条、三按钮行。
+3. 拖动进度条、切换下一集、末集按钮置灰；点 Episodes/Comments 打开现有弹窗。
+4. 有评论时检查精选评论卡与 View all；无评论时应隐藏。
+5. 从播放器更多菜单验证下载/PiP；点全屏进入横屏，退出后回到卡片布局。
+6. 检查收藏、举报、续看进度、票据失败重试与自动连播未回退。