From c5def287b8b275c42cd84ab5bd3ea12c1b1f7082 Mon Sep 17 00:00:00 2001 From: Zhou Weidong <502333560@qq.com> Date: Tue, 20 Oct 2026 19:58:09 +0800 Subject: [PATCH] =?UTF-8?q?docs(plans):=20=E7=95=99=E7=97=95=20K66=20?= =?UTF-8?q?=E5=90=AF=E5=8A=A8=E9=A1=B5=E5=81=9C=E7=95=99=E9=A6=96=E9=A1=B5?= =?UTF-8?q?=E5=B0=B1=E7=BB=AA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/plans/INBOX.md | 80 ++++++++++++++++++++++++------------------ docs/plans/PROGRESS.md | 31 ++++++++++++++++ 2 files changed, 77 insertions(+), 34 deletions(-) diff --git a/docs/plans/INBOX.md b/docs/plans/INBOX.md index f9bc8dd..b940bd2 100644 --- a/docs/plans/INBOX.md +++ b/docs/plans/INBOX.md @@ -1,55 +1,67 @@ # INBOX -## [已处理] K65-A 冷启动提前拉取首页数据 +## [已处理] K66-A 启动页停留到首页就绪再进首页 + +### 背景 + +K65-A 已把首页预取提前到启动阶段。产品要求再简化观感： + +> 「等首页加载完就进入首页就行了」 + +即：别再出现「深底 + 转圈」这种中间页，启动期间保持与原生开屏一致的品牌画面， +目录数据就绪后直接进首页。 ### 现状 -- `lib/main.dart` 在 `runApp` 之前 `await AppConfig.probeAndApplyBaseUrl()`，三个候选地址 - （`127.0.0.1` / `192.168.31.187` / 公网）**串行**探测，每个 2s 超时，最坏 6s。 - 这段时间原生开屏一直停留，首页请求根本还没开始。 -- `runApp` 之后，`app.dart` 的 Provider 才创建 `CatalogController` 并 `..load()`。 +`lib/pages/home/home_view.dart` 的 `_buildHome`： + +- `catalog.loading` 为 true 时返回 `AnnotatedRegion(light) + Scaffold(splashInk, 居中主题色转圈)` +- 数据就绪后才渲染 `_HomeTabs` ### 目标 -- 冷启动尽快开始首页数据请求：第一帧立即绘制（深底 + 主题色转圈），探测一完成立刻拉首页。 -- 探测并行化：三个候选同时探测，总耗时上限约 2s；仍按 - `127.0.0.1 > 192.168.31.187 > 公网` 的优先级选第一个可用地址。 -- 观感：原生开屏 → 应用内同款深底转圈（数据在拉）→ 首页。 +- `catalog.loading` 且**首次启动尚未 settled** 时，显示与原生开屏一致的品牌画面： + 深底 `AppColors.splashInk` + 居中的开屏图，不再显示转圈。 +- 目录数据就绪后同帧切到首页。 +- 非首次（`settled == true`，例如失败重试）仍保留原来的转圈 loading，避免重复播品牌画面。 ### 实现 -1. `lib/core/config/app_config.dart` - - 新增 `static Future ready = Future.value();`，作为「启动探测完成」的信号； - 默认已完成，保证现有测试无感。 - - `probeAndApplyBaseUrl` 改为**并行**发起所有候选探测（`Future.wait`）， - 全部返回后按原优先级取第一个成功地址并 `applyRuntimeBaseUrl`； - 全失败时仍走 `fallbackBaseUrl ?? defaultBaseUrl`。 - - 保留 `probe` 注入参数与现有「运行中重试」语义。 -2. `lib/main.dart` - - 不再 `await` 探测：`AppConfig.ready = AppConfig.probeAndApplyBaseUrl();` 后立即 `runApp`。 - - `ServerEndpoint.load()`、竖屏锁定仍保持 `await`。 -3. `lib/core/data/services/catalog_controller.dart` - - `load()` 里先 `loading = true; error = null; debugError = null; notifyListeners();` - 然后 `await AppConfig.ready;` 再发起请求，保证请求用的是探测后的地址， - 且等待期间首页显示转圈而不是「暂无短剧」。 -4. 测试 - - `probeAndApplyBaseUrl`：三个候选并行、优先级选择、全失败回落。 - - `CatalogController.load()`：`AppConfig.ready` 未完成时 `loading == true` 且未发请求， - 完成后按最终地址发请求；测试结束复位 `AppConfig.ready` 与运行时地址。 - - 其余测试如受 `AppConfig.ready` 影响，需在 `setUp` 复位为 `Future.value()`。 +1. `pubspec.yaml`：`flutter.assets` 增加 + - `assets/icon/splash_logo.png` + - `assets/icon/splash_logo_android12.png` +2. `lib/pages/home/home_view.dart` + - 新增私有 `_startupSplash()`： + - `AnnotatedRegion(value: SystemUiOverlayStyle.light)` + - `ColoredBox(color: AppColors.splashInk)` + - 居中 `Image.asset(..., key: Key('startup-splash'))` + - Android 用 `splash_logo_android12.png`、其它平台用 `splash_logo.png` + （与各自原生开屏的取图一致，避免切换时跳变） + - 尺寸：Android 288 逻辑像素见方，其它平台 384 + - `_buildHome`： + ```dart + if (catalog.loading) { + return catalog.settled ? _retryLoading() : _startupSplash(); + } + ``` + `_retryLoading()` 即现有的深底 + 主题色转圈。 +3. 测试（`test/home/` 下） + - `settled == false` 且 loading：出现 `startup-splash`，不出现 `CircularProgressIndicator` + - `settled == true` 且 loading：出现转圈，不出现 `startup-splash` + - 数据就绪：出现首页 feed，`startup-splash` 消失 +4. 真机自查建议：冷启动录屏，确认原生开屏 → 品牌画面（无转圈）→ 首页，无闪白。 ### 验收 -- 冷启动不再有「原生开屏停住等探测」的空窗：第一帧立即出现深底转圈。 -- 探测总等待从最长 6s 降到约 2s。 +- 冷启动不再出现单独的转圈页。 - 门禁：`dart analyze lib test` 零告警、`flutter test` 全过、`flutter build apk --debug` 成功。 ### Git -- 从 `develop` 拉 `feat/startup-prefetch`。 -- 提交：`perf(home): 冷启动提前拉取首页数据`，作者 `Zhou Weidong <502333560@qq.com>`。 -- `--no-ff` 合回 `develop` 并 push；`FruitServer/docs/plans/PROGRESS.md` 追加 K65-A 留痕。 +- 从 `develop` 拉 `feat/startup-splash-hold`。 +- 提交：`feat(home): 启动页停留至首页就绪`，作者 `Zhou Weidong <502333560@qq.com>`。 +- `--no-ff` 合回 `develop` 并 push；`FruitServer/docs/plans/PROGRESS.md` 追加 K66-A 留痕。 ### 约束 -- 全程中文；禁止 `git add -A`；不改原生开屏资源、不改 UI 视觉；完成后停住等待验收。 +- 全程中文；禁止 `git add -A`；不改原生开屏资源与其它页面；完成后停住等待验收。 diff --git a/docs/plans/PROGRESS.md b/docs/plans/PROGRESS.md index 5d90b48..fb73daa 100644 --- a/docs/plans/PROGRESS.md +++ b/docs/plans/PROGRESS.md @@ -22362,3 +22362,34 @@ Running Gradle task 'assembleDebug'... ``` 解读：静态检查零告警，475 条测试全部通过，debug APK 构建成功。真机验收由用户执行。 + +## 2026-10-20 ReelShort：K66-A 启动页停留到首页就绪再进首页 + +- 前置状态：K65-A 已完成并合并，develop 合并提交 `c76b388`。 +- 分支：`feat/startup-splash-hold` +- 功能提交：`7871b0c feat(home): 启动页停留至首页就绪` +- develop 合并提交：`d2174c5 merge: 合并 K66-A 启动页停留至首页就绪`，已推送。 +- `pubspec.yaml` 将 Android 12 与通用品牌开屏图加入 Flutter 资产，应用内启动阶段可直接复用原生开屏图。 +- 首次 `catalog.loading && !settled` 时显示深底品牌启动图，不再显示单独转圈；Android 使用 `splash_logo_android12.png` 288 逻辑像素，其它平台使用 `splash_logo.png` 384 逻辑像素。 +- `catalog.settled` 后的失败重试仍显示原深底主题色转圈；目录数据完成后启动图同帧移除并进入首页 feed。 +- 门禁产生的 `pubspec.lock` 依赖漂移已还原，未纳入本批提交。 + +测试：新增首次启动品牌图 Android/iOS 路径与尺寸、settled 重试转圈、数据完成后启动图消失并出现首页 feed 三条用例。 + +门禁原始输出： + +```text +$ dart analyze lib test +Analyzing lib, test... +No issues found! + +$ flutter test +00:57 +478: All tests passed! + +$ flutter build apk --debug +Running Gradle task 'assembleDebug'... + 7.8s +✓ Built build/app/outputs/flutter-apk/app-debug.apk +``` + +解读：静态检查零告警，478 条测试全部通过，debug APK 构建成功。真机验收由用户执行。