From 5e509b20ed8060e5cfaed25a32b8c043eadd2cb8 Mon Sep 17 00:00:00 2001 From: Zhou Weidong <502333560@qq.com> Date: Tue, 20 Oct 2026 19:52:23 +0800 Subject: [PATCH] =?UTF-8?q?docs(plans):=20=E7=95=99=E7=97=95=20K65=20?= =?UTF-8?q?=E5=86=B7=E5=90=AF=E5=8A=A8=E9=A6=96=E9=A1=B5=E9=A2=84=E5=8F=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/plans/INBOX.md | 84 ++++++++++++++++++++---------------------- docs/plans/PROGRESS.md | 31 ++++++++++++++++ 2 files changed, 71 insertions(+), 44 deletions(-) diff --git a/docs/plans/INBOX.md b/docs/plans/INBOX.md index 18611c5..f9bc8dd 100644 --- a/docs/plans/INBOX.md +++ b/docs/plans/INBOX.md @@ -1,59 +1,55 @@ # INBOX -## [已处理] K64-A 原生开屏改为品牌启动图 +## [已处理] K65-A 冷启动提前拉取首页数据 -### 背景 +### 现状 -自定义 Flutter 动画开屏页观感不佳（元素多、文字不够亮）。按产品要求改为**只保留原生启动屏**： +- `lib/main.dart` 在 `runApp` 之前 `await AppConfig.probeAndApplyBaseUrl()`，三个候选地址 + （`127.0.0.1` / `192.168.31.187` / 公网）**串行**探测，每个 2s 超时，最坏 6s。 + 这段时间原生开屏一直停留，首页请求根本还没开始。 +- `runApp` 之后，`app.dart` 的 Provider 才创建 `CatalogController` 并 `..load()`。 -- 深暖底 `#1F1B16` 上一枚果篮图标 + 明亮奶油白 `FruitShorts` + 橙色「水果短剧」 -- 原生启动屏由 `flutter_native_splash` 生成，Android 12+ 用 `android12splash`，旧版本用 `splash`， - iOS 用 `LaunchImage` / `LaunchBackground` -- 删除自定义开屏页，首页首帧加载态改为同款深底 + 主题色转圈，避免深→浅闪白 +### 目标 -已完成本机实现与真机验证（Android 16 录屏逐帧确认：开屏 → 加载 → feed 全程深色，无白闪）。 -门禁已由 Trae 复跑：`dart analyze lib test` 零告警、`flutter test` 473 条全过、`flutter build apk --debug` 成功。 +- 冷启动尽快开始首页数据请求：第一帧立即绘制（深底 + 主题色转圈），探测一完成立刻拉首页。 +- 探测并行化：三个候选同时探测，总耗时上限约 2s；仍按 + `127.0.0.1 > 192.168.31.187 > 公网` 的优先级选第一个可用地址。 +- 观感：原生开屏 → 应用内同款深底转圈（数据在拉）→ 首页。 -### 工作区改动（ReelShort，develop，未提交） +### 实现 -新增： -- `assets/icon/splash_logo.png` -- `assets/icon/splash_logo_android12.png` -- `android/app/src/main/res/drawable/background.png` -- `android/app/src/main/res/drawable-v21/background.png` -- `android/app/src/main/res/drawable-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}/splash.png` -- `android/app/src/main/res/drawable-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}/android12splash.png` -- `android/app/src/main/res/drawable-night-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi}/android12splash.png` -- `ios/Runner/Assets.xcassets/LaunchImage.imageset/` -- `ios/Runner/Assets.xcassets/LaunchBackground.imageset/` +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()`。 -修改： -- `pubspec.yaml`（移除 `splash_mark.png` 资产声明，`flutter_native_splash` 配置改为深底 + 新图） -- `lib/core/theme/app_colors.dart`（新增 `splashInk = #1F1B16`） -- `lib/pages/home/home_view.dart`（删除 `SplashPage` 分支；加载态改深底 + 浅色状态栏） -- `android/app/src/main/res/drawable/launch_background.xml` -- `android/app/src/main/res/drawable-v21/launch_background.xml` -- `android/app/src/main/res/values/colors.xml` -- `android/app/src/main/res/values-v31/styles.xml` -- `android/app/src/main/res/values-night-v31/styles.xml` -- `ios/Runner/Base.lproj/LaunchScreen.storyboard` +### 验收 -删除： -- `assets/icon/splash_mark.png` -- `lib/pages/splash/splash_page.dart` -- `test/splash/splash_gate_test.dart` +- 冷启动不再有「原生开屏停住等探测」的空窗：第一帧立即出现深底转圈。 +- 探测总等待从最长 6s 降到约 2s。 +- 门禁：`dart analyze lib test` 零告警、`flutter test` 全过、`flutter build apk --debug` 成功。 -### 任务 +### Git -1. 从 `develop` 拉分支 `feat/native-splash-logo`（工作区改动直接带入）。 -2. 只提交上述文件；**禁止 `git add -A`**。 -3. **不要提交** `pubspec.lock`、`android/app/src/main/AndroidManifest.xml`、`ios/Runner/Info.plist` - （这三处已还原为 develop 原样，禁止再改动）。 -4. 提交：`feat(splash): 原生开屏改为品牌启动图`，作者 `Zhou Weidong <502333560@qq.com>`。 -5. 门禁：`dart analyze lib test`、`flutter test`、`flutter build apk --debug` 全过。 -6. `--no-ff` 合并回 `develop` 并 push。 -7. `FruitServer/docs/plans/PROGRESS.md` 追加 K64-A 留痕（分支、commit、门禁原始输出）。 +- 从 `develop` 拉 `feat/startup-prefetch`。 +- 提交：`perf(home): 冷启动提前拉取首页数据`，作者 `Zhou Weidong <502333560@qq.com>`。 +- `--no-ff` 合回 `develop` 并 push；`FruitServer/docs/plans/PROGRESS.md` 追加 K65-A 留痕。 ### 约束 -- 全程中文；不改其它功能代码；完成后停住，等待验收。 +- 全程中文；禁止 `git add -A`；不改原生开屏资源、不改 UI 视觉；完成后停住等待验收。 diff --git a/docs/plans/PROGRESS.md b/docs/plans/PROGRESS.md index 9e48703..5d90b48 100644 --- a/docs/plans/PROGRESS.md +++ b/docs/plans/PROGRESS.md @@ -22331,3 +22331,34 @@ Running Gradle task 'assembleDebug'... ``` 解读：静态检查零告警，473 条测试全部通过，debug APK 构建成功。真机验收由用户执行。 + +## 2026-10-20 ReelShort：K65-A 冷启动提前拉取首页数据 + +- 前置状态：K64-A 已完成并合并，develop 合并提交 `1199db7`。 +- 分支：`feat/startup-prefetch` +- 功能提交：`9b31d83 perf(home): 冷启动提前拉取首页数据` +- develop 合并提交：`c76b388 merge: 合并 K65-A 冷启动首页预取`，已推送。 +- `main()` 不再等待地址探测，先启动 `AppConfig.ready` 并立即 `runApp`；竖屏设置与本地服务地址读取仍保持等待。 +- 三个地址候选改为 `Future.wait` 并行探测，全部返回后仍按本机、开发机、公网的原有优先级选择首个成功地址；全部失败继续使用指定 fallback 或平台默认地址。 +- `CatalogController.load()` 首帧先进入 loading，再等待 ready 后请求首页；默认 ready 按需生成已完成 Future，避免 fake-async 跨用例复用造成挂起。 +- `ApiClient` 未显式指定 baseUrl 时，在每次请求前同步最新运行时地址；显式 baseUrl 保持固定，确保启动探测完成后首页请求真正发往选中地址。 + +测试：新增并行探测门闩、优先级选择、ready 完成前零请求、最终地址生效及客户端先构造后探测动态地址用例；全量既有用例保持通过。 + +门禁原始输出： + +```text +$ dart analyze lib test +Analyzing lib, test... +No issues found! + +$ flutter test +00:48 +475: All tests passed! + +$ flutter build apk --debug +Running Gradle task 'assembleDebug'... + 7.5s +✓ Built build/app/outputs/flutter-apk/app-debug.apk +``` + +解读：静态检查零告警，475 条测试全部通过，debug APK 构建成功。真机验收由用户执行。