App 前端总览

本板块说明 Flutter 前端工程的组织方式、主要边界和关键替换点。页面体验、主流程和视觉说明已经放在 App 使用与页面说明；这里重点回答的是：

• Flutter 端代码怎么组织
• 页面、BLoC、API client 和通用组件怎么协作
• 当前前端有哪些真实替换点和测试护栏

结论

当前前端是一个典型的 Flutter 单应用结构，核心实现特点有四个：

1. 入口集中在 lib/main.dart，统一注册全局 BlocProvider、主题和命名路由。
2. 页面主要落在 lib/screens/，状态管理以 feature BLoC 为主，目录在 lib/bloc/。
3. API 访问层分为两种风格：
   • dio 风格 client，如 AuthApiClient、ChatApiClient
   • http 风格 client，如 UserApiClient、AssessmentApiClient
4. 前端已经具备较完整测试骨架，包含 api / bloc / screens / widgets / integration 多层测试。

这四点说明前端已经有清晰的工程骨架，但读者需要同时区分三个层面：页面是否存在、入口是否当前可达、数据是否已经完全接入后端。代码保留或测试存在，不自动等于该能力属于当前主业务入口。

内容地图

文档	说明
Flutter 架构	lib/ 目录、分层、通用组件、配置与运行边界
路由与页面实现	MaterialApp + routes + onGenerateRoute + Navigator 的真实路由结构
BLoC 状态管理	feature BLoC 列表、职责、事件与状态边界
API Client 与数据流	前端 client、鉴权 token、网络配置、数据回流路径
测试与替换点	可注入依赖、contract tests、widget / integration 护栏

前端结构图

应用入口lib/main.dart

全局装配MaterialApp / BlocProvider

页面与组件screens / widgets

状态与数据模型bloc / models

↴

数据访问api / services / utils

后端接口FastAPI APIs

主题与网络配置config/theme / network

当前实现判断

1. 页面是 feature-first 的，但不是严格模块化包结构

• 页面、BLoC、widgets、api、models 仍按技术层拆目录。
• 这意味着它易于快速定位技术面，但 feature 内聚度仍依赖命名与目录约定，而不是独立 package。

2. 全局依赖集中在 main.dart

• AuthBloc、PrescriptionBloc、ExerciseBloc、CompanionBloc、HealthOverviewBloc、CalendarBloc、WeeklyReportBloc 在应用根部注册。
• 一些页面内部还会再创建局部 BLoC，例如 ChatScreen、SplashScreen、OnboardingFlowScreen。

3. 数据访问层存在技术风格混用

• ChatApiClient 用 Dio + Interceptor + secure storage
• UserApiClient / AssessmentApiClient 用 http.Client + secure storage
• 这不是错误，但会影响统一的错误处理、超时、日志和替换点口径。

4. 并不是所有前端数据都已经完全接入真实后端

• ExerciseBloc 的运动分类当前仍通过 _loadMockExerciseCategories() 构造本地数据。
• 首页部分统计卡片仍有静态展示值。
• HealthOverviewScreen、WeeklyReportScreen 相关 BLoC 与测试仍保留，但当前入口隐藏。
• 文档必须把这些“前端看起来完整，但内部仍有 mock/static”的点说清楚。

这意味着阅读前端工程文档时，既要看页面结构是否完整，也要看数据链是否真正接通。对于交接和联调来说，这一点比单纯知道页面放在哪个目录更重要。

变更落点判断

变更类型	优先落点	同步检查
新页面或新入口	lib/screens/ + main.dart route / 页面内 Navigator	页面是否当前可达、是否需要截图和路由文档更新
跨页面状态或 API 状态	lib/bloc/<feature>/	是否需要 event/state/test，是否影响已有全局 BLoC
后端请求或 token 传递	lib/api/*ApiClient	使用 Dio 还是 http.Client，是否支持依赖注入和错误处理
通用视觉组件	lib/widgets/common/ 或 lib/config/theme/	是否复用 token，是否影响 UI consistency tests
本地展示数据	lib/data/ 或 feature 内局部数据	是否明确标注为 static/mock，不能在产品文档写成后端动态数据
隐藏入口能力维护	原 feature 文件 + 测试	只能说明代码仍可维护，不改变产品可达性口径

接续阅读

想继续看什么	推荐入口
想快速理解 lib/ 怎么分层	Flutter 架构
想看命名路由和页面入口	路由与页面实现
想看每个 BLoC 管什么	BLoC 状态管理
想看 token、网络和依赖注入	API Client 与数据流
想看如何做替换测试	测试与替换点

来源锚点

• Flutter entry：apps/flutter_app/lib/main.dart
• API clients：apps/flutter_app/lib/api/
• BLoCs：apps/flutter_app/lib/bloc/
• Screens：apps/flutter_app/lib/screens/
• Tests：apps/flutter_app/test/