feat: 加入了调试器

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

269
docs/API.md 普通文件
查看文件

@ -0,0 +1,269 @@
# API 文档
## 基础信息
- **Base URL**: `http://localhost:8000`
- **Content-Type**: `application/json`
- **会话管理**: 通过 `X-Session-Id` 请求头标识会话,默认为 `"default"`
## 端点列表
### 系统
#### `GET /`
返回服务信息。
**响应**:
```json
{
"message": "Physics Experiment Backend",
"version": "1.0.0",
"endpoints": {
"form": ["GET /form", "GET /form/list", "GET /form/{experiment_name}"],
"value": ["POST /value", "GET /value", "GET /value/{field_id}", "DELETE /value/{field_id}", "DELETE /value"],
"device": ["GET /device/status", "POST /device/peak"],
"measurement": ["POST /measurement/{standing_wave|phase|time_diff}"],
"system": ["GET /health"]
}
}
```
#### `GET /health`
健康检查。
**响应**:
```json
{ "status": "healthy", "service": "physics-experiment-backend" }
```
---
### 表单配置
#### `GET /form`
加载指定实验的网格配置。
**查询参数**:
| 参数 | 类型 | 默认值 | 说明 |
| ---------- | ------ | -------------- | ---------- |
| experiment | string | "voice_speed" | 实验名称 |
**响应**: `ExperimentGridConfig` JSON
#### `GET /form/list`
列出所有可用实验。
**响应**:
```json
{
"experiments": [
{ "name": "voice_speed", "title": "超声波声速测量实验(记录表)", "description": "..." }
],
"count": 1
}
```
#### `GET /form/{experiment_name}`
按名称加载特定实验配置。
**响应**: `ExperimentGridConfig` JSON
---
### 字段值
#### `POST /value`
验证并存储字段值。先进行基础校验(类型/范围/正则),再进行读数守卫校验(如果配置了)。
**查询参数**:
| 参数 | 类型 | 默认值 | 说明 |
| ---------- | ------ | -------------- | ---------- |
| experiment | string | "voice_speed" | 实验名称 |
**请求头**:
| 头 | 类型 | 说明 |
| ------------ | ------ | -------- |
| X-Session-Id | string | 会话标识 |
**请求体**:
```json
{
"field_id": "f1",
"value": "36.540"
}
```
**响应**:
```json
{
"accept": true,
"message": "validation passed"
}
```
#### `GET /value`
获取当前会话所有字段值。
**响应**:
```json
{
"fields": { "f1": "36.540", "f2": "36.539" },
"count": 2,
"session_id": "default"
}
```
#### `GET /value/{field_id}`
获取单个字段值。
#### `DELETE /value/{field_id}`
删除单个字段值。
#### `DELETE /value`
清除当前会话所有字段值。
---
### 设备控制
#### `GET /device/status`
探测示波器连接状态。
**响应**:
```json
{
"status": "online|offline|simulated",
"device_idn": "...",
"peak_value": null,
"frequency_hz": null,
"note": "..."
}
```
#### `POST /device/peak`
捕获示波器峰值。
#### `POST /device/manual-answer`
设置读数守卫的手动参考值。
**请求体**:
```json
{
"field_id": "f1",
"value": 36.540
}
```
---
### 测量分析
#### `POST /measurement/{method}`
分析测量数据并计算声速。
**路径参数**:
| 参数 | 类型 | 可选值 |
| ------ | ------ | --------------------------------- |
| method | string | `standing_wave`, `phase`, `time_diff` |
**请求体** (`standing_wave` / `phase` 方法):
```json
{
"frequency_hz": 36540.0,
"temperature_c": 25.0,
"cursor_readings_mm": [144.02, 148.80, 153.50, 158.30, 163.00, 167.80, 172.66, 177.30, 182.29, 186.84]
}
```
**请求体** (`time_diff` 方法):
```json
{
"distance_readings_mm": [62.80, 84.00, 65.30, 15.58, 29.16],
"time_deltas_us": [180, 240, 192, 44, 84]
}
```
**响应**:
```json
{
"method": "standing_wave",
"sample_count": 5,
"velocity_mps": 347.25,
"wavelength_m": 0.0095,
"uncertainty_mps": 0.12,
"theoretical_velocity_mps": 346.8,
"details": {
"pair_deltas_mm": [23.78, 23.86, 23.80, 23.99, 23.84],
"mean_delta_mm": 23.854,
"std_delta_mm": 0.074
}
}
```
---
## 数据模型
### ExperimentGridConfig
```json
{
"title": "实验标题",
"description": "实验说明",
"sheets": [
{
"id": "sheet_id",
"title": "表标题",
"columns": 6,
"columnHeaders": ["项目", "1", "2", "3", "4", "5"],
"cells": [
[
{ "type": "label", "content": "行标签" },
{ "type": "input", "fieldId": "f1", "validation": { "type": "number", "min": 0, "max": 100, "required": true } },
{ "type": "computed", "areaId": "avg", "expression": "(f1+f2)/2", "variables": ["f1","f2"], "format": "0.00" },
null
]
]
}
]
}
```
### 单元格类型
| type | 用途 | 关键字段 |
| ---------- | -------- | ------------------------------- |
| `label` | 静态标签 | `content` (支持 LaTeX) |
| `input` | 数据输入 | `fieldId`, `validation`, `unit` |
| `computed` | 自动计算 | `areaId`, `expression`, `variables`, `format` |
### 校验配置
```json
{
"type": "number",
"min": 30,
"max": 45,
"required": true
}
```
| type | 额外字段 | 说明 |
| ------- | --------------- | ---------------------------- |
| number | `min`, `max` | 数值范围校验 |
| text | `required` | 非空文本 |
| regex | `pattern` | 正则匹配 |

217
docs/ARCHITECTURE.md 普通文件
查看文件

@ -0,0 +1,217 @@
# 架构总览
## 系统架构图
```
┌─────────────────────────────────────────────────────────┐
│ 浏览器 (SPA) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
│ │ Vue 3 │ │ KaTeX │ │ Pinia Store │ │
│ │ Router │ │ mathjs │ │ (experiment/student) │ │
│ └──────────┘ └──────────┘ └──────────────────────┘ │
│ │ │ │
│ │ HTTP REST + SSE │ │
└─────────┼───────────────────────────────────────────┘ │
│ │
┌─────────┼───────────────────────────────────────────┐ │
│ ▼ FastAPI 后端 │ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │
│ │ api/ │ │ core/ │ │ schemas/ │ │ │
│ │ 路由层 │→│ 业务层 │←│ Pydantic 模型 │ │ │
│ └──────────┘ └──────────┘ └──────────────────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌──────────────────────────────────────────────┐ │ │
│ │ hardware/ 示波器驱动 (PyUSB, 可选) │ │ │
│ └──────────────────────────────────────────────┘ │ │
│ │ │
│ ┌──────────────────────────────────────────────┐ │ │
│ │ config/experiments/*.json 实验配置文件 │ │ │
│ └──────────────────────────────────────────────┘ │ │
└─────────────────────────────────────────────────────┘ │
│ │
│ │
┌─────────┼───────────────────────────────────────────┐ │
│ ▼ AI 服务 (外部) │ │
│ ┌──────────────────────────────────────────────┐ │ │
│ │ /api/chat REST + SSE 端点 │ │ │
│ │ teacher_type: question | data_eval | grader │ │ │
│ └──────────────────────────────────────────────┘ │ │
└─────────────────────────────────────────────────────┘ │
```
## 数据流
### 实验表单流程
```
1. 前端加载配置
GET /form?experiment=voice_speed
→ 后端返回 ExperimentGridConfig (JSON)
→ 前端渲染网格表单
2. 用户填入数据
输入 → 本地校验 (mathjs) → 背景色变化
失焦 → POST /value { field_id, value }
→ 后端 Pydantic 校验 → { accept, message }
→ 前端更新验证状态 → 背景色更新
3. 自动计算
依赖字段验证通过后
→ mathjs 编译表达式 → 计算结果
→ 级联更新所有受影响的计算区
4. AI 评价
鼠标悬停 600ms
→ POST /api/chat (teacherType=data_eval)
→ 显示评价 tooltip
```
### 字段验证详细流程
```
POST /value { field_id: "f1", value: "36.540" }
→ FieldValidator.validate_by_config()
→ 类型校验 (number/text/regex)
→ 范围校验 (min/max)
→ 必填校验 (required)
→ ReadingGuardManager.validate()
→ 检查读数顺序 (如果启用)
→ 检查容差 (如果启用)
→ SessionStore.set_value()
→ 返回 { accept: true/false, message: "..." }
```
## 数据模型
### 实验配置 (Grid 模式)
```
ExperimentGridConfig
├── title
├── description
└── sheets[]
├── id
├── columns: int
├── columnHeaders?: string[]
└── cells[][] → GridCell[]
├── GridLabelCell { type:"label", content }
├── GridInputCell { type:"input", fieldId, validation? }
└── GridComputedCell { type:"computed", areaId, expression, variables[] }
```
### 验证状态可视化
| 状态 | 背景色 | 含义 |
| -------------- | -------- | -------------- |
| 未填写 | `#ffffff` | 尚未输入 |
| 已填写未验证 | `#fff3cd` | 等待后端验证 |
| 验证通过 | `#d4edda` | 数据合格 |
| 验证失败 | `#f8d7da` | 数据不合格 |
| 计算错误 | `#f8d7da` | 表达式异常 |
## 路由设计
### 前端路由
| 路径 | 组件 | 说明 |
| ---------------- | ---------------- | ------------ |
| `/login` | StudentLogin | 学生登录 |
| `/exp?expid=...` | ExperienceFrame | 实验主框架 |
| `/select` | ExperienceSwitch | 实验选择 |
### 后端 API
| 方法 | 路径 | 说明 |
| ------ | ----------------------------- | ------------------ |
| GET | `/health` | 健康检查 |
| GET | `/form?experiment=...` | 加载实验配置 |
| POST | `/value?experiment=...` | 验证字段值 |
| GET | `/device/status` | 示波器状态 |
| POST | `/measurement/{method}` | 测量数据分析 |
## 用户导航流程
```
/login (StudentLogin)
→ 登录成功 → /select (ExperienceSwitch)
→ 选择实验卡片 → /exp?expid=<id> (ExperienceFrame)
→ 阶段导航: 预习 → 测验 → 实验 → 考试 → 总结
```
- **登录守卫**: `router.beforeEach` 检查 `localStorage.PhyExp.StudentInfo`,未登录重定向到 `/login`
- **实验选择页**: 网格卡片布局,展示所有可用实验的封面、标题、作者、阶段标签,点击跳转
- **实验框架**: 通过 `?expid=` 查询参数加载对应实验,阶段切换通过 `Process` 索引控制
## 组件层级
```
App.vue
└── RouterView
└── ExperimentPage
├── ExperimentForm (provide AIEvalContext)
│ └── ExperimentGrid[] (每个 Sheet)
│ └── ExperimentGridCell[] (label / input / computed)
├── ExperimentPrintTable (隐藏 PDF 渲染)
└── AIChatSidebar (浮动 AI 助教)
├── 单元格选择器
└── 单元格上下文显示
```
## 跨层通信
### 前端 → 后端
| 端点 | 用途 | 请求格式 |
| ----------------- | ------------------- | -------------------------------- |
| `GET /form` | 加载实验表结构 | `?experiment=voice_speed` |
| `POST /value` | 验证单个字段 | `{ field_id, value }` |
| `DELETE /value` | 清除所有字段值 | |
### 前端 → AI 服务
| teacherType | 用途 | 通信方式 |
| ------------ | ----------------- | ------------ |
| `question` | AI 助教对话 | SSE 流式 |
| `data_eval` | 实验数据评价 | REST |
| `grader` | 测验错题分析 | REST |
### 前端内部
| Store | 职责 |
| ------------------ | --------------------------- |
| `useExperimentStore` | 表单数据、验证、计算、依赖图 |
| `useStudentStore` | 学生认证、持久化 |
## 声速实验计算
### 驻波法 / 相位法
```
ΔL_i = L_{i+5} - L_i (i = 0..4)
λ = 2 × mean(ΔL) / 1000 [m]
v = f × λ
Δv = f × 2 × σ(ΔL) / 1000
```
### 时差法
```
v_i = (ΔL_i / 1000) / (ΔT_i / 1e6)
v = mean(v_i)
Δv = σ(v_i)
```
### 理论声速 (温度校正)
```
v₀ = 331.5 + 0.6 × t [m/s]
```
### 相对误差
```
A_% = |v - v₀| / v₀ × 100%
```
每个测量方法独立计算相对误差,均基于温度推导的理论值 v₀。

152
docs/DEPLOYMENT.md 普通文件
查看文件

@ -0,0 +1,152 @@
# 部署指南
## 生产构建
### 前端
```bash
cd frontend
yarn build
# 产物在 frontend/dist/
```
### 后端
```bash
cd backend
uv sync --frozen
# 使用 uvicorn 直接启动
```
## 部署方案
### 方案 A: 单机部署 (推荐)
使用 Nginx 反向代理,前后端同机运行。
```nginx
server {
listen 80;
server_name phyexp.example.com;
# 前端静态文件
root /opt/phyexp/frontend/dist;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
# 后端 API 反向代理
location /api/ {
# 如果 AI 服务在同一机器
proxy_pass http://127.0.0.1:8000/api/;
}
# 后端直接端点
location ~ ^/(form|value|device|measurement|health) {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
### 方案 B: 分离部署
- 前端: 部署到 CDN 或静态服务器 (Nginx, Vercel, Netlify)
- 后端: 独立服务器运行 FastAPI
- AI 服务: 独立部署
## 后端启动
### 使用 uvicorn
```bash
cd backend
uv run uvicorn app.main:App --host 0.0.0.0 --port 8000
```
### 使用 systemd (Linux)
```ini
# /etc/systemd/system/phyexp-backend.service
[Unit]
Description=PhyExp Backend
After=network.target
[Service]
Type=simple
User=phyexp
WorkingDirectory=/opt/phyexp/backend
ExecStart=/home/phyexp/.local/bin/uv run uvicorn app.main:App --host 127.0.0.1 --port 8000
Restart=always
Environment="PYTHONUNBUFFERED=1"
[Install]
WantedBy=multi-user.target
```
### 使用 Docker
```dockerfile
# backend/Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN pip install uv && uv sync --frozen
COPY . .
EXPOSE 8000
CMD ["uv", "run", "uvicorn", "app.main:App", "--host", "0.0.0.0", "--port", "8000"]
```
```bash
docker build -t phyexp-backend backend/
docker run -d -p 8000:8000 phyexp-backend
```
## 环境变量
| 变量 | 默认值 | 说明 |
| ---------------------- | ----------------------------- | --------------------- |
| `AI_BASE_URL` | (无) | AI 服务端点 URL |
| `EXPERIMENT_CONFIG_DIR`| `config/experiments` | 实验配置文件目录 |
## 配置 AI 服务
前端通过 `window.__AI_BASE_URL__` 或 `/config.json` 获取 AI 服务地址。
在部署时,在 Nginx 中注入:
```nginx
location /config.json {
alias /opt/phyexp/config.json;
}
```
`/opt/phyexp/config.json`:
```json
{
"aiBaseUrl": "https://ai-service.example.com"
}
```
## 检查清单
- [ ] Python >= 3.10,Node.js >= 18
- [ ] `backend/` 下 `uv sync` 通过
- [ ] `frontend/` 下 `yarn build` 通过
- [ ] Nginx 配置正确,静态资源路径指向 `frontend/dist/`
- [ ] API 代理正确转发 `/form`, `/value`, `/health` 等端点
- [ ] CORS 配置与部署环境一致 (生产环境应限制 `allow_origins`)
- [ ] AI 服务可访问
- [ ] 防火墙开放 80/443 端口
- [ ] (可选) 示波器 USB 设备连接正确
## 安全建议
- 生产环境修改 `app/main.py` 中的 `allow_origins` 为具体域名
- 使用 HTTPS (Let's Encrypt + Certbot)
- 不要在生产环境中启用 `reload=True`
- 会话存储 (`SessionStore`) 当前为内存实现,多进程部署需要替换为 Redis

214
docs/DEVELOPMENT.md 普通文件
查看文件

@ -0,0 +1,214 @@
# 开发指南
## 环境准备
### 必需工具
- **Node.js** >= 18 (推荐 20+)
- **Python** >= 3.10 (推荐 3.11+)
- **yarn** (前端包管理器,严禁使用 npm)
- **uv** (Python 包管理器)
- **VS Code** (推荐,已配置 `.vscode/`)
### 安装依赖
```bash
# 后端
cd backend
uv sync
# 前端
cd frontend
yarn install
```
### 启动开发服务器
```bash
# 终端 1: 后端 (默认 :8000)
cd backend
uv run python -m app.main
# 终端 2: 前端 (默认 :5173)
cd frontend
yarn dev
```
## 项目结构规范
### 后端目录规范
```
backend/
├── app/
│ ├── main.py # FastAPI 应用入口,CORS 配置,路由注册
│ ├── models.py # 兼容性导出 (实际定义在 schemas/)
│ ├── schemas/ # Pydantic 数据模型 (唯一真相来源)
│ │ ├── experiment.py # 实验配置模型 (GridSheet, GridCell...)
│ │ └── validation.py # 验证请求/响应模型
│ ├── api/ # REST 路由层 (薄层,委托给 core/)
│ │ ├── form.py # GET /form ...
│ │ ├── value.py # POST/GET/DELETE /value ...
│ │ ├── device.py # 示波器端点
│ │ └── measurement.py # 测量计算端点
│ ├── core/ # 业务逻辑层 (无 FastAPI 依赖)
│ │ ├── config_loader.py # 加载/验证 JSON 配置
│ │ ├── dependencies.py # 服务单例 + 辅助函数
│ │ ├── validation.py # 字段校验器
│ │ ├── reading_guard.py # 读数守卫
│ │ ├── measurement.py # 测量统计算法
│ │ └── session_store.py # 会话 KV 存储
│ └── hardware/ # 硬件交互 (与实验逻辑解耦)
│ ├── oscilloscope.py # PyUSB 驱动
│ ├── progress.py # SCPI 命令执行
│ └── service.py # OscilloscopeService
└── config/experiments/ # 实验 JSON 配置
```
**原则**:
- `api/` 只做路由和参数解析,不写业务逻辑
- `core/` 是纯 Python 逻辑,不依赖 FastAPI (除了 HTTPException)
- `schemas/` 是唯一的数据模型定义点,前后端类型保持对齐
- `hardware/` 与实验逻辑完全解耦,可独立测试
### 前端目录规范
```
frontend/src/
├── components/ # 可复用 Vue 组件
│ ├── experiment/ # 实验相关组件
│ ├── AIChatSidebar.vue # AI 聊天
│ ├── DebugPanel.vue # 调试面板
│ └── QuestionTable.vue # 试题渲染
├── pages/ # 路由页面 (每个路由一个文件)
├── stores/ # Pinia 状态管理
├── types/ # TypeScript 类型定义
├── utils/ # 工具函数 (纯函数,无副作用)
├── composables/ # Vue Composables (有状态逻辑)
├── router/ # Vue Router 配置
└── assets/ # 静态资源 + JSON 配置
```
**原则**:
- `components/` 放可复用 UI 组件,`pages/` 放路由页面
- `stores/` 是全局状态,页面间共享
- `utils/` 是纯函数工具,不依赖 Vue
- `composables/` 是 Vue 特定的可组合逻辑
- `types/` 定义所有 TypeScript 接口/类型,与后端 Pydantic 模型对齐
## 代码规范
### Python
- 所有文件第一行: `from __future__ import annotations`
- 类型注解: 全部使用 Python 3.10+ 语法 (`str | None` 而非 `Optional[str]`)
- Pydantic 模型: 使用 v2 语法,`model_dump(by_alias=True)` 输出 camelCase
- 错误处理: 使用 FastAPI `HTTPException`,带中文错误信息
- 导入顺序: `__future__` → 标准库 → 第三方 (fastapi, pydantic) → 项目内部 (app.*)
- 命名: `snake_case` 变量/函数,`PascalCase` 类,`UPPER_CASE` 常量
### TypeScript / Vue
- 使用 `<script setup lang="ts">` 语法
- Props 使用 `defineProps<{ ... }>()` 泛型语法
- Emits 使用 `defineEmits<{ event: [param: type] }>()` 泛型语法
- 类型文件: `types/experiment.ts` 定义实验相关接口,与后端 Pydantic 对齐
- Composable: `ref()` 管理响应式状态,`computed()` 派生,`watch()` 副作用
- 命名: `camelCase` 变量/函数,`PascalCase` 组件/类型,`.vue` 单文件组件
### JSON 配置
- 实验配置文件位于 `backend/config/experiments/`
- 字段命名: `camelCase` (与前端 JS 风格一致)
- LaTeX 字符串: 使用标准 LaTeX 语法,JSON 中正确转义反斜杠
## 添加新实验
### 1. 创建配置文件
在 `backend/config/experiments/` 下创建 `new_experiment.json`:
```json
{
"title": "新实验标题",
"description": "实验说明",
"sheets": [
{
"id": "sheet1",
"title": "表1 数据",
"columns": 5,
"columnHeaders": ["项目", "1", "2", "3", "4", "5"],
"cells": [
[
{"type": "label", "content": "行标签"},
{"type": "input", "fieldId": "f1", "validation": {"type": "number", "min": 0, "max": 100, "required": true}},
...
]
]
}
]
}
```
### 2. 注册到前端实验列表
编辑 `frontend/src/assets/experiences.json` 添加新实验条目。
### 3. 如果是新实验类型 (需要专门的预习/测验)
在 `frontend/src/assets/` 下创建对应的 `question.json`、`prelearn.json` 等。
## 调试
### 前端调试面板
设置 `localStorage.DEBUG = 'true'` 启用调试面板,支持:
- 实验导航
- 跳过阶段限制
- AI 设置查看
- AI 请求日志
### 后端调试
```bash
cd backend
uv run python -c "
from app.core.config_loader import config_service
cfg = config_service.load_validated('voice_speed')
print(cfg.model_dump_json(indent=2))
"
```
## 测试
### 后端
```bash
cd backend
python -c "
from app.core.validation import FieldValidator
from app.schemas.experiment import ValidationConfig, ValidationType
cfg = ValidationConfig(type=ValidationType.NUMBER, min=0, max=100, required=True)
result = FieldValidator.validate_by_config('test', '50', cfg)
assert result.accept == True
print('OK')
"
```
### 前端
```bash
cd frontend
yarn type-check # TypeScript 类型检查
yarn build # 生产构建
```
## Git 规范
- 提交信息: 中文描述,格式 `类型: 简短描述`
- `feat: 添加网格表格布局`
- `fix: 修复列标题 LaTeX 渲染`
- `refactor: 重组后端目录结构`
- `docs: 更新架构文档`
- 不提交: `node_modules/`, `.venv/`, `dist/`, `__pycache__/`, `.env`
- 不提交密钥/AI endpoint/密码

85
docs/README.md 普通文件
查看文件

@ -0,0 +1,85 @@
# 物理实验教学平台 (PhyExp)
## 项目概述
PhyExp 是一个交互式物理实验教学平台,支持学生在线完成实验预习、测验、数据记录和 AI 辅助分析。平台采用前后端分离架构,前端基于 Vue 3 + TypeScript,后端基于 Python FastAPI。
### 核心功能
- **分阶段实验流程**:预习 → 测验 → 实验 → 考试 → 总结
- **Excel 风格数据表**:网格布局的数据录入界面,支持 LaTeX 数学公式渲染
- **AI 助教**:基于 SSE 的流式对话,支持实验数据评价、答疑和错题分析
- **自动计算与验证**:前端 mathjs 即时计算,后端 Pydantic 验证,背景色可视化反馈
- **PDF 导出**:实验数据导出为 A4 格式 PDF
- **示波器集成**:可选的 PyUSB 示波器数据采集(含模拟模式回退)
### 技术栈
| 层 | 技术 |
| ------ | ----------------------------------- |
| 前端 | Vue 3, TypeScript, Vite, Pinia, KaTeX, mathjs |
| 后端 | Python, FastAPI, Pydantic v2, Uvicorn |
| 硬件 | PyUSB, libusb (可选) |
| AI | REST + SSE (Server-Sent Events) |
## 快速开始
### 环境要求
- Node.js >= 18
- Python >= 3.10
- uv (Python 包管理器)
- yarn (Node.js 包管理器)
### 启动后端
```bash
cd backend
uv sync
uv run python -m app.main
# 默认监听 http://0.0.0.0:8000
```
### 启动前端
```bash
cd frontend
yarn install
yarn dev
# 默认监听 http://localhost:5173
```
## 目录结构
```
PhyExpRefactor/
├── backend/ # Python FastAPI 后端
│ ├── app/
│ │ ├── main.py # FastAPI 应用入口
│ │ ├── models.py # 模型兼容导出
│ │ ├── schemas/ # Pydantic 数据模型
│ │ ├── api/ # REST API 路由
│ │ ├── core/ # 业务逻辑层
│ │ └── hardware/ # 示波器硬件驱动
│ ├── config/experiments/ # 实验 JSON 配置
│ └── ARCHITECTURE.md # 后端架构文档
├── frontend/ # Vue 3 前端
│ ├── src/
│ │ ├── components/ # 可复用组件
│ │ ├── pages/ # 页面组件
│ │ ├── stores/ # Pinia 状态管理
│ │ ├── types/ # TypeScript 类型定义
│ │ └── utils/ # 工具函数
│ └── ARCHITECTURE.md # 前端架构文档
├── docs/ # 本目录 - 项目文档
└── .vscode/ # VS Code 配置
```
## 相关文档
- [架构总览](./ARCHITECTURE.md)
- [开发指南](./DEVELOPMENT.md)
- [部署指南](./DEPLOYMENT.md)
- [API 文档](./API.md)
- [前端架构](../frontend/ARCHITECTURE.md)
- [后端架构](../backend/ARCHITECTURE.md)