外观
API 与接口契约总览
乐橙智康后端由 FastAPI 装配，当前生产入口通过 Nginx 转发到 fitdoc-core:8001。接口路径来自 app/bootstrap.py 的 include prefix 与各 router 自身 prefix 组合，当前不是统一 /api/v1/ 版本面。
路径分组
| 分组 | Base Path | 鉴权 | 主要消费者 | 数据落点 |
|---|---|---|---|---|
| 认证 | /api/auth | 登录注册接口无 JWT；complete-health-info 需要 Bearer JWT | AuthApiClient、AuthBloc | users、sms_verifications、login_logs |
| 用户档案 | /api/user | Bearer JWT | UserApiClient、建档/我的页面 | users、user_profiles、user_diseases、user_operations、update_logs |
| 聊天 | /api/chat | 大多数接口 Bearer JWT；安全指南公开 | ChatApiClient、ChatBloc | chat_sessions、dialogue_logs；RAG 读取 knowledge_chunks |
| 处方 | /api/prescription | Bearer JWT | PrescriptionApiClient、PrescriptionBloc、Chat 处方卡 | sport_schemes；可写 dialogue_logs |
| 运动 | /api/sport | Bearer JWT | SportApiClient、FeedbackApiClient、ExerciseHistoryApiClient | sport_logs、sport_schemes、user_profiles |
| 评估 | /api/assessment | safety_check、submit、last 需要 Bearer JWT；symptoms 当前公开 | AssessmentApiClient、详细评估流程 | user_health_profiles、user_profiles.assessment_context |
| 安全 | /api/safety | 当前 router 未挂 JWT dependency | safety / chat / RAG 调试链路 | 内容检查不落库；事件报告写 safety_incidents 脱敏审计记录 |
| 陪伴 | /api/companion | Bearer JWT；debug route 只在开发模式注册 | CompanionApiClient、健康总览相关 BLoC | virtual_companion、users、user_profiles、sport_logs |
通用鉴权
受保护接口通过 HTTPBearer 解析 Authorization: Bearer <jwt>。JWT payload 必须包含 user_id，后端会再查询 users 表确认用户存在。缺失、无效或用户不存在均返回 401。
跨端联调边界
| 类型 | 当前事实 | 处理方式 |
|---|---|---|
| Base URL | Flutter 默认 EnvironmentConfig.baseUrl 为 /api，部分 client 会把模块前缀裁掉后再写完整 path。 | 以最终请求路径为准，不从 client 构造方式推断后端真实 prefix。 |
| 非统一版本面 | 后端没有统一 /api/v1。 | 文档使用真实路径，不添加版本前缀。 |
| 兼容型接口 | /api/sport/types、/api/sport/sync-calendar、/api/companion/status-history 已作为生产接口保留。 | 文档按真实 endpoint 记录；其中 calendar sync 当前是幂等 no-op，companion status history 返回当前状态快照。 |
| 陪伴 debug route | /api/companion/test、/api/companion/health-overview-test 只在 DEVELOPMENT_MODE=true 时注册。 | 不作为生产 API。 |
| 隐藏入口页面 | HealthOverviewScreen 与 WeeklyReportScreen 的代码和路由保留，但当前不作为可达入口。 | API 可存在，页面入口不可写成当前可达。 |
Endpoint 索引
| 文档 | 覆盖内容 |
|---|---|
| 认证 API | 短信、验证码注册/登录、密码注册/登录、健康信息完成标记。 |
| 用户 API | 基本资料、健康指标、疾病史、手术史、头像、完整档案。 |
| 聊天 API | 聊天消息、历史、会话、软删除、安全指南。 |
| 处方 API | 处方生成、当前处方、替换、统计、Demo 动作库处方。 |
| 运动 API | 运动记录、运动分类、MET、日历、周报、历史、自定义运动、方案与一致性检查。 |
| 评估 API | G1-M3 安全检查、症状标签、完整评估提交、最近评估读取。 |
| 安全 API | 内容安全检查、风险评估、安全指南、事件报告、运动建议、知识库验证。 |
| 陪伴 API | 虚拟陪伴状态、情绪、外观、健康总览。 |
| 错误码与鉴权 | 401/403/404/409/422/429/5xx 与前端处理口径。 |
来源锚点
- Backend app assembly:
apps/backend_service/app/bootstrap.py - Backend routers:
apps/backend_service/app/api/ - Auth dependency:
apps/backend_service/app/api/auth_dependencies.py - Flutter clients:
apps/flutter_app/lib/api/ - Backend tests:
apps/backend_service/tests/api/、apps/backend_service/tests/use_cases/