运动 API

运动接口覆盖运动记录、运动分类、MET、日历、周报、历史、自定义运动和数据一致性检查。所有生产 endpoint 都要求 Bearer JWT。

Endpoint 索引

Method	Path	用途
GET	/api/sport/met-values	读取 MET 数据。
GET	/api/sport/exercises	读取运动分类。
GET	/api/sport/types	读取历史筛选使用的运动类型 id。
POST	/api/sport/log	创建运动记录。
GET	/api/sport/logs	分页读取运动记录。
GET	/api/sport/log/{log_id}	读取单条运动记录。
GET	/api/sport/active	读取当前进行中运动。
PUT	/api/sport/log/{log_id}	更新运动记录。
DELETE	/api/sport/log/{log_id}	删除运动记录。
PUT	/api/sport/log/{log_id}/feedback	提交运动反馈。
GET	/api/sport/stats	读取运动统计。
GET	/api/sport/logs/calendar	读取日历聚合数据。
POST	/api/sport/sync-calendar	日历同步兼容入口。
GET	/api/sport/weekly-report	读取周报数据。
GET	/api/sport/history	读取历史记录筛选结果。
POST	/api/sport/log/custom	添加自定义运动记录。
GET	/api/sport/schemes/user/{user_id}	读取指定用户运动方案。
GET	/api/sport/validate-consistency/{user_id}	校验用户运动数据一致性。

Endpoint 契约

运动分类与 MET

GET /api/sport/met-values

项	内容
Request	无
Response	met_data
Errors	401；500
Consumer	SportApiClient.getMetValues
Handler	sport.get_met_values
DB Touchpoints	当前从服务内静态运动分类计算，不读 DB
Tests	tests/services/test_sport_service.py

GET /api/sport/exercises

项	内容
Request	query category
Response	exercise_categories
Errors	401；500
Consumer	SportApiClient.getExerciseCategories
Handler	sport.get_exercise_categories
DB Touchpoints	当前为服务内静态分类，不读 DB
Tests	tests/api/test_sport.py

GET /api/sport/types

项	内容
Request	无
Response	types，值来自运动分类的 category_id
Errors	401；500
Consumer	ExerciseHistoryApiClient 历史筛选
Handler	sport.get_exercise_types
DB Touchpoints	当前从服务内静态分类计算，不读 DB
Tests	tests/api/test_sport.py、tests/api/test_story_7_4_fixes.py

运动记录

POST /api/sport/log

项	内容
Request	sport_name、sport_start、sport_end、cal、iffinish 等
Response	运动记录公开字段
Errors	400 校验失败；409 已有进行中运动；401；500
Consumer	SportApiClient.createSportLog
Handler	sport.create_sport_log
DB Touchpoints	写 sport_logs；读 users；检查 active log
Tests	tests/api/test_sport.py、tests/services/test_sport_service_active_guard.py

GET /api/sport/logs

项	内容
Request	query limit 1-100、offset >=0
Response	logs、total、分页字段
Errors	401；500
Consumer	SportApiClient.getUserSportLogs
Handler	sport.get_user_sport_logs
DB Touchpoints	读当前用户 sport_logs
Tests	tests/api/test_sport.py

GET /api/sport/log/{log_id}

项	内容
Request	path log_id
Response	单条运动记录
Errors	403 非本人；404 不存在；401；500
Consumer	ExerciseHistoryApiClient.getExerciseDetails、FeedbackApiClient.getSportLogWithFeedback
Handler	sport.get_sport_log
DB Touchpoints	读 sport_logs 并校验归属
Tests	tests/api/test_sport.py

GET /api/sport/active

项	内容
Request	无
Response	当前未完成运动记录
Errors	404 无进行中运动；401；500
Consumer	SportApiClient.getActiveSportLog
Handler	sport.get_active_sport_log
DB Touchpoints	读 sport_logs 中 iffinish=false 记录
Tests	tests/api/test_sport.py

PUT /api/sport/log/{log_id}

项	内容
Request	sport_end、cal、iffinish、sport_feedback
Response	更新后记录
Errors	403 非本人；404 不存在；401；500
Consumer	SportApiClient.updateSportLog、ExerciseHistoryApiClient.updateExerciseHistory
Handler	sport.update_sport_log
DB Touchpoints	更新本人 sport_logs
Tests	tests/api/test_sport.py

DELETE /api/sport/log/{log_id}

项	内容
Request	path log_id
Response	message、log_id
Errors	403 非本人；404 不存在；401；500
Consumer	ExerciseHistoryApiClient.deleteExerciseHistory
Handler	sport.delete_sport_log
DB Touchpoints	删除/软删除本人 sport_logs，以 repository 实现为准
Tests	tests/api/test_sport.py

PUT /api/sport/log/{log_id}/feedback

项	内容
Request	completion_status、feeling_rating、custom_notes、final_calories
Response	message、log
Errors	403 非本人；404 不存在；401；500
Consumer	FeedbackApiClient.submitFeedback
Handler	sport.submit_sport_feedback
DB Touchpoints	更新 sport_logs.sport_feedback、cal、iffinish
Tests	tests/services/test_sport_service.py、Flutter feedback tests

统计、日历与历史

GET /api/sport/stats

项	内容
Request	无
Response	用户运动统计
Errors	401；500
Consumer	运动统计入口
Handler	sport.get_user_sport_stats
DB Touchpoints	聚合读 sport_logs
Tests	tests/api/test_sport.py

GET /api/sport/logs/calendar

项	内容
Request	start_date、end_date
Response	calendar_data、summary
Errors	400 日期范围非法；401；500
Consumer	SportApiClient.getCalendarData、CalendarBloc
Handler	sport.get_calendar_data
DB Touchpoints	按日期范围读 sport_logs
Tests	Flutter calendar tests

POST /api/sport/sync-calendar

项	内容
Request	无
Response	synced_count=0、duplicate_count=0、errors=[]
Errors	401
Consumer	SportApiClient.syncCalendarData
Handler	sport.sync_calendar
DB Touchpoints	不读写 DB；当前没有外部日历源
Tests	tests/api/test_sport.py、tests/api/test_story_7_4_fixes.py

GET /api/sport/weekly-report

项	内容
Request	start_date、end_date
Response	report_data
Errors	400 日期范围非法；401；500
Consumer	SportApiClient.getWeeklyReport、WeeklyReportBloc
Handler	sport.get_weekly_report
DB Touchpoints	读 users、user_profiles、sport_logs
Tests	weekly report tests；WeeklyReportScreen 代码与路由保留，但当前不作为可达入口

GET /api/sport/history

项	内容
Request	日期、运动类型、exclude_custom、分页
Response	records、total_count、has_more、next_offset
Errors	400 日期格式；401；500
Consumer	ExerciseHistoryApiClient.getExerciseHistory
Handler	sport.get_exercise_history
DB Touchpoints	筛选读 sport_logs
Tests	test/api/exercise_history_api_client_test.dart

POST /api/sport/log/custom

项	内容
Request	query/form 参数：sport_name、sport_start、sport_end、cal 等
Response	自定义运动记录
Errors	400 日期/参数；401；500
Consumer	ExerciseHistoryApiClient.addCustomExercise
Handler	sport.add_custom_exercise
DB Touchpoints	写 sport_logs，附加自定义字段响应
Tests	test/api/exercise_history_api_client_test.dart

方案与一致性

GET /api/sport/schemes/user/{user_id}

项	内容
Request	path user_id、分页
Response	schemes、分页字段
Errors	403 访问他人；401；500
Consumer	运动方案调试/校验入口
Handler	sport.get_user_schemes
DB Touchpoints	读 sport_schemes
Tests	tests/api/test_sport.py

GET /api/sport/validate-consistency/{user_id}

项	内容
Request	path user_id
Response	checks、issues、status
Errors	403 访问他人；401；500
Consumer	数据一致性校验入口
Handler	sport.validate_user_data_consistency
DB Touchpoints	读 users、sport_logs、sport_schemes
Tests	source inspection

运动记录请求字段

Field	Type	Required	Description
sport_name	string	yes	运动名称。
sport_start	datetime	yes	开始时间。
sport_end	datetime	no	结束时间。
cal	integer	yes	热量。
iffinish	boolean	yes	是否完成；false 会触发 active log 互斥检查。
sport_feedback	string	no	运动反馈，可为结构化 JSON 字符串。
notes / exercise_type / is_custom	mixed	no	自定义运动与历史筛选辅助字段。

接口边界

接口	当前状态	文档口径
POST /api/sport/sync-calendar	生产 route 存在	兼容 Flutter 日历同步动作；当前无外部同步源，因此返回 0 同步结果。
GET /api/sport/types	生产 route 存在	面向历史筛选返回运动分类 id，来源与 /api/sport/exercises 的静态分类一致。
GET /api/sport/weekly-report	后端存在，Flutter client 存在	WeeklyReportScreen 代码与路由保留，但当前不作为可达入口。

来源锚点

• Router: apps/backend_service/app/api/sport.py
• Service: apps/backend_service/app/services/sport_service.py
• Repository: apps/backend_service/app/repositories/sport_log_repository.py
• Flutter: apps/flutter_app/lib/api/sport_api_client.dart、feedback_api_client.dart、exercise_history_api_client.dart
• Tests: apps/backend_service/tests/api/test_sport.py、apps/flutter_app/test/api/exercise_history_api_client_test.dart