From f1d56b10403b9d4d724dc4e7cb95b383f01237d3 Mon Sep 17 00:00:00 2001 From: Zhou Weidong <502333560@qq.com> Date: Sat, 17 Oct 2026 17:39:28 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs(plans):=20=E5=A2=9E=E5=8A=A0=20K10=20?= =?UTF-8?q?=E7=BB=9F=E4=B8=80=E7=A9=BA=E6=80=81=E5=AE=9E=E6=96=BD=E8=AE=A1?= =?UTF-8?q?=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/plans/2026-10-17-K10.md | 90 ++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 docs/plans/2026-10-17-K10.md diff --git a/docs/plans/2026-10-17-K10.md b/docs/plans/2026-10-17-K10.md new file mode 100644 index 0000000..ac111bf --- /dev/null +++ b/docs/plans/2026-10-17-K10.md @@ -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 宽度和浅/深色主题下无溢出。 From 3b2afc9f474897a0d72985f0cd01d8e2ce305a5e Mon Sep 17 00:00:00 2001 From: Zhou Weidong <502333560@qq.com> Date: Sat, 17 Oct 2026 21:56:35 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs(plans):=20=E8=AE=B0=E5=BD=95=20K10=20?= =?UTF-8?q?=E7=BB=9F=E4=B8=80=E7=A9=BA=E6=80=81=E5=AE=9E=E6=96=BD=E5=9B=9E?= =?UTF-8?q?=E6=89=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/plans/INBOX.md | 26 ++++++- docs/plans/PROGRESS.md | 157 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 182 insertions(+), 1 deletion(-) diff --git a/docs/plans/INBOX.md b/docs/plans/INBOX.md index d1ed19b..1c6e002 100644 --- a/docs/plans/INBOX.md +++ b/docs/plans/INBOX.md @@ -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 列全部剧目） diff --git a/docs/plans/PROGRESS.md b/docs/plans/PROGRESS.md index bea2411..3d600be 100644 --- a/docs/plans/PROGRESS.md +++ b/docs/plans/PROGRESS.md @@ -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 现象与根因