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

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`。