82 lines
4.7 KiB
Markdown
82 lines
4.7 KiB
Markdown
# 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/`。
|