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

## 1. 文档目的

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

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

当前版本覆盖以下能力：

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

本文档不包含以下能力：

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

---

## 2. 系统范围与边界

### 2.1 系统角色

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

1. **PLC**
   - 通过 OMRON FINS 与上位机通信
   - 提供 PCB 到位、复位、放行确认等状态
   - 接收上位机忙碌、放行和最终结果信号

2. **扫码枪1**
   - 通过 TCP Socket 与上位机通信
   - 接收上位机触发扫描命令 `T`
   - 返回二维码或条码字符串

3. **扫码枪2**
   - 通过 TCP Socket 与上位机通信
   - 接收上位机触发扫描命令 `T`
   - 返回二维码或条码字符串

4. **SFTP 服务器**
   - 用于存放与 PCB 二维码 ID 对应的判定文件或放行文件
   - 上位机根据扫码结果访问指定目录并查找目标文件

5. **安灯系统**
   - 通过 HTTP 接口接收报警请求
   - 用于扫码失败等异常场景的现场告警

6. **上位机软件**
   - 负责流程编排、设备通信、状态控制、日志记录、异常处理和 PLC 结果回写

### 2.2 运行约束

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

---

## 3. 系统通信结构

```text
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 状态定义

建议定义以下流程状态：

1. **Idle**：空闲，等待 PLC 到位
2. **Triggered**：接收到到位信号，准备启动流程
3. **ScanningScanner1**：正在触发扫码枪1
4. **ScanningScanner2**：正在触发扫码枪2
5. **MergingScanResult**：正在汇总双扫码结果
6. **ScanFailedReleased**：双扫码均失败，已报警并决定 NG 放行
7. **CheckingSftp**：正在检查 SFTP 文件是否存在
8. **WaitingSftpRetry**：文件未找到，等待下一次轮询
9. **SftpPassed**：文件找到，允许正常放行
10. **SftpTimeoutReleased**：文件未找到超时，决定 NG 放行
11. **Releasing**：向 PLC 发送放行信号
12. **Completed**：本次流程结束
13. **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 主流程

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

### 9.2 双扫码流程

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

### 9.3 SFTP 校验流程

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

说明：

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

### 9.4 安灯报警流程

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

### 9.5 放行与复位流程

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

---

## 10. 工序流程图

```mermaid
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

#### 发送

```text
T
```

#### 接收

```text
二维码/条码字符串
```

### 11.2 扫码枪2

#### 发送

```text
T
```

#### 接收

```text
二维码/条码字符串
```

### 11.3 配置项

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

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

### 11.4 行为建议

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

---

## 12. SFTP 文件查找设计

### 12.1 查找策略

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

1. **完整文件名匹配**
   - 例如：`${barcode}.txt`
2. **前缀/后缀匹配**
   - 例如：`${barcode}_OK.xml`
3. **目录内模糊匹配**
   - 例如：包含二维码 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 根目录不存在
- 安灯接口配置错误

处理原则：

- 写入故障结果码 `90`。
- 日志详细记录异常上下文。
- 进入 `Faulted`。
- 故障恢复后需人工复位或 PLC 复位后方可重新接板。

### 16.3 防重入要求

- 流程执行中必须禁止重复触发新板流程。
- 放行写入必须有一次性保护。
- SFTP 查询不得并发重复执行。
- 报警接口同一事件只发送一次。
- PLC 复位前不得自动清除最终结果码。

---

## 17. 日志与追溯要求

### 17.1 日志级别建议

- `Info`：流程开始、扫码成功、SFTP 命中、放行完成、PLC 复位完成。
- `Warning`：单把扫码枪失败、两把扫码枪条码不一致、文件未找到等待重试、报警接口失败、放行应答超时。
- `Error`：PLC/扫码枪/SFTP/HTTP 调用异常、配置异常。

### 17.2 单板结果摘要建议

每块 PCB 建议形成一条结果记录，包含：

- 流水时间戳
- 扫码枪1原始条码
- 扫码枪2原始条码
- 最终选定条码
- SFTP 查询次数
- 最终结果码
- 最终结果描述
- 是否放行
- 是否报警
- 异常摘要

---

## 18. 联调与验收建议

### 18.1 联调顺序建议

1. 先打通 PLC FINS 基础读写。
2. 再联调扫码枪1 TCP 触发。
3. 再联调扫码枪2 TCP 触发。
4. 再联调双扫码结果汇总。
5. 再联调 SFTP 文件查找。
6. 再联调安灯 HTTP 接口。
7. 最后做整流程串联测试。

### 18.2 关键测试场景

1. PLC 到位，扫码枪1成功，扫码枪2成功且条码一致，SFTP 一次命中，正常放行。
2. PLC 到位，仅扫码枪1成功，SFTP 命中，正常放行。
3. PLC 到位，仅扫码枪2成功，SFTP 命中，正常放行。
4. PLC 到位，两把扫码枪都成功但条码不一致，优先使用扫码枪1条码，SFTP 命中，正常放行并记录不一致日志。
5. PLC 到位，两把扫码枪均失败，安灯报警成功，最终 NG 放行。
6. PLC 到位，扫码成功，SFTP 多次未命中，超时后 NG 放行。
7. PLC 到位，扫码成功，但 SFTP 连接异常，系统进入故障，禁止自动放行。
8. 安灯接口调用失败，但扫码失败场景仍按既定规则 NG 放行，并有异常日志。
9. 流程处理中重复收到到位信号，不允许重复触发。
10. PLC 写入 `D1002 PlcReset = 1` 后，上位机正确清除 `D1051`、`D1052`、`D1100`。

### 18.3 验收重点

- 是否稳定识别 `D1001 PcbArrived` 到位触发。
- 是否正确写入 `D1051 PcBusy`。
- 是否正确触发两把 TCP 扫码枪并发送 `T`。
- 是否按“任一成功即可”规则进入 SFTP。
- 是否在双成功不一致时优先使用扫码枪1。
- 是否按配置进行 SFTP 首次查询和后续 N 次重试。
- 是否在规定场景下正确写入 `D1100 ResultCode`。
- 是否正确输出 `D1052 ReleasePermit`。
- 是否正确处理 `D1003 PlcAckRelease` 和 `D1002 PlcReset`。
- 是否正确触发安灯报警。
- 是否正确区分“文件未找到”和“SFTP 系统异常”。
- 是否具备清晰日志和结果码追溯能力。

---

## 19. 与旧设计差异摘要

### 19.1 已调整内容

- PLC 通信由旧设计中的 Modbus TCP 调整为 OMRON FINS。
- PLC 地址由旧设计中的线圈、离散输入、保持寄存器表达，调整为 `D1001`、`D1051`、`D1100` 系列点位。
- 扫码枪由旧设计中的单把串口扫码枪，调整为两把 TCP Socket 扫码枪。
- 扫码触发命令由可配置串口触发命令，调整为当前流程固定命令 `T`。
- 扫码成功规则由单扫码结果，调整为双扫码汇总后“任一成功即可”。
- 双扫码都成功但内容不一致时，采用“优先扫码枪1并记录日志”的规则。
- 最终 PLC 结果码收敛为 `0`、`1`、`10`、`20`、`90`。

### 19.2 继续保留内容

- SFTP 文件校验仍保留在扫码成功之后、放行之前。
- 安灯报警仍保留在扫码失败位置。
- 文件未找到超时仍按业务 NG 放行。
- SFTP 连接、认证、目录等系统异常仍进入系统故障。
- 安灯接口失败不阻断既定放行流程。
- 关键日志、单板结果追溯和异常分级处理继续保留。

---

## 20. 最终结论

当前项目适合采用**单工位串行状态机 + OMRON FINS + 双 TCP 扫码枪 + SFTP 文件校验 + HTTP 安灯报警**的轻量化上位机方案。

该方案具备以下特点：

- 与当前定稿通信流程匹配。
- PLC 点位少，易联调。
- 双扫码枪提高扫码成功率。
- SFTP 与安灯继续保持原业务位置，不丢失既有流程约束。
- 能满足“扫码失败 NG 放行”和“文件未找到超时 NG 放行”的业务要求。
- 对 SFTP 系统异常与普通文件未命中进行了明确区分。
- 具备后续扩展为更完整目检系统的演进空间。