外观
主流程与跳转关系
本页集中说明用户从启动到核心业务闭环的主流程，以及当前代码里的主要跳转方式。当前导航真相源仍然是 MaterialApp + routes + onGenerateRoute + Navigator，不是 GoRouter。
主流程图
mermaid
flowchart LR
Splash["启动检查\nSplashScreen"] --> Access["登录或注册\nAuth flow"]
Access --> Profile["建档分流\nprofile gate"]
Profile --> Home["主容器\nHomeScreen"]
Home --> Tabs["主功能入口\nDashboard / Chat / Exercise / Profile"]导航骨架
| 层级 | 当前实现 | 说明 |
|---|---|---|
| App 默认入口 | home: SplashScreen() | 启动后先检查登录态 |
| 命名路由 | /splash /home /chat /chat/history /registration /onboarding /health-overview /weekly-report | MaterialApp.routes 中定义 |
| 兜底路由 | onGenerateRoute | 当前对 /health-overview、/weekly-report、/chat/history 指定转场 |
| 主业务容器 | HomeScreen | 底部 4 栏 + 首页内部双 tab |
| 跨页跳转 | Navigator.push / pushReplacement / pushAndRemoveUntil + AppTransitions.* | 大量细节页使用自定义转场 |
跳转类型
| 类型 | 表现 | 典型位置 | 交接关注点 |
|---|---|---|---|
| 路由替换 | 当前页被新页替换，返回键不回到原页 | SplashScreen、注册成功、建档完成 | 用于分流或流程收口，避免回到过期状态 |
| 清栈跳转 | 清空历史栈后进入目标页 | 密码登录成功、退出登录 | 决定用户能否回到鉴权页或主页前状态 |
| 详情推进 | 保留上一页，进入详情或执行页 | 密码登录、个人信息、设置、运动执行、运动历史 | 需要确认返回后是否刷新上层状态 |
| 容器切页 | 不创建新路由，只改当前 tab index | 底部四栏、首页/日历、Dashboard 处方卡 | 读者不能把它误读成独立页面跳转 |
| 弹窗 / 抽屉 | 不离开当前页面，只覆盖局部交互层 | Chat 会话删除、帮助/关于、退出确认、Chat 历史抽屉 | 不应在页面索引中当作独立页面 |
关键跳转表
| From | Action | To | 当前实现 | 备注 |
|---|---|---|---|---|
SplashScreen | SplashRouteTarget.home | HomeScreen | Navigator.pushReplacement(MaterialPageRoute) | 启动页分流到主页 |
SplashScreen | SplashRouteTarget.login | PhoneInputScreen | Navigator.pushReplacement(MaterialPageRoute) | 启动页分流到登录 |
PhoneInputScreen | 验证码发送成功 | VerificationCodeScreen | Navigator.push(AppTransitions.pushDetail(...)) | 保留返回上一步能力 |
PhoneInputScreen | 点击密码登录 | PasswordLoginScreen | Navigator.push(AppTransitions.pushDetail(...)) | 鉴权分支切换 |
VerificationCodeScreen | 注册成功 | RegistrationSuccessScreen | Navigator.pushReplacement(...) | 进入注册成功页 |
RegistrationSuccessScreen | 点击开始使用 | OnboardingFlowScreen | Navigator.pushAndRemoveUntil(MaterialPageRoute) | 短信验证码注册分支进入建档 |
PasswordRegisterScreen | 注册成功 | OnboardingFlowScreen | Navigator.pushAndRemoveUntil(MaterialPageRoute) | 密码注册分支进入建档 |
PasswordLoginScreen | 登录成功且已完成建档 | HomeScreen | pushAndRemoveUntil(AppTransitions.fade(...)) | 清空栈进入主页 |
PasswordLoginScreen | 登录成功但未完成建档 | OnboardingFlowScreen | pushAndRemoveUntil(AppTransitions.fade(...)) | 首次建档入口 |
OnboardingFlowScreen | 首次建档完成 | OnboardingCompleteScreen | pushReplacement(MaterialPageRoute) | 完成后再回主页 |
OnboardingFlowScreen(isEditMode: true) | 编辑档案保存成功 | ProfilePage | Navigator.pop({'saved': true, ...}) | 返回后刷新个人资料概览 |
ProfilePage | 编辑健康档案 | OnboardingFlowScreen(isEditMode: true) | Navigator.push(AppTransitions.pushDetail(...)) | 编辑模式复用建档流程 |
HomeScreen | 点击底部 AI助手 | ChatScreen | 底部导航切 tab | 非独立 push |
HomeScreen | 点击底部 健身 | ExerciseScreen | 底部导航切 tab | 非独立 push |
HomeScreen | 点击底部 我的 | ProfilePage | 底部导航切 tab | 非独立 push |
HomeScreen | 首页顶部 日历 tab | CalendarScreen | TabBarView 切页 | 仍处于首页栏内部 |
Dashboard | 处方卡 开始运动 | ExerciseScreen | 通过 navigateToTab(2) | 直接切到底部健身 tab |
Dashboard | 处方卡 生成处方 | ChatScreen | 通过 navigateToTab(1) | 跳到 Chat 生成方案 |
ExerciseScreen | 点击某动作开始 | ExerciseExecutionScreen | Navigator.push(AppTransitions.pushDetail(...)) | 进入执行页 |
ExerciseExecutionScreen | 退出确认 | ExerciseScreen | Navigator.pop | 回到运动中心 |
ExerciseExecutionScreen | 运动完成 | ExerciseFeedbackScreen | Navigator.pushReplacement(MaterialPageRoute) | 执行页被反馈页替换 |
ExerciseFeedbackScreen | 反馈提交成功 | ExerciseScreen | Navigator.popUntil((route) => route.isFirst) | 自动返回主容器 |
ExerciseScreen | 点击历史按钮 | ExerciseHistoryScreen | Navigator.push(AppTransitions.pushDetail(...)) | 进入历史页 |
ExerciseHistoryScreen | 关闭详情弹窗 | 当前历史页 | Navigator.pop | 只关闭弹窗，不离开历史页 |
ProfilePage | 点击个人信息 | PersonalInfoScreen | Navigator.push(AppTransitions.pushDetail(...)) | 返回后刷新 profile overview |
ProfilePage | 点击设置 | SettingsScreen | Navigator.push(AppTransitions.pushDetail(...)) | 设置页是独立详情页 |
ProfilePage | 点击帮助 / 关于 | 弹窗 | showDialog | 不进入独立页面 |
ProfilePage | 退出登录 | PhoneInputScreen | pushAndRemoveUntil(AppTransitions.fade(...)) | 清空栈回登录 |
分阶段理解
1. 启动与鉴权
这一阶段决定用户进入系统后的第一条路径。
SplashScreen先判断登录态。- 未登录用户进入
PhoneInputScreen，可继续走短信验证码分支，也可切到PasswordLoginScreen。 - 短信验证码注册成功后进入
RegistrationSuccessScreen，点击“开始使用”进入OnboardingFlowScreen。 - 密码登录成功后按
healthInfoCompleted分流：已建档进入HomeScreen，未建档进入OnboardingFlowScreen。 - 密码注册成功后直接进入
OnboardingFlowScreen。
2. 建档
建档阶段决定健康资料如何进入主业务容器。
- 密码注册或未建档密码登录会进入首次建档流程。
- 已登录用户从个人中心编辑健康档案时复用同一套
OnboardingFlowScreen，但使用isEditMode=true。 - 首次建档完成后进入
OnboardingCompleteScreen，再清栈进入HomeScreen。 - 编辑模式保存成功后
pop回个人中心，并刷新ProfileOverviewBloc。
3. 主页与主业务容器
主业务容器同时处理底部主导航和首页内部切换。
- 底部四栏是
首页 / AI助手 / 健身 / 我的，通过_selectedIndex切换，不创建新路由栈。 - 首页栏内部再由
TabBar + TabBarView切换首页 / 日历。 - 切回首页时会刷新 profile、assessment、prescription；切到健身时会加载当前处方。
DashboardPage的处方卡通过navigateToTab(1/2)切到 Chat 或 Exercise。
4. AI 咨询与处方
AI 咨询阶段把问答、处方生成和运动入口连接在同一条业务链上。
- Chat 主界面位于底部
AI助手tab，不是独立详情页。 - 历史会话既可以通过 Chat 内部抽屉访问，也保留
/chat/history命名路由；抽屉服务会话切换，历史页服务独立列表阅读。 - 会话删除使用
showDialog确认，不离开 Chat 当前页面。 - 处方生成结果会进入对话流，并作为后续运动中心执行的来源之一。
- Dashboard 中无处方时，处方卡把用户切到 Chat 生成方案；已有处方时，处方卡把用户切到 Exercise 执行。
5. 运动执行闭环
运动阶段把计划转成一次可记录的执行闭环。
- 运动中心有
我的计划 / 有氧运动 / 抗阻训练 / 柔韧训练四个 tab。 - 点击动作后，页面会先检查是否存在进行中的运动记录；存在时恢复执行，不存在时新建执行。
- 执行页完成后用
pushReplacement进入反馈页，避免用户回退到已完成的执行态。 - 反馈提交成功后自动回到主容器；运动历史页用于查看列表和详情弹窗。
6. 我的与设置
个人中心聚合资料、设置和账号退出动作。
ProfilePage是个人资料、健康档案、今日状态、设置与退出登录的聚合入口。PersonalInfoScreen和SettingsScreen都从这里以详情页方式推进。- 健康档案编辑从这里进入
OnboardingFlowScreen(isEditMode: true)，保存后回到个人中心刷新资料。 - 帮助与关于使用弹窗呈现，不是独立页面；设置页中的关于信息同样以对话框承载。
- 退出登录先弹出确认框，确认后清理本地 token 和相关 BLoC 状态，并清空栈回到
PhoneInputScreen。
7. 当前不属于主链入口的页面
HealthOverviewScreenWeeklyReportScreen
这两个页面在代码中仍保留路由与实现，但当前入口已隐藏，因此不作为现阶段主链页面理解。
来源锚点
- Flutter entry：
apps/flutter_app/lib/main.dart - Splash：
apps/flutter_app/lib/screens/splash/splash_screen.dart - Auth：
apps/flutter_app/lib/screens/registration/phone_input_screen.dart - Password login：
apps/flutter_app/lib/screens/auth/password_login_screen.dart - Home：
apps/flutter_app/lib/screens/home/home_screen.dart - Exercise：
apps/flutter_app/lib/screens/exercise/exercise_screen.dart