Files
scanner_record/README.md
T
2026-06-09 14:36:42 +08:00

385 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 质量追溯系统 (Scanner Record)
西门子 S7 PLC 测量数据自动采集与追溯系统。
## 目录结构
```
scanner_record/
├── project/ # TypeScript 项目(主程序)
│ ├── src/
│ │ ├── index.ts # 入口:HTTP 服务 + PLC 轮询启动
│ │ ├── types.ts # 共享类型定义
│ │ ├── logger.ts # 分级日志(D/I/W/E + 时间戳 + 模块标签)
│ │ ├── database/
│ │ │ ├── connection.ts # better-sqlite3 连接管理(WAL 模式)
│ │ │ ├── schema.ts # 建表 / CRUD / 查询
│ │ │ └── init.ts # 从 config.json 初始化(仅旧版用)
│ │ ├── api/
│ │ │ ├── config.ts # 设备配置 REST API
│ │ │ ├── query.ts # 产品追溯 + 工序互锁查询 API
│ │ │ └── monitor.ts # 系统状态 API
│ │ ├── plc/
│ │ │ ├── protocol.ts # DB 地址偏移 / ControlWord 位操作
│ │ │ ├── client.ts # Snap7 连接 / 读写封装
│ │ │ └── scanner.ts # 定时轮询(1000ms)
│ │ └── services/
│ │ ├── collection.ts # DataReady → 采集入库
│ │ └── interlock.ts # PrevResultReq → 查前工序写回
│ ├── web/ # 前端(Vite + TypeScript + Tailwind CDN)
│ │ └── src/
│ │ ├── main.ts # 三页面:追溯查询 / 设备配置 / 系统状态
│ │ ├── api/client.ts # 后端 API 封装
│ │ └── styles.css # 页面切换样式
│ ├── test/
│ │ ├── plc-comm.ts # PLC 通信诊断工具
│ │ └── README-PLC.md # PLC 诊断说明
│ └── data/ # SQLite 数据库文件(gitignored)
├── plc_protocol_design.md # PLC 端地址规划与通信协议
├── pc_database_design.md # PC 端数据库设计文档
├── test_snap7.py # PLC 手动写入测试(Python)
├── db_init.py / simulate.py # 旧版 Python 原型(仅供参考)
└── .gitignore
```
---
## 项目进展
### ✅ 已完成
- [x] PLC 端协议设计(24 字节/工序,ControlWord 位定义,详见 `plc_protocol_design.md`)
- [x] PC 端数据库设计(EAV 模型 → 按检测点分表,详见 `pc_database_design.md`)
- [x] TypeScript 后端骨架(Hono + better-sqlite3 + node-snap7)
- [x] 前端 Vite 项目(Tailwind CSS,追溯查询 + 设备配置页面)
- [x] 数据库 CRUD API(检测点 / PLC / 工序 增删改查)
- [x] PLC 轮询扫描(1s 间隔,读取 ControlWord 判断 DataReady / PrevResultReq)
- [x] 数据自动采集(DataReady=1 → 读取全量 → 入库 → 清标志)
- [x] 工序互锁(PrevResultReq=1 → 查数据库 → 写回结果)
- [x] 日志系统(分级 + 时间戳 + 模块标签)
- [x] 启动时自动建库(空数据库也能直接启动)
- [x] PLC 通信诊断工具(`npm run test:plc`)
- [x] 前端在线配置(检测点 / PLC / 工序 增删改)
### 🚧 待完成
- [ ] Snap7 连接自动重连机制
- [ ] 数据导出(CSV / Excel)
- [ ] ECharts 趋势图
- [ ] 用户登录 / 权限管理
- [ ] Windows 服务注册(开机自启)
---
## 快速开始
### 环境要求
- **Node.js** 22.x(node-snap7 不兼容 v25+)
- **npm** 11+
- **Python** 3.x(仅测试脚本需要)
### 启动
```bash
cd project
# 安装依赖
npm install
cd web && npm install && cd ..
# 构建前端
cd web && npm run build && cd ..
# 启动(无 PLC 模式,只启动 API + 前端)
SKIP_PLC=1 npm run start
# 启动(连接真实 PLC)
npm run start
```
### 前端开发(热更新)
```bash
# 终端 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。
```json
[
{
"Id": 1,
"PLCName": "PLC01_焊接段",
"IPAddress": "192.168.0.10",
"DBNumber": 100,
"StationCount": 3
}
]
```
#### `POST /api/config/plcs`
新增 PLC。
```json
// Request
{ "PLCName": "PLC01", "IPAddress": "192.168.0.10", "DBNumber": 100 }
// Response
{ "Id": 1 }
```
#### `PUT /api/config/plcs/:id`
修改 PLC。
```json
{ "PLCName": "PLC01", "IPAddress": "192.168.0.11", "DBNumber": 200 }
```
#### `DELETE /api/config/plcs/:id`
删除 PLC(级联删除关联工序)。
---
#### `GET /api/config/measurement-points`
获取所有检测点。
```json
[
{ "Id": 1, "PointName": "焊接温度", "FieldUnit": "℃" }
]
```
#### `POST /api/config/measurement-points`
新增检测点(自动创建对应数据表)。
```json
{ "PointName": "焊接温度", "FieldUnit": "℃" }
```
---
#### `GET /api/config/stations`
获取所有工序。支持 `?plcId=1` 过滤。
```json
[
{ "Id": 1, "PLCId": 1, "StationIndex": 0, "StationName": "预焊接", "PointId": 1, "pointName": "焊接温度" }
]
```
#### `POST /api/config/stations`
新增工序。不传 `StationName` 时自动取检测点名。
```json
{ "PLCId": 1, "StationName": "预焊接", "PointId": 1, "StationIndex": 0 }
```
---
### 数据查询
#### `GET /api/query/:productId`
查询某产品在所有检测点的测量数据。
```json
{
"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`
查询某产品在某工序的上一工序合格情况。
```json
{
"currentStation": "焊后检测",
"currentPoint": "焊点直径",
"prevStation": "主焊接",
"prevPoint": "焊接电流",
"prevResult": 1
}
```
### 监控
#### `GET /api/monitor/status`
```json
{
"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
```
---
## 常见问题
### node-snap7 报 TypeError: Wrong arguments
Node.js v25+ 与 `node-snap7` 的 C++ 绑定不兼容。需降级到 Node.js 22.x:
```bash
nvm install 22
nvm use 22
npm rebuild node-snap7
```
### PLC 连接失败
使用诊断工具排查:
```bash
cd project
npm run test:plc -- <PLC_IP> 0 2
```
### 启动报 SQLITE_IOERR
删除旧的 WAL 文件后重试:
```bash
rm -f project/data/production.db*
```