From aebca40edf0f84ce88af5304df919e8157b18eda Mon Sep 17 00:00:00 2001 From: zlm Date: Wed, 10 Jun 2026 10:56:29 +0800 Subject: [PATCH] docs: update README with new features, .env config, test tool --- README.md | 137 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 104 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 59b0b7e..fa8cd5f 100644 --- a/README.md +++ b/README.md @@ -7,38 +7,40 @@ ``` scanner_record/ ├── project/ # TypeScript 项目(主程序) +│ ├── .env # 配置文件(gitignored) +│ ├── .env.example # 配置示例 │ ├── src/ -│ │ ├── index.ts # 入口:HTTP 服务 + PLC 轮询启动 -│ │ ├── types.ts # 共享类型定义 -│ │ ├── logger.ts # 分级日志(D/I/W/E + 时间戳 + 模块标签) +│ │ ├── index.ts # 入口:HTTP + PLC 轮询 +│ │ ├── logger.ts # 分级日志 + 按天滚动保留 7 天 +│ │ ├── types.ts # 共享类型 │ │ ├── database/ -│ │ │ ├── connection.ts # better-sqlite3 连接管理(WAL 模式) -│ │ │ ├── schema.ts # 建表 / CRUD / 查询 -│ │ │ └── init.ts # 从 config.json 初始化(仅旧版用) +│ │ │ ├── connection.ts # SQLite 连接(WAL) +│ │ │ └── schema.ts # 建表 / CRUD │ │ ├── api/ -│ │ │ ├── config.ts # 设备配置 REST API -│ │ │ ├── query.ts # 产品追溯 + 工序互锁查询 API -│ │ │ └── monitor.ts # 系统状态 API +│ │ │ ├── config.ts # 设备配置 API +│ │ │ ├── query.ts # 追溯 + 互锁 API +│ │ │ └── monitor.ts # 状态 API │ │ ├── plc/ -│ │ │ ├── protocol.ts # DB 地址偏移 / ControlWord 位操作 -│ │ │ ├── client.ts # Snap7 连接 / 读写封装 -│ │ │ └── scanner.ts # 定时轮询(1000ms) +│ │ │ ├── protocol.ts # 地址偏移 / ControlWord +│ │ │ ├── client.ts # Snap7 读写 + TCP 探测 +│ │ │ └── scanner.ts # 轮询 + 断线重连 │ │ └── services/ -│ │ ├── collection.ts # DataReady → 采集入库 -│ │ └── interlock.ts # PrevResultReq → 查前工序写回 -│ ├── web/ # 前端(Vite + TypeScript + Tailwind CDN) +│ │ ├── collection.ts # 采集入库 +│ │ └── interlock.ts # 工序互锁 +│ ├── web/ # 前端(Vite + Tailwind CDN) │ │ └── src/ -│ │ ├── main.ts # 三页面:追溯查询 / 设备配置 / 系统状态 -│ │ ├── api/client.ts # 后端 API 封装 -│ │ └── styles.css # 页面切换样式 +│ │ ├── main.ts # 追溯 / 配置(二级标签) +│ │ └── api/client.ts # 后端 API 封装 │ ├── 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 原型(仅供参考) +│ │ ├── plc-comm.ts # PLC 通信诊断 +│ │ └── README-PLC.md +│ └── data/ # SQLite(gitignored) +├── plc_protocol_design.md # PLC 协议文档 +├── pc_database_design.md # PC 数据库设计 +├── test_snap7.py # PLC 测试工具(Python CLI) +├── db_init.py / simulate.py # 旧版原型(参考) +├── FLOWCHART.md # Mermaid 流程图 +├── README.md └── .gitignore ``` @@ -48,22 +50,25 @@ scanner_record/ ### ✅ 已完成 -- [x] PLC 端协议设计(24 字节/工序,ControlWord 位定义,详见 `plc_protocol_design.md`) -- [x] PC 端数据库设计(EAV 模型 → 按检测点分表,详见 `pc_database_design.md`) +- [x] PLC 端协议设计(24 字节/工序,ControlWord 位定义) +- [x] PC 端数据库设计(按检测点分表,每天一张) - [x] TypeScript 后端骨架(Hono + better-sqlite3 + node-snap7) -- [x] 前端 Vite 项目(Tailwind CSS,追溯查询 + 设备配置页面) +- [x] 前端 Vite 项目(Tailwind CSS,追溯查询 + 设备配置) - [x] 数据库 CRUD API(检测点 / PLC / 工序 增删改查) -- [x] PLC 轮询扫描(1s 间隔,读取 ControlWord 判断 DataReady / PrevResultReq) -- [x] 数据自动采集(DataReady=1 → 读取全量 → 入库 → 清标志) +- [x] PLC 轮询扫描(每秒一次,批量读取所有工序) +- [x] 数据自动采集(DataReady=1 → 读取 → 入库 → 清标志) - [x] 工序互锁(PrevResultReq=1 → 查数据库 → 写回结果) -- [x] 日志系统(分级 + 时间戳 + 模块标签) +- [x] 日志系统(分级 + 时间戳 + 模块标签 + 按天滚动保留 7 天) - [x] 启动时自动建库(空数据库也能直接启动) - [x] PLC 通信诊断工具(`npm run test:plc`) - [x] 前端在线配置(检测点 / PLC / 工序 增删改) +- [x] `.env` 配置文件(轮询间隔、日志级别、断线参数) +- [x] PLC 断线自动重连机制(TCP 探测 + 状态机) +- [x] 批量 DB 读取(一次网络请求读完所有工序) +- [x] 测试脚本 `test_snap7.py` 命令行参数化 ### 🚧 待完成 -- [ ] Snap7 连接自动重连机制 - [ ] 数据导出(CSV / Excel) - [ ] ECharts 趋势图 - [ ] 用户登录 / 权限管理 @@ -79,6 +84,20 @@ scanner_record/ - **npm** 11+ - **Python** 3.x(仅测试脚本需要) +### 配置 + +创建 `project/.env`(可从 `.env.example` 复制): + +```ini +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 连接(开发用) +``` + ### 启动 ```bash @@ -91,7 +110,7 @@ cd web && npm install && cd .. # 构建前端 cd web && npm run build && cd .. -# 启动(无 PLC 模式,只启动 API + 前端) +# 启动(无 PLC 模式,开发调试) SKIP_PLC=1 npm run start # 启动(连接真实 PLC) @@ -354,6 +373,58 @@ MPData_P1_2026_06_08: --- +--- + +## PLC 断线重连机制 + +``` +正常轮询 ── 连续失败 N 次 ──→ TCP 探测模式 ──→ 端口恢复 ──→ 重连 ──→ 正常轮询 +``` + +- 连续读取失败 `PLC_FAIL_LIMIT`(默认 3)次后,停止对该 PLC 的 DB 读取 +- 进入 TCP 探测模式,每 `PLC_PROBE_INTERVAL_MS`(默认 5s)检查一次 TCP 102 端口 +- 端口恢复后自动调用 Snap7 `ConnectTo` 重连,成功后回到正常轮询 +- 失败期间控制台**不刷屏**,只输出关键状态变更 + +--- + +## 测试工具 + +`test_snap7.py` 用于手动向 PLC 写入测试数据: + +```bash +# 写入工序 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