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/。

开发记录