docs: add comprehensive README

This commit is contained in:
zlm committed 2026-06-09 14:36:42 +08:00
1 parent ae90bc9368
commit 5166df13f6
1 file changed
+384
+384
View File
@@ -0,0 +1,384 @@
# 质量追溯系统 (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*
```