docs(plans): 合并 K10 统一空态回执

2026-10-17 21:56:48 +08:00
commit aa54e03d52
@@ -0,0 +1,90 @@
+# 2026-10-17 K10 统一空列表占位（EmptyState）
+
+## 一、目标与边界
+
+新建统一 `EmptyState` 组件，替换任务书列出的 10 处纯文字空态，保留现有空态
+文案、按钮行为和错误态逻辑。只改空态视觉、三语 l10n 与测试，不改数据、接口、
+列表加载/失败逻辑或页面信息架构。
+
+- 客户端分支：`feature/flutter-k10-empty-states`，基线 `develop 19babb8`。
+- 文档分支：`docs/k10-empty-states`，FruitServer 基线 K10 任务书 `3f84bc6`。
+- 不引入图片、SVG、字体或第三方依赖。
+- 不跑真机，设备侧深色/浅色、小屏和页面状态由用户验收。
+
+## 二、组件设计
+
+`lib/core/widgets/empty_state.dart`：
+
+1. 默认居中，最大宽度 280，外层 Padding 24。
+2. 默认图形 96x96、圆角 28，背景 `AppColors.blue` 透明度 0.11；图标 42。
+3. 深色图标色 `AppColors.blueSoft`，浅色图标色 `AppColors.blue`。
+4. compact 图形 64x64、圆角 18、图标 28，用于评论弹窗。
+5. 标题 16/w600（compact 14）、最多 2 行；可选副标题 13、`muted`、最多 2 行。
+6. 可选主色 TextButton，最小点击区域 44x44；保留调用方动作。
+7. 外层 `Semantics(label: title)`；图形、标题和副标题文本使用
+   `ExcludeSemantics`，避免重复朗读，操作按钮仍保持可访问。
+8. 稳定 Key：`empty-state-art`、`empty-state-icon`、`empty-state-title`、
+   `empty-state-action`。
+
+新增通用副标题 `emptyHint`：
+
+- zh：有新内容时会显示在这里。
+- en：New content will appear here.
+- id：Konten baru akan muncul di sini.
+
+## 三、10 处替换与图标
+
+| 位置 | 图标 | 行为 |
+|---|---|---|
+| 首页 noStories | `movie_outlined` | 保留重试 |
+| 首页分类空 | `grid_view_rounded` | 无新增动作 |
+| 首页搜索空 | `search_off_rounded` | 无新增动作 |
+| 收藏 noFavorites | `favorite_border_rounded` | 原按钮不变 |
+| 通知 noNotices | `notifications_none_rounded` | 原下拉刷新不变 |
+| 详情 noEpisodesYet | `video_library_outlined` | 保留重试 |
+| 我的-片单 noSavedShows | `bookmark_border_rounded` | 无新增动作 |
+| 我的-最近剧目 noStories | `history_rounded` | 无新增动作 |
+| 下载 noDownloads | `download_outlined` | 原清空按钮不变 |
+| 观看记录 noWatchRecords | `history_rounded` | 原清空/刷新逻辑不变 |
+| 评论 noComments | `chat_bubble_outline_rounded` | compact |
+
+首页错误态继续使用 `error_outline_rounded` 和 `catalogError`；分类、收藏、通知、
+记录、评论等失败态继续使用原错误图标/重试，不允许用 `EmptyState` 冒充失败。
+
+## 四、影响文件
+
+- `lib/core/widgets/empty_state.dart`（新增）
+- `lib/pages/home/home_view.dart`
+- `lib/pages/discover/widgets/home_drama_grid.dart`
+- `lib/pages/favorites/favorites_page.dart`
+- `lib/pages/notices/notices_page.dart`
+- `lib/pages/drama_detail/drama_detail_view.dart`
+- `lib/pages/mine/mine_view.dart`
+- `lib/pages/downloads/downloads_page.dart`
+- `lib/pages/watch_records/watch_records_page.dart`
+- `lib/pages/player/widgets/drama_comments_sheet.dart`
+- `lib/l10n/app_en.arb`、`app_zh.arb`、`app_id.arb` 与生成文件
+- 组件测试及收藏/下载/记录/通知/评论页面空态测试
+- `FruitServer/docs/plans/2026-10-17-K10.md`
+- `FruitServer/docs/plans/PROGRESS.md`
+- `FruitServer/docs/plans/INBOX.md`
+
+## 五、TDD 与门禁
+
+1. 先新增 `EmptyState` 组件测试和五处页面空态测试，确认组件不存在时红灯。
+2. 实现组件并替换 10 处空态后跑定向测试绿灯。
+3. 运行 `dart analyze lib test`、`flutter test`、`flutter build apk --debug`。
+4. 构建前检查并发 `flutter run/build`；当前有用户 iOS `flutter run` 会话，
+   不主动终止，若仍未结束则等待其退出后再构建。
+5. 完成后 `merge --no-ff` 回客户端 `develop` 并 push；FruitServer 文档同样
+   合并推送。作者与提交者统一为
+   `Zhou Weidong <502333560@qq.com>`。
+
+## 六、风险与待确认
+
+- 首页当前把 `catalog.error` 与空列表放在同一分支，需先拆出错误态，再单独用
+  `EmptyState` 渲染 noStories，避免错误态被误认为空态。
+- 部分空态位于 Sliver、固定高度滚动区或弹窗内，需保持可滚动和居中。
+- 组件外层统一读标题，若操作按钮位于同一 Semantics 容器内，必须确保按钮自身
+  语义未被 `ExcludeSemantics` 吞掉。
+- 最大宽度 280 与 compact 64 图标容器需在 320px 宽度和浅/深色主题下无溢出。
@@ -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 现象与根因