外观
处方 API
处方接口生成、读取和替换运动处方。所有 endpoint 都要求 Bearer JWT。生成接口会调用处方服务、RAG/LLM 链路并写入 sport_schemes；传入 sessionId 时还会尝试把处方卡写入聊天记录。
Endpoint 索引
| Method | Path | 用途 |
|---|---|---|
| POST | /api/prescription/generate | 生成正式运动处方。 |
| GET | /api/prescription/current | 读取当前有效处方。 |
| PUT | /api/prescription/{scheme_id}/replace | 替换指定处方。 |
| GET | /api/prescription/statistics | 读取处方服务统计。 |
| POST | /api/prescription/demo | 生成 Demo 动作库处方。 |
Endpoint 契约
POST /api/prescription/generate
| 项 | 内容 |
|---|---|
| Request | user_context、duration_days、sessionId |
| Response | prescription、scheme_id、RAG/LLM/safety 元数据、有效期、审核状态 |
| Errors | 400 参数错误；401；500 生成失败 |
| Consumer | PrescriptionApiClient.generatePrescription(useDemo=false)、Chat 处方按钮 |
| Handler | prescription.generate_prescription -> GeneratePrescriptionUseCase |
| DB Touchpoints | 读用户档案；写 sport_schemes；可写 dialogue_logs；RAG 读 knowledge_chunks |
| Tests | tests/api/test_prescription.py、tests/use_cases/test_generate_prescription_use_case.py |
GET /api/prescription/current
| 项 | 内容 |
|---|---|
| Request | 无 |
| Response | 当前有效处方或 null |
| Errors | 401；500 |
| Consumer | PrescriptionApiClient.getCurrentPrescription、运动中心 |
| Handler | prescription.get_current_prescription -> GetCurrentPrescriptionUseCase |
| DB Touchpoints | 读 sport_schemes |
| Tests | tests/api/test_prescription.py、tests/use_cases/test_manage_prescription_use_case.py |
PUT /api/prescription/{scheme_id}/replace
| 项 | 内容 |
|---|---|
| Request | query/body 当前以 duration_days 为准；path scheme_id |
| Response | 新处方响应 |
| Errors | 400 有效天数非法；401；500 |
| Consumer | PrescriptionApiClient.replacePrescription |
| Handler | prescription.replace_prescription -> ReplacePrescriptionUseCase |
| DB Touchpoints | 读旧 sport_schemes；写新 sport_schemes |
| Tests | tests/api/test_prescription.py |
GET /api/prescription/statistics
| 项 | 内容 |
|---|---|
| Request | 无 |
| Response | status、data、user_id |
| Errors | 401；500 |
| Consumer | 后端统计/调试入口 |
| Handler | prescription.get_prescription_statistics |
| DB Touchpoints | 读处方统计相关数据 |
| Tests | tests/api/test_prescription.py |
POST /api/prescription/demo
| 项 | 内容 |
|---|---|
| Request | duration_days |
| Response | 与生成接口相同，内容来自 Demo 动作库 |
| Errors | 401；500 |
| Consumer | PrescriptionApiClient.generatePrescription(useDemo=true)、居家 Demo 路径 |
| Handler | prescription.generate_demo_prescription |
| DB Touchpoints | 写 sport_schemes，is_demo=true |
| Tests | tests/services/test_demo_prescription_service.py、test/bloc/prescription/prescription_bloc_phase4_test.dart |
请求字段
| Field | Type | Required | Description |
|---|---|---|---|
user_context | object | no | 前端传入的补充上下文，处方生成会与后端用户档案合并使用。 |
duration_days | integer | no | 默认 7；生成接口约束 1-30。 |
sessionId | string | no | 关联聊天会话，用于把处方卡写回 dialogue_logs。 |
处方响应字段
| Field | Description |
|---|---|
prescription | 处方正文 JSON，包含动作、强度、安全提示等结构化内容。 |
scheme_id | sport_schemes.pk_sport_scheme。 |
information_source | 信息来源标识。 |
rag_used / knowledge_correlation | RAG 使用情况与相关性分数。 |
safety_check | 生成链路安全检查结果。 |
llm_info | 模型调用元数据，不包含 provider secret。 |
check_status / check_result | 当前审核状态与结果文本。 |
跨端注意
PrescriptionApiClient.replacePrescription 目前会发送 new_prescription body，但后端 handler 当前只使用 scheme_id 与 duration_days 重新生成替换处方。联调时不要假设前端传入的完整处方会被后端直接保存。
来源锚点
- Router:
apps/backend_service/app/api/prescription.py - Use cases:
apps/backend_service/app/use_cases/prescription/ - Service:
apps/backend_service/app/services/prescription_service.py - Flutter:
apps/flutter_app/lib/api/prescription_api_client.dart - Tests:
apps/backend_service/tests/api/test_prescription.py、apps/flutter_app/test/api/prescription_api_client_test.dart