Files
scanner_record/README.md
T
2026-06-10 11:18:45 +08:00

13 KiB
Raw Blame History

质量追溯系统 (Scanner Record)

西门子 S7 PLC 测量数据自动采集与追溯系统。

目录结构

scanner_record/
├── project/                        # TypeScript 项目(主程序)
│   ├── .env                         # 配置文件(gitignored)
│   ├── .env.example                 # 配置示例
│   ├── src/
│   │   ├── index.ts                # 入口:HTTP + PLC 轮询
│   │   ├── logger.ts               # 分级日志 + 按天滚动保留 7 天
│   │   ├── types.ts                # 共享类型
│   │   ├── database/
│   │   │   ├── connection.ts       # SQLite 连接(WAL)
│   │   │   └── schema.ts           # 建表 / CRUD
│   │   ├── api/
│   │   │   ├── config.ts           # 设备配置 API
│   │   │   ├── query.ts            # 追溯 + 互锁 API
│   │   │   └── monitor.ts          # 状态 API
│   │   ├── plc/
│   │   │   ├── protocol.ts         # 地址偏移 / ControlWord
│   │   │   ├── client.ts           # Snap7 读写 + TCP 探测
│   │   │   └── scanner.ts          # 轮询 + 断线重连
│   │   └── services/
│   │       ├── collection.ts       # 采集入库
│   │       └── interlock.ts        # 工序互锁
│   ├── web/                        # 前端(Vite + Tailwind CDN)
│   │   └── src/
│   │       ├── main.ts             # 追溯 / 配置(二级标签)
│   │       └── api/client.ts       # 后端 API 封装
│   ├── test/
│   │   ├── plc-comm.ts             # PLC 通信诊断
│   │   └── README-PLC.md
│   └── data/                       # SQLite(gitignored)
├── plc_protocol_design.md          # PLC 协议文档
├── pc_database_design.md           # PC 数据库设计
├── desktop/                        # Electron 桌面壳(系统托盘 + 日志窗口)
├── test_snap7.py                   # PLC 测试工具(Python CLI)
├── db_init.py / simulate.py        # 旧版原型(参考)
├── FLOWCHART.md                    # Mermaid 流程图
├── README.md
└── .gitignore

项目进展

✅ 已完成

  • PLC 端协议设计(24 字节/工序,ControlWord 位定义)
  • PC 端数据库设计(按检测点分表,每天一张)
  • TypeScript 后端骨架(Hono + better-sqlite3 + node-snap7)
  • 前端 Vite 项目(Tailwind CSS,追溯查询 + 设备配置)
  • 数据库 CRUD API(检测点 / PLC / 工序 增删改查)
  • PLC 轮询扫描(每秒一次,批量读取所有工序)
  • 数据自动采集(DataReady=1 → 读取 → 入库 → 清标志)
  • 工序互锁(PrevResultReq=1 → 查数据库 → 写回结果)
  • 日志系统(分级 + 时间戳 + 模块标签 + 按天滚动保留 7 天)
  • 启动时自动建库(空数据库也能直接启动)
  • PLC 通信诊断工具(npm run test:plc)
  • 前端在线配置(检测点 / PLC / 工序 增删改)
  • .env 配置文件(轮询间隔、日志级别、断线参数)
  • PLC 断线自动重连机制(TCP 探测 + 状态机)
  • 批量 DB 读取(一次网络请求读完所有工序)
  • 测试脚本 test_snap7.py 命令行参数化

🚧 待完成

  • 数据导出(CSV / Excel)
  • ECharts 趋势图
  • 用户登录 / 权限管理
  • Windows 服务注册(开机自启)

快速开始

环境要求

  • Node.js 22.x(node-snap7 不兼容 v25+)
  • npm 11+
  • Python 3.x(仅测试脚本需要)

配置

创建 project/.env(可从 .env.example 复制):

PORT=3000                       # 服务端口
POLL_INTERVAL_MS=1000           # PLC 轮询间隔(毫秒)
LOG_LEVEL=1                     # 日志级别: 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR
PLC_FAIL_LIMIT=3                # 连续失败次数上限
PLC_PROBE_INTERVAL_MS=5000      # TCP 探测间隔(毫秒)
PLC_PROBE_TIMEOUT_MS=2000       # TCP 探测超时(毫秒)
# SKIP_PLC=1                    # 跳过 PLC 连接(开发用)

启动

cd project

# 安装依赖
npm install
cd web && npm install && cd ..

# 构建前端
cd web && npm run build && cd ..

# 启动(无 PLC 模式,开发调试)
SKIP_PLC=1 npm run start

# 启动(连接真实 PLC)
npm run start

前端开发(热更新)

# 终端 1:后端
cd project && npm run dev

# 终端 2:前端(HMR)
cd project/web && npm run dev

架构

┌──────────────────────────────────────────────────────┐
│          西门子 S7 PLC                               │
│  DB 块:工序 0 (偏移 0) | 工序 1 (偏移 24) | ...     │
│  ControlWord: DataReady / IsQualified / PrevResultReq│
└──────────────────────┬───────────────────────────────┘
                       │ S7 协议 (Ethernet)
┌──────────────────────▼───────────────────────────────┐
│          Node.js 进程 (Hono)                          │
│                                                       │
│  ┌─────────────┐  ┌──────────────┐                    │
│  │ PLC Scanner  │  │  REST API    │  :3000            │
│  │ (1s 轮询)    │  │  /api/*     │                    │
│  └──────┬───────┘  └──────┬───────┘                    │
│         │                │                            │
│  ┌──────▼────────────────▼───────┐                    │
│  │     better-sqlite3           │                    │
│  │     data/production.db       │                    │
│  └──────────────────────────────┘                    │
└──────┬───────────────────────────────────────────────┘
       │ 静态文件 (/web/*)
┌──────▼───────────────────────────────────────────────┐
│  前端 (Vite 构建产物)                                 │
│  追溯查询 / 设备配置 / 系统状态                       │
└──────────────────────────────────────────────────────┘

PLC 通信协议

字段 偏移 类型 大小 方向 说明
ProductID +0 DINT 4 PLC→PC 当前产品唯一编号
UpperLimit +4 REAL 4 PLC→PC 测量上限
LowerLimit +8 REAL 4 PLC→PC 测量下限
MeasuredValue +12 REAL 4 PLC→PC 实测值
ControlWord +16 WORD 2 双向 控制字(见下方)
Reserved +18 — 6 — 保留

ControlWord 位定义

位 名称 方向 说明
Bit 0 DataReady PLC→PC 1=有新的测量数据待读取
Bit 1 IsQualified PLC→PC 1=合格
Bit 2 PrevResultReq PLC→PC 1=请求上一工序结果
Bit 3 PrevResult PC→PLC PC 写入:1=合格,0=不合格

详见 plc_protocol_design.md。


API 文档

基础信息

  • Base URL: http://localhost:3000/api
  • Content-Type: application/json

设备配置

GET /api/config/plcs

获取所有 PLC。

[
  {
    "Id": 1,
    "PLCName": "PLC01_焊接段",
    "IPAddress": "192.168.0.10",
    "DBNumber": 100,
    "StationCount": 3
  }
]

POST /api/config/plcs

新增 PLC。

// Request
{ "PLCName": "PLC01", "IPAddress": "192.168.0.10", "DBNumber": 100 }
// Response
{ "Id": 1 }

PUT /api/config/plcs/:id

修改 PLC。

{ "PLCName": "PLC01", "IPAddress": "192.168.0.11", "DBNumber": 200 }

DELETE /api/config/plcs/:id

删除 PLC(级联删除关联工序)。


GET /api/config/measurement-points

获取所有检测点。

[
  { "Id": 1, "PointName": "焊接温度", "FieldUnit": "℃" }
]

POST /api/config/measurement-points

新增检测点(自动创建对应数据表)。

{ "PointName": "焊接温度", "FieldUnit": "℃" }

GET /api/config/stations

获取所有工序。支持 ?plcId=1 过滤。

[
  { "Id": 1, "PLCId": 1, "StationIndex": 0, "StationName": "预焊接", "PointId": 1, "pointName": "焊接温度" }
]

POST /api/config/stations

新增工序。不传 StationName 时自动取检测点名。

{ "PLCId": 1, "StationName": "预焊接", "PointId": 1, "StationIndex": 0 }

数据查询

GET /api/query/:productId

查询某产品在所有检测点的测量数据。

{
  "productId": "PROD-003",
  "data": [
    {
      "pointId": 1,
      "pointName": "焊接温度",
      "fieldUnit": "℃",
      "recordTime": "2026-06-08 07:54:42",
      "isQualified": 1,
      "inspectionCount": 1,
      "upperLimit": 93.3,
      "lowerLimit": 75.2,
      "measuredValue": 90.2
    }
  ]
}

GET /api/query/:productId/interlock/:stationName

查询某产品在某工序的上一工序合格情况。

{
  "currentStation": "焊后检测",
  "currentPoint": "焊点直径",
  "prevStation": "主焊接",
  "prevPoint": "焊接电流",
  "prevResult": 1
}

监控

GET /api/monitor/status

{
  "plcCount": 2,
  "stationCount": 5,
  "pointCount": 5,
  "dataTableCount": 5,
  "totalRecords": 60
}

数据流

采集流程

PLC:  ControlWord.DataReady = 1
  ↓
PC:  读 DB 块 32 字节 → 解析 ProductID + 测量值 + ControlWord
  ↓
PC:  查数据库 → InspectionCount = max + 1
  ↓
PC:  INSERT/UPDATE → MPData_P{PointId}_{日期}
  ↓
PC:  ControlWord.DataReady = 0

互锁流程

PLC:  ControlWord.PrevResultReq = 1
  ↓
PC:  读 DB → 获取 ProductID
  ↓
PC:  查数据库 → 前工序的最新 IsQualified
  ↓
PC:  ControlWord.PrevResult = 1/0
  ↓
PC:  ControlWord.PrevResultReq = 0

数据库结构

配置表

MeasurementPoints (Id, PointName, FieldUnit)
PLCs             (Id, PLCName, IPAddress, DBNumber, StationCount)
Stations         (Id, PLCId, StationIndex, StationName, PointId)

数据表(按检测点分表,每天一张)

MPData_P1_2026_06_08:
  Id | ProductID | RecordTime | IsQualified | InspectionCount |
  UpperLimit | LowerLimit | MeasuredValue


PLC 断线重连机制

正常轮询 ── 连续失败 N 次 ──→ TCP 探测模式 ──→ 端口恢复 ──→ 重连 ──→ 正常轮询
  • 连续读取失败 PLC_FAIL_LIMIT(默认 3)次后,停止对该 PLC 的 DB 读取
  • 进入 TCP 探测模式,每 PLC_PROBE_INTERVAL_MS(默认 5s)检查一次 TCP 102 端口
  • 端口恢复后自动调用 Snap7 ConnectTo 重连,成功后回到正常轮询
  • 失败期间控制台不刷屏,只输出关键状态变更

测试工具

test_snap7.py 用于手动向 PLC 写入测试数据:

# 写入工序 0 完整数据 + 触发采集
python test_snap7.py --station 0 --product-id 10086 --upper 100.0 \
  --lower 80.0 --measured 95.5 --dataready --qualified

# 工序 2 触发 PrevResultReq
python test_snap7.py --station 2 --prev-req

# 只读某一工序
python test_snap7.py --station 1 --read

# 触发 DataReady + 不合格
python test_snap7.py --station 0 --dataready --unqualified

参数说明

参数 说明
--ip PLC IP(默认 192.168.2.125)
--db DB 块号(默认 1)
--station 工序索引(默认 0)
--read 读取本工序所有字段
--product-id 写入 ProductID (DINT)
--upper / --lower / --measured 写入上限/下限/实测值 (REAL)
--dataready 设置 ControlWord Bit0=1
--qualified 设置 Bit1=1(合格)
--unqualified 设置 Bit1=0(不合格)
--prev-req 设置 Bit2=1 (PrevResultReq)
--value 直接写入 ControlWord 值

常见问题

node-snap7 报 TypeError: Wrong arguments

Node.js v25+ 与 node-snap7 的 C++ 绑定不兼容。需降级到 Node.js 22.x:

nvm install 22
nvm use 22
npm rebuild node-snap7

PLC 连接失败

使用诊断工具排查:

cd project
npm run test:plc -- <PLC_IP> 0 2

Windows 桌面版

cd desktop
npm install
npm run dev

启动后隐藏终端,系统托盘出现蓝色图标,双击打开日志窗口。关闭窗口不退出程序,右键托盘选"退出"结束。


启动报 SQLITE_IOERR

删除旧的 WAL 文件后重试:

rm -f project/data/production.db*