356 lines
14 KiB
Markdown
356 lines
14 KiB
Markdown
# FATrace.OEMApp 软件使用手册（SOP）
|
||
|
||
## 1. 文档说明
|
||
|
||
### 1.1 适用范围
|
||
|
||
- 本手册适用于 FATrace.OEMApp（WinForms 客户端）。
|
||
- 该客户端用于：接收“内袋二维码/条码”触发事件，调用海康 NVR 按时间段下载录像文件，保存到本地/NAS，并将视频文件与条码信息写入数据库，提供历史查询与播放。
|
||
|
||
### 1.2 目标读者
|
||
|
||
- 产线操作人员：负责扫码触发、查看任务状态、核对视频保存结果。
|
||
- 追溯/质量人员：负责历史查询与视频回放。
|
||
- IT 运维：负责安装部署、网络与设备连通性、配置项维护、日志排查与数据清理策略。
|
||
|
||
### 1.3 术语与口径
|
||
|
||
- NVR：海康网络录像机（通过海康 SDK 登录并下载录像）。
|
||
- 内袋二维码/条码：来自产线/外部系统的条码字符串；系统会解析出原料编号、批号、重量、保质期、产地、日产量等字段（解析规则见第 8 章）。
|
||
- 下载任务：系统将一次“回溯录像下载请求”持久化为 `DownloadTask`，并由后台队列顺序执行。
|
||
- 历史记录：数据库表 `OEMRawUse`，用于追溯条码对应的视频文件路径、名称与创建时间等。
|
||
- NAS：本系统将视频保存路径配置为网络盘/共享盘（例如 `Y:`），用于长期留存。
|
||
|
||
## 2. 系统概述
|
||
|
||
FATrace.OEMApp 的核心流程为：
|
||
|
||
1. 接收条码（PLC 扫码或 TCP 客户端发送）；
|
||
2. 解析条码得到业务字段；
|
||
3. 生成下载任务 `DownloadTask` 并入队；
|
||
4. 后台 `DownloadTaskWorker` 按顺序执行：
|
||
- 根据配置的 NVR 账号登录状态，从 NVR 按时间范围下载录像
|
||
- 将视频保存到 `NVRVideoSavePath` 指定目录（支持盘符/网络盘）
|
||
- 下载成功后写入 `OEMRawUse`（视频文件路径、视频名、条码信息等）
|
||
- 可选：生成 CSV（`RawUseCsvPath`）
|
||
5. 历史页可查询 `OEMRawUse` 并双击播放视频。
|
||
|
||
## 3. 运行环境与依赖
|
||
|
||
### 3.1 操作系统
|
||
|
||
- Windows 10/11。
|
||
|
||
### 3.2 网络与外设
|
||
|
||
- SQL Server 数据库（用于存储任务与追溯索引）。
|
||
- 海康 NVR（IP/端口/账号/密码在配置中）。
|
||
- 视频保存目录（本地磁盘或 NAS 网络盘，如 `Y:`）。
|
||
-（可选）PLC/基恩士：用于从寄存器读取扫码结果。
|
||
-（可选）TCP 客户端（如 PDA/中间件）：向 OEMApp 内置 TCP Server 发送扫码文本。
|
||
|
||
### 3.3 关键组件（实现层面）
|
||
|
||
- 数据库：FreeSql + SQL Server Provider（自动同步表结构已启用）。
|
||
- 海康 SDK：CHCNetSDK（程序启动后输出 SDK 日志到 `C:\SdkLog\`）。
|
||
- 视频播放：LibVLCSharp（VideoView）。
|
||
- TCP Server：TouchSocket（多客户端）。
|
||
- PLC 通信：HslCommunication（KeyenceMcNet）。
|
||
- 日志：NLog（错误日志 + 操作日志）。
|
||
- CSV：CsvHelper（导出单条 CSV）。
|
||
-（可选）Jellyfin：RestSharp 客户端与监控服务（当前主流程标记为停用）。
|
||
|
||
## 4. 安装与部署（IT 运维）
|
||
|
||
### 4.1 部署方式
|
||
|
||
- 使用发布后的程序目录（含 exe、dll、`App.config`、`NLog.config`、VideoLAN.LibVLC 等依赖）。
|
||
- 建议将程序目录放置在非系统盘且具备写权限的位置（日志目录在程序目录下生成）。
|
||
|
||
### 4.2 单实例限制
|
||
|
||
- 程序启动会检测单实例：若已运行会提示“程序已运行，不能再次打开！”。
|
||
|
||
### 4.3 授权提示
|
||
|
||
- 程序启动会进行授权校验；失败时提示“授权失败！当前程序只能使用8小时！”。
|
||
|
||
### 4.4 首次启动检查清单
|
||
|
||
- 数据库连通性：确认 `App.config` 中 `connecting` 正确，且 SQL Server 可访问。
|
||
- NVR 可达：确认 `NVRIP` / `NVRPort` 可 ping 通，端口可达。
|
||
- 视频保存盘符：确认 `NVRVideoSavePath` 盘符存在且可写（如为网络盘需先映射）。
|
||
- SDK 日志目录：`C:\SdkLog\` 可创建且可写（建议提前创建目录并赋权）。
|
||
|
||
## 5. 配置说明（App.config）
|
||
|
||
文件位置：`FATrace.OEMApp/App.config`
|
||
|
||
### 5.1 数据库连接
|
||
|
||
- `connecting`：SQL Server 主库连接字符串（OEMApp 实际使用该键）。
|
||
- `connecting1` / `RemoteConnecting`：保留项，是否使用取决于现场版本。
|
||
|
||
### 5.2 PLC 配置
|
||
|
||
- `PLCIP`：PLC IP
|
||
- `PLCPort`：PLC 端口
|
||
- `PLCScan`：扫描周期（毫秒），默认 600
|
||
- `PDAScanCode`：PLC 内保存扫码字符串的寄存器地址（例如 `D1000`）
|
||
|
||
### 5.3 TCP Server（外部扫码接入）
|
||
|
||
- `TcpServerIp`：OEMApp 内置 TCP Server 监听 IP
|
||
- `TcpServerPort`：OEMApp 内置 TCP Server 监听端口
|
||
|
||
### 5.4 下载任务与回溯时长
|
||
|
||
- `VideoTime`：下载时长（秒），默认 30。系统会下载 `[NvrStartTime, NvrEndTime]` 时间窗。
|
||
- `DownloadTaskMaxRetry`：失败重试次数上限（程序重启后会将未超过次数的 Failed 重置为 Pending）。
|
||
- `DownloadTaskTimeoutSeconds`：单任务下载超时时间（秒）。若未配置，系统会按“时间窗*3”并限制到 `[120,1800]` 计算。
|
||
|
||
### 5.5 NVR 配置
|
||
|
||
- `NVRIP`：NVR IP
|
||
- `NVRPort`：NVR 端口（通常 8000）
|
||
- `NVRUserName`：NVR 登录用户名
|
||
- `NVRPw`：NVR 登录密码
|
||
- `NVRVideoSavePath`：视频保存根路径（支持本地盘符或网络盘符，如 `Y:`）
|
||
|
||
### 5.6 数据清理策略
|
||
|
||
- `VideoFileSaveDay`：视频文件保留天数（用于清理 DownloadTask 关联的视频文件）
|
||
- `DbSaveDay`：数据库记录保留天数（用于清理 DownloadTask/OEMRawUse/VideoAction 等旧记录）
|
||
- `DataCleanupEnabled`：是否启用定时清理（默认 true）
|
||
- `DataCleanupTimeOfDay`：每日执行时间（默认 02:00:00）
|
||
|
||
### 5.7 CSV 导出
|
||
|
||
- `RawUseCsvPath`：CSV 保存目录（如 `D:\TestData`）
|
||
|
||
### 5.8 Jellyfin（可选/当前停用）
|
||
|
||
- `JellyfinBaseUrl` / `JellyfinApiKey` / `JellyfinParentId` / `JellyfinPollIntervalMs` / `JellyfinPollMaxWaitMs`
|
||
|
||
## 6. 日志与目录说明
|
||
|
||
### 6.1 NLog 日志
|
||
|
||
文件：`FATrace.OEMApp/NLog.config`
|
||
|
||
- 错误日志：`程序目录\Log\yyyy-MM-dd\ErrorMessage.txt`
|
||
- 操作日志：`程序目录\OperationLogs\yyyy-MM-dd\OperationLog.txt`
|
||
- 默认保留 60 天（`maxArchiveDays=60`）
|
||
|
||
### 6.2 海康 SDK 日志
|
||
|
||
- 程序启动时启用 SDK 日志输出到：`C:\SdkLog\`
|
||
- 建议 IT 运维定期清理该目录，避免长期占用磁盘。
|
||
|
||
## 7. 界面结构与功能入口
|
||
|
||
### 7.1 左侧导航栏
|
||
|
||
- 主界面：显示扫码信息、任务队列状态、日志列表、CSV 保存状态等。
|
||
- 历史记录：查询 `OEMRawUse` 并播放对应视频。
|
||
- 设置：预留页（当前可用于放置 NVR 登录、下载进度等相关操作）。
|
||
|
||
### 7.2 顶部/底部状态栏
|
||
|
||
- Plc连接状态：来自 `PLCDataService`（若未启用 PLC，此状态可能不准确或保持默认）。
|
||
- 服务连接状态：数据库连通性检测（`SELECT 1`）。
|
||
- NAS连接状态：检测 `NVRVideoSavePath` 目录是否存在。
|
||
- NVR连接状态：检测 NVR 登录态与在线状态。
|
||
|
||
## 8. 条码格式与解析规则（重要）
|
||
|
||
系统条码解析由 `FATrace.Com.NVRCom.ParseCodeFull(code)` 实现。
|
||
|
||
### 8.1 支持的分隔符
|
||
|
||
- 支持英文逗号 `,`
|
||
- 支持中文逗号 `，`
|
||
- 支持分号 `;` / `；`
|
||
- 支持空格分隔
|
||
|
||
### 8.2 推荐条码字段结构（按顺序）
|
||
|
||
1. RawCode：原料编号
|
||
2. Batch：批号（通常为 8 位日期 `yyyyMMdd`；系统会提取前 8 位数字）
|
||
3. Weight：重量（3/4 位数字，最后 1 位为小数位，例如 `802 => 80.2`）
|
||
4. ShelfLifeMonths：保质期（月）
|
||
5. RegionCode：产地编码（`01=国内`，`02=日本`，其他=未知）
|
||
6. Count：日产量序号
|
||
|
||
### 8.3 视频文件命名规则
|
||
|
||
- 视频文件路径：`NVRVideoSavePath\{Code}.mp4`（会清洗非法文件名字符）
|
||
- 视频名称：`{Code}.mp4`
|
||
|
||
## 9. 日常操作 SOP（产线/追溯人员）
|
||
|
||
### 9.1 开机前检查（每日/每班）
|
||
|
||
1. 启动 OEMApp。
|
||
2. 查看底部状态栏：
|
||
- 服务连接状态：应为“正常”
|
||
- NAS连接状态：应为“正常”（表示视频保存目录存在）
|
||
- NVR连接状态：应为“正常”（表示 NVR 已登录且在线）
|
||
3. 若异常，按第 12 章排查。
|
||
|
||
### 9.2 NVR 登录
|
||
|
||
- 主界面启动时会自动调用登录（NVRLogin），也可使用“设置页/登录按钮”手动登录（btnNVRLogin）。
|
||
- 登录成功会弹窗“登录成功”。
|
||
- 登录失败会弹窗“登录失败：{错误信息}”。
|
||
|
||
### 9.3 扫码触发（两种方式）
|
||
|
||
#### 方式 A：TCP Server 接入（推荐用于外部设备/中间件）
|
||
|
||
1. OEMApp 启动后会读取配置 `TcpServerIp` / `TcpServerPort` 并启动 `TouchSocketServer`。
|
||
2. 外部客户端连接后发送条码字符串（UTF-8 文本）。
|
||
3. OEMApp 接收后会：
|
||
- 解析条码并填充界面（内袋二维码、原料编号等）
|
||
- 调用 `DownloadTaskWorker.Enqueue` 创建下载任务并入队
|
||
- 向客户端回复“OK”
|
||
|
||
#### 方式 B：PLC 扫码（若现场启用 PLCDataService）
|
||
|
||
1. `PLCDataService` 会按 `PLCScan` 周期从 `PDAScanCode` 地址读取字符串。
|
||
2. 读取到新值后触发 `ScanCodeEventHandler`。
|
||
3. OEMApp 会解析条码并入队下载任务。
|
||
|
||
### 9.4 下载任务执行与监控
|
||
|
||
- 下载队列服务：`DownloadTaskWorker.Instance.Start(HkCameraClient)`
|
||
- 执行模型：单线程顺序下载（同一时刻只有一个任务 Running）。
|
||
- 主界面显示：
|
||
- `DownloadFileName`：显示当前下载文件名
|
||
- `DownloadProgressBarMain`：显示下载进度（来自海康 SDK 回调）
|
||
- `gridRULog`：展示任务列表（时间、类型、条码、任务Id、状态、进度、备注）
|
||
|
||
### 9.5 暂停下载
|
||
|
||
- 点击“停止下载/暂停”（btnStopLoadVideo 或 btnRawStopLoadVideo）会调用 `Sdk_NET_DVR_StopGetFile`。
|
||
- 注意：暂停会导致当前任务失败或中断，后续可依赖重试策略重新下载。
|
||
|
||
### 9.6 任务完成后的结果
|
||
|
||
下载成功后系统会：
|
||
|
||
- 在视频保存目录生成视频文件（例如 `Y:\{Code}.mp4`）。
|
||
- 在数据库表 `OEMRawUse` 写入一条记录：
|
||
- InBagCode、RawName、RawCode、User
|
||
- VideoStartTime、VideoEndTime
|
||
- VideoFilePath、VideoName
|
||
- 在主界面/日志中提示下载完成。
|
||
|
||
### 9.7 CSV 文件生成（可选）
|
||
|
||
- 系统在 `SaveCsvForTaskAsync` 中会为任务生成 `RawUseCsvDto`，并调用 `CsvService.ExportSingle` 导出 CSV。
|
||
- CSV 输出目录：`RawUseCsvPath`
|
||
- 文件名：`{InBagCode}.csv`（若条码含非法字符会被替换）
|
||
- 主界面“CSV文件生成状态”会提示成功/失败路径。
|
||
|
||
### 9.8 历史查询与视频播放
|
||
|
||
1. 点击左侧“历史记录”。
|
||
2. 输入查询条件：
|
||
- 关键字：支持 InBagCode/RawCode/RawName 模糊匹配
|
||
- 日期范围：按 CreateTime 过滤（起始日 00:00:00 到结束日次日 00:00:00）
|
||
3. 点击查询（btnHistoryVideoSearch）。
|
||
4. 双击表格行播放对应视频（从 `OEMRawUse.VideoFilePath` 读取）。
|
||
5. 点击“停止播放”（btnStopHistoryPlay）停止当前播放。
|
||
|
||
## 10. 数据表口径（追溯/IT）
|
||
|
||
- `DownloadTask`：下载任务表（队列持久化）
|
||
- Status：Pending/Running/Completed/Failed
|
||
- TryCount：尝试次数
|
||
- VideoFilePath：目标保存路径
|
||
- Error：失败原因
|
||
- `OEMRawUse`：追溯索引表（历史记录页数据源）
|
||
- `VideoAction` / `JellyfinMonitorTask`：历史遗留/扩展表（定时清理会涉及）
|
||
|
||
## 11. 定时清理策略（IT 运维）
|
||
|
||
`TimeClearDataService` 每日按配置时间执行：
|
||
|
||
- 先按 `VideoFileSaveDay` 删除 `DownloadTask` 关联的视频文件；
|
||
- 再按 `DbSaveDay` 删除 `DownloadTask` / `JellyfinMonitorTask` / `OEMRawUse` / `VideoAction` 等旧记录；
|
||
- 删除数据库记录前会再次尽力删除关联文件，避免“库删了文件还在”。
|
||
|
||
运维建议：
|
||
|
||
- 若视频文件非常大，建议将 `VideoFileSaveDay` 与 `DbSaveDay` 分开设置。
|
||
- 若需要永久留存视频，请将 `VideoFileSaveDay` 设置为较大值，并确保 NAS 容量与备份策略。
|
||
|
||
## 12. 常见问题与排查（FAQ/故障处理）
|
||
|
||
### 12.1 底部“服务连接状态：异常”
|
||
|
||
- 原因：SQL Server 不可达、连接字符串错误、账号权限不足。
|
||
- 处理：
|
||
1. 检查 `App.config` 的 `connecting`。
|
||
2. 检查数据库服务是否启动、网络是否可达。
|
||
3. 查看错误日志 `ErrorMessage.txt`。
|
||
|
||
### 12.2 “NVR连接状态：异常”或登录失败
|
||
|
||
- 原因：NVRIP/NVRPort 不通、账号密码错误、NVR 离线、海康 SDK 环境/依赖缺失。
|
||
- 处理：
|
||
1. Ping `NVRIP` 并确认端口可达（8000）。
|
||
2. 核对 `NVRUserName` / `NVRPw`。
|
||
3. 查看 `C:\SdkLog\` 与 NLog 错误日志。
|
||
|
||
### 12.3 “NAS连接状态：异常”
|
||
|
||
- 原因：`NVRVideoSavePath` 不存在、网络盘未映射、权限不足。
|
||
- 处理：
|
||
1. 在资源管理器确认该盘符/目录存在并可创建文件。
|
||
2. 若为网络共享，确认映射在“运行 OEMApp 的同一账号”下可用。
|
||
3. 建议使用固定盘符映射并设置开机自动重连。
|
||
|
||
### 12.4 扫码后无任务入队/无反应
|
||
|
||
- TCP 方式：
|
||
1. 确认 `TcpServerIp` / `TcpServerPort` 配置正确。
|
||
2. 确认防火墙放行端口。
|
||
3. 查看操作日志是否有“客户端连接/接收数据”。
|
||
- PLC 方式：
|
||
1. 检查 `PLCIP` / `PLCPort` / `PDAScanCode`。
|
||
2. 检查 PLC 是否正确写入字符串。
|
||
|
||
### 12.5 下载任务一直 Pending
|
||
|
||
- 可能原因：任务的 `NvrEndTime` 还未到（系统会等待 `NvrEndTime < Now+5 秒` 才取出执行）。
|
||
- 处理：等待数秒后观察；或检查系统时间是否正确。
|
||
|
||
### 12.6 下载失败/超时
|
||
|
||
- 原因：网络抖动、NVR 负载高、录像文件不可用、保存路径不可写。
|
||
- 处理：
|
||
1. 检查视频保存路径是否可写。
|
||
2. 检查 NVR 登录与在线。
|
||
3. 适当增大 `DownloadTaskTimeoutSeconds`。
|
||
4. 查看 `DownloadTask.Error` 与 `ErrorMessage.txt`。
|
||
|
||
### 12.7 历史记录能查到但播放失败
|
||
|
||
- 原因：视频文件被清理、路径变更、盘符未映射。
|
||
- 处理：
|
||
1. 按 `VideoFilePath` 检查文件是否存在。
|
||
2. 检查 NAS 映射与权限。
|
||
3. 如文件已被清理，需调整 `VideoFileSaveDay` 或备份策略。
|
||
|
||
## 13. 安全与合规建议
|
||
|
||
- 不建议在现场明文传播数据库 sa 密码；建议使用最小权限账号。
|
||
- 建议对 NAS 目录做访问控制，防止误删/篡改。
|
||
- 建议定期备份数据库与关键视频目录。
|
||
|
||
## 14. 版本记录
|
||
|
||
- V1.0：OEMApp 初版 SOP（安装/配置/扫码触发下载/历史播放/CSV/定时清理/故障排查）
|