陪伴 API

陪伴接口维护虚拟陪伴状态、情绪、外观配置，并提供健康总览聚合数据。生产接口都要求 Bearer JWT；debug route 只在 DEVELOPMENT_MODE=true 时注册。

Endpoint 索引

Method	Path	用途
GET	/api/companion/status	读取虚拟陪伴状态。
PUT	/api/companion/update-emotion	按健康分数更新情绪。
POST	/api/companion/initialize	初始化虚拟陪伴。
PUT	/api/companion/appearance	更新外观配置。
POST	/api/companion/auto-configure-appearance	按用户资料自动配置外观。
GET	/api/companion/health-overview	读取健康总览聚合数据。
GET	/api/companion/status-history	读取陪伴状态兼容快照。

Endpoint 契约

GET /api/companion/status

项	内容
Request	无
Response	companion status
Errors	401；404 未初始化且无法自动创建；500
Consumer	后端生产接口；当前 Flutter client 主要误调 debug /test
Handler	companion.get_companion_status
DB Touchpoints	读/可能创建 virtual_companion；读 user_profiles
Tests	tests/api/test_story_7_4_fixes.py

PUT /api/companion/update-emotion

项	内容
Request	health_score 0-100、trigger_reason
Response	更新后的 companion status
Errors	401；404；422；500
Consumer	CompanionApiClient.updateCompanionEmotion
Handler	companion.update_companion_emotion
DB Touchpoints	更新 virtual_companion
Tests	service tests / source inspection

POST /api/companion/initialize

项	内容
Request	user_gender、user_age、initial_health_score
Response	companion status
Errors	401；422；500
Consumer	CompanionApiClient.initializeCompanion
Handler	companion.initialize_companion
DB Touchpoints	写或读 virtual_companion
Tests	source inspection

PUT /api/companion/appearance

项	内容
Request	外观配置字段
Response	companion status
Errors	400 无更新字段；401；404；422；500
Consumer	CompanionApiClient.updateCompanionAppearance
Handler	companion.update_companion_appearance
DB Touchpoints	更新 virtual_companion.appearance_config
Tests	source inspection

POST /api/companion/auto-configure-appearance

项	内容
Request	无
Response	companion status
Errors	401；404 companion 或 profile 缺失；500
Consumer	CompanionApiClient.autoConfigureCompanionAppearance
Handler	companion.auto_configure_companion_appearance
DB Touchpoints	读 user_profiles；更新 virtual_companion
Tests	source inspection

GET /api/companion/health-overview

项	内容
Request	无
Response	user profile、health metrics、exercise statistics、trend、companion status、recommendations
Errors	401；500
Consumer	CompanionApiClient.getHealthOverview、HealthOverviewBloc
Handler	companion.get_health_overview -> GetHealthOverviewUseCase
DB Touchpoints	读 users、user_profiles、user_diseases、sport_logs、virtual_companion
Tests	tests/use_cases/test_get_health_overview_use_case.py、Flutter health overview tests；HealthOverviewScreen 代码与路由保留，但当前不作为可达入口

GET /api/companion/status-history

项	内容
Request	query days，范围 1-365，默认 30
Response	当前 companion status 快照数组；未初始化时返回空数组
Errors	401；422；500
Consumer	CompanionApiClient.getCompanionStatusHistory
Handler	companion.get_companion_status_history
DB Touchpoints	读 virtual_companion 当前状态
Tests	tests/api/test_companion_debug_route_guards.py、tests/api/test_story_7_4_fixes.py

Debug route

Method	Path	注册条件	说明
GET	/api/companion/health-overview-test	DEVELOPMENT_MODE=true	无鉴权调试健康总览，包含固定测试 user id；生产不注册。
GET	/api/companion/test	DEVELOPMENT_MODE=true	无鉴权 companion mock status；生产不注册。

前后端契约差异

Flutter 调用	后端当前状态	处理方式
GET /api/companion/test	只在开发模式注册	不能作为生产获取状态接口；生产应使用 /api/companion/status。
GET /api/companion/status-history?days=...	生产 route 存在	返回当前状态快照，不代表独立历史流水表。
GET /api/companion/health-overview	后端存在，Flutter client 存在	HealthOverviewScreen 代码与路由保留，但当前不作为可达入口。

Response 结构

Companion status 典型字段：

{
  "companion_id": "<id>",
  "gender": "female",
  "age_group": "young",
  "current_emotion": "happy",
  "health_score": 75,
  "current_state": "female_young_happy",
  "state_config": {},
  "appearance_config": {},
  "position_config": {},
  "last_updated": "2026-05-08T10:00:00Z"
}

来源锚点

• Router: apps/backend_service/app/api/companion.py
• Service: apps/backend_service/app/services/companion_service.py
• Use case: apps/backend_service/app/use_cases/companion/get_health_overview.py
• Flutter: apps/flutter_app/lib/api/companion_api_client.dart
• Tests: apps/backend_service/tests/api/test_companion_debug_route_guards.py、apps/backend_service/tests/use_cases/test_get_health_overview_use_case.py