71 lines
3.6 KiB
Markdown
71 lines
3.6 KiB
Markdown
# EST-100 实验模拟与教学平台（前端）
|
||
|
||
基于 Next.js 14 与 React 18 的教学前端，聚合了“线缆测试与故障诊断”相关的实验模拟页面（Fluke 模拟器）与教学资源（课件/教案），并提供成绩查询与导出功能。
|
||
|
||
## 技术栈
|
||
- Next.js 14（`pages` 路由模式，关闭 `appDir`）
|
||
- React 18
|
||
- Bootstrap 5（通过 `_document.js` 引入样式、`_app.jsx` 注入脚本）
|
||
- jQuery（随 Bootstrap 交互一并注入）
|
||
- CSS Modules（页面/组件级样式）
|
||
|
||
## 快速开始
|
||
1. 安装依赖：`npm install`
|
||
2. 开发启动：`npm run dev`（默认端口 `3002`）
|
||
3. 生产构建：`npm run build`
|
||
4. 生产启动：`npm start`（默认端口 `3002`）
|
||
|
||
启动后请访问：
|
||
- 主实验页：`/FlukeMoniPage`
|
||
- 控制台：`/Control`
|
||
- 首页 `/` 当前为占位页（显示“错误的加载”），后续可改为跳转或主页导航。
|
||
|
||
## 主要功能与页面
|
||
- `/FlukeMoniPage` 实验页入口
|
||
- 列出“实验一~实验五”卡片。
|
||
- 点击“打开”触发模态框，内嵌 iFrame 加载对应静态模拟器页面：`/public/flukemoni/{Ex}/HOMEPAGE.html`。
|
||
- “实验指导”链接在新窗口打开，目标地址基于当前主机名与端口 `3001` 的文档站。
|
||
- `/Control` 控制台
|
||
- 成绩查询：按组织（URL 参数 `org`）与用户名筛选，支持排序、仅最高分、CSV 导出。
|
||
- 课件/教案：从 `public/doc/` 直接下载 PDF/PPTX/DOCX，以及部分 `.flw` 实验数据。
|
||
|
||
## 数据与外部服务
|
||
- 成绩查询 API（前端内置的默认约定）：
|
||
- `GET http://<当前主机>:3000/survey-answers?org=<组织>&username=<用户名>`
|
||
- 期望返回：`{ success: boolean, data: Array<{ projectId, username, score, submitTime }> }`
|
||
- 项目 ID 映射内置于前端（如 `XEdP7K` → “实验一随堂练” 等）。
|
||
- 前端在控制台页通过 URL 参数 `org` 读取组织，如：`/Control?org=计算机学院`。
|
||
- 教学文档站（实验指导）：
|
||
- 基于 `window.location` 推断为 `http(s)://<当前主机>:3001/docs/fluke/...`。
|
||
- 如部署拓扑不同，可在 `src/pages/FlukeMoniPage/index.jsx` 中调整 `BASE_URL`。
|
||
|
||
## 目录结构
|
||
- `src/pages/`
|
||
- `_app.jsx`：注入 `jquery` 与 `bootstrap.bundle`，引入全局样式。
|
||
- `_document.js`：引入 `public/styles/bootstrap.min.css`。
|
||
- `index.jsx`：占位首页。
|
||
- `FlukeMoniPage/`：主实验页面（卡片 + 模态框 + iFrame）。
|
||
- `Control/`：控制台（成绩查询与资源下载）。
|
||
- `src/components/`
|
||
- `ScoreQuery/`：成绩查询组件（筛选、排序、导出）。
|
||
- `Materials/`：课件/教案下载组件（PDF/PPT/Word/数据）。
|
||
- `public/`
|
||
- `flukemoni/Ex1~Ex5/`：实验静态页面（大量 HTML/CSS/JS，入口 `HOMEPAGE.html`）。
|
||
- `doc/`：课件与教案文件（PDF/PPTX/DOCX）及部分实验数据（`.flw`）。
|
||
- `scripts/`、`styles/`：前端脚本与样式资源。
|
||
|
||
## 配置与约定
|
||
- 端口约定：
|
||
- 前端开发：`3002`；生产：`3002`（Next 默认）。
|
||
- 成绩查询 API：`3002`（同域不同路径）；若后端独立部署，请调整 `ScoreQuery` 的 `getBaseUrl()`。
|
||
- 文档站：`3002`（跨端口新窗口打开）。
|
||
- 路由约定：使用 Next `pages` 路由，`/FlukeMoniPage` 与 `/Control` 为主要入口。
|
||
- 路径别名：`jsconfig.json` 配置 `@/* → ./src/*`。
|
||
|
||
|
||
|
||
## 后续改进建议
|
||
- 将首页改为导航页或自动跳转至 `/FlukeMoniPage`。
|
||
- 抽取 `BASE_URL`（文档站）与成绩查询 API 地址为环境变量。
|
||
- 统一使用 React 生态组件替代 jQuery 依赖（可选）。
|
||
- 清理未使用依赖（如 `axios`/`express`/`cors` 在纯前端中未直接用到）。 |