FruitServer/docs/plans/INBOX.md

[已处理] 2026-10-20 | K57-A iOS 视频未加载诊断 + 封面→视频切换防闪（仅 App 端）

用户指令（2026-10-20，原文）：

「iOS 视频资源未加载出来 显示封面有另一个问题 会闪屏 封面会闪一下」

口径（只改 Flutter，不动后端、不改接口）

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 行为不变（有封面时同样走淡入）。

测试/门禁

• 新增：未初始化时封面可见且视频 opacity 0；初始化后 200ms 内过渡到 1；有错误时出现 player-video-error 且封面仍在；
• dart analyze lib test 零告警 + flutter test 全过 + flutter build apk --debug。

流程：从 develop 拉 fix/ios-k57-video-flash；作者 Zhou Weidong <502333560@qq.com>；--no-ff 合回 develop 并 push；PROGRESS 留痕；iOS 复现由用户执行（把 player-debug-video 的文案发回来即可定位视频源问题）。