物理实验后端(FastAPI)
该目录实现了与前端 ExperimentForm 对齐的后端 API,覆盖:
- 实验配置下发(
/form) - 字段值验证与会话存储(
/value) - 声速实验三方法计算(
/measurement)
架构概览
main.py: FastAPI 入口、CORS、路由注册models.py: 与前端协议对应的 Pydantic 模型api/form.py: 实验表单配置接口api/value.py: 字段值验证与会话数据接口api/measurement.py: 驻波法/相位法/时差法计算接口core/config_loader.py: 配置文件加载与校验core/validation.py: 配置驱动字段验证core/session_store.py: 内存会话态字段存储core/measurement.py: 声速实验计算逻辑../config/experiments/*.json: 实验配置文件
运行
在 backend 目录执行:
uv run uvicorn main:app --app-dir src --reload --host 0.0.0.0 --port 8000
或直接:
python src/main.py
主要接口
GET /form?experiment=voice_speedGET /form/listPOST /valueGET /valueDELETE /valuePOST /measurement/{standing_wave|phase|time_diff}GET /health
会话设计
- 通过请求头
X-Session-Id区分不同学生/实验会话。 - 未提供时使用默认会话
default。 - 当前为内存存储,后续可替换为 Redis/数据库。
计算方法说明
standing_wave/phase:- 输入
cursor_readings_mm至少 10 个读数。 - 使用“后五次减前五次”配对差统计平均值与不确定度。
- 依据
frequency_hz计算波长与声速。
- 输入
time_diff:- 输入
distance_readings_mm与time_deltas_us,按组计算速度并求均值与标准差。
- 输入
下一步建议
- 将
oscilloscope.py与 OCR 能力接入measurement路由。 - 将
session_store升级为持久化存储。 - 增加
pytest接口测试覆盖边界输入。