1、立项原因是出口锂电池包装（UN3480 等）的申报环节长期依靠人工在产线工位机与海关单一窗口之间来回搬运数据：扫码、拍照、组包、随附单据分散在多个工位，纸质台账和 Excel 并存。一旦海关下发图片抽核指令或退单，很难快速定位是哪一箱、哪张图出的问题，合规留痕和事后追溯的成本极高。本项目的立项目标就是把这套分散流程沉淀成一台后台服务器上的可追溯系统。
2、行业场景属于跨境贸易与出口危险货物包装申报（企业服务与智能硬件产线）。业务背景是海关要求出口锂电包装逐箱留痕、随附各面外观照片，并按箱号抽核。企业必须在产线不能断网停产的前提下，完成预甄别、生产物流、信息补录、组批、随附单据五个环节的报文申报与回执闭环。
系统共八个功能模块：
1、扫码上报接入：接收多台产线扫码端通过 HTTP multipart 上报的扫码记录与照片，使用 X-Api-Key 鉴权，可控制设备启停；图片在扫码端与服务端双份留存，断网后自动补传。
2、申报单管理：覆盖出口锂电包装的预甄别（ELBP001）、生产物流（ELBP002）、信息补录（ELBP004）、组批（ELBP003）、随附单据（ELBP005）五个环节，支持暂存与申报、按阶段单向推进状态机、退单后修改重报。
3、报文组装与海关对接：按 DecMessage 规范组装申报 XML，把图片以 Base64 内嵌，并在本地校验必填字段和字段长度；通过 OutBox/InBox/SentBox/FailBox/archive 五个目录的文件接口与官方导入客户端交换数据，申报文件以原子方式写入。
4、回执解析：常驻监听 InBox，优先解析 JSON 回执，JSON 缺失时回退解析 XML，解析 ELBP101 业务回执（已申报、已放行、退单）与 ELBP103 图片抽核指令；自动更新申报单状态，并把抽核箱号写入数据库。
5、照片与随附单据审核：外观各面图按箱号关联；支持从回执中一键重建抽核箱号清单，提供未审核单据的一键入口；抓取照片时会自动带入申报单的箱号清单。
6、管理后台：提供记录查询、重传、退单、回执明细、统计、用户权限，以及企业和文件接口配置；配置修改后即时生效，不需要重启服务。
7、扫码端运维：通过心跳响应下发待执行指令，支持配置拉取和远程清空数据；采用拉取式设计，适配单向内网和云端部署。
8、授权与受控：用三档 License 控制功能开关；没有有效授权时只关闭受控功能，基础扫码拍照仍可正常使用。
负责从零完成该项目的架构设计与全部后端实现：包括整体技术选型、数据模型与状态机设计、海关报文组装与字段校验、文件接口对接、回执解析、Web 管理后台、离线授权体系、部署分发与客户现场实施。
技术栈：Rust 2021 + axum 0.7 + tokio 异步 Web 服务，sqlx 0.8 采用 AnyPool 在同一套代码中适配 SQLite（默认单文件零依赖）与 MySQL（多客户集中部署），serde 序列化，ed25519-dalek 离线 License 签发验签与 hmac 请求验签，tracing 日志，前端用 Tailwind CDN + 原生 JS 内联渲染、无构建步骤，交付形态是 exe + config + data 单文件分发包，另提供 Docker + Caddy 的 HTTPS 部署方案。
亮点与难点：
1、安全边界——后台绝不接触 USBKey、国密私钥与签名，改为通过五目录文件接口与官方导入客户端解耦；申报 XML 以临时文件 + Rename 原子写入，并用文件大小两次采样一致才读取，避免客户端读到只写了一半的文件，同时规避了消息队列在客户内网的部署难题。
2、状态机只升不降——状态推进统一用 SQL CASE WHEN 比较阶段序号实现，防止信息补录把单据状态拉回早期阶段。
3、回执关联兜底——ELBP101 回执不含客户端流水号，需要按统一编号关联；当编号为空时按当前环节兜底关联并回填，关联不到的孤立回执以空外键写入数据库而不是丢弃，保证漏单可查。
4、免运维交付——编译为单 exe、零运行时依赖，客户工作机不需要 Rust/MSVC 工具链，拷贝即跑。
评论