Flutter 架构

本页说明 apps/flutter_app/lib/ 的工程组织方式，以及各层在当前实现中的职责边界。

目录结构

目录	当前职责	典型内容
lib/api/	后端访问层	AuthApiClient、ChatApiClient、UserApiClient
lib/bloc/	feature 状态管理	AuthBloc、ChatBloc、ExerciseBloc 等
lib/config/	环境、网络、主题	environment_config.dart、network_config.dart、theme/
lib/data/	前端静态内容数据	康复知识卡、静态内容池
lib/models/	API 与页面模型	auth/chat/exercise/health 等模型
lib/screens/	页面与容器页	auth、chat、home、exercise、profile 等
lib/services/	非 API 的服务逻辑	export_service.dart、llm_provider_service.dart
lib/utils/	纯工具逻辑	卡路里计算、错误处理、profile 文案解析
lib/widgets/	可复用 UI 组件	common、chat、exercise、health、weekly_report 等
lib/main.dart	入口与装配	MaterialApp、主题、路由、全局 Bloc 注册

装配入口

main()

• 调用 WidgetsFlutterBinding.ensureInitialized()
• 初始化 LLMProviderService.instance.init()
• 启动 FitDocApp

FitDocApp

• 用 MultiBlocProvider 注册全局 BLoC
• 配置 MaterialApp
• 注入：
  • AppTheme.lightTheme
  • 本地化 delegates
  • home: SplashScreen()
  • 命名路由与 onGenerateRoute

当前分层关系

应用装配main.dart

页面容器Screen

状态与流程BLoC

↴

复用渲染Widgets / Theme Tokens

数据访问API Client / Service

运行依赖NetworkConfig / SecureStorage

关键实现特征

1. 根部注册 + 页面内局部创建并存

全局在 main.dart 注册的 BLoC：

• AuthBloc
• PrescriptionBloc
• ExerciseBloc
• CompanionBloc
• HealthOverviewBloc
• CalendarBloc
• WeeklyReportBloc

页面内局部创建的典型 BLoC：

• SplashScreen -> SplashBloc
• ChatScreen -> ChatBloc
• OnboardingFlowScreen -> OnboardingBloc
• ExerciseHistoryScreen -> ExerciseHistoryBloc

这说明当前前端采用的是“全局公共状态 + 页面局部状态”混合装配模式。

2. 主题系统已经独立成一套 token 层

lib/config/theme/ 当前包括：

• app_colors.dart
• app_typography.dart
• app_sizes.dart
• app_theme.dart
• app_animations.dart
• app_transitions.dart

首页、Chat、运动、我的页、启动页和设置页都在向这套主题系统收敛；新增页面应优先复用这些 token 与转场工具。

3. 通用组件层已经形成复用中心

lib/widgets/common/ 是当前 Flutter 架构里的重要稳定层，包含：

• fitdoc_card.dart
• primary_button.dart
• network_error_widget.dart
• skeleton_loader.dart
• fitdoc_app_bar.dart
• tab_navigation_controller.dart
• inline_status_banner.dart

这些组件贯穿 auth、home、exercise、health、profile 等页面。

4. feature 边界仍依赖命名约定

虽然 bloc/auth、bloc/chat、bloc/exercise 等按 feature 分目录，但 screens/、widgets/、api/ 仍是按技术层收纳。 优点是查找快；代价是需要开发者自己维护 feature 间边界，不是强模块化结构。

已知工程事实

• ExerciseBloc 内部仍包含 _loadMockExerciseCategories()，说明运动动作库并未完全来自后端。
• ChatApiClient 使用 Dio，而 UserApiClient / AssessmentApiClient 使用 http.Client，网络访问风格尚未统一。
• flutter_secure_storage 是多个 client / bloc 的共用依赖，承担 JWT token 读取与部分缓存功能。

这些事实意味着 Flutter 工程已经具备较清晰的装配骨架和复用中心，但尚未完全收敛为单一技术风格。对开发者来说，这意味着它足够支撑功能迭代与交接，却仍需要在新增实现时有意识地维护边界一致性。

架构阅读建议

如果目的是快速理解 Flutter 工程：

1. 先看 main.dart，确认装配入口。
2. 再看 lib/bloc/，确认状态流和业务流程是怎么切的。
3. 再看 lib/api/，确认前端如何触达后端。
4. 最后回到 lib/screens/ 和 lib/widgets/ 看页面和组件。

来源锚点

• apps/flutter_app/lib/main.dart
• apps/flutter_app/lib/config/theme/
• apps/flutter_app/lib/widgets/common/
• apps/flutter_app/lib/bloc/
• apps/flutter_app/lib/api/