边界与主链

本页回答两个问题：

1. 当前系统的主要边界是怎么切的。
2. 用户主链在跨端和跨层之间是怎么被装配起来的。

后端边界

入口与装配main.py / bootstrap.py

运行时依赖runtime.py / app.state

HTTP 适配层app/api/*

业务编排层use_cases / services

↴

数据访问层repositories / models

外部持久化PostgreSQL / LLM

AI 与安全边界core / external

当前解释

层级	当前职责	备注
main.py	暴露 ASGI app	不应重新塞回装配细节
bootstrap.py	创建 FastAPI app、注册 router、配置 CORS/static	当前 backend composition root
runtime.py	运行时读取 settings、session、db、rag、storage	当前依赖解析入口
api/	HTTP adapter	请求/响应、鉴权、状态码、schema
use_cases/	主链编排	chat / prescription / assessment / companion 已有样板
core/	规则、配置、RAG partial boundary	不是纯领域层全集
services/	面向基础设施与存量业务服务	部分是 legacy 兼容承载层
repositories/models	数据访问与持久化	SQLAlchemy + PostgreSQL

Flutter 边界

应用入口lib/main.dart

全局装配MaterialApp / routes

页面与组件screens / widgets

↴

状态与模型bloc / models

后端访问api / network config

后端 APIFastAPI

当前解释

层级	当前职责	备注
main.dart	主题、路由、全局 BlocProvider	入口装配层
screens/	页面与容器	页面结构与轻导航
widgets/	复用渲染组件	common / feature widgets
bloc/	状态流与事件边界	feature 级状态管理
api/	backend 访问层	dio 与 http client 混用
models/	前端 contract 与状态数据	页面和 API 都依赖

主链装配

主链 1：登录 / 建档 / 主页

sequenceDiagram
  participant User as User
  participant Splash as SplashScreen
  participant Auth as Auth Screens
  participant AB as AuthBloc
  participant API as AuthApiClient
  participant Onboarding as OnboardingFlow
  participant Home as HomeScreen

  User->>Splash: 启动 App
  Splash-->>Auth: 未登录 -> 登录入口
  Auth->>AB: 发起验证码或密码登录
  AB->>API: 调 auth backend
  API-->>AB: token / userId / healthInfoCompleted
  AB-->>Auth: AuthAuthenticated
  Auth-->>Onboarding: 未完成建档
  Auth-->>Home: 已完成建档

主链 2：评估 / 咨询 / 处方 / 运动执行

sequenceDiagram
  participant Home as Dashboard
  participant Chat as ChatScreen
  participant PB as PrescriptionBloc
  participant CB as ChatBloc
  participant API as Backend APIs
  participant Exercise as ExerciseScreen
  participant Exec as ExerciseExecution

  Home-->>Chat: 生成处方入口
  Chat->>CB: 发送咨询消息
  CB->>API: chat API
  API-->>CB: 对话响应 / 会话ID
  Chat->>PB: 发起处方生成
  PB->>API: prescription API
  API-->>PB: 当前处方
  PB-->>Exercise: 处方进入运动中心
  Exercise-->>Exec: 开始一次运动执行

主链 3：运动记录 / 健康总览回流

阶段	前端	后端 / 数据层
运动执行中	ExerciseExecutionScreen + ExerciseBloc	active sport log
运动完成	保存日志并进入反馈页	sport_logs
历史查看	ExerciseHistoryScreen	history / pagination
日历回看	CalendarScreen	calendar aggregation
健康总览	HealthOverviewScreen	companion / overview aggregation

健康总览在这里表示 companion overview 聚合能力的代码边界。HealthOverviewScreen 当前入口隐藏，因此它不应被当作当前用户主链的可达终点；对架构读者来说，更重要的是理解 sport / calendar / companion 之间的聚合关系。

当前边界纪律

• 新 backend 主链优先进入 use_cases/，不要把完整业务编排写回 router。
• 新 runtime 依赖优先通过 bootstrap/runtime 装配。
• Flutter screen/widget 只负责消费状态、派发事件和轻量导航，不重新握住主业务编排。
• Flutter 导航真相源仍然是 MaterialApp + routes + onGenerateRoute + Navigator。

跨边界检查表

变更穿过的边界	必查项
Flutter screen -> BLoC	页面是否只派发事件和渲染状态，是否把复杂业务判断塞回 widget
BLoC -> API client	client 是否可注入，token / error / timeout 是否有一致处理
API client -> backend route	path、auth、request / response 是否与后端 route surface 对齐
API route -> use case	route 是否只做 adapter，主链编排是否进入 use case 或既有 service
use case -> repository / model	读写表是否清楚，事务和异常边界是否可测试
backend -> RAG / LLM	prompt、召回、安全过滤、provider error 是否有降级或可审计边界
runtime -> production	本地配置、环境变量、systemd / Nginx 口径是否与当前单服务部署一致

这张表用于判断一次变更是否已经跨过单页或单模块范围。跨边界越多，越需要同步更新对应文档、测试和来源锚点。

当前残余但不应误写的事实

• services/ 层仍承接部分 legacy 业务逻辑，不应被文档写成已经完全“纯 port/gateway 化”。
• Flutter 并不是全仓严格 feature package 化结构，而是技术层目录 + feature 命名约定的混合模式。
• RAG 的深层治理边界仍然应回专项文档，不在这里展开。
• HealthOverviewScreen、WeeklyReportScreen 代码与路由保留，但当前入口隐藏；架构文档可以记录边界存在，流程文档不能把它们写成当前主入口。

来源锚点

• apps/backend_service/app/main.py
• apps/backend_service/app/bootstrap.py
• apps/backend_service/app/runtime.py
• apps/backend_service/app/use_cases/
• apps/flutter_app/lib/main.dart
• apps/flutter_app/lib/bloc/