✨ feat(file-check): 忽略无效扫码结果并完善汇报材料

docs/纯plan.md

@@ -0,0 +1,682 @@
+# 欧姆龙 PLC PCB 条码文件判定系统项目计划
+
+## 1. 项目目标
+
+开发一个 Windows WinForms 上位机程序，实现：
+
+1. 通过 FINS/TCP 与欧姆龙 PLC 通信。
+2. 等待 PLC 发出 PCB 到位信号。
+3. 同时触发两把 TCP Server 扫描枪。
+4. 两把扫描枪分别扫描 PCB 正面和反面，任意一把返回有效条码即可。
+5. 根据条码检查本地目录中的 `<条码>.txt` 文件。
+6. 将检查结果返回 PLC。
+7. 通过 WinForms 界面显示 PLC、扫描枪、文件检查和当前任务状态。
+8. 对通信超时、断线、重复触发和异常情况进行处理并记录日志。
+
+## 2. 当前需求基线
+
+### PLC 通信
+
+| 项目 | 配置 |
+|---|---|
+| 协议 | Omron FINS/TCP |
+| PLC IP | `192.168.2.100` |
+| 端口 | `9600` |
+| UnitAddress | `0` |
+| SourceNodeAddress | `0` |
+| EndianFormat | `ABCD` |
+| PLC 区域 | D 区 |
+
+### PLC 点位
+
+| 名称 | 地址 | 类型 | 初步用途 |
+|---|---:|---|---|
+| PcbArrived | D101 | Bool | PCB 到位信号 |
+| PlcReset | D102 | Bool | PLC 复位本轮流程 |
+| PlcAckRelease | D103 | Bool | PLC 确认放行结果 |
+| PcBusy | D51 | Bool | 上位机忙碌状态 |
+| ReleasePermit | D52 | Bool | 是否允许放行 |
+| ResultCode | D401 | Word | 扫描和文件检查结果 |
+
+初版按 D 区字值 `0/1` 处理 Bool：
+
+```text
+0 = False
+1 = True
+```
+
+如果 PLC 实际使用 `D101.00` 这类 bit 位，需要在开发前调整 FINS 读写实现。
+
+### 扫描枪
+
+| 项目 | 扫描枪 1 | 扫描枪 2 |
+|---|---|---|
+| IP | `192.168.2.13` | `192.168.2.14` |
+| 端口 | `2001` | `2001` |
+| 设备角色 | PCB 正面 | PCB 反面 |
+| 通信模式 | TCP Server | TCP Server |
+| 上位机角色 | TCP Client | TCP Client |
+| 触发指令 | `T` | `T` |
+| 返回结束符 | 无 | 无 |
+| 超时时间 | 2000 ms | 2000 ms |
+
+### 文件检查
+
+```text
+根目录：D:\test
+文件规则：D:\test\<条码>.txt
+```
+
+例如条码为：
+
+```text
+PCB202608040001
+```
+
+检查文件：
+
+```text
+D:\test\PCB202608040001.txt
+```
+
+## 3. 业务流程
+
+```mermaid
+flowchart TD
+    A["等待 D101 到位信号"] --> B{"D101 是否为 True"}
+    B -- 否 --> A
+    B -- 是 --> C["生成任务号并锁存本轮触发"]
+    C --> D["写入 D51 = 1，进入扫描中"]
+    D --> E["并行连接两把扫描枪并发送 T"]
+    E --> F{"是否收到有效条码"}
+    F -- 是 --> G["记录第一条有效条码"]
+    F -- 否且未超时 --> E
+    F -- 超时 --> H["写入扫描超时结果"]
+    G --> I["检查 D:\\test\\条码.txt"]
+    I --> J{"文件是否存在"}
+    J -- 是 --> K["D401 写入通过结果，D52 = 1"]
+    J -- 否 --> L["D401 写入不通过结果，D52 = 0"]
+    K --> M["等待 PLC 确认或复位"]
+    L --> M
+    H --> M
+    M --> N{"D102 PlcReset 是否为 True"}
+    N -- 否 --> M
+    N -- 是 --> O["清除 D51、D52 和本轮结果"]
+    O --> P["等待 D101 恢复 False"]
+    P --> A
+```
+
+## 4. 详细握手策略
+
+### 等待到位
+
+- 程序持续读取 `D101`。
+- `D101=True` 时只创建一次任务。
+- 在本轮任务结束前，即使 `D101` 一直保持 True，也不能重复触发扫描。
+- 程序重启时，如果发现 `D101` 已经为 True，默认不立即重复处理，等待 PLC 先复位到 False。
+
+### 扫描阶段
+
+- 设置 `D51=1`。
+- 两把扫描枪并行发送 `T`。
+- 任意一把返回非空条码后结束等待。
+- 另一把扫描枪的迟到结果记录为本轮无效数据，不参与下一轮。
+- 两把扫描枪都无返回时，2000 ms 后判定扫描超时。
+
+### 文件判断阶段
+
+- 对条码进行去除空白、长度检查和非法文件名字符检查。
+- 禁止条码产生 `..`、路径分隔符或越过 `D:\test` 的路径。
+- 使用精确路径检查 `<根目录>\<条码>.txt`。
+- 文件存在即判定为允许放行。
+- 文件不存在即判定为不允许放行。
+
+### 结果保持阶段
+
+- `D401` 结果写入后保持。
+- 文件存在时 `D52=1`。
+- 文件不存在或扫描失败时 `D52=0`。
+- `D51` 在本轮任务期间保持为 1。
+- 收到 `D102=True` 后清除本轮输出。
+- `D103` 用于记录 PLC 是否确认放行结果；其是否作为必须等待的条件，需要 PLC 程序最终确认。
+
+## 5. 建议结果编码
+
+结果编码必须最终与 PLC 程序确认，建议如下：
+
+| ResultCode | 含义 |
+|---:|---|
+| 0 | 空闲 |
+| 1 | 扫描中 |
+| 2 | 文件存在，允许放行 |
+| 3 | 文件不存在，不允许放行 |
+| 4 | 两把扫描枪均超时 |
+| 5 | 扫描枪通信异常 |
+| 6 | 条码为空或格式错误 |
+| 7 | PLC 通信异常 |
+| 8 | PLC 复位 |
+| 9 | 系统异常 |
+
+建议 `ReleasePermit` 只表达一个含义：
+
+```text
+D52 = 1：允许放行
+D52 = 0：不允许放行
+```
+
+具体 `ResultCode` 用于区分“不存在文件”“扫描超时”“通信异常”等原因。
+
+## 6. 系统架构
+
+建议采用分层结构：
+
+```text
+src/
+  PcbCheck.Desktop/
+  PcbCheck.Application/
+  PcbCheck.Domain/
+  PcbCheck.Devices/
+  PcbCheck.Infrastructure/
+
+tests/
+  PcbCheck.Tests/
+  PcbCheck.IntegrationTests/
+
+docs/
+  architecture.md
+  plc-protocol.md
+  scanner-protocol.md
+  deployment.md
+  acceptance-checklist.md
+```
+
+### PcbCheck.Desktop
+
+负责：
+
+- WinForms 窗体
+- 当前状态显示
+- 设备连接状态显示
+- 当前条码显示
+- 文件检查结果显示
+- 任务耗时和最近结果显示
+- 错误提示
+- 手动连接、断开和复位操作
+
+界面层不能直接拼装 FINS 报文或操作 TCP 流。
+
+### PcbCheck.Application
+
+负责：
+
+- PCB 检测流程编排
+- PLC 到位触发处理
+- 双扫描枪并行扫描
+- 条码选择策略
+- 文件检查调用
+- PLC 结果写回
+- 超时和异常状态处理
+- 任务去重和复位控制
+
+核心流程建议命名为：
+
+```text
+PcbInspectionWorkflow
+```
+
+### PcbCheck.Domain
+
+负责：
+
+- 任务状态
+- 设备状态
+- 扫描结果
+- 文件检查结果
+- PLC 结果编码
+- 业务异常类型
+
+该层不引用 WinForms、TCP、FINS、文件系统或第三方 SDK。
+
+### PcbCheck.Devices
+
+负责：
+
+- FINS/TCP PLC 客户端
+- TCP 扫描枪客户端
+- Fake PLC
+- Fake 扫描枪
+- 设备连接状态和重连机制
+
+建议接口：
+
+```text
+IFinsPlcClient
+ITcpScannerClient
+IIndustrialDevice
+```
+
+### PcbCheck.Infrastructure
+
+负责：
+
+- 本地文件检查
+- 配置加载
+- 日志
+- 任务记录
+- 文件路径安全校验
+- 系统时间和基础设施封装
+
+## 7. 扫描枪无结束符处理方案
+
+扫描枪返回不带结束符，不能简单地认为一次 TCP `Receive` 就是一条完整条码，因为 TCP 可能出现：
+
+- 一条报文拆成多次接收；
+- 多条报文合并接收；
+- 返回后保持连接不断开。
+
+因此开发前必须确认扫描枪的实际行为：
+
+### 优先方案
+
+扫描枪返回条码后主动关闭本次 TCP 连接。程序读取到连接关闭即认为一条数据完成。
+
+### 备用方案
+
+如果扫描枪保持长连接，则使用：
+
+- 最大报文长度限制；
+- 接收缓冲区；
+- 字节间空闲超时；
+- 2000 ms 总超时；
+- 收到数据后短暂等待后判定报文结束。
+
+该参数需要配置化，不能写死在界面代码中。
+
+## 8. WinForms 界面计划
+
+### 设备状态区
+
+显示：
+
+- PLC：已连接、连接中、断开、故障
+- 扫描枪 1：已连接、断开、超时
+- 扫描枪 2：已连接、断开、超时
+- 本地目录：存在、不可访问
+
+### 当前任务区
+
+显示：
+
+- 当前流程状态
+- 当前任务号
+- PCB 到位状态
+- 当前条码
+- 条码来源：正面/反面
+- 文件完整路径
+- 文件是否存在
+- ResultCode
+- ReleasePermit
+- 本轮耗时
+
+### 统计区
+
+显示：
+
+- 总扫描数
+- 通过数量
+- 不通过数量
+- 扫描超时数量
+- 扫描枪通信异常数量
+- PLC 通信异常数量
+- 最近一次任务时间
+
+### 操作区
+
+建议提供：
+
+- 连接设备
+- 断开设备
+- 清除报警
+- 手动复位
+- 打开日志目录
+- 打开文件根目录
+- 进入配置页面
+
+手动写 PLC 点位的功能应限制权限，避免普通操作员误操作生产信号。
+
+## 9. 配置文件计划
+
+所有通信参数和业务参数放入配置文件，不硬编码在程序中。
+
+```json
+{
+  "Plc": {
+    "Host": "192.168.2.100",
+    "Port": 9600,
+    "UnitAddress": 0,
+    "SourceNodeAddress": 0,
+    "EndianFormat": "ABCD",
+    "MemoryArea": "D",
+    "Inputs": {
+      "PcbArrived": 101,
+      "PlcReset": 102,
+      "PlcAckRelease": 103
+    },
+    "Outputs": {
+      "PcBusy": 51,
+      "ReleasePermit": 52
+    },
+    "Registers": {
+      "ResultCode": 401
+    }
+  },
+  "Scanners": [
+    {
+      "Name": "FrontScanner",
+      "Host": "192.168.2.13",
+      "Port": 2001,
+      "Trigger": "T",
+      "TimeoutMs": 2000,
+      "Encoding": "ASCII"
+    },
+    {
+      "Name": "BackScanner",
+      "Host": "192.168.2.14",
+      "Port": 2001,
+      "Trigger": "T",
+      "TimeoutMs": 2000,
+      "Encoding": "ASCII"
+    }
+  ],
+  "FileCheck": {
+    "RootPath": "D:\\test",
+    "FileNamePattern": "{Barcode}.txt",
+    "IgnoreCase": false
+  },
+  "Workflow": {
+    "WaitPlcReset": true,
+    "RequireReleaseAck": false,
+    "ClearResultAfterReset": true
+  }
+}
+```
+
+`RequireReleaseAck` 在 PLC 握手确认后再决定是否启用，默认关闭。
+
+## 10. 日志要求
+
+每一轮 PCB 任务生成唯一任务号，日志至少记录：
+
+- 任务号
+- 开始时间和结束时间
+- PLC 地址和读写结果
+- 到位信号变化
+- 两把扫描枪触发内容
+- 两把扫描枪原始返回内容
+- 选中的条码和来源设备
+- 文件检查路径和结果
+- ResultCode
+- ReleasePermit
+- PlcAckRelease
+- PlcReset
+- 每个步骤耗时
+- 异常消息和通信错误
+
+日志按日期滚动保存，例如：
+
+```text
+logs\
+  2026-08-04\
+    application.log
+    communication.log
+    task.log
+```
+
+## 11. 异常和恢复策略
+
+### PLC 断线
+
+- 状态显示为 PLC 断开。
+- 停止触发扫描。
+- 进入自动重连。
+- 重连成功后重新读取当前状态。
+- 不重复执行已经完成的任务。
+
+### 扫描枪断线
+
+- 单把扫描枪断线时，仍允许另一把扫描枪继续工作。
+- 两把均断线时，任务判定为通信异常。
+- 支持自动重连。
+- 记录具体设备名称和异常原因。
+
+### PLC 到位信号长时间保持
+
+- 通过任务状态和任务锁避免重复触发。
+- 本轮流程未复位前不再次发送 `T`。
+- 复位后要求 `D101` 先恢复 False，再允许下一轮触发。
+
+### 文件目录不可访问
+
+- 不判定为普通“文件不存在”。
+- 返回独立的系统异常码。
+- 界面显示目录访问错误。
+- 日志记录完整路径和系统异常。
+
+### 程序重启
+
+- 启动时先连接 PLC 和扫描枪。
+- 如果 `D101=True`，默认等待 PLC 复位，不自动重扫。
+- 如果存在上一次未完成任务，记录为中断任务，不自动伪造结果。
+
+## 12. 开发阶段
+
+### 阶段一：需求和协议确认
+
+确认：
+
+- D 区 Bool 是字值 0/1 还是 bit；
+- `D103 PlcAckRelease` 的真实含义；
+- `D102 PlcReset` 的触发和清除时序；
+- `D401` 结果编码；
+- 扫描枪返回后是否断开 TCP；
+- 扫描枪编码格式；
+- 条码最大长度和合法字符；
+- 两把枪同时返回时的处理规则。
+
+交付物：
+
+- PLC 点位表
+- PLC 握手时序图
+- 扫描枪报文说明
+- 结果编码表
+- 文件规则说明
+
+### 阶段二：项目骨架
+
+实现：
+
+- WinForms 工程
+- 分层项目结构
+- 配置加载
+- 日志系统
+- 依赖注入
+- 领域状态和结果模型
+- 基础状态界面
+
+### 阶段三：FINS/TCP 通信
+
+实现：
+
+- FINS/TCP 连接
+- D 区 Bool 读取
+- D 区 Bool 写入
+- D401 结果写入
+- 连接超时
+- 读写超时
+- 断线重连
+- 原始通信日志
+- Fake PLC 测试实现
+
+### 阶段四：双扫描枪通信
+
+实现：
+
+- 两个 TCP Client
+- 自动连接和重连
+- 同时发送 `T`
+- 无结束符报文接收
+- 2000 ms 超时
+- 首个有效结果选择
+- 空结果和异常处理
+- Fake 扫描枪测试实现
+
+### 阶段五：文件检查和流程编排
+
+实现：
+
+- 条码清洗
+- 文件名安全校验
+- `D:\test\<条码>.txt` 精确检查
+- PLC 信号与扫描枪流程串联
+- 结果保持
+- PLC 复位
+- 任务去重
+- 异常恢复
+
+### 阶段六：WinForms 状态界面
+
+实现：
+
+- PLC 状态
+- 两把扫描枪状态
+- 文件目录状态
+- 当前任务显示
+- 结果和统计显示
+- 日志查看入口
+- 报警显示
+- 手动复位和连接控制
+
+### 阶段七：测试和交付
+
+实现：
+
+- 单元测试
+- Fake 设备流程测试
+- 通信异常测试
+- 现场联调
+- 发布包
+- 配置模板
+- 操作说明书
+- 维护说明书
+- 验收记录
+
+## 13. 测试计划
+
+### 单元测试
+
+覆盖：
+
+- ResultCode 映射
+- 文件路径拼接
+- 条码非法字符校验
+- 文件存在和不存在
+- D101 长保持防重复
+- PLC 复位流程
+- 扫描超时
+- 首个有效条码选择
+- 两把扫描枪同时返回
+- 连接断开和重连
+
+### 协议测试
+
+覆盖：
+
+- FINS/TCP 建连
+- D 区读取
+- D 区写入
+- D401 数值写入
+- ABCD 字节序
+- 错误响应
+- 超时响应
+- PLC 断电重连
+
+### 模拟流程测试
+
+覆盖：
+
+1. 正常扫描，文件存在。
+2. 正常扫描，文件不存在。
+3. 正面扫描成功，反面无结果。
+4. 反面扫描成功，正面无结果。
+5. 两把均无结果。
+6. 一把断线，另一把成功。
+7. 两把均断线。
+8. D101 长时间保持 True。
+9. 扫描过程中收到 D102。
+10. PLC 结果确认。
+11. 程序重启时 D101 为 True。
+12. 文件目录不存在或无权限。
+
+### 现场测试
+
+硬件测试必须在现场或真实设备环境中执行，模拟测试不能替代现场验收。
+
+现场至少验证：
+
+- PLC 实际 IP 和 FINS 节点；
+- D 区真实点位；
+- 真实 Bool 表达方式；
+- 真实扫描枪触发报文；
+- 真实返回报文边界；
+- 两把扫描枪同时触发；
+- PLC 复位和放行确认；
+- 连续生产 30～60 个 PCB 的稳定性。
+
+## 14. 交付标准
+
+满足以下条件才算完成：
+
+- Release 构建成功。
+- 单元测试全部通过。
+- Fake PLC 和 Fake 扫描枪流程测试通过。
+- 所有设备操作均有超时和取消机制。
+- UI 线程无阻塞通信。
+- PLC 断线能够显示并重连。
+- 扫描枪断线能够显示并恢复。
+- D101 长保持不会重复扫描。
+- 文件检查路径不可越界。
+- 结果能够正确保持和复位。
+- 日志能够定位每一轮任务。
+- 配置文件不包含硬编码生产密码。
+- 完成真实 PLC、扫描枪和本地目录现场验收。
+
+## 15. 预计开发周期
+
+在 PLC 和扫描枪可及时提供测试的前提下：
+
+| 阶段 | 预计时间 |
+|---|---:|
+| 需求和协议确认 | 0.5～1 天 |
+| 项目骨架和配置 | 0.5～1 天 |
+| FINS/TCP 通信 | 1～2 天 |
+| 双扫描枪通信 | 1～2 天 |
+| 流程和文件判断 | 1 天 |
+| WinForms 界面 | 1～2 天 |
+| 测试和修复 | 1～2 天 |
+| 现场联调 | 1～2 天 |
+
+预计开发周期为 6～10 个工作日，现场联调时间取决于 PLC 点位、扫描枪协议和设备可用情况。
+
+## 16. 当前开发门槛
+
+正式编写现场通信代码前，必须最终确认：
+
+1. D101、D102、D103、D51、D52 是否使用 D 字的 0/1。
+2. 扫描枪返回后是否主动断开 TCP。
+3. `D401` 的正式结果编码。
+4. `D103 PlcAckRelease` 的正式握手含义。
+5. 文件不存在时是否直接结束，还是继续等待另一把扫描枪。
+6. PLC 程序是否要求 `D51`、`D52` 和 `D401` 保持到 `D102` 复位。
+7. 真实条码编码和最大长度。
+
+本计划采用设备接口隔离、后台异步通信、超时与重连、Fake 设备测试和真实设备验收分离的方式，便于先完成可测试的软件闭环，再进行现场通信确认。