From 5166df13f623ab51f5b1fce39db4a4a42b867272 Mon Sep 17 00:00:00 2001 From: zlm Date: Tue, 9 Jun 2026 14:36:42 +0800 Subject: [PATCH] docs: add comprehensive README --- README.md | 384 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 384 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..59b0b7e --- /dev/null +++ b/README.md @@ -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 -- 0 2 +``` + +### 启动报 SQLITE_IOERR + +删除旧的 WAL 文件后重试: + +```bash +rm -f project/data/production.db* +```