5.7 KiB
5.7 KiB
项目长期记忆：强宝爱记账
项目概况
- 名称：
qiangbao_accounting（强宝爱记账），一个 Flutter 记账类 App。 - 定位：由 uniApp 项目
pages/login/login.vue复刻迁移而来（见login_page.dart顶部注释）。 - 环境：Flutter 3.47.4 stable / Dart 3.13.3（Windows 开发）。
- 目标平台：仅
android/、ios/、web/，未配置桌面端。
技术栈与约定
- 状态管理：flutter_riverpod ^3.0.0（
Notifier/NotifierProvider，非旧版 StateNotifier）。 - 网络：dio ^5.8.0，API 层按模块拆分在
lib/api/，每个模块导出xxxApiProvider = Provider<XxxApi>(...)。 - 本地存储：
shared_preferences，统一封装在lib/core/storage/local_storage.dart。 - 其他依赖：
image_picker（OCR 选图）、intl、cupertino_icons。 - UI：Material 3（Flutter 3.16+ 默认启用），未显式设置
useMaterial3。
架构与关键文件
lib/app.dart：根组件QiangbaoApp extends ConsumerWidget。配置 M3 主题，用auth.isLoggedIn在MainShell/LoginPage之间分发。全局navigatorKey已抽到lib/core/navigation/navigator_key.dart（避免 app.dart ↔ 网络层循环依赖），供网络层 401 跳转与全局 toast 使用。lib/core/network/auth_redirect.dart：网络层与 Riverpod 的桥接（configureAuthRedirect(container)在main.dart调用），提供forceLogout()/logoutAndGoLogin()。lib/pages/shell/main_shell.dart：主框架，4 个 Tab（首页/记账/统计/我的），用IndexedStack保留各页状态，NavigationBar（M3）承载导航，默认_index = 1（记账）。initState里有登录态兜底跳转。lib/pages/login/login_page.dart：登录/注册页，含毛玻璃卡片（BackdropFilter）、动画背景圆球（AnimationController+Stack+Positioned+Transform.translate）、记住密码（utils/crypto.dart加解密）。- 目前只有「记账」页（
AddPage，含manual_entry_tab.dart、ocr_tab.dart、ocr_result_card.dart）是真实实现，首页/统计/我的仍是_PlaceholderPage。
设计规范（配色）
- 品牌主色：
#C8956E（驼色/焦糖色），在app.dart中作为ColorScheme.fromSeed的 seedColor。 - 深棕文字色：
#5D4037；辅助文字：#8D6E63；页面底色：#F8F8F8。 - 登录页另用暖橙渐变
#FFE5CC → #FFD4A8 → #FFC08A，点缀金色#FFD700、粉色#FFB6C1。 - 注意：项目中颜色多为硬编码字面量，尚未统一走
Theme.of(context).colorScheme（有优化空间）。
网络环境配置（重要）
- 环境切换在
lib/core/network/api_env.dart：baseUrl三级优先级 =--dart-define=API_BASE_URL>!kDebugMode取kProdBaseUrl>kLocalBaseUrl。 - 消费链：
dio_client.dart的dioProvider→BaseOptions.baseUrl；API 层使用相对路径（如/auth/login）。 - 生产地址当前为
http://103.36.220.231:12345/api（明文 HTTP + 裸 IP）。与注释及docs/Flutter打包与真机安装指南.md中记录的https://accounting.aqroid.cn/api不一致。 ios/Runner/Info.plist无任何 ATS 例外配置 → iOS 包请求 http 会被拦截。android/app/src/main/AndroidManifest.xml已设android:usesCleartextTraffic="true"。- 已知风险：①
--dart-define在 release 下同样生效，可击穿"正式包走生产"的保证；②kDebugMode在 profile 模式为 false → profile 包会连生产，宜改用kReleaseMode。
待办 / 可优化点
- 硬编码颜色可迁移为 M3 角色色（
colorScheme.primary等），并补暗色模式。 api_env.dart优先用kReleaseMode显式判断，并统一生产地址（域名 + HTTPS）；多环境改用--dart-define-from-file；加运行时自检/启动日志显示当前 baseUrl。- iOS 若需访问明文 HTTP，需在
Info.plist增加 ATS 例外（NSAllowsLocalNetworking或域例外）。 MainShell未做响应式：宽屏（≥600dp/840dp）应切换NavigationRail/NavigationDrawer。MainShell.initState的addPostFrameCallback回调里可加if (!mounted) return;。- Flutter 3.47 起 Material/Cupertino 已解耦为
material_ui/cupertino_ui包，package:flutter/material.dart仍可用，暂无需迁移。
应用名称与图标（已落地）
- 显示名统一为 强宝爱记账：
AndroidManifest.xml的android:label、Info.plist的CFBundleDisplayName、web/index.html的<title>与apple-mobile-web-app-title；web/manifest.json用short_name = 强宝记账（4 字以内避免桌面截断）。 - 图标链路：
tools/make_app_icon.py（去水印 + 抠图 + 缩放）→assets/icon/app_icon.png+app_icon_fg.png→dart run flutter_launcher_icons。 - 图标配置在
pubspec.yaml末尾的flutter_launcher_icons段；dev 依赖已加flutter_launcher_icons: ^0.14.0。 - 素材归档在
assets/icon/_source/（raw_bear.png采用、raw_bear_dog.png备选）。assets/icon/未声明为 Flutter assets，不会进包。 assets/images/logo.png（1120×928 贴纸海报）不可用作图标：非正方形、带虚化底纹、含大字，48px 下不可读。- 改图标 = 重跑上面两条命令；改名字后需卸载重装才刷新桌面。
用户画像与偏好
- 用户正在系统学习 Flutter 基础概念，常就单个文件/代码片段提问（如
GlobalKey、ConsumerWidget、ref、Stack）。 - 沟通偏好：希望用中文解释，讲清「是什么 + 为什么这么写 + 在本项目中的上下文」，并配合结构化的表格/分层说明。
- 用户对 Material 3、多端适配、官方文档出处感兴趣，回答时应附官方文档链接。