feat: 加入了调试器
docs: 完善了文档
这个提交包含在:
269
docs/API.md
普通文件
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
普通文件
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
普通文件
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
普通文件
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
普通文件
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)
|
||||
在新工单中引用
屏蔽一个用户