文件
NeoPhyExp/backend/app
..

物理实验后端(FastAPI)

该目录实现了与前端 ExperimentForm 对齐的后端 API,覆盖:

  1. 实验配置下发(/form)
  2. 字段值验证与会话存储(/value)
  3. 声速实验三方法计算(/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

主要接口

  1. GET /form?experiment=voice_speed
  2. GET /form/list
  3. POST /value
  4. GET /value
  5. DELETE /value
  6. POST /measurement/{standing_wave|phase|time_diff}
  7. GET /health

会话设计

  • 通过请求头 X-Session-Id 区分不同学生/实验会话。
  • 未提供时使用默认会话 default。
  • 当前为内存存储,后续可替换为 Redis/数据库。

计算方法说明

  • standing_wave / phase:
    • 输入 cursor_readings_mm 至少 10 个读数。
    • 使用“后五次减前五次”配对差统计平均值与不确定度。
    • 依据 frequency_hz 计算波长与声速。
  • time_diff:
    • 输入 distance_readings_mm 与 time_deltas_us,按组计算速度并求均值与标准差。

下一步建议

  1. 将 oscilloscope.py 与 OCR 能力接入 measurement 路由。
  2. 将 session_store 升级为持久化存储。
  3. 增加 pytest 接口测试覆盖边界输入。