Files

yunxiao.zhu d70b94e904 ✨ feat(*): 添加扫码枪启动探活、全局退出助手及 README

- 添加扫码枪串口启动探活，检测端口占用并更新 UI 状态
- 新增 ShutdownHelper 安全停止 Host 扩展方法
- 新增 README.md 项目说明文档
- 更新 WorkflowHostedService 启动探活逻辑
- 补充 ShutdownHelper 与 WorkflowHostedService 单元测试
- 优化 DashboardPage 与 SystemSettingsPage 界面布局
- 调整 ModbusTcpPlcService 监控镜像读取逻辑

2026-04-19 14:29:07 +08:00

23 KiB

Raw Blame History

PCB 目检软件需求与方案设计

1. 文档目的

本文档用于整理当前 PCB 简易目检上位机的软件需求、业务流程、通信接口、异常处理和 Modbus TCP 点位设计，作为后续开发、联调和现场验收的依据。

当前版本仅覆盖以下能力：

PLC 到位信号接入
串口触发扫码枪扫码
SFTP 文件存在性校验
PLC 放行信号回写
HTTP 安灯报警接口调用
关键过程日志与状态记录

本文档不包含以下能力：

相机采图
图像算法判定
人工复判
多工位并行处理
MES/WMS 深度集成

2. 系统范围与边界

2.1 系统角色

系统由以下四个外部对象和一个上位机应用组成：

PLC
- 通过 Modbus TCP 与上位机通信
- 提供 PCB 到位、复位、运行允许等状态
- 接收上位机放行、流程完成、故障/报警等结果信号
扫码枪
- 通过串口与上位机通信
- 接收上位机触发扫描指令
- 返回二维码内容或超时失败
SFTP 服务器
- 用于存放与 PCB 二维码 ID 对应的判定文件或放行文件
- 上位机根据扫码结果访问指定目录并查找目标文件
安灯系统
- 通过 HTTP 接口接收报警请求
- 用于扫码失败等异常场景的现场告警
上位机软件
- 负责流程编排、设备通信、状态机控制、日志记录、异常处理和 PLC 结果回写

2.2 运行约束

运行模式为单件串行处理
同一时刻只处理一块 PCB
上位机作为 Modbus TCP Client
PLC 作为 Modbus TCP Server
扫码最多尝试 3 次（含首次触发）
SFTP 采用 1 次首次查询 + 最多 N 次重试 的方式检查目标文件
扫码失败 3 次后仍放行，同时触发安灯报警
SFTP 文件最终未找到时仍放行，默认仅记录日志，不强制安灯报警
SFTP 连接失败、认证失败、目录配置错误等系统级异常不等同于“文件不存在”，默认进入系统故障，不自动放行

3. 需求整理

3.1 功能需求

3.1.1 到位触发

当 PCB 到达指定工位后，PLC 通过 Modbus TCP 点位通知上位机“PCB 已到位”
上位机在检测到到位信号后，启动本次单板处理流程
上位机应避免同一块板被重复触发处理

3.1.2 扫码控制

上位机通过串口向扫码枪发送触发命令
扫码枪返回二维码字符串
如果单次扫码失败，上位机允许继续重试
当前版本最大尝试次数固定为 3 次（含首次触发）

3.1.3 扫码失败处理

若连续 3 次扫码失败：
- 上位机调用 HTTP 安灯报警接口
- 上位机记录失败原因和报警结果
- 上位机仍向 PLC 发送放行信号
- 本次流程结果标记为“扫码失败放行”

3.1.4 SFTP 文件校验

扫码成功后，上位机根据二维码 ID 到配置好的 SFTP 目录中查找对应文件
当前版本采用 首次查询 1 次 + 文件未命中后最多重试 N 次 的规则，N 为可配置项
若文件存在：
- 视为校验通过
- 上位机立即发送放行信号给 PLC
若文件不存在：
- 等待 X 秒后再次检查
- 达到重试上限后按“文件未找到超时处理”执行

3.1.5 文件未找到超时处理

若达到 SFTP 查询重试上限后仍未找到对应文件：
- 上位机记录“文件未找到超时放行”
- 上位机仍向 PLC 发送放行信号
- 默认不强制调用安灯接口，但应保留后续扩展为可配置报警策略的设计空间

3.1.6 二维码内容处理

二维码字符串在用于 SFTP 查询前，应先执行基础清洗：
- 去除首尾空白字符
- 去除回车换行等控制字符
清洗后若为空字符串，则视为本次扫码失败
当前版本不增加更复杂的正则或长度业务校验，避免引入未确认的规则

3.1.7 PLC 交互

上位机需向 PLC 提供以下反馈能力：
- 忙碌状态
- 当前流程完成状态
- 放行信号
- 扫码成功/失败状态
- 文件存在/不存在状态
- 故障或报警状态
- 异常代码/结果代码

3.1.8 日志与追溯

上位机应记录以下关键日志：
- 到位触发时间
- 扫码每次尝试结果
- 最终二维码内容
- SFTP 连接与查找结果
- HTTP 报警调用结果
- PLC 点位写入动作
- 本次流程最终结果

3.2 非功能需求

支持稳定连续运行
所有外部接口都应具备超时控制
所有异常都必须记录日志，不允许静默吞掉
同一时刻只能处理一块 PCB，避免并发混板
配置项应集中管理，避免硬编码 IP、端口、账号、目录和重试参数

4. 推荐总体方案

4.1 总体架构

推荐采用单工位串行状态机架构。

该方案由一个主流程控制器串联以下模块：

PLC 通信模块
扫码枪控制模块
SFTP 校验模块
安灯报警模块
流程状态机模块
日志与结果记录模块

4.2 方案特点

适合当前“单件串行”场景
逻辑清晰，便于现场联调
点位数量可控，便于 PLC 程序实现
后续可在不推翻主体结构的前提下扩展更多结果码、报警策略和 UI 状态展示

4.3 不推荐的当前方案

当前阶段不建议直接采用多任务队列、多工位并行或由 PLC 承担大部分业务编排的重型架构，因为会显著增加联调复杂度，不符合“简单目检软件”的目标。

5. 软件模块设计

5.1 流程控制模块

负责：

接收 PLC 到位信号
驱动整个业务状态机流转
管理当前板的处理上下文
决定何时触发扫码、何时检查文件、何时报警、何时放行

建议职责边界：

一个流程控制器只负责一块当前 PCB
所有外部服务都由流程控制器统一调度
不允许 PLC、扫码、SFTP、报警模块彼此直接耦合调用

5.2 PLC 通信模块

负责：

周期性读取 PLC 点位
写入上位机结果点位
做好写脉冲、保持位和复位逻辑
管理断线重连和通信状态

建议接口：

ReadSignalsAsync()：读取 PLC 输入状态
WriteHandshakeAsync()：写入握手和结果点位
PulseReleaseAsync()：发送放行脉冲
ResetResultBitsAsync()：清理本次流程结果位

5.3 扫码枪控制模块

负责：

管理串口打开、关闭、重连
发送扫码命令
接收扫码返回值
执行单次扫码超时控制
将扫码结果以统一对象返回给流程控制器

建议输出统一结果：

是否成功
扫码内容
原始返回报文
失败原因
本次耗时

5.4 SFTP 校验模块

负责：

根据配置建立 SFTP 连接
按二维码 ID 查找目标文件
支持按目录、文件名模板或通配方式查找
执行重试、等待和超时控制
输出最终查找结果

建议支持的配置项：

服务器地址
端口
用户名
密码/密钥
根目录
文件名匹配规则
单次连接超时
查询等待秒数
最大重试次数

5.5 安灯报警模块

负责：

调用 HTTP 安灯接口
发送报警编码、报警内容、工位号、二维码等参数
处理响应结果并记录日志

建议支持的配置项：

接口 URL
请求方法
请求头
超时时间
报警编码
工位名称
是否启用扫码失败报警
是否启用文件未找到报警（预留）

5.6 日志与结果记录模块

负责：

写入运行日志
保存每板处理结果摘要
输出 UI 可显示的当前状态、结果和错误信息

建议记录字段：

触发时间
完成时间
条码内容
扫码次数
SFTP 重试次数
最终结果代码
最终结果描述
是否调用安灯
PLC 放行发送时间

6. 业务状态机设计

6.1 状态定义

建议定义以下流程状态：

Idle：空闲，等待 PLC 到位
Triggered：接收到到位信号，准备启动流程
Scanning：正在触发扫码枪扫码
ScanRetrying：扫码失败，等待下一次扫码尝试
ScanFailedReleased：扫码失败 3 次，已报警并决定放行
CheckingSftp：正在检查 SFTP 文件是否存在
WaitingSftpRetry：文件未找到，等待下一次轮询
SftpPassed：文件找到，允许放行
SftpTimeoutReleased：文件未找到超时，决定放行
Releasing：向 PLC 发送放行信号
Completed：本次流程结束
Faulted：出现系统级故障，如 PLC 通信异常、配置错误、串口不可用、SFTP 连接异常等

6.2 状态流转

正常流转

Idle -> Triggered -> Scanning -> CheckingSftp -> SftpPassed -> Releasing -> Completed -> Idle

扫码失败放行流转

Idle -> Triggered -> Scanning -> ScanRetrying -> Scanning -> ScanRetrying -> Scanning -> ScanFailedReleased -> Releasing -> Completed -> Idle

文件未找到超时放行流转

Idle -> Triggered -> Scanning -> CheckingSftp -> WaitingSftpRetry -> CheckingSftp -> ... -> SftpTimeoutReleased -> Releasing -> Completed -> Idle

系统故障流转

任意流程态 -> Faulted -> 人工复位/PLC复位 -> Idle

6.3 状态机约束

只有 Idle 状态才允许接收新的 PCB 到位触发
系统进入 Faulted 后，不允许自动接收下一块板，必须在故障恢复后由人工复位或 PLC 复位解除
允许后台自动执行断线重连，但在 Faulted 未解除前不得恢复业务处理
每次开始新流程前必须清理上一板的过程结果位
Release 动作必须具备防重复发送保护

6.4 启动前置条件

系统只有在以下条件同时满足时，才视为处于可接板的 Idle 状态：

PLC 通信已建立
PlcReady = 1
AutoMode = 1
StationEnable = 1
上位机不存在未解除的 SystemFault

若上述条件不满足，上位机仅保持监视，不启动新板流程。

7. 详细流程说明

7.1 主流程

上位机轮询 PLC 到位点位
当检测到“到位”且当前状态为 Idle 时：
- 记录开始时间
- 置 Busy 位
- 清理上次结果位
- 写入当前流程状态码
- 进入扫码流程
扫码成功后，进入 SFTP 校验流程
根据 SFTP 结果决定立即放行或超时后放行
发送放行信号给 PLC
置流程完成位，并将最终结果码保持为稳定值
等待 PLC 应答或到位信号撤销
回到空闲状态

7.2 扫码流程

发送扫码枪触发指令
等待扫码结果，单次扫码应设置超时
对扫码结果进行基础清洗：去掉空白和控制字符
若成功：
- 保存二维码内容
- 清除 ScanNg
- 置 ScanOk
- 写入当前流程状态码
- 进入 SFTP 校验流程
若失败：
- 累加尝试次数
- 记录日志
- 若未达到最大尝试次数，则进入下一轮扫码
达到 3 次后仍失败：
- 清除 ScanOk
- 置 ScanNg
- 调用安灯报警
- 写入结果代码“扫码失败放行”
- 进入放行流程

说明：

ScanNg 表示最终扫码失败，不用于表示中间某一次扫码失败
当前版本“3 次”定义为总共最多 3 次尝试，不是“首次 1 次 + 额外重试 3 次”

7.3 SFTP 校验流程

按配置建立 SFTP 连接
根据二维码 ID 拼接目标文件名或查找规则
立即执行首次查询
若文件存在：
- 清除 FileNotFound
- 置 FileFound
- 写入结果代码“文件存在放行”
- 进入放行流程
若文件不存在：
- 记录当前查询未命中
- 若未达到重试上限，则等待 X 秒再次查询
- 若达到重试上限，则清除 FileFound、置 FileNotFound、写入结果代码“文件未找到超时放行”，进入放行流程
若出现 SFTP 连接失败、认证失败、目录不存在等系统级异常：
- 置 SystemFault
- 写入故障结果码
- 进入 Faulted

说明：

当前版本 MaxRetryCount = N 表示首次未命中后的最多重试次数
因此总查询次数为 1 + N
FileNotFound 表示最终未找到，不用于表示中间某次查询未命中

7.4 放行流程

上位机向 PLC 写入放行请求位 ReleasePermit
推荐采用脉冲方式输出放行信号，默认脉冲时长建议为 500ms，可配置
同时写入最终结果码、流程完成位和稳定的状态位
若 PLC 提供 PlcAckRelease：
- 上位机等待 PLC 应答
- 最长等待时间建议为 2000ms，超时则记录告警并自动清除放行脉冲
若 PLC 不提供 PlcAckRelease：
- 上位机保持 ReleasePermit 至配置脉冲时长结束后自动清除
ProcessDone = 1 时，表示 ResultCode、AlarmCode、ScanTryCount、SftpTryCount 均已为最终稳定值

8. Modbus TCP 通信设计

8.1 通信角色

上位机：Modbus TCP Client
PLC：Modbus TCP Server
轮询周期建议：100ms ~ 300ms
布尔量优先使用位点位，结果码优先使用 Holding Register

8.2 点位设计原则

输入点和输出点职责分离
只保留流程闭环必需的少量点位
详细错误原因由上位机日志与界面表达，不强依赖 PLC 点位细分
放行信号使用脉冲，忙碌位使用保持方式
本文档采用PLC -> 上位机为 Discrete Input、上位机 -> PLC 为 Coil 的常规表达方式；若现场 PLC 地址区定义不同，可在实施阶段做地址映射，不改变信号语义

8.3 PLC -> 上位机点位（建议）

以下点位由 PLC 提供，上位机读取：

序号	地址类型	地址	点位名称	方向	说明
1	Discrete Input	10001	PcbArrived	PLC -> PC	PCB 已到位，请求上位机处理
2	Discrete Input	10002	PlcReset	PLC -> PC	PLC 请求上位机清状态/复位
3	Discrete Input	10003	PlcAckRelease	PLC -> PC	PLC 已接收到放行信号，可选

说明：

PcbArrived 为本流程主触发点
PlcAckRelease 为可选应答点，若 PLC 侧不需要可取消
PlcReset 用于人工清故障、恢复空闲态或清除保持位
10004 ~ 10050 预留给后续 PLC -> 上位机扩展信号

8.4 上位机 -> PLC 点位（建议）

以下点位由上位机写入，PLC 读取：

序号	地址类型	地址	点位名称	方向	说明
1	Coil	00051	PcBusy	PC -> PLC	上位机正在处理当前 PCB
2	Coil	00052	ReleasePermit	PC -> PLC	放行脉冲信号

说明：

ReleasePermit 采用脉冲输出，不建议长时间保持
PcBusy = 1 表示当前板卡流程尚未结束
ResultCode 在流程进行中和结束后都可读取，不依赖额外完成位

8.5 结果寄存器设计（建议）

建议仅保留一个 Holding Register 表达最终结果。

序号	地址类型	地址	名称	说明
1	Holding Register	40001	ResultCode	本次最终结果代码

8.6 推荐结果代码定义

代码	含义
0	Idle / 无结果
1	处理中
10	扫码成功，文件存在，正常放行
20	本次处理结果 NG，但按规则放行
90	系统故障

8.7 点位清理策略

建议按如下规则清理点位：

新板开始前清理：PcBusy、ReleasePermit、ResultCode
流程处理中保持：PcBusy
放行时脉冲输出：ReleasePermit
流程结束后清理：PcBusy
故障恢复后在人工复位或 PlcReset 时清理 ResultCode

9. 串口扫码设计建议

9.1 配置项

建议配置以下参数：

串口号
波特率
数据位
校验位
停止位
单次扫码超时毫秒数
触发命令
结束符/返回报文规则

9.2 抽象接口建议

扫码服务建议统一为：

TriggerScanAsync()
返回 ScanResult

ScanResult 建议包含：

IsSuccess
Barcode
RawMessage
ErrorMessage
DurationMs

9.3 行为建议

串口打开失败时立即记录系统故障
每次扫码都必须单独设置超时
返回空字符串、格式错误或无结束符都视为失败
对扫码值仅做基础清洗，不额外加入未确认的业务规则

10. SFTP 文件查找设计建议

10.1 查找策略

建议支持以下任一方式，由配置指定：

完整文件名匹配
- 例如：${barcode}.txt
前缀/后缀匹配
- 例如：${barcode}_OK.xml
目录内模糊匹配
- 例如：包含二维码 ID 的文件名即视为命中

初版推荐采用完整文件名匹配，规则最清晰，误判概率最低。

10.2 条码到文件名映射

当前版本以清洗后的二维码字符串作为查询键
推荐默认文件名规则为：${barcode}.txt
实际文件名后缀或模板通过配置项 FileNamePattern 指定
若后续现场规则变更，可通过配置调整，不修改流程主逻辑

10.3 配置项

Host
Port
Username
Password 或私钥
RootPath
FileNamePattern
RetryIntervalSeconds
MaxRetryCount
ConnectTimeoutMs

10.4 行为建议

每次查询都要记录当前第几次尝试
若 SFTP 连接失败，应区分“连接失败”和“文件不存在”
对于连接失败、认证失败、目录错误，不按“文件不存在超时放行”处理，而按系统异常处理
若目录配置错误，应作为配置异常处理

11. 安灯 HTTP 接口设计建议

11.1 报警触发场景

当前版本建议至少在以下场景调用安灯接口：

扫码连续失败 3 次

后续可扩展场景：

SFTP 文件未找到超时
PLC 通信异常
串口设备离线

11.2 请求内容建议

建议请求体包含：

工位编码
工位名称
报警类型
报警编码
报警描述
二维码内容（若有）
触发时间
设备名/IP

11.3 报警代码建议

代码	含义
1001	扫码连续失败 3 次
1002	SFTP 文件超时未找到
1003	SFTP 连接异常
1004	串口设备异常
1005	PLC 通信异常

11.4 设计要求

HTTP 请求必须有超时控制
请求失败必须记录日志
若报警接口失败，不影响当前“放行”主流程，但需在日志和结果码中体现

12. 配置设计建议

建议在配置文件中划分如下配置节：

12.1 PlcOptions

IP 地址
端口
轮询周期
连接超时
点位地址映射
放行脉冲时长
放行应答超时时间

12.2 ScannerOptions

串口参数
触发命令
单次扫码超时
最大扫码次数（当前固定建议值为 3）

12.3 SftpOptions

服务器连接参数
根目录
文件匹配规则
重试等待秒数
最大重试次数

12.4 AndonOptions

是否启用
接口地址
请求方式
超时时间
工位编码
默认报警码映射

12.5 WorkflowOptions

启动前是否要求 PlcReady = 1
启动前是否要求自动模式
故障恢复后是否必须人工复位
日志保留天数

说明：

当前版本“扫码失败 3 次后放行”和“文件未找到超时后放行”属于固定业务规则，不作为普通配置开关
若未来需要改成拦截模式，应通过需求变更单独评审

13. UI 展示建议

当前系统虽为简化版，仍建议主界面至少展示以下信息：

PLC 连接状态
扫码枪连接状态
SFTP 连接状态
安灯接口状态
当前流程状态
当前二维码内容
扫码次数
SFTP 查询次数
当前结果描述
最近若干条运行日志

建议增加以下按钮：

手动复位
手动重连 PLC
手动重连扫码枪
测试安灯接口
打开配置

14. 异常处理策略

14.1 业务异常

业务异常指当前板流程内的可接受结果：

扫码失败 3 次
文件未找到超时

处理原则：

记录日志
写入明确结果码
当前版本仍放行

14.2 系统异常

系统异常指上位机自身能力不可用：

PLC 无法连接
串口打开失败
SFTP 配置缺失或无法认证
SFTP 根目录不存在
安灯接口配置错误