docs(plans): 记录 K10 统一空态实施回执

2026-10-17 21:56:35 +08:00
1 parent f1d56b1040
commit 3b2afc9f47
@@ -20,7 +20,7 @@

 ---

-## [待处理] 2026-10-17 | K10 统一空列表占位（EmptyState）
+## [已处理·待用户验收] 2026-10-17 | K10 统一空列表占位（EmptyState）

 **用户指令（2026-10-17）**：「做空列表的占位图，所有的列表，要求简单大方、符合审美」。

@@ -95,6 +95,30 @@
 - 先写 `FruitServer/docs/plans/2026-10-17-K10.md`；每步「叙述 + 命令 + 原始输出 + 解读」追加到 `PROGRESS.md`；完成后停住写回执。
 - 提交作者与提交者统一 `Zhou Weidong <502333560@qq.com>`。

+### 五、K10 完成回执（2026-10-17）
+
+**结论**：新增统一 `EmptyState` 组件，任务书表格中的 10 处空态已全部替换；
+错误/加载态保持原逻辑，未引入图片、SVG、字体或接口改动。未跑真机。
+
+- 客户端分支 `feature/flutter-k10-empty-states` 从 `19babb8` 完成并
+  `--no-ff` 合并；功能提交 `6d08330`，合并提交 `0466b4b`，已推送
+  `19babb8..0466b4b develop`。
+- 默认图形 96x96、圆角 28，blue 11% 背景，图标 42；compact 为 64x64、
+  图标 28；标题 16/w600，副标题 13，操作按钮至少 44pt。
+- 深色主题图标 `blueSoft`，浅色主题图标 `blue`；外层 Semantics 只读标题，
+  图形和文本不重复朗读，操作按钮保持可访问。
+- 10 处替换完成：首页、首页分类/搜索、收藏、通知、详情剧集、我的两处、
+  下载、观看记录、评论 compact。
+- 新增三语 `emptyHint`；原有空态 l10n key、页面文案和操作行为保留。
+- 新增 `test/empty_state/empty_state_test.dart` 4 个组件用例；收藏、下载、
+  记录、通知、评论五处页面测试已断言 `EmptyState`，评论还校验 compact。
+- `dart analyze lib test` 零告警；`flutter test` 为
+  `00:18 +302 ~1: All tests passed!`；Android debug APK 在独立副本中构建成功。
+
+用户真机验证步骤与逐步预期、原始输出见
+`docs/plans/PROGRESS.md`「26. K10 统一空列表占位」。
+设备侧深色/浅色、小屏与各页面空态验收由用户执行。
+
 ---

 ## [待处理] 2026-10-17 | K9 首页剧目列表改造（2 列全部剧目）
@@ -2202,6 +2202,163 @@ $ flutter test

 ---

+## 2026-10-17 K10 统一空列表占位
+
+### 26.1 范围、分支与计划
+
+叙述：新增统一 `EmptyState`，替换任务书表格中的 10 处纯文字空态。只改空态
+视觉、三语 l10n 与测试，不改列表数据、接口、加载/失败逻辑。
+
+- 客户端分支：`feature/flutter-k10-empty-states`，基线 `19babb8`。
+- 文档分支：`docs/k10-empty-states`，基线 K10 任务书 `3f84bc6`。
+
+开工前先写并提交计划：
+
+```text
+f1d56b1 docs(plans): 增加 K10 统一空态实施计划
+```
+
+### 26.2 先红：组件与页面
+
+组件文件尚不存在：
+
+```text
+$ flutter test test/empty_state/empty_state_test.dart
+Error when reading 'lib/core/widgets/empty_state.dart': No such file or directory
+Failed to load ".../empty_state_test.dart"
+```
+
+页面测试已能运行，但五处空态仍是旧实现：
+
+```text
+$ flutter test test/library/favorites_page_test.dart test/download/downloads_page_test.dart test/watch/watch_records_page_test.dart test/notice/notices_page_test.dart test/comment/drama_comments_sheet_test.dart
+Found 0 widgets with type "EmptyState": []
+00:03 +28 -6: Some tests failed.
+```
+
+解读：组件、收藏、下载、记录、通知、评论空态均未接入，红灯符合 K10 范围。
+
+### 26.3 组件实现
+
+新增：
+
+```text
+128 lib/core/widgets/empty_state.dart
+```
+
+规格：
+
+- 默认 96x96、圆角 28、`AppColors.blue` 11% 背景，图标 42。
+- compact 64x64、圆角 18、图标 28。
+- 标题 16/w600，副标题 13 muted，最多 2 行。
+- 可选 TextButton 最小高度 44，主题主色。
+- 深色主题图标 `blueSoft`，浅色主题图标 `blue`。
+- 外层 Semantics 只读标题；图形和文本排除重复语义，操作按钮仍可访问。
+
+新增三语副标题：
+
+```text
+en: New content will appear here.
+zh: 有新内容时会显示在这里。
+id: Konten baru akan muncul di sini.
+```
+
+### 26.4 10 处替换
+
+```text
+lib/pages/home/home_view.dart                         movie_outlined
+lib/pages/discover/widgets/home_drama_grid.dart        grid_view_rounded / search_off_rounded
+lib/pages/favorites/favorites_page.dart                favorite_border_rounded
+lib/pages/notices/notices_page.dart                    notifications_none_rounded
+lib/pages/drama_detail/drama_detail_view.dart          video_library_outlined
+lib/pages/mine/mine_view.dart                          bookmark_border_rounded / history_rounded
+lib/pages/downloads/downloads_page.dart                download_outlined
+lib/pages/watch_records/watch_records_page.dart        history_rounded
+lib/pages/player/widgets/drama_comments_sheet.dart     chat_bubble_outline_rounded（compact）
+```
+
+首页将原合并的 `error || empty` 分支拆开：
+
+- error 继续使用 `error_outline_rounded`、`catalogError`、重试与 debug API 地址。
+- 空列表才使用 `EmptyState(noStories)`。
+
+收藏、通知、记录、评论等失败态仍保留原错误与重试，不用 `EmptyState`。
+
+### 26.5 定向与全量绿灯
+
+组件测试：
+
+```text
+$ flutter test test/empty_state/empty_state_test.dart
+00:00 +4: All tests passed!
+```
+
+组件与五处页面：
+
+```text
+$ flutter test test/empty_state/empty_state_test.dart test/library/favorites_page_test.dart test/download/downloads_page_test.dart test/watch/watch_records_page_test.dart test/notice/notices_page_test.dart test/comment/drama_comments_sheet_test.dart
+00:03 +38: All tests passed!
+```
+
+```text
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+```
+
+```text
+$ flutter test
+00:18 +302 ~1: All tests passed!
+```
+
+解读：302 项通过，1 项联调测试因客户端接口服务未启动按设计跳过；既有页面
+用例保留，新增断言只增加 `EmptyState` 校验，不删除原用例。
+
+### 26.6 Android debug 构建
+
+用户 iOS `flutter run` 仍在运行，未终止该会话。为避免争用原项目 `build/`，
+将同一工作区（排除 build/.git/.dart_tool/ephemeral）同步到独立临时副本后构建：
+
+```text
+$ flutter build apk --debug
+Running Gradle task 'assembleDebug'...                              6.9s
+✓ Built build/app/outputs/flutter-apk/app-debug.apk
+```
+
+解读：K10 最终代码通过 Android debug 构建，且原 iOS 运行会话未被中断。
+
+### 26.7 Git
+
+```text
+6d08330 feat(flutter): 统一空列表占位组件
+0466b4b merge: 合并 K10 统一空态组件
+19babb8..0466b4b  develop -> develop
+```
+
+功能提交与合并提交 author/committer 均为
+`Zhou Weidong <502333560@qq.com>`。
+
+### 26.8 用户真机验证步骤与预期
+
+以下设备侧取证由用户执行，Codex 未跑真机。
+
+1. 使用最新客户端 `develop`，分别切换深色和浅色主题进入一个空列表页面。
+   预期：显示 96x96 柔和蓝色底、图标、标题与可选说明，不白屏、不溢出。
+2. 打开收藏、下载、观看记录、通知页面并清空对应数据。
+   预期：均显示统一 `EmptyState`，原有文案与清空/刷新逻辑正常。
+3. 打开无评论的剧目评论弹窗。
+   预期：显示 compact 64x64 图标占位，弹窗仍可滚动与输入。
+4. 打开无剧集详情或首页无剧目场景。
+   预期：显示对应空态；重试按钮行为保持不变。
+5. 模拟接口失败。
+   预期：仍显示原错误图标、错误文案和重试，不显示空态占位。
+6. 在 320px 宽小屏检查长标题、副标题和按钮。
+   预期：最多两行、可换行且无横向溢出，按钮点击区域不小于 44pt。
+
+设备侧截图、语音朗读与最终验收结论由用户执行。
+
+---
+
 ## 2026-10-17 iOS 构建阻塞：固定 shared_preferences_foundation 2.5.6

 ### 25.1 现象与根因