核心链路

本页描述 backend 在几条关键业务链路中的端到端职责。这里不追求把每一个接口细节写满，而是强调：入口从哪里来、业务如何编排、数据落到哪里、异常通常出现在哪一段。

1. 登录认证链路

维度	当前情况
前端入口	PhoneInputScreen、VerificationCodeScreen、PasswordLoginScreen
后端入口	app/api/auth.py
主要服务	AuthService、SmsService
主要存储	sms_verifications、login_logs、users 相关表
关键结果	返回 token、userId、healthInfoCompleted

说明

• auth 模块不仅完成注册和登录，还负责登录后是否进入建档闭环的判断依据。
• 登录成功后前端会把 token 写入 secure storage，后续 user/chat/exercise 等 client 通过它继续访问主链。

2. AI 聊天链路

维度	当前情况
前端入口	ChatScreen
后端入口	app/api/chat.py
主要编排	SendChatMessageUseCase
关键依赖	RAG、LLM manager、dialogue repository
主要存储	dialogue_logs、chat_sessions

说明

• 这是当前最典型的“router -> use case” 主链样板。
• 聊天响应不只返回文本，还会返回 sessionId、RAG 上下文、置信信息等内容。
• 会话相关能力还包括历史记录、session 列表、删除 session 与 safety guidelines。

3. 运动处方链路

维度	当前情况
前端入口	DashboardPage、ChatScreen、ExerciseScreen
后端入口	app/api/prescription.py
主要编排	GeneratePrescriptionUseCase、GetCurrentPrescriptionUseCase、ReplacePrescriptionUseCase
关键依赖	PrescriptionService、RAG / user profile / repository
主要存储	sport_schemes、相关对话记录

说明

• 处方既是单独模块，也是 Chat 与 Exercise 之间的桥梁。
• 前端生成处方后，会让 PrescriptionBloc 和 ExerciseBloc 共同消费结果。
• 当前 prescription 模块还带有统计、demo 等外围 surface，阅读时应与核心主链区分开。

4. 运动执行与记录链路

维度	当前情况
前端入口	ExerciseScreen、ExerciseExecutionScreen、ExerciseHistoryScreen
后端入口	app/api/sport.py
主要服务	SportService、SportLogRepository、SportSchemeRepository
主要存储	sport_logs、sport_schemes、update_logs
关键行为	active log、反馈、历史、日历、统计

说明

• sport 模块承载面最宽，既有执行主链，也有历史和聚合展示。
• 对交接来说，最重要的是先看 active log、保存日志、反馈、历史这条执行闭环，再看 calendar / stats / weekly-report 等聚合视图。

5. 评估与健康总览链路

维度	当前情况
前端入口	DashboardPage、DetailedAssessmentModal；HealthOverviewScreen 代码保留但当前入口隐藏
后端入口	app/api/assessment.py、app/api/companion.py
主要编排	PerformSafetyCheckUseCase、SubmitFullAssessmentUseCase、GetHealthOverviewUseCase
关键依赖	profile、assessment data、companion aggregation
主要结果	安全结论、评估提交、健康总览聚合结果

说明

• assessment 和 companion 一前一后，前者更偏评估输入，后者更偏聚合展示输出。
• 这条链路对首页摘要、我的页今日状态和 companion overview 聚合能力都有影响。
• GetHealthOverviewUseCase 与 /api/companion/health-overview 仍是后端有效边界；但 Flutter 的 HealthOverviewScreen 当前入口隐藏，不能把它写成当前可达主流程页面。

当前链路阅读建议

如果只想先抓住 backend 最重要的四条主链，建议按这个顺序：

1. auth
2. chat
3. prescription
4. sport

assessment / companion 则更适合作为“主链两端的输入与结果聚合层”理解。

异常与排查落点

链路	常见异常位置	优先排查
auth	验证码、密码登录、token 写入、建档标记	auth router、AuthService、sms_verifications、login_logs
chat	会话 ID、RAG context、LLM 响应、安全提示	SendChatMessageUseCase、dialogue repository、RAG / LLM client
prescription	用户 profile 不完整、RAG 召回、处方保存、当前处方读取	prescription use cases、PrescriptionService、sport_schemes
sport	active log 恢复、日志保存、反馈提交、历史分页	SportService、sport repositories、sport_logs
assessment / companion	安全检查、评估提交、overview 聚合、隐藏入口误判	assessment / companion use cases、profile / assessment data

这些排查落点不替代 API reference 和数据库 reference。它们用于帮助读者先判断故障在哪条链路、哪一层最可能出问题。

来源锚点

• apps/backend_service/app/api/auth.py
• apps/backend_service/app/api/chat.py
• apps/backend_service/app/api/prescription.py
• apps/backend_service/app/api/sport.py
• apps/backend_service/app/api/assessment.py
• apps/backend_service/app/api/companion.py
• apps/backend_service/app/use_cases/