From e0f7db1b1cb7646a179f15a4a308fcb304293f6e Mon Sep 17 00:00:00 2001
From: husky <husky.chen@langkun.com>
Date: Wed, 22 Oct 2025 03:46:04 +0000
Subject: [PATCH] dev

---
 README.md    | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 package.json |  2 +-
 2 files changed, 72 insertions(+), 1 deletion(-)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..59ca597
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+# 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` 在纯前端中未直接用到）。
\ No newline at end of file
diff --git a/package.json b/package.json
index 75e3ef9..33a289b 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "next dev --port 3002",
     "build": "next build",
-    "start": "next start",
+    "start": "next start --port 3002",
     "lint": "next lint"
   },
   "dependencies": {