docs(plans): 留痕 K57 视频首帧防闪

docs/plans/INBOX.md

@@ -1,19 +1,23 @@
-## [已处理] 2026-10-20 | K56-A 失败页增加「手动设置服务地址」（仅 debug，仅 App 端）
+## [已处理] 2026-10-20 | K57-A iOS 视频未加载诊断 + 封面→视频切换防闪（仅 App 端）
 
-**背景**
-iOS 真机日志显示：`127.0.0.1` 拒绝、`192.168.31.187:8081` 与 `39.162.50.99:8081` 均 `No route to host (errno 65)`。Mac 侧后端正常、防火墙已放行 java。属于设备网络不可达（不同网段 / 本地网络权限被拒 / 无互联网），需要让用户能不改包直接切换服务地址排查。
+**用户指令（2026-10-20，原文）**：
+> 「iOS 视频资源未加载出来 显示封面有另一个问题 会闪屏 封面会闪一下」
 
 **口径（只改 Flutter，不动后端、不改接口）**
-1. `kDebugMode` 下，首页/剧场失败页在重试按钮下方增加「设置服务地址」文字按钮（Key `catalog-debug-endpoint-edit`）：
-   - 打开对话框：预填 `AppConfig.apiBaseUrl`，用户可输入 `http://IP:端口`；
-   - 确认后 `ServerEndpoint.save(input)` → `AppConfig.probeAndApplyBaseUrl()` → `catalog.load()`；
-   - 校验非法地址时对话框内红字提示（`ServerEndpoint.normalize` 为空）。
-2. 对话框附提示文字：「手机需与电脑同一 Wi-Fi，并在 iOS 设置-隐私与安全性-本地网络 中允许本应用」。
-3. release 构建不显示该入口。
-4. 现有 debug 信息两行（K55-A）保留。
+
+1. 视频状态可观测（仅 `kDebugMode`）：
+   - 播放页/首页 feed 在封面占位右下角显示 11 号小字（Key `player-debug-video`）：`initialized` / `buffering` / `error: <controller.value.errorDescription>` / `loading`；
+   - 状态变化时 `debugPrint('[video] init=... err=... url=<脱敏后的 host:port>')`。
+2. 封面→视频防闪：
+   - 封面占位（`player-fallback-background`）始终作为底层背景保留；
+   - 视频层用 `AnimatedOpacity`（200ms）淡入，条件为 `value.isInitialized && value.size.width > 0` 且已收到首帧（`ValueListenableBuilder` 里用 `value.position > Duration.zero || value.isPlaying` 判定，或监听首帧后置位）；
+   - 未完成淡入前不卸载封面，避免「封面消失 → 黑帧 → 视频」造成的闪一下；
+   - 切换过程中不重建 `VideoPlayer` 组件（保持同一个 controller 与 Key）。
+3. iOS 视频源排查辅助：debug 下若 `controller.value.hasError`，在封面占位中央显示错误摘要（最多 3 行，Key `player-video-error`），并保留现有重试入口。
+4. Android 行为不变（有封面时同样走淡入）。
 
 **测试/门禁**
-- 单测：debug 模式失败页出现入口，输入合法地址后调用 save + probe + load；非法地址不保存并提示；
+- 新增：未初始化时封面可见且视频 opacity 0；初始化后 200ms 内过渡到 1；有错误时出现 `player-video-error` 且封面仍在；
 - `dart analyze lib test` 零告警 + `flutter test` 全过 + `flutter build apk --debug`。
 
-**流程**：从 `develop` 拉 `feature/flutter-k56-endpoint-editor`；作者 `Zhou Weidong <502333560@qq.com>`；`--no-ff` 合回 develop 并 push；PROGRESS 留痕；真机验收由用户执行。
+**流程**：从 `develop` 拉 `fix/ios-k57-video-flash`；作者 `Zhou Weidong <502333560@qq.com>`；`--no-ff` 合回 develop 并 push；PROGRESS 留痕；iOS 复现由用户执行（把 `player-debug-video` 的文案发回来即可定位视频源问题）。

docs/plans/PROGRESS.md

@@ -21979,6 +21979,36 @@ Running Gradle task 'assembleDebug'...
 
 解读：静态检查零告警，468 条测试全部通过，debug APK 构建成功。工作区无锁文件残留。iOS 真机可打开 debug 失败页手动切换服务地址，实际连通性由用户验收。
 
+## 2026-10-20 ReelShort：K57-A 视频首帧诊断与防闪
+
+- 前置状态：K56-A 已完成并合并，develop 合并提交 `ca67765`。
+- 分支：`fix/ios-k57-video-flash`
+- 功能提交：`6b39701 fix(flutter): 修复 iOS 视频首帧闪屏`
+- develop 合并提交：`576f2b9 merge: 合并 K57 视频首帧防闪`，已推送。
+- 新增共用 `PlayerVideoSurface`：封面 `player-fallback-background` 始终保留为底层，视频层使用 200ms `AnimatedOpacity`，仅在初始化、尺寸有效且首帧播放进度/播放状态到位后淡入；视频未重建，controller 与 `VideoPlayer` Key 保持稳定。
+- debug 下右下角显示 `player-debug-video` 状态：initialized / buffering / error: 描述 / loading；状态变化输出 `[video] init=... err=... host=host:port`。
+- debug 下视频错误时封面中央显示 `player-video-error`，最多 3 行；现有票据错误重试入口未改动。播放页与首页 feed 均复用同一组件。
+
+测试：新增未初始化封面可见且 opacity 0、初始化后 200ms 淡入到 1、错误摘要出现且封面仍保留的组件测试，并保持播放页回归通过。
+
+门禁原始输出：
+
+```text
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+
+$ flutter test
+00:46 +471: All tests passed!
+
+$ flutter build apk --debug
+Running Gradle task 'assembleDebug'...
+   8.1s
+✓ Built build/app/outputs/flutter-apk/app-debug.apk
+```
+
+解读：静态检查零告警，471 条测试全部通过，debug APK 构建成功。工作区无锁文件残留。iOS 复现时查看 `player-debug-video` 文案或 Xcode 中 `[video]` 日志即可定位视频源状态。
+
 ## 2026-10-20 ReelShort：K53-A 详情页首帧直出
 
 - 前置状态：K52-A 已完成并合并，develop 合并提交 `a11ba50`。