feat: 加入了调试器

docs: 完善了文档
这个提交包含在:
2026-05-23 21:40:58 +08:00
父节点 41813abe48
当前提交 8790fcb5a9
共有 32 个文件被更改,包括 4024 次插入 和 360 次删除

123
backend/app/api/debug.py 普通文件
查看文件

@ -0,0 +1,123 @@
from __future__ import annotations
from fastapi import APIRouter, HTTPException, Query
from app.core.experiment_debug import VoiceSpeedDebugProvider, debug_registry
from app.schemas.validation import DebugMenuItem, DebugMenuResponse
router = APIRouter(prefix="/debug", tags=["debug"])
def _oscilloscope_menu_items() -> list[DebugMenuItem]:
return [
DebugMenuItem(
label="示波器状态",
action="oscilloscope_status",
method="GET",
endpoint="/debug/oscilloscope?action=status",
description="查看示波器连接状态、设备ID、当前峰值和频率",
),
DebugMenuItem(
label="读取CH2峰值",
action="oscilloscope_peak",
method="GET",
endpoint="/debug/oscilloscope?action=peak",
description="捕获示波器 CH2 通道的当前峰值",
),
DebugMenuItem(
label="读取CH1频率",
action="oscilloscope_frequency",
method="GET",
endpoint="/debug/oscilloscope?action=frequency",
description="捕获示波器 CH1 通道的信号频率",
),
]
def _peak_monitor_menu_items() -> list[DebugMenuItem]:
return [
DebugMenuItem(
label="峰值监控 - 启动",
action="peak_monitor_start",
method="POST",
endpoint="/peak-monitor/start",
description="启动驻波法峰值检测监控线程",
),
DebugMenuItem(
label="峰值监控 - 状态",
action="peak_monitor_status",
method="GET",
endpoint="/peak-monitor/status",
description="查询当前峰值监控的状态和OCR读数",
),
DebugMenuItem(
label="峰值监控 - 停止",
action="peak_monitor_stop",
method="POST",
endpoint="/peak-monitor/stop",
description="停止峰值监控线程",
),
]
@router.get("/menu")
async def debug_menu(experiment: str = Query(default="cn.edu.muc.lxy.phyexp.voicespeed")):
provider = debug_registry.get(experiment)
if provider is None:
raise HTTPException(status_code=404, detail=f"no debug provider for experiment '{experiment}'")
items: list[DebugMenuItem] = []
capabilities = provider.capabilities()
if "oscilloscope_status" in capabilities:
items.extend(_oscilloscope_menu_items())
if "peak_monitor" in capabilities:
items.extend(_peak_monitor_menu_items())
return DebugMenuResponse(
experiment=experiment,
title=f"{experiment} 实验调试工具",
description=f"{experiment} 实验特有的调试功能列表",
items=items,
)
@router.get("/status")
async def debug_status(experiment: str = Query(default="cn.edu.muc.lxy.phyexp.voicespeed")):
provider = debug_registry.get(experiment)
if provider is None:
raise HTTPException(status_code=404, detail=f"no debug provider for experiment '{experiment}'")
status = provider.status()
return {
"experiment": experiment,
"capabilities": provider.capabilities(),
**status,
}
@router.post("/probe")
async def debug_probe(experiment: str = Query(default="cn.edu.muc.lxy.phyexp.voicespeed")):
provider = debug_registry.get(experiment)
if provider is None:
raise HTTPException(status_code=404, detail=f"no debug provider for experiment '{experiment}'")
result = provider.probe()
return {"experiment": experiment, **result}
@router.get("/oscilloscope")
async def debug_oscilloscope(action: str = Query(default="status")):
provider = debug_registry.get("cn.edu.muc.lxy.phyexp.voicespeed")
if provider is None:
raise HTTPException(status_code=404, detail="no debug provider for cn.edu.muc.lxy.phyexp.voicespeed")
if not isinstance(provider, VoiceSpeedDebugProvider):
raise HTTPException(status_code=400, detail="oscilloscope debug only available for cn.edu.muc.lxy.phyexp.voicespeed")
if action == "status":
return provider.status()
elif action == "peak":
return provider.capture_peak()
elif action == "frequency":
return provider.capture_frequency()
else:
raise HTTPException(status_code=400, detail=f"unknown action '{action}', use: status, peak, frequency")

查看文件

@ -9,7 +9,7 @@ router = APIRouter(prefix="/form", tags=["form"])
@router.get("")
async def get_experiment_form(experiment: str = "voice_speed"):
async def get_experiment_form(experiment: str = "cn.edu.muc.lxy.phyexp.voicespeed"):
config = config_service.load_validated(experiment)
return config.model_dump(by_alias=True)

查看文件

@ -0,0 +1,168 @@
from __future__ import annotations
import logging
import threading
import time
from typing import Optional
from fastapi import APIRouter, Header, HTTPException
from app.core.dependencies import resolve_session_id
from app.core.ocr_service import caliper_ocr_service
from app.core.peak_detector import PeakDetector, PeakState
from app.core.reading_guard import reading_guard_manager
from app.hardware.service import oscilloscope_service
from app.schemas.validation import PeakMonitorResponse, PeakMonitorStartRequest
_logger = logging.getLogger("peak_monitor")
router = APIRouter(prefix="/peak-monitor", tags=["peak_monitor"])
POLL_INTERVAL: float = 0.3
_active_monitors: dict[str, "_PeakMonitor"] = {}
_lock = threading.Lock()
class _PeakMonitor:
def __init__(
self,
session_id: str,
detector: PeakDetector,
) -> None:
self.session_id = session_id
self.detector = detector
self._running = False
self._thread: Optional[threading.Thread] = None
def start(self) -> None:
self._running = True
self._thread = threading.Thread(target=self._poll_loop, daemon=True)
self._thread.start()
def stop(self) -> None:
self._running = False
if self._thread is not None:
self._thread.join(timeout=2.0)
self._thread = None
def _poll_loop(self) -> None:
_logger.info("峰值监控线程启动 session=%s", self.session_id)
while self._running:
try:
peak_value = _fetch_peak()
if peak_value is not None:
result = self.detector.feed(peak_value)
if result.state == PeakState.PEAK_TRIGGERED and result.ocr_reading is None:
ocr_result = caliper_ocr_service.capture()
if ocr_result.success and ocr_result.reading_mm is not None:
self.detector.set_ocr_reading(ocr_result.reading_mm)
_logger.info("峰值 %d 已检测 OCR读数=%.2f mm session=%s",
result.peak_index, ocr_result.reading_mm, self.session_id)
except Exception as exc:
_logger.warning("峰值轮询异常: %s", exc)
time.sleep(POLL_INTERVAL)
_logger.info("峰值监控线程停止 session=%s", self.session_id)
def _fetch_peak() -> Optional[float]:
snapshot = oscilloscope_service.capture_peak()
if snapshot.peak_value is None:
return None
return float(snapshot.peak_value)
def _get_monitor(session_id: str) -> Optional["_PeakMonitor"]:
return _active_monitors.get(session_id)
@router.get("/status")
async def peak_monitor_status(
x_session_id: str | None = Header(default=None),
):
session_id = resolve_session_id(x_session_id)
monitor = _get_monitor(session_id)
if monitor is None:
return PeakMonitorResponse(running=False)
detector = monitor.detector
current_peak = _fetch_peak()
with detector._lock:
result = detector._snapshot(current_peak)
return PeakMonitorResponse(
running=monitor._running,
state=result.state,
current_peak=result.current_peak,
peak_max=result.peak_max,
ocr_reading=result.ocr_reading,
pending_field=result.pending_field,
peak_index=result.peak_index,
trend=result.trend,
)
@router.post("/start")
async def peak_monitor_start(
request: PeakMonitorStartRequest,
x_session_id: str | None = Header(default=None),
):
session_id = resolve_session_id(x_session_id)
with _lock:
existing = _active_monitors.pop(session_id, None)
if existing is not None:
existing.stop()
detector = PeakDetector(
drop_ratio=request.drop_ratio,
cooldown_ratio=request.cooldown_ratio,
)
caliper_ocr_service.reset()
monitor = _PeakMonitor(session_id, detector)
_active_monitors[session_id] = monitor
monitor.start()
_logger.info("峰值监控已启动 session=%s experiment=%s", session_id, request.experiment)
return {
"success": True,
"message": "峰值监控已启动,请转动旋钮寻找峰值",
"session_id": session_id,
}
@router.post("/stop")
async def peak_monitor_stop(
x_session_id: str | None = Header(default=None),
):
session_id = resolve_session_id(x_session_id)
with _lock:
monitor = _active_monitors.pop(session_id, None)
if monitor is not None:
monitor.stop()
monitor.detector.reset()
caliper_ocr_service.reset()
return {"success": True, "message": "峰值监控已停止", "session_id": session_id}
@router.post("/acknowledge")
async def peak_monitor_acknowledge(
field_id: str,
x_session_id: str | None = Header(default=None),
):
session_id = resolve_session_id(x_session_id)
monitor = _get_monitor(session_id)
if monitor is None:
raise HTTPException(status_code=400, detail="峰值监控未启动")
detector = monitor.detector
result = detector.acknowledge_peak()
if result.ocr_reading is not None:
reading_guard_manager.submit_peak_ocr_answer(
session_id, field_id, result.ocr_reading
)
_logger.info("峰值已确认 field=%s ocr=%.2f session=%s", field_id, result.ocr_reading, session_id)
return {
"success": True,
"message": f"峰值 {result.peak_index} 已确认,OCR 读数已记录",
"peak_index": result.peak_index,
"state": result.state,
}

查看文件

@ -13,7 +13,7 @@ router = APIRouter(prefix="/value", tags=["value"])
@router.post("")
async def validate_field_value(
request: FieldValidationRequest,
experiment: str = Query(default="voice_speed"),
experiment: str = Query(default="cn.edu.muc.lxy.phyexp.voicespeed"),
x_session_id: str | None = Header(default=None),
) -> FieldValidationResponse:
session_id = resolve_session_id(x_session_id)