fix(home): Scrollbar+SingleChildScrollView primary:true (no ScrollPosition runtime error); docs: runtime issues in TODO §9

TODO.md

@@ -225,3 +225,26 @@ f8a90ad  基线
 flutter build web        # 目标：无 error，生成 build/web
 flutter run -d chrome    # 目标：能打开、首页/商品/购物车/结账流程跑通
 ```
+
+---
+
+## 9. 运行时问题（应用已能运行，以下为后续优化，非阻塞）
+
+应用 `flutter run -d chrome` 已成功启动并加载首页/API 数据/数据库。控制台有以下运行时警告/异常：
+
+### 9.1 Scrollbar 缺 ScrollPosition（真实，影响滚动条显示）
+4 个 `Scrollbar(` 未配 `controller`，新版 Flutter 的 Scrollbar 找不到 ScrollPosition：
+- `lib/pages/home.dart:101` — ✅ 已修：给 `SingleChildScrollView` 加 `primary: true`
+- `lib/pages/blog.dart:24` — 子是 `DesktopBlog`（自定义组件）
+- `lib/pages/download.dart:63` — 子是 `DesktopDownloadApps`（自定义组件）
+- `lib/widgets/desktop/shop.dart:137` — 包裹 `NotificationListener`
+
+后 3 处的子是自定义组件，需让内部 ListView/ScrollView 暴露 controller（设 `primary: true`）或 Scrollbar 改用 `NotificationListener` 关联。**仅影响滚动条渲染，不影响内容加载/显示。**
+
+### 9.2 CustomersLogo setState-after-dispose（小 bug）
+`lib/widgets/desktop/desktop_customers_logo.dart` 的 `Timer.periodic`（每 10s 刷新 logo）未在 `dispose()` 里 `cancel()`，组件卸载后 timer 仍触发 `setState`。建议在 `dispose` 里 `timer?.cancel()`。**热重载时易触发，干净启动偶发。**
+
+### 9.3 `_business` LateInitializationError（热重载假象）
+`_business` 是店铺页面组件（`shop_promote.dart`/`shop.dart` 等）的 `late Business` 字段。热重载重建 widget 树时字段状态丢失触发，**干净启动（浏览器刷新 Cmd+R）不会出现**。
+
+> **验证方式**：在浏览器里 Cmd+R 刷新页面（而非热重载），9.2/9.3 类异常应消失，仅剩 9.1 的滚动条警告。

build_web.sh

@@ -5,15 +5,17 @@
 #   ./build_web.sh run      # 构建并在 Chrome 中运行调试版
 #
 # 说明:
-#   - 必须 --no-tree-shake-icons: 项目中有 24 处 IconData(codePoint) 使用
-#     来自 JSON/API 的动态 code point(非 const), icon tree-shaking 无法处理。
+#   - 构建(release)必须 --no-tree-shake-icons: 项目中有 24 处 IconData(codePoint)
+#     使用来自 JSON/API 的动态 code point(非 const), icon tree-shaking 无法处理。
+#     注意: --no-tree-shake-icons 仅 build 支持; flutter run(debug)不做 tree-shaking,
+#     因此 run 分支不带该 flag。
 #   - Dart SDK: 本地 Flutter 3.29.3 / Dart 3.7.2(未升级全局 SDK)。
 set -e
 cd "$(dirname "$0")"
 
 if [ "$1" = "run" ]; then
-  echo ">>> flutter run -d chrome --no-tree-shake-icons"
-  flutter run -d chrome --no-tree-shake-icons
+  echo ">>> flutter run -d chrome"
+  flutter run -d chrome
 else
   echo ">>> flutter build web --no-tree-shake-icons"
   flutter build web --no-tree-shake-icons

lib/pages/home.dart

@@ -101,6 +101,7 @@ class HomeState extends State<Home> {
               desktop: Scrollbar(
                 thumbVisibility: true,
                 child: SingleChildScrollView(
+                  primary: true,
                   child: Column(
                     mainAxisSize: MainAxisSize.min,
                     children: [