Files

yunxiao.zhu ce356bffff ✨ feat(*): 重构PCB放行流程并接入双扫码校验

- 将流程改为 OMRON FINS + TCP 双扫码 + SFTP 文件校验
- 新增文件校验与扫码结果汇总实现，补充对应单测
- 同步更新流程设计文档、配置和系统设置页面文案

2026-05-17 14:08:05 +08:00

28 KiB

Raw Blame History

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

1. 文档目的

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

当前定稿流程以 docs/正式的工作流程 为 PLC 与扫码枪通信依据，并保留旧流程设计中已经确认的 SFTP 文件校验、安灯报警、日志追溯和系统异常处理规则。

当前版本覆盖以下能力：

PLC 到位、复位、放行确认信号接入
上位机通过 OMRON FINS 读取和写入 PLC 点位
两把 TCP 扫码枪触发扫码
扫码结果汇总与条码选择
SFTP 文件存在性校验
PLC 放行信号回写
HTTP 安灯报警接口调用
关键过程日志与状态记录

本文档不包含以下能力：

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

2. 系统范围与边界

2.1 系统角色

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

PLC
- 通过 OMRON FINS 与上位机通信
- 提供 PCB 到位、复位、放行确认等状态
- 接收上位机忙碌、放行和最终结果信号
扫码枪1
- 通过 TCP Socket 与上位机通信
- 接收上位机触发扫描命令 T
- 返回二维码或条码字符串
扫码枪2
- 通过 TCP Socket 与上位机通信
- 接收上位机触发扫描命令 T
- 返回二维码或条码字符串
SFTP 服务器
- 用于存放与 PCB 二维码 ID 对应的判定文件或放行文件
- 上位机根据扫码结果访问指定目录并查找目标文件
安灯系统
- 通过 HTTP 接口接收报警请求
- 用于扫码失败等异常场景的现场告警
上位机软件
- 负责流程编排、设备通信、状态控制、日志记录、异常处理和 PLC 结果回写

2.2 运行约束

运行模式为单件串行处理。
同一时刻只处理一块 PCB。
PLC 与上位机之间使用 OMRON FINS。
上位机与扫码枪之间使用 TCP Socket。
两把扫码枪的触发命令均为 T。
扫码结果采用“任一成功即可”的规则进入 SFTP 校验。
两把扫码枪都成功但条码内容不一致时，优先使用扫码枪1条码，并记录不一致日志。
两把扫码枪均失败时，上位机调用安灯报警接口，并按 NG 放行。
SFTP 采用 1 次首次查询 + 最多 N 次重试 的方式检查目标文件。
SFTP 文件最终未找到时仍按 NG 放行，默认仅记录日志，不强制安灯报警。
SFTP 连接失败、认证失败、目录配置错误等系统级异常不等同于“文件不存在”，默认进入系统故障，不自动放行。

3. 系统通信结构

PLC <--FINS--> C# 上位机 <--TCP--> 扫码枪1
                               <--TCP--> 扫码枪2
                         <--SFTP--> SFTP 服务器
                         <--HTTP--> 安灯系统

3.1 PLC 与上位机

通信协议：OMRON FINS
上位机读取 PLC 点位
上位机写入 PLC 点位
PLC 负责提供到位、复位、放行确认信号
上位机负责写入忙碌、放行脉冲和最终结果码

3.2 上位机与扫码枪

通信协议：TCP Socket
扫码枪数量：2 把
发送触发命令：T
接收扫码结果：二维码或条码字符串
任一扫码枪返回有效条码即可继续后续 SFTP 校验

3.3 上位机与 SFTP

上位机根据最终选定条码拼接或匹配目标文件名
文件存在表示可以正常放行
文件未找到超时表示按 NG 放行
SFTP 系统异常表示上位机能力不可用，应进入系统故障

3.4 上位机与安灯

扫码失败时调用安灯报警接口
文件未找到报警保留为可配置扩展
安灯接口调用失败不阻断既定放行流程，但必须记录日志

4. PLC 通信点位定义

4.1 PLC -> 上位机（上位机读取）

地址	名称	类型	说明
D1001	PcbArrived	Bool	PCB 已到位，请求上位机处理
D1002	PlcReset	Bool	PLC 请求上位机清状态/复位
D1003	PlcAckRelease	Bool	PLC 已接收到放行信号，可选

预留点位：

地址范围	说明
D1004 ~ D1010	PLC -> 上位机扩展信号预留

说明：

PcbArrived 为本流程主触发点。
PlcReset 用于人工清故障、恢复空闲态或清除保持位。
PlcAckRelease 为可选应答点，若 PLC 侧不需要可取消。

4.2 上位机 -> PLC（上位机写入）

地址	名称	类型	说明
D1051	PcBusy	Bool	上位机正在处理当前 PCB
D1052	ReleasePermit	Bool	放行脉冲信号

说明：

PcBusy = 1 表示当前板卡流程尚未结束。
ReleasePermit 采用脉冲输出，不建议长时间保持。

4.3 结果寄存器（上位机写入）

地址	名称	类型	说明
D1100	ResultCode	Int	本次最终结果代码

4.4 ResultCode 定义

数值	含义
0	Idle
1	处理中
10	正常放行
20	NG 放行
90	系统故障

4.5 点位清理策略

新板开始时写入 D1051 PcBusy = 1、D1100 ResultCode = 1。
放行时写入 D1052 ReleasePermit = 1。
PLC 若启用放行确认，则上位机等待 D1003 PlcAckRelease = 1。
PLC 进入复位流程时写入 D1002 PlcReset = 1。
上位机收到复位后清理 D1051 PcBusy = 0、D1052 ReleasePermit = 0、D1100 ResultCode = 0。

5. 功能需求

5.1 到位触发

当 PCB 到达指定工位后，PLC 写入 D1001 PcbArrived = 1。
上位机通过 FINS 读取到位信号。
上位机在检测到到位信号后，启动本次单板处理流程。
上位机应避免同一块板被重复触发处理。

5.2 双扫码枪控制

上位机通过 TCP Socket 向扫码枪1发送 T。
上位机通过 TCP Socket 向扫码枪2发送 T。
两把扫码枪可以同时触发，也可以按实现限制依次触发，但同一块板必须汇总两路结果后再判定。
每把扫码枪都应具备独立连接、独立超时和独立错误日志。

5.3 扫码结果汇总

任一扫码枪返回有效条码，即视为扫码汇总成功。
仅扫码枪1成功时，使用扫码枪1条码进入 SFTP 校验。
仅扫码枪2成功时，使用扫码枪2条码进入 SFTP 校验。
两把扫码枪都成功且条码一致时，使用该条码进入 SFTP 校验。
两把扫码枪都成功但条码不一致时，优先使用扫码枪1条码进入 SFTP 校验，并记录扫码枪2条码和不一致日志。
两把扫码枪均失败时，视为本次扫码失败。

5.4 扫码失败处理

若两把扫码枪均未返回有效条码：
- 上位机调用 HTTP 安灯报警接口。
- 上位机记录两把扫码枪的失败原因和报警结果。
- 上位机写入 D1100 ResultCode = 20。
- 上位机仍向 PLC 发送放行信号。
- 本次流程结果标记为“扫码失败 NG 放行”。

5.5 SFTP 文件校验

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

5.6 文件未找到超时处理

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

5.7 二维码内容处理

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

5.8 日志与追溯

上位机应记录以下关键日志：

到位触发时间
扫码枪1触发、返回、超时、失败原因
扫码枪2触发、返回、超时、失败原因
双扫码枪汇总结果和最终选定条码
双扫码枪条码不一致时的两路原始条码
SFTP 连接与查找结果
HTTP 报警调用结果
PLC 点位写入动作
本次流程最终结果

6. 推荐总体方案

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

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

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

方案特点：

适合当前“单件串行”场景。
PLC 点位数量少，便于现场联调。
两把扫码枪提高扫码成功率。
SFTP 文件校验和安灯报警继续保持原业务位置。
后续可在不推翻主体结构的前提下扩展更多结果码、报警策略和 UI 状态展示。

7. 软件模块设计

7.1 流程控制模块

负责：

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

建议职责边界：

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

7.2 PLC FINS 通信模块

负责：

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

建议接口：

ReadSignalsAsync()：读取 D1001、D1002、D1003。
WriteProcessStateAsync()：写入 D1051、D1052、D1100。
PulseReleaseAsync()：发送放行脉冲。
ResetResultBitsAsync()：清理本次流程结果位。

7.3 TCP 扫码枪控制模块

负责：

管理扫码枪 TCP 连接。
发送扫码命令 T。
接收扫码返回值。
执行单把扫码枪的超时控制。
将扫码结果以统一对象返回给流程控制器。

建议每把扫码枪输出统一结果：

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

7.4 双扫码结果汇总模块

负责：

汇总扫码枪1和扫码枪2结果。
按“任一成功即可”规则判断是否进入 SFTP。
按“扫码枪1优先”规则处理双成功但内容不一致场景。
输出最终选定条码、两路原始结果和汇总说明。

7.5 SFTP 校验模块

负责：

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

建议支持的配置项：

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

7.6 安灯报警模块

负责：

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

建议支持的配置项：

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

7.7 日志与结果记录模块

负责：

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

建议记录字段：

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

8. 业务状态机设计

8.1 状态定义

建议定义以下流程状态：

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

8.2 状态流转

正常流转

Idle -> Triggered -> ScanningScanner1/ScanningScanner2 -> MergingScanResult -> CheckingSftp -> SftpPassed -> Releasing -> Completed -> Idle

扫码失败 NG 放行流转

Idle -> Triggered -> ScanningScanner1/ScanningScanner2 -> MergingScanResult -> ScanFailedReleased -> Releasing -> Completed -> Idle

文件未找到超时 NG 放行流转

Idle -> Triggered -> ScanningScanner1/ScanningScanner2 -> MergingScanResult -> CheckingSftp -> WaitingSftpRetry -> CheckingSftp -> ... -> SftpTimeoutReleased -> Releasing -> Completed -> Idle

系统故障流转

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

8.3 状态机约束

只有 Idle 状态才允许接收新的 PCB 到位触发。
系统进入 Faulted 后，不允许自动接收下一块板，必须在故障恢复后由人工复位或 PLC 复位解除。
允许后台自动执行断线重连，但在 Faulted 未解除前不得恢复业务处理。
每次开始新流程前必须清理上一板的过程结果位。
ReleasePermit 动作必须具备防重复发送保护。
两把扫码枪的单次失败不直接等同于本板失败，必须先执行汇总判定。

9. 详细流程说明

9.1 主流程

PLC 写入 D1001 PcbArrived = 1。
上位机通过 FINS 读取到位信号。
当检测到到位且当前状态为 Idle 时：
- 记录开始时间。
- 写入 D1051 PcBusy = 1。
- 写入 D1100 ResultCode = 1。
- 清理上次过程结果。
- 进入双扫码流程。
双扫码汇总成功后，进入 SFTP 校验流程。
根据 SFTP 结果决定正常放行、NG 放行或系统故障。
正常放行或 NG 放行时，写入最终 ResultCode 并发送 D1052 ReleasePermit = 1。
若启用 D1003 PlcAckRelease，上位机等待 PLC 放行确认。
PLC 写入 D1002 PlcReset = 1 后，上位机执行复位。
上位机写入 D1051 = 0、D1052 = 0、D1100 = 0，回到空闲状态。

9.2 双扫码流程

上位机向扫码枪1发送 TCP 命令 T。
上位机向扫码枪2发送 TCP 命令 T。
分别等待两把扫码枪返回，单把扫码枪应设置独立超时。
对两路扫码结果分别执行基础清洗：去掉空白和控制字符。
若仅一路成功：
- 保存成功条码为最终选定条码。
- 记录另一路失败原因。
- 进入 SFTP 校验流程。
若两路都成功且条码一致：
- 保存该条码为最终选定条码。
- 进入 SFTP 校验流程。
若两路都成功但条码不一致：
- 优先使用扫码枪1条码作为最终选定条码。
- 记录扫码枪1条码、扫码枪2条码和不一致说明。
- 进入 SFTP 校验流程。
若两路均失败：
- 调用安灯报警。
- 写入 D1100 ResultCode = 20。
- 进入放行流程。

9.3 SFTP 校验流程

按配置建立 SFTP 连接。
根据最终选定条码拼接目标文件名或查找规则。
立即执行首次查询。
若文件存在：
- 写入 D1100 ResultCode = 10。
- 进入放行流程。
若文件不存在：
- 记录当前查询未命中。
- 若未达到重试上限，则等待 X 秒再次查询。
- 若达到重试上限，则写入 D1100 ResultCode = 20，进入放行流程。
若出现 SFTP 连接失败、认证失败、目录不存在等系统级异常：
- 写入 D1100 ResultCode = 90。
- 进入 Faulted。

说明：

当前版本 MaxRetryCount = N 表示首次未命中后的最多重试次数。
因此总查询次数为 1 + N。
文件未找到是业务 NG，SFTP 不可用是系统故障，两者必须区分。

9.4 安灯报警流程

双扫码均失败时，上位机调用安灯报警接口。
报警内容应包含工位、报警编码、报警描述、扫码枪1失败原因、扫码枪2失败原因和触发时间。
安灯接口调用成功或失败都必须记录日志。
安灯接口失败不阻断扫码失败 NG 放行。
文件未找到超时是否报警保留为配置策略，默认不强制报警。

9.5 放行与复位流程

上位机写入最终 D1100 ResultCode：
- 10：正常放行。
- 20：NG 放行。
上位机写入 D1052 ReleasePermit = 1。
若 PLC 提供 D1003 PlcAckRelease：
- 上位机等待 PLC 应答。
- 超时则记录告警并按脉冲策略自动清除放行位。
若 PLC 不提供 D1003 PlcAckRelease：
- 上位机保持 ReleasePermit 至配置脉冲时长结束后自动清除。
PLC 写入 D1002 PlcReset = 1。
上位机执行复位：
- 写入 D1051 PcBusy = 0。
- 写入 D1052 ReleasePermit = 0。
- 写入 D1100 ResultCode = 0。

10. 工序流程图

flowchart TD

    A[PLC写入 D1001=PcbArrived=1]
    --> B[C#上位机通过FINS读取到位信号]

    B --> C[上位机写入 D1051=PcBusy=1]
    B --> D[上位机写入 D1100=1 处理中]

    D --> E[TCP发送 T 到扫码枪1]
    D --> F[TCP发送 T 到扫码枪2]

    E --> G[扫码枪1返回扫码结果]
    F --> H[扫码枪2返回扫码结果]

    G --> I[上位机汇总扫码结果]
    H --> I

    I --> J{是否至少一路扫码成功}

    J -->|是| K[选择最终条码]
    J -->|否| L[调用安灯报警]

    K --> M[SFTP查找对应文件]
    L --> N[写入 D1100=20 NG放行]

    M --> O{SFTP结果}
    O -->|文件存在| P[写入 D1100=10 正常放行]
    O -->|文件未找到超时| Q[写入 D1100=20 NG放行]
    O -->|系统异常| R[写入 D1100=90 系统故障]

    P --> S[写入 D1052=ReleasePermit=1]
    Q --> S
    N --> S

    S --> T[PLC收到放行信号]
    T --> U{是否启用确认信号}

    U -->|启用| V[PLC写入 D1003=PlcAckRelease=1]
    U -->|不启用| W[进入复位流程]

    V --> W
    W --> X[PLC写入 D1002=PlcReset=1]
    X --> Y[上位机执行复位]
    Y --> Z[写入 D1051=0, D1052=0, D1100=0 Idle]

    R --> AA[进入系统故障, 等待复位]

11. TCP 扫码枪通信设计

11.1 扫码枪1

发送

接收

二维码/条码字符串

11.2 扫码枪2

发送

接收

二维码/条码字符串

11.3 配置项

建议每把扫码枪配置以下参数：

名称
IP 地址
端口
连接超时毫秒数
读取超时毫秒数
触发命令，当前固定为 T
返回结束符或返回报文规则

11.4 行为建议

TCP 连接失败时记录该扫码枪失败原因。
单把扫码枪失败不直接判定整板失败，必须经过双扫码汇总。
两把扫码枪均失败才进入扫码失败安灯报警和 NG 放行。
返回空字符串或仅包含控制字符，视为该扫码枪失败。

12. SFTP 文件查找设计

12.1 查找策略

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

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

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

12.2 条码到文件名映射

当前版本以双扫码汇总后的最终选定条码作为查询键。
推荐默认文件名规则为：${barcode}.txt。
实际文件名后缀或模板通过配置项 FileNamePattern 指定。
若后续现场规则变更，可通过配置调整，不修改流程主逻辑。

12.3 行为要求

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

13. 安灯 HTTP 接口设计

13.1 报警触发场景

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

扫码枪1和扫码枪2均扫码失败

后续可扩展场景：

SFTP 文件未找到超时
PLC 通信异常
扫码枪设备离线

13.2 请求内容建议

建议请求体包含：

工位编码
工位名称
报警类型
报警编码
报警描述
扫码枪1失败原因
扫码枪2失败原因
二维码内容（若有）
触发时间
设备名/IP

13.3 报警代码建议

代码	含义
1001	两把扫码枪均扫码失败
1002	SFTP 文件超时未找到
1003	SFTP 连接异常
1004	扫码枪设备异常
1005	PLC 通信异常

13.4 设计要求

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

14. 配置设计建议

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

14.1 PlcOptions

PLC IP 地址
PLC 端口
FINS 网络号、节点号、单元号
轮询周期
连接超时
点位地址映射
放行脉冲时长
放行应答超时时间

14.2 ScannerOptions

扫码枪1 IP、端口、超时、触发命令
扫码枪2 IP、端口、超时、触发命令
返回结束符或报文规则
双扫码汇总策略

14.3 SftpOptions

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

14.4 AndonOptions

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

14.5 WorkflowOptions

故障恢复后是否必须人工复位
日志保留天数
放行确认是否启用
两把扫码枪是否并发触发

说明：

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

15. UI 展示建议

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

PLC 连接状态
扫码枪1连接状态
扫码枪2连接状态
SFTP 连接状态
安灯接口状态
当前流程状态
扫码枪1原始结果
扫码枪2原始结果
最终选定条码
SFTP 查询次数
当前结果描述
最近若干条运行日志

建议增加以下按钮：

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

16. 异常处理策略

16.1 业务异常

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

两把扫码枪均扫码失败
文件未找到超时

处理原则：

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

16.2 系统异常

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

PLC 无法连接
两把扫码枪 TCP 连接均不可用且被判定为设备异常
SFTP 配置缺失或无法认证
SFTP 根目录不存在
安灯接口配置错误