dev

README.md

@@ -0,0 +1,81 @@
+# EST-DSX 信息网络布线仿真测试平台
+
+一个基于 Next.js 的仿真与竞赛平台，用于模拟信息网络布线测试（铜缆与光纤）、连接配置、过程记录与赛后统计。前端提供可视化场景与操作界面，后端 Express 服务提供连接图与比赛数据 API。
+
+## 项目概览
+- 前端：Next.js 15、React、Tailwind CSS 4、Zustand 状态管理、Headless UI、Chart.js/ECharts、JsPlumb 等
+- 典型端口：
+  - `3003` 前端开发端口（`npm run dev`）
+
+## 目录结构（简要）
+- `src/pages`：核心页面（`index` 仿真、`admin` 管理、`competition` 统计）
+- `src/components`：场景与功能组件（Office/Industry/DataCenter/WorldSkill、连接/测试组件等）
+- `src/store`：Zustand 状态与测试数据（`COPPER`/`FIBER` JSON 等）
+- `src/config/api.js`：前端 API 基址与路径
+- `server/app.js`：主要 API 服务（连接图、竞赛）
+- `server/server.js`：静态下载与作为前端默认基地址（需要代理 `/dsxapi` 到 3007）
+- `public/`：图片与静态资源
+
+## 环境要求
+- Node.js ≥ 18.18（推荐 20+ LTS）
+- npm ≥ 9
+
+## 快速开始（本地开发）
+1) 安装依赖
+- 在根目录：`npm install`
+- 在 `server/` 目录（后端有独立 `package.json`）：`cd server && npm install`
+
+2) 启动后端 API（默认 3007）
+- 在根目录或 `server/`：`node server/app.js`
+
+3) 启动网关/静态服务（默认 3000）
+- 在根目录或 `server/`：`node server/server.js`
+- 说明：前端默认将请求发到 `http://<host>:3000/dsxapi/api/*`。需要代理 `/dsxapi` 到 `http://localhost:3007` 才能正常调用后端。
+
+4) 启动前端（默认 3003）
+- 在根目录：`npm run dev`
+
+5) 访问
+- 仿真主页（`/`）仅支持在 iframe 中访问且需要 `token`（见下文“鉴权与嵌入”）；本地调试请优先使用 `/admin` 与 `/competition` 页面。
+- 管理页：`http://localhost:3003/admin`
+- 统计页：`http://localhost:3003/competition`
+
+## 代理与 API 配置
+- 前端 API 路径位于 `src/config/api.js`：默认 `BASE_URL` 指向 `http(s)://<host>:3000`，并使用 `/dsxapi/api/*` 路由。
+- 本地开发有两种方式：
+  - 方式 A（推荐）：在 3000 端口上配置反向代理，将 `/dsxapi` 代理到 `http://localhost:3007`。
+  - 方式 B（快速）：临时修改 `src/config/api.js`，将 `BASE_URL` 设置为 `http://localhost:3007` 并移除 `/dsxapi` 前缀，使前端直接访问 `http://localhost:3007/api/*`。
+- 注：`/verify-admin`、`/check-auth` 路由由外部系统提供，仓库中未实现。如需本地验证，可在前端暂时跳过或模拟。
+
+## 前端页面与功能
+- 仿真页面（`/`）：
+  - 仅 iframe 嵌入访问（会校验是否处于 iframe 且携带 `token`）
+  - 场景：Office、Industry、DataCenter、WorldSkill 以及对应任务页；支持设备/模块安装、连接物品、故障场景、结果展示等
+- 管理页面（`/admin`）：
+  - 选择场景并编辑连接映射；限制部分端口不可配置；支持保存、初始化、导入/导出 JSON
+- 统计页面（`/competition`）：
+  - 实时拉取参赛席位数据，按条件排序与计算评分；支持导出 Excel
+
+## 后端 API（`server/app.js`，默认 3007）
+- 连接映射
+  - `GET /api/connectionMap?scene=<scene>`：返回 `pass` 场景与指定场景合并后的连接图
+  - `POST /api/connectionMap`：提交 `{ <scene>: { ...connections } }` 更新并持久化到 `server/connection_maps/connectionMap.json`（禁止修改 `pass`）
+  - `POST /api/initConnectionMap`：重置为内置初始映射并持久化
+- 竞赛
+  - `POST /api/competition/start`：开始比赛，返回 `UUID`；每分钟备份编码 `.est`（`server/competition_tmp/<UUID>/`）
+  - `POST /api/competition/end`：结束比赛并保存编码 `.est` 到 `server/competition_data/`，返回 `uuid` 与数据
+  - `GET /api/competition/status`：返回比赛状态与开始时间/UUID（如在运行）
+  - `POST /api/competition/data`：提交 `{ UUID, fingerprint, timestamp, data }`，以指纹为键保存最新数据
+  - `GET /api/competition/data`：返回当前所有参赛数据快照
+
+## 构建与部署
+- 构建：`npm run build`
+- 生产启动：`npm run start`（默认 3003）
+- 部署建议：
+  - 在生产网关（3000）上反代 `/dsxapi` 到后端 API（3007）
+  - 按需提供外部鉴权服务（`/check-auth`、`/verify-admin`）并在 iframe 中嵌入主页
+
+## 常见问题
+- 主页显示 502/拒绝访问：未在 iframe 中或缺少 `token`；用于集成环境，请从外部系统携带 `token` 打开。
+- 前端请求 404：未配置 `/dsxapi` 代理；参见上文“代理与 API 配置”。
+- 管理页保存失败：确保未修改 `pass` 场景；检查后端是否启动并可写 `server/connection_maps/`。