单一窗口报关单与配套单证整合采集程序

用途
1. 递归监控官方“单一窗口导入客户端”的报关单数据订阅推送 InBox。
2. 只读取 XML/ZIP 并上传到 https://crossdocflow.com，不移动、不删除、不修改官方客户端文件。
3. 本地按文件哈希记录上传结果；网络中断后自动重试，重复文件不会重复生成报关单。
4. 使用同一份配置取得当前主体缺失的委托报关协议和无纸化放行通知书，通过官方单一窗口页面采集后自动上传。
5. 已有手工上传有效单证的报关单不会下发采集任务，上传前服务器会再次检查并禁止覆盖。

准备
1. 在系统“报关单管理 > 单一窗口自动同步”中，选择企业主体并创建同步客户端。
2. 立即复制客户端编号和一次性密钥。
3. 下载本程序和示例配置，把示例配置改名为 customs-declaration-sync-agent.json。
4. 填写 source_id、token 和官方客户端实际 InBox 路径。
5. Windows 电脑需安装 Python 3.9 或更高版本。只同步XML/ZIP时无需第三方包。
6. 使用单证一键采集前执行：pip install playwright，并确保已安装Edge、电子口岸控件和操作员卡驱动。
7. 把 single_window_url 设为实际使用的“货物申报-综合查询-报关数据查询”页面地址。

先测试
python customs-declaration-sync-agent.py --config customs-declaration-sync-agent.json --test

扫描一次
python customs-declaration-sync-agent.py --config customs-declaration-sync-agent.json --once

持续运行
python customs-declaration-sync-agent.py --config customs-declaration-sync-agent.json

只补齐缺失委托协议和放行通知书
python customs-declaration-sync-agent.py --config customs-declaration-sync-agent.json --documents-only

先用一张报关单校准官方页面
python customs-declaration-sync-agent.py --config customs-declaration-sync-agent.json --documents-only --limit 1

启动时先补单证，然后继续监控XML/ZIP
python customs-declaration-sync-agent.py --config customs-declaration-sync-agent.json --collect-documents

双击一键采集
将 run-single-window-supporting-document-agent.bat 与原采集程序、原配置文件放在同一文件夹，双击后只补齐缺失单证。

首次单证采集
- 程序打开独立Edge用户目录，请使用该配置绑定主体的操作员卡登录。
- 进入报关数据查询页后，程序按缺失清单查询、下载并上传。
- 卡PIN、单一窗口Cookie和证书不会上传到本系统。
- 各地页面控件不同时，single-window-failures 会保存失败截图，供首次校准。

文件说明
- customs-declaration-sync-agent.db：本地去重和重试状态。
- customs-declaration-sync-agent.log：运行日志，不记录密钥。

正式使用前，请先用官方客户端收到的一份真实 XML/ZIP 做字段核对。没有新报关单时，连接测试成功即可保持运行；以后 InBox 出现新文件会自动上传。