# 物流地磅采集程序 1.4.0

1.4.0 改进：RTSP 保持视频连接，合并摄像头任务领取请求，上传后直接回传网页，减少连接与轮询等待。

1.3.0 新增“摄像头同步测试”：无需地磅、无需进仓单，可在 ERP 网页点击测试拍照，由 Windows 抓拍上传。测试照片仅由相同 ERP 账号、相同商家查看，服务器临时保留15分钟；不写入业务重量、入库附件或本机称重队列。

1.2.0 已增加 ERP 实时重量与人工拍照：网页先显示地磅重量，确认稳定后由员工点击“拍照并保存重量”；Windows 在后台读取串口、抓拍并上传。同一流程可在电脑、手机和平板使用。尚未连接地磅时显示未连接，不能生成称重记录；摄像头可单独测试。

海康 HK-H3S4M-P（固件 V6.0.3 build 260616）已在 JackNepair 测试 Windows 使用 1.1.0 的同一 RTSP 解码组件实际出图，2560×1440。连续5次冷启动抓拍全部成功，平均1.151秒，范围1.146–1.154秒（从启动解码进程到收到完整 JPEG，不含 ERP 上传和页面刷新）。真实 COM 地磅尚未连接，称重全流程硬件验收待现场接线。JackNepair 不是物流现场电脑。未向生产 ERP 写入测试记录；摄像头画面日期未校准，以采集电脑时间及 ERP 接收时间留档。

这是连接现场设备与新版物流 ERP 的 Windows 程序。Windows 用网线上网，地磅通过 COM / USB 转串口连接电脑，海康摄像头与 Windows 在可互通的局域网内。手机、平板可以使用其他 Wi-Fi 或移动数据，通过日本服务器上的 ERP 发起任务和查看结果，无需与现场电脑同网段。

程序不开放本机 HTTP 服务，不需要公网摄像头地址、端口转发或公网访问现场电脑。采集程序主动通过 HTTPS 访问新版 ERP。

## 安装与准备

1. 在现场 64 位 Windows 电脑下载并完整解压便携包，启动 `WarehouseCollector.exe`。包内包含 .NET 和 RTSP 运行环境，无需安装 Python、视频插件或开发工具；无需管理员权限。**请保留 exe 旁的 `rtsp-runtime` 文件夹，不要单独复制 exe。**目标是 Windows 10/11 x64，Windows 真机启动与串口驱动需现场验证。
2. 用新版 ERP 员工账号登录。管理员分配的商家项目和仓库范围同时生效；若需首次修改密码，先在 ERP 网页完成。ERP 密码不保存；每次启动需登录，会话失效后重新登录并重试队列。
3. 打开“设备设置”，为采集站取一个便于现场辨认的名称，如“一号地磅”。
4. 按 Windows 设备管理器与仪表实际设置填写 COM、波特率、数据位、校验位、停止位。初始显示的 9600 / 8N1 **不是对 X80 默认参数的确认**。
5. 填写摄像头局域网地址（例如 `http://192.168.1.64`）、账号和密码。这只海康选择“RTSP（海康 HK-H3S4M-P）”，端口 `554`，视频路径 `/Streaming/Channels/101`。已经激活的设备无需重新激活；摄像头须正常供电且与电脑互通，避免 IP 冲突。
6. 点击“测试抓拍”，成功后显示真实画面。仅测试摄像头时无需 ERP 登录或连接地磅，测试照片只在本机预览，不上传、不生成业务记录。地磅接好后再点击“连接地磅”核对重量。

升级：退出旧版，将新版解压到新文件夹后启动；当前 Windows 用户的加密设置和待上传队列继续保留。旧设置默认采用“自动”，HTTP 接口明确不支持时转为 RTSP；可直接选 RTSP，省去一次 HTTP 请求。不要删除 `%LOCALAPPDATA%\WarehouseCollector`。

程序未做商业代码签名。若现场 Windows 的安全策略限制启动，请由现场 IT 核对来源和 SHA-256，并按公司的软件审批流程部署；不要关闭杀毒或证书校验。

## 地磅与摄像头支持范围

- 本版称重采集支持用户提供的《X80计重仪表串行协议(1).pdf》中的 tF=0 / tF=5 ASCII 输出。仅接受仪表标记为 `ST`（稳定）、`GS`（毛重）的正数重量。
- 至少连续三个有效采样、稳定一秒才允许人工点击拍照；数据超过1.5秒未更新、状态变化或抓拍过程中重量变化，均不生成记录。净重、皮重、超载、零值、负值不回填毛重。
- 原始串口报文、原始单位及数值同时留档；kg / g / t / lb 换算为 kg，ERP 保存到0.001 kg，采用四舍五入。最终适用单位仍需与现场仪表配置核对。
- 默认仅监听串口。tF=0 的“RG 毛重查询”可选，每500毫秒请求一次；可配置两位仪表地址。不发送置零、去皮、单位切换命令。
- `diagnostic` 只显示接收到的原始十六进制数据。其他 tF 协议不据重复数值猜测稳定状态。若现场输出格式不符，先留样再适配。
- 照片上的 XHL-3 是大显示屏，PDF 是 X80 仪表协议。仪表和大屏是否共用输出口仍待核实；不要自行拆分串口线或切换 tF 破坏大屏显示。
- 支持三种抓拍方式：RTSP、HTTP 图片接口、自动。RTSP 保持 TCP 视频连接，只在收到拍照指令后编码新画面，不复用上次照片、不保存连续录像或音频；等待新画面15秒上限，断流、超时或取消会结束解码进程并在后续重连；图片最大10MB、2400万像素。密码仅通过进程内的匿名管道传给解码器，不进入命令行、日志、网址配置或临时文件。
- 自动模式只在 HTTP 明确报告接口不存在、不支持或路径参数不兼容时转 RTSP。HTTP 401 或普通权限错误不会继续尝试另一种认证。HTTP Digest 接口默认 `/ISAPI/Streaming/channels/1/picture`；HTTPS 也支持 Basic，证书须有效，不跟随重定向。
- HK-H3S4M-P 已实测通道101为 H.265，RTSP 可用。当前画面自带日期不准确，正式使用前由现场校准摄像头及电脑时钟。抓拍期间必须持续收到同一稳定重量；保存照片时采用最新有效串口采样，任何重量变化、数据中断或超时均不生成成功记录。

## 不接地磅，先从 ERP 网页测试摄像头

1. 运行1.4.0采集器，使用现有ERP账号登录，选择需要测试的商家，并保持实时同步选项勾选。摄像头沿用“设备设置”中的配置；无需点击“连接地磅”。
2. 手机、Mac或Windows浏览器打开 [摄像头同步测试](https://warehouse-logistics.yukong.top/warehouse-device-test)，使用与采集器相同的ERP账号，选择相同商家及采集站。作业台和称重卡片也有此入口。
3. 点击“测试拍照并上传”，网页显示等待、抓拍上传、完成或失败。正常完成后显示现场真实照片和接收时间；页面未刷新时也会显示从点击到照片展示的耗时。
4. 照片仅作设备测试，临时保留15分钟，服务重启也会清除；不绑定进仓单，不需要重量，不影响库存。正式称重仍要求地磅稳定正毛重，不能用测试照片代替称重记录。
5. 为避免同时使用摄像头，同一采集站的测试和正式称重任务相互排队。测试超时或程序退出后中断的任务不会重复自动抓拍，请重新点击测试。

## Windows 上发起

1. ERP 中先完成到仓登记，生成可称重的进仓单。只有预约、尚未到仓的单据不直接称重。
2. 在程序选择商家，扫描进仓编号或货品二维码，也可以搜索列表选择单据。
3. 选择“整单”或具体箱号的“分箱”。整单表示这张进仓单的全部货物一起上磅；不能把一箱当整单。
4. 将对应货物放上地磅并保持稳定。核对实时重量后点击“拍照并保存重量”，照片附带商家、进仓单、箱号、重量、采集站、电脑时间及采集编号水印。
5. 每次点击只采集一次；下一箱重新选择箱号并确认实时重量，点击拍照。重量变化或数据中断会使本次失败，需重新核对后再拍。

## ERP 网页发起（电脑 / 手机 / 平板）

1. Windows 程序登录，选择对应商家，连接地磅并配置好摄像头；保持勾选“同步当前商家的实时重量，并接收 ERP 拍照指令”。
2. 手机扫描货品二维码，点击“员工称重 / 作业（需登录）”，或在作业台打开进仓单。
3. 在“地磅称重与抓拍”中选择现场采集站、整单或箱号。将本单货物上磅，网页自动更新实时重量；仅稳定正毛重允许拍照。
4. 核对重量后点击“拍照并保存重量”。Windows 收到指令立即检查重量是否仍一致，再抓拍；页面自动刷新结果，可查看照片。任务有效期30秒，同一采集站一次只处理一个任务。稳定本身不会触发拍照。网页请求结果不确定时，“确认上次拍照请求”沿用同一编号，不重复生成任务。
5. Windows 只同步当前商家。约每秒上传最新重量；网页约每秒读取，预览最多3秒有效，过期即停用拍照。电脑时钟需准确。切换商家后新心跳会替换原项目在线状态，最迟45秒过期。Windows 关机、休眠、程序退出或网络中断时，手机任务无法采集。请保持 Windows 程序运行并避免工作期间休眠。
6. 取消的远程任务不能被后来补传的数据自动写成成功。程序重启后发现已领取但未留存照片的任务，会标为中断，要求核对货物后重新发起。

## 保存、重试与 ERP 毛重

- 重量和 JPEG 照片先作为同一记录写入本机，再作为同一次请求上传。只有收到匹配的 ERP 回执后才移入“已上传”目录。断网、超时重试沿用同一采集编号，不重复入账。
- 原商家、进仓单、箱号和采集员工固定在本机记录中。切换项目或登录另一员工，不会把待上传记录改绑；须由原员工登录同一 ERP 补传。
- 整单记录在单据版本未变化时自动回填毛重；单据已修改时只保留称重证据，需在 ERP 点击“采用此毛重”。
- 分箱记录分别保存，不自动覆盖整单毛重。ERP 核对箱号数量与到货箱数、一箱一号且全部已称重后，才能采用各箱最新重量合计。
- 称重不会自动完成质检或入库。毛重发生变化后，按现有流程重新核对质检。
- 最多允许离线30天，保留原始采集时间和服务器接收时间。已入库、已取消、权限已撤销、照片校验失败或关联信息变化时，保留本机记录并显示需处理，不自动改绑或丢弃。
- 队列中有红色提示时，先解决账号、权限或单据问题，再点“重试待上传”。会话过期需重新登录。普通网络错误自动退避重试。
- 本机记录目录：`%LOCALAPPDATA%\WarehouseCollector\records`，含 `pending`、`sent`、`staging`。使用“打开本机记录”查看；未上传的目录不要删除。照片总量达到2GB时暂停新增，先按公司要求归档已上传目录。
- `settings.protected` 使用 Windows DPAPI 按当前用户加密，包含摄像头密码；不要复制到其他用户或电脑。ERP 密码不在该文件中。

## 现场验收

1. 核对仪表型号、输出口、串口参数和 tF 模式，读到的重量与显示值一致；保留一次原始串口样本。
2. 空磅、负值、抖动、净重、超载和断开串口均不能生成称重成功记录；稳定正毛重可以生成。
3. 摄像头账号错误、地址错误、断电或返回登录页时不能生成假照片；真实照片能辨认货物与称重区域。
4. Windows 发起一次整单称重，核对 ERP 商家、进仓单、毛重、照片和操作员工。
5. 手机使用移动数据发起一次任务，核对 Windows 收到正确商家和箱号；再验证取消和重复点击不产生串单。
6. 选定进仓单后断开 Windows 外网，称重留存本机；恢复网络后仅上传一次。关闭并重启程序后原待上传记录仍在。
7. 两箱分别称重，核对合计；故意漏一箱时不能采用合计。单据修改或入库后补传须提示复核。

## 开发与验证

源代码位于 `windows-collector/Core`、`App`、`Checks`、`rtsp`。使用 .NET 10 SDK；Windows 包为 `win-x64` self-contained，NuGet 依赖固定并有锁文件。打包脚本使用 Python 3.11+，固定官方 CPython 3.14.9、PyAV 19.0.2 Windows x64 文件并核对 SHA-256；完整保留 PyAV 自带 DLL 和许可证。

```sh
dotnet build windows-collector/App/Collector.App.csproj -c Release
dotnet run --project windows-collector/Checks/Collector.Checks.csproj -c Release
dotnet publish windows-collector/App/Collector.App.csproj -c Release -r win-x64 --self-contained true -p:RestoreLockedMode=true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:DebugType=None -o windows-collector/dist/win-x64
python3 windows-collector/package.py --cache tmp/collector-dependencies
npm run check
npm test
```

`scripts/collector-test-server.js` 可启动隔离的 localhost 模拟 ERP，并把一次性测试描述写入命令行指定的临时文件。将该文件路径传给 Checks 可验证手机任务、客户端登录、商家权限、multipart 上传及重复请求。它只创建临时合成数据，不连接生产存储。

验证范围：隔离 ERP 的实时预览、人工任务、重量变化/过期拒绝、商家权限、照片与重量原子上传及幂等重试；C# 核心包含串口稳定窗口与 RTSP 进程失败、超时、取消检查。Windows 1.1.0 实机启动、嵌入式解码与摄像头测试已通过。1.2.0 原生启动、配置继承、断开地磅按钮禁用和真实摄像头抓拍已在 JackNepair 通过。1.3.0 网页到 Windows 的实机往返及真实 COM 联调须以最新测试报告为准。macOS 可设置 `COLLECTOR_TEST_PYTHON` 为可信 Python 可执行文件运行额外8项进程边界检查；不设置时跳过这些检查。

参考：

- 用户提供的 X80 串口协议，第1–4页 tF=0/5、状态字与毛重查询；其余协议的稳定标志及校验能力不推断。
- [海康官方 RTSP 路径说明](https://supportusa.hikvision.com/support/solutions/articles/17000129022-do-you-have-an-example-showing-the-format-for-getting-a-rtsp-stream-from-a-camera-)；[PyAV 官方安装说明](https://pyav.basswood.io/docs/stable/overview/installation.html)。
- [Microsoft SerialPort](https://learn.microsoft.com/dotnet/api/system.io.ports.serialport)、[Windows 跨平台编译](https://learn.microsoft.com/en-us/dotnet/core/tools/sdk-errors/netsdk1100)。

维护启动通道：受信任的启动器可用 `--login-stdin` 通过匿名标准输入管道传入 origin、username、password，由程序调用既有 HTTPS 登录接口，然后显示已登录的主窗口。仅匹配当前已配置 ERP 域名；输入限4KB、10秒，使用后丢弃，不写配置、文件、命令行或环境。正常双击仍使用原登录方式。该通道不新增权限、不绕过服务器账号策略，也不开放本机网络端口。
