docs: update README with new features, .env config, test tool

This commit is contained in:
zlm committed 2026-06-10 10:56:29 +08:00
1 parent cf3d482646
commit aebca40edf
1 file changed
+104 -33
+104 -33
View File
@@ -7,38 +7,40 @@
``` ```
scanner_record/ scanner_record/
├── project/ # TypeScript 项目(主程序) ├── project/ # TypeScript 项目(主程序)
│ ├── .env # 配置文件(gitignored)
│ ├── .env.example # 配置示例
│ ├── src/ │ ├── src/
│ │ ├── index.ts # 入口:HTTP 服务 + PLC 轮询启动 │ │ ├── index.ts # 入口:HTTP + PLC 轮询
│ │ ├── types.ts # 共享类型定义 │ │ ├── logger.ts # 分级日志 + 按天滚动保留 7 天
│ │ ├── logger.ts # 分级日志(D/I/W/E + 时间戳 + 模块标签) │ │ ├── types.ts # 共享类型
│ │ ├── database/ │ │ ├── database/
│ │ │ ├── connection.ts # better-sqlite3 连接管理(WAL 模式) │ │ │ ├── connection.ts # SQLite 连接(WAL)
│ │ │ ├── schema.ts # 建表 / CRUD / 查询 │ │ │ └── schema.ts # 建表 / CRUD
│ │ │ └── init.ts # 从 config.json 初始化(仅旧版用)
│ │ ├── api/ │ │ ├── api/
│ │ │ ├── config.ts # 设备配置 REST API │ │ │ ├── config.ts # 设备配置 API
│ │ │ ├── query.ts # 产品追溯 + 工序互锁查询 API │ │ │ ├── query.ts # 追溯 + 互锁 API
│ │ │ └── monitor.ts # 系统状态 API │ │ │ └── monitor.ts # 状态 API
│ │ ├── plc/ │ │ ├── plc/
│ │ │ ├── protocol.ts # DB 地址偏移 / ControlWord 位操作 │ │ │ ├── protocol.ts # 地址偏移 / ControlWord
│ │ │ ├── client.ts # Snap7 连接 / 读写封装 │ │ │ ├── client.ts # Snap7 读写 + TCP 探测
│ │ │ └── scanner.ts # 定时轮询(1000ms) │ │ │ └── scanner.ts # 轮询 + 断线重连
│ │ └── services/ │ │ └── services/
│ │ ├── collection.ts # DataReady → 采集入库 │ │ ├── collection.ts # 采集入库
│ │ └── interlock.ts # PrevResultReq → 查前工序写回 │ │ └── interlock.ts # 工序互锁
│ ├── web/ # 前端(Vite + TypeScript + Tailwind CDN) │ ├── web/ # 前端(Vite + Tailwind CDN)
│ │ └── src/ │ │ └── src/
│ │ ├── main.ts # 三页面:追溯查询 / 设备配置 / 系统状态 │ │ ├── main.ts # 追溯 / 配置(二级标签)
│ │ ├── api/client.ts # 后端 API 封装 │ │ └── api/client.ts # 后端 API 封装
│ │ └── styles.css # 页面切换样式
│ ├── test/ │ ├── test/
│ │ ├── plc-comm.ts # PLC 通信诊断工具 │ │ ├── plc-comm.ts # PLC 通信诊断
│ │ └── README-PLC.md # PLC 诊断说明 │ │ └── README-PLC.md
│ └── data/ # SQLite 数据库文件(gitignored) │ └── data/ # SQLite(gitignored)
├── plc_protocol_design.md # PLC 端地址规划与通信协议 ├── plc_protocol_design.md # PLC 协议文档
├── pc_database_design.md # PC 端数据库设计文档 ├── pc_database_design.md # PC 数据库设计
├── test_snap7.py # PLC 手动写入测试(Python) ├── test_snap7.py # PLC 测试工具(Python CLI)
├── db_init.py / simulate.py # 旧版 Python 原型(仅供参考) ├── db_init.py / simulate.py # 旧版原型(参考)
├── FLOWCHART.md # Mermaid 流程图
├── README.md
└── .gitignore └── .gitignore
``` ```
@@ -48,22 +50,25 @@ scanner_record/
### ✅ 已完成 ### ✅ 已完成
- [x] PLC 端协议设计(24 字节/工序,ControlWord 位定义,详见 `plc_protocol_design.md`) - [x] PLC 端协议设计(24 字节/工序,ControlWord 位定义)
- [x] PC 端数据库设计(EAV 模型 → 按检测点分表,详见 `pc_database_design.md`) - [x] PC 端数据库设计(按检测点分表,每天一张)
- [x] TypeScript 后端骨架(Hono + better-sqlite3 + node-snap7) - [x] TypeScript 后端骨架(Hono + better-sqlite3 + node-snap7)
- [x] 前端 Vite 项目(Tailwind CSS,追溯查询 + 设备配置页面) - [x] 前端 Vite 项目(Tailwind CSS,追溯查询 + 设备配置)
- [x] 数据库 CRUD API(检测点 / PLC / 工序 增删改查) - [x] 数据库 CRUD API(检测点 / PLC / 工序 增删改查)
- [x] PLC 轮询扫描(1s 间隔,读取 ControlWord 判断 DataReady / PrevResultReq) - [x] PLC 轮询扫描(每秒一次,批量读取所有工序)
- [x] 数据自动采集(DataReady=1 → 读取全量 → 入库 → 清标志) - [x] 数据自动采集(DataReady=1 → 读取 → 入库 → 清标志)
- [x] 工序互锁(PrevResultReq=1 → 查数据库 → 写回结果) - [x] 工序互锁(PrevResultReq=1 → 查数据库 → 写回结果)
- [x] 日志系统(分级 + 时间戳 + 模块标签) - [x] 日志系统(分级 + 时间戳 + 模块标签 + 按天滚动保留 7 天)
- [x] 启动时自动建库(空数据库也能直接启动) - [x] 启动时自动建库(空数据库也能直接启动)
- [x] PLC 通信诊断工具(`npm run test:plc`) - [x] PLC 通信诊断工具(`npm run test:plc`)
- [x] 前端在线配置(检测点 / PLC / 工序 增删改) - [x] 前端在线配置(检测点 / PLC / 工序 增删改)
- [x] `.env` 配置文件(轮询间隔、日志级别、断线参数)
- [x] PLC 断线自动重连机制(TCP 探测 + 状态机)
- [x] 批量 DB 读取(一次网络请求读完所有工序)
- [x] 测试脚本 `test_snap7.py` 命令行参数化
### 🚧 待完成 ### 🚧 待完成
- [ ] Snap7 连接自动重连机制
- [ ] 数据导出(CSV / Excel) - [ ] 数据导出(CSV / Excel)
- [ ] ECharts 趋势图 - [ ] ECharts 趋势图
- [ ] 用户登录 / 权限管理 - [ ] 用户登录 / 权限管理
@@ -79,6 +84,20 @@ scanner_record/
- **npm** 11+ - **npm** 11+
- **Python** 3.x(仅测试脚本需要) - **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 ```bash
@@ -91,7 +110,7 @@ cd web && npm install && cd ..
# 构建前端 # 构建前端
cd web && npm run build && cd .. cd web && npm run build && cd ..
# 启动(无 PLC 模式,只启动 API + 前端) # 启动(无 PLC 模式,开发调试)
SKIP_PLC=1 npm run start SKIP_PLC=1 npm run start
# 启动(连接真实 PLC) # 启动(连接真实 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 ### node-snap7 报 TypeError: Wrong arguments