# Nexus-Station

**Repository Path**: NexusERP/nexus-station

## Basic Information

- **Project Name**: Nexus-Station
- **Description**: Nexus系列-工位一体机：烧录 / FCT / 装配等工位工控机上的桌面作业端
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-08-20
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Electron, Vue, TypeScript

## README

# nexus-station — Nexus 工位智能终端

烧录 / FCT / 装配等工位工控机上的桌面作业端（Electron + Vue 3 + TypeScript）。
**不是** Web 管理端的桌面壳——管理职能由 nexus-erp/plus-ui 承担。

> **主项目**（nexus-erp，Spring Boot 的 MES/ERP 后端）：https://gitee.com/NexusERP/nexus-erp
> **本仓库**：https://gitee.com/NexusERP/nexus-station

## 界面总览

以下截图均由真实 App 连接真实 MES 后端自动采集（数据为联调测试工位数据）。

### 启动与设置

扫工号条码上岗（或跳过直接进入），冷启动每次执行一次：

![启动上岗](doc/screenshots/01-boot.png)

工位设置：MES 连接 / 工位绑定码（`STN|车间|产线|工序|形态|设备编码` 六段码，第 6 段设备编码自动剥离回填）/ 烧录驱动 / 综测串口：

![工位设置](doc/screenshots/11-settings.png)

### 作业页

工作台（FLASH 形态）：扫 SN 拉取待刷清单 → 执行刷写全程进度可视（下载/擦除/写入/校验/复位）→ 完成即上报 MES：

![工作台](doc/screenshots/02-workbench.png)

SN 过站：四重校验（前置工序 / 工位匹配 / 防重复 / 质量扣押），绿屏放行红屏拦截，拦截后选不良代码上报：

![SN 过站](doc/screenshots/03-pass.png)

批量计数报工：良品 +1/+5/+10 计数、不良代码分类计数：

![批量计数](doc/screenshots/04-batch.png)

关键件绑定：先扫成品 SN 锁定父件，再连续扫组件 SN 累加提交，支持单项删除与解绑/换板：

![关键件绑定](doc/screenshots/05-bind.png)

综测监控：串口收数自动上报，最新报文红绿即时反馈 + 报文统计（串口路径/设备编码在工位设置中配置）：

![综测监控](doc/screenshots/10-test.png)

### 工具页

SN 全履历追溯：概要 + 工序链 + 刷写/综测/过站/绑定四源时间线：

![SN 追溯](doc/screenshots/06-trace.png)

设备点检：按工位工序关联设备逐项点检，异常自动置设备故障并呼叫维修安灯：

![设备点检](doc/screenshots/07-checkup.png)

作业指导 SOP：多文档页签，PDF / 图片轮播 / 视频在线预览，版本不符红条阻断开工：

![作业指导 SOP](doc/screenshots/08-sop.png)

上料防错：扫批次码/条码按工单 MBOM 快照比对，绿屏通过（含替代料标记）/ 红屏展示允许上料清单：

![上料防错](doc/screenshots/09-material.png)

## 定位与边界

| 端 | 定位 |
|---|---|
| **nexus-station（本工程）** | 工位作业端：扫 SN 拉待刷清单 → 下载固件/预取内容 → 串口/CLI 烧录 → 结果上报 → 完工门禁闭环 |
| nexus-pda | 手持作业端（仓库/产线扫码） |
| Nexus_App | 移动管理端（办公场景） |
| plus-ui | Web 管理端 |

## 功能特性

- **三形态工位**：FLASH 烧录 / TEST 综测 / GENERAL 过站，按工位码第 5 段自动装载对应工作台
- **刷写闭环**：prepare 预取 → 固件下载（边下边算 MD5）→ 驱动烧录 → 上报 → 同 SN 连续失败 3 次自动呼叫质量安灯
- **过站体系**：SN 单件过站四重校验、批量计数报工、关键件绑定/解绑（防环、留痕）
- **质量工具**：SN 全履历追溯、设备点检（异常联动安灯）、SOP 作业指导（版本强控）、上料防错（MBOM 快照 + 替代料）
- **平台能力**：操作员上岗/下岗、安灯四键呼叫、离线队列（断网暂存 30s 回放）、设备心跳、自动更新（静默下载+夜间安装）
- **工位机体验**：扫码自动聚焦/连续扫码、声光语音反馈（蜂鸣+中文 TTS）、Kiosk 全屏锁定（`STATION_KIOSK=1`）、F12 开发者工具

## 技术栈

- **壳**: Electron 33 + electron-vite + electron-builder (NSIS)
- **UI**: Vue 3 + TypeScript + Element Plus（主题对齐品牌色）+ Pinia + Vue Router
- **硬件层（主进程）**: `serialport`（串口）/ `child_process`（包装厂商 CLI：STM32CubeProgrammer 等），烧录驱动为 SPI 插件式（`FlasherDriver`）
- **测试**: Vitest（主进程纯逻辑模块，驱动注入式测试）

## 快速开始

```bash
npm install          # .npmrc 已配置国内 Electron 镜像
npm run dev          # 开发模式（mock 烧录驱动）
npm test             # 单元测试
npm run typecheck    # 类型检查
npm run build:win    # 打包 Windows NSIS 安装包 (dist/)
```

工位机常开模式：`STATION_KIOSK=1 npm run dev`（全屏锁定）。

## 联调测试数据

后端仓库提供一套幂等可重跑的 QC 测试工位数据（`nexus-erp/script/sql/update/2026-08-22-station-qc-test-data.sql`），覆盖全部设备通道场景：

| 项 | 值 |
|---|---|
| 工位码（过站形态，6 段） | `STN\|TEST\|L1\|QC\|GENERAL\|GZZ0002` |
| 工位码（刷写形态） | `STN\|TEST\|L1\|QC\|FLASH\|GZZ0002` |
| 上岗工号 | `SCZX20251222017`（张明） |
| 过站 SN | `SNQCTEST0001 ~ 0005` |
| 刷写 SN（FLASH 工位扫） | `SNQCFLASH0001 ~ 0003` |
| 组件 SN（绑定） | `SNQCCOMP0001 ~ 0006` |
| 上料批次 | `B20260822001`（主料）/ `B20260822002`（替代料）/ `B202606040001`（错误料，应拦截） |
| 上料条码 | `RC20260822000001` |

## 目录结构

```
src/
├── main/                        主进程（业务后端）
│   ├── index.ts                 入口: 窗口/驱动注册/sop://协议/心跳/自动更新/F12
│   ├── config.ts                工位配置 (userData/config.json, 含综测串口)
│   ├── ipc.ts                   IPC 契约 (渲染层↔主进程全部通道)
│   ├── operator.ts              操作员上岗会话
│   ├── heartbeat.ts             设备心跳 (60s)
│   ├── updater.ts               自动更新 (静默下载+夜间安装)
│   ├── mes/                     MES 免登录设备通道客户端 (X-API-KEY)
│   │   ├── client.ts            C1-C20 全部接口 (含 [MES] 调用日志)
│   │   ├── types.ts             接口契约类型
│   │   ├── firmware.ts          固件下载器 (边下边算 MD5)
│   │   └── sop.ts               SOP 文档下载器
│   ├── hardware/                烧录驱动层 (FlasherDriver SPI 插件式)
│   │   ├── flasher-driver.ts    驱动接口
│   │   ├── flasher-registry.ts  注册中心
│   │   └── drivers/             mock / serial-generic / cli-*
│   └── job/
│       ├── flash-job-runner.ts  刷写编排 (prepare→download→flash→report)
│       └── offline-queue.ts     断网暂存队列 (30s 自动回放)
├── preload/index.ts             contextBridge: window.station
└── renderer/                    渲染层 (Vue 3)
    └── src/
        ├── App.vue              全局壳: 顶栏/SOP 版本红条/上岗对话框
        ├── router/              11 个页面路由 (hash 模式)
        ├── stores/station.ts    全局状态 (配置/操作员/SOP 版本)
        ├── api/station.ts       主进程 API 入口 (IPC 参数净化)
        ├── components/          ScanInput / PageHeader / ResultScreen / AndonBar
        ├── composables/         useDefectCodes (不良代码字典)
        ├── utils/feedback.ts    声光语音反馈
        ├── styles/theme.css     设计 token + Element Plus 主题对齐
        └── views/               11 个页面视图
```

## 与 MES 的对接

走免登录设备通道（`X-API-KEY` 请求头，后端配置 `mes.api-key`），契约权威定义见 `nexus-erp/doc/station/README.md`（C1-C20 全部交付）：

| 能力 | 接口 |
|---|---|
| 上岗（C1） | `GET /mes/station/operator` |
| 过站（C2-C4） | `POST /mes/station/pass/validate` · `pass/report` · `pass/report-batch` |
| 绑定（C5/C6） | `POST /mes/station/sn/bind` · `sn/unbind` |
| 不良代码（C9） | `GET /mes/station/defect-codes` |
| 安灯（C7/C8） | `POST /mes/station/andon/call` · `GET /mes/station/andon/latest` |
| 追溯（C13） | `GET /mes/station/trace/{snCode}` |
| 点检（C14/C15） | `GET /mes/station/inspection/tasks` · `POST /mes/station/inspection/submit` |
| SOP（C16-C18） | `GET /mes/station/sop/current` · `sop/version-check` · `{sopId}/download` |
| 上料（C19/C20） | `POST /mes/station/material/load` · `GET /mes/station/material/current` |
| 心跳（C10） | `POST /mes/flash/report/station/heartbeat` |
| 刷写/综测（C11/C12） | `GET /mes/flash/report/station/pending` · `POST station/prepare` · `GET firmware/{id}/download` · `POST flash/auto` · `POST test/auto` |

## 调试技巧

- **F12 / Ctrl+Shift+I**：切换开发者工具（Console / Network / Vue 组件检查）
- **工位机终端**：每次 MES 调用打印一行 `[MES] GET/POST 路径 -> 状态 (耗时)`，接口是否真的调了、报了什么错一目了然
- **渲染层日志**：`ELECTRON_ENABLE_LOGGING=1 npm run dev` 可将渲染层 console 输出到终端
- **后端 SQL**：nexus-erp 控制台有 p6spy 全量 SQL 日志；刷写上报为宽松模式（HTTP 200 + `failed` 列表），工位机已对业务拒绝显式报错

## 文档

- [doc/design/2026-08-20-功能设计.md](doc/design/2026-08-20-功能设计.md) — 功能设计总纲

## 注意事项

- 烧录驱动为 SPI 插件式（`FlasherDriver`），新增烧录器型号只需实现接口并在 `src/main/index.ts` 注册；开发调试用 `mock` 驱动即可走通全链路（含真实固件下载与上报）
- 串口/HID 依赖含原生模块，切换 Electron 大版本后执行 `npm run postinstall` 重编译
- `StationPendingItem` 字段名以后端 `selectStationPending` SQL 别名为准
- 渲染层传给主进程的对象会被 Vue 响应式代理包装，`api/station.ts` 已统一净化（contextBridge 无法封送 Proxy）；新增 IPC 通道无需在页面侧做 toRaw
- README 截图可用 `npx electron scripts/capture-screenshots.cjs` 自动重采（先 `npm run build`，需连接运行中的 MES 后端与联调测试数据）