# 2026-09-21

## 代码讲解（Flutter 入门答疑，未改动业务代码）
围绕项目已有文件做概念讲解，帮助用户理解 Flutter/Riverpod 基础：

- `lib/app.dart`：讲解根组件职责 = 全局 `navigatorKey` + M3 主题 + 登录态路由分发（`auth.isLoggedIn ? MainShell : LoginPage`）。
- `GlobalKey`：讲解其"全局可寻址"特性；本项目 `navigatorKey` 属于第①类用法（获取 `NavigatorState` 以在无 `BuildContext` 的网络层执行跳转）。
- `ConsumerWidget`：讲解它是「带 `ref` 的 StatelessWidget」；对照本项目的三种用法分布——`ConsumerWidget`（`app.dart`、`ocr_tab.dart`、`ocr_result_card.dart`）、`ConsumerStatefulWidget`（`main_shell.dart`、`login_page.dart`、`manual_entry_tab.dart`）、`Consumer` 局部订阅（`manual_entry_tab.dart` 的 `categoriesProvider`）。
- `main_shell.dart` 全文件：`ConsumerStatefulWidget` 选型理由、`_index` 本地状态、`initState` 兜底跳转（`addPostFrameCallback` + `pushAndRemoveUntil` 的用意）、`IndexedStack` 保留 Tab 状态、M3 `NavigationBar` 参数（`indicatorColor: 0x33C8956E` 的 `33` 是透明度）。
- `main_shell.dart` 中 `ref` 的来源：`ConsumerState` 的继承成员（非普通变量），`initState` 内只能用 `ref.read` 不能 `watch`。
- `login_page.dart` 的 `Stack`（L132-152）：层叠布局——先画 4 个 `Positioned` 装饰圆球，再画 `SafeArea → Center → SingleChildScrollView → Column` 内容层；`..._buildBackgroundBalls()` 是 Dart 展开运算符。

## 环境确认
- 执行 `flutter --version` 确认：**Flutter 3.47.4 stable / Dart 3.13.3**。这正好是 Material & Cupertino 从 SDK 解耦（拆为 `material_ui` / `cupertino_ui` 独立包）的版本，现有 `package:flutter/material.dart` 导入仍兼容。

## 学习资料指引（已提供给用户）
- 设计规范：`m3.material.io`（尤其 `/components`）、`/develop/flutter`、Theme Builder。
- Flutter 文档：`docs.flutter.dev/ui/design/material`、Widget Catalog、`api.flutter.dev` 的 `material-library` / `ThemeData` / `ColorScheme`。
- 中文：`docs.flutter.cn`。示例：`flutter.github.io/samples`。在线试验：`dartpad.dev`。
- 多端与自适应：`docs.flutter.cn/ui/adaptive-responsive/`、`.adaptive` 构造（`Switch.adaptive` 等）、窗口尺寸类别（Compact <600 / Medium 600-839 / Expanded ≥840）、`flutter_adaptive_scaffold`。

## 结论性判断
- 项目已是 Material 3，无需开启 `useMaterial3`。
- 项目"多端"现状：仅 Android/iOS/Web，纯 M3、未做平台自适应与响应式布局。
- 向用户提出了三个可选后续任务：① `MainShell` 响应式改造（小屏 `NavigationBar` / 宽屏 `NavigationRail`）② 关键组件加 `.adaptive` ③ 补桌面端平台目录。用户尚未选择。