墨家设备测量上传接口说明-V3.md

@@ -0,0 +1,96 @@
+# 墨家设备测量上传接口说明
+
+版本：V3  
+适用对象：墨家箱体测量设备服务
+
+## 1. 接口用途
+
+墨家设备扫描柏悦唛头并上传当前箱子的测量结果。每次请求对应一次设备测量，不需要传订单内部字段，也不需要关心柏悦后续如何保存、审核或计费。
+
+唛头二维码内容由柏悦生成，设备应原样读取并作为 `boxCode` 上传。例如：
+
+```text
+PCHK2608040174#19-1
+```
+
+设备不需要解析或修改 `boxCode`。
+
+## 2. 接口地址
+
+```text
+POST <GATEWAY_HOST>/openapi/v1/inbound-measurements
+```
+
+`<GATEWAY_HOST>` 由柏悦另行提供。
+
+## 3. 请求格式
+
+请求头：
+
+| Header | 必填 | 说明 |
+|---|---|---|
+| `Content-Type` | 是 | `application/json` |
+| `X-App-Key` | 是 | 柏悦分配的固定应用标识 |
+| `X-Timestamp` | 待确认 | Unix 毫秒时间戳 |
+| `X-Nonce` | 待确认 | 每次请求唯一的随机字符串 |
+| `X-Signature` | 待确认 | HMAC-SHA256 动态签名 |
+| `Idempotency-Key` | 待确认 | 网络重试时用于识别同一次上传 |
+
+请求 JSON：
+
+```json
+{
+  "boxCode": "PCHK2608040174#19-1",
+  "length": 100.1,
+  "width": 100.2,
+  "height": 100.3,
+  "weight": 100.4,
+  "machineNo": "MJ20210327",
+  "picture": "data:image/jpeg;base64,/9j..."
+}
+```
+
+字段说明：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `boxCode` | 是 | 扫描得到的唛头二维码文本，必须原样传输 |
+| `length` | 是 | 当前箱长度，单位 cm |
+| `width` | 是 | 当前箱宽度，单位 cm |
+| `height` | 是 | 当前箱高度，单位 cm |
+| `weight` | 待确认 | 当前箱重量，单位 kg；请确认精度和是否必传 |
+| `machineNo` | 是 | 墨家设备编号，每台机器固定且唯一 |
+| `picture` | 是 | JPEG 图片的 Data URL Base64 文本 |
+
+## 4. 图片格式
+
+图片格式：
+
+```text
+data:image/jpeg;base64,<Base64内容>
+```
+
+服务端会校验图片格式和大小。当前约定解码后的图片不超过 5 MB。接口不接受图片 URL 或图片 ID。
+
+## 5. 返回结果
+
+成功时返回 HTTP 200 和 JSON 成功结果。墨家只需判断 HTTP 状态和响应中的成功标识，不需要处理柏悦内部业务字段。
+
+失败时，柏悦会返回 HTTP 错误或 JSON 错误信息。设备应记录请求时间、`boxCode`、`machineNo` 和响应信息，便于重试和排查。
+
+## 6. 重试约定
+
+网络超时或未收到响应时，设备可以重试同一次上传。若柏悦最终确认启用 `Idempotency-Key`，同一次重试必须使用相同的幂等键；新的测量上传使用新的幂等键。
+
+同一个 `boxCode` 后续再次上传时，以最新一次设备测量结果为准，设备无需额外传版本号。
+
+## 7. 待墨家确认
+
+1. `boxCode` 是否可以原样上传完整二维码文本，例如 `PCHK2608040174#19-1`。
+2. `picture` 是否可以按 `data:image/jpeg;base64,...` 格式上传。
+3. `weight` 的单位、精度和是否必传。
+4. `machineNo` 是否每台机器固定且唯一。
+5. 设备是否支持每次请求动态生成 HMAC-SHA256 签名。
+6. 设备是否支持在网络重试时携带同一个请求幂等键。
+
+柏悦侧会另行提供正式接口地址、固定 AppKey、认证参数和测试数据。本说明不包含任何真实密钥或柏悦内部业务处理规则。

墨家设备测量接口对接说明-V2.md

@@ -0,0 +1,128 @@
+# 墨家设备测量回传接口对接说明（V2）
+
+版本：V2  
+适用对象：墨家箱体测量设备服务
+
+## 1. 业务流程
+
+柏悦在头程下单完成后，按订单箱规分段生成唛头，并为每个实际箱子生成固定二维码。二维码内容格式为：
+
+```text
+入库码#总箱数-箱下标
+```
+
+示例：
+
+```text
+PCHK2608040174#19-1
+PCHK2608040174#19-2
+```
+
+柏悦会在首次打印前保存 `boxCode` 与箱规/订单货物明细的对应关系。重复打印或部分补打均沿用原二维码，不重新分配箱号。订单打印后箱规明细不可直接修改，如需变更须取消并重新生成唛头。
+
+墨家设备每次只上传当前扫描到的一个实际箱子的测量结果。一次测量不会覆盖订单中的其他箱规或其他箱子。
+
+## 2. 上传内容
+
+```json
+{
+  "boxCode": "PCHK2608040174#19-1",
+  "length": 100.1,
+  "width": 100.2,
+  "height": 100.3,
+  "weight": 100.4,
+  "machineNo": "MJ20210327",
+  "picture": "data:image/jpeg;base64,/9j..."
+}
+```
+
+字段说明：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `boxCode` | 是 | 扫描唛头二维码得到的完整内容；格式为入库码#总箱数-箱下标 |
+| `length` | 是 | 当前箱长度，单位 cm |
+| `width` | 是 | 当前箱宽度，单位 cm |
+| `height` | 是 | 当前箱高度，单位 cm |
+| `weight` | 是 | 当前箱重量，单位 kg；如设备不提供需另行确认 |
+| `machineNo` | 是 | 墨家设备编号，多台设备各自固定 |
+| `picture` | 是 | Data URL 格式的 JPEG Base64 图片，前缀为 `data:image/jpeg;base64,` |
+
+墨家不需要传柏悦内部的 `inboundDetailId`、客户 ID、仓库 ID 或箱规名称；柏悦服务端根据 `boxCode` 查询已保存的箱号映射。
+
+## 3. 测量记录规则
+
+### 首次扫描
+
+当前 `boxCode` 没有测量记录时，新增一条记录：
+
+- 保存本次长、宽、高、重量、图片、机器编号和测量时间；
+- 人工确认箱数初始为 1；
+- 该记录只代表当前扫描箱，不能自动套用到其他箱子。
+
+### 同箱重新扫描
+
+同一个 `boxCode` 再次扫描时，不新增记录，直接覆盖当前设备测量数据：
+
+- 长、宽、高；
+- 重量；
+- 图片；
+- 机器编号；
+- 测量时间。
+
+人工已经填写的确认箱数保持不变。旧图片同步替换/清理，当前一个箱号只保留一张有效图片和一条当前记录。
+
+### 多箱抽样
+
+扫几箱就保留几条独立测量记录。相同箱规抽测多箱时，不在设备回传阶段自动合并；由平台人员逐条确认每条测量数据分别代表多少箱。
+
+例如 100 箱 A 规格抽测两箱：
+
+| 实际箱 | 实测数据 | 人工确认箱数 |
+|---|---|---:|
+| `...#100-1` | 第一箱的尺寸、重量和图片 | 60 |
+| `...#100-35` | 第二箱的尺寸、重量和图片 | 40 |
+
+### 提交审核
+
+人工确认箱数之和必须等于入库单原始总箱数，才允许正常提交审核。不一致时服务端阻止提交；有权限人员填写异常原因后，才允许异常放行。
+
+## 4. 状态和覆盖限制
+
+- `WAIT_MEASURE`、`MEASURE_REJECTED`：允许新增或覆盖同一 `boxCode`；
+- 测量已提交审核：墨家再次上传直接拒绝；
+- 审核通过、计费或入库后：禁止设备覆盖；
+- 如需重新测量，必须由平台人员退回测量修正；
+- 退回后才重新允许墨家上传。
+
+## 5. 图片要求
+
+`picture` 必须为：
+
+```text
+data:image/jpeg;base64,<Base64内容>
+```
+
+服务端会去除 Data URL 前缀、解码并校验 JPEG 内容，按解码后的实际图片大小限制最大 5 MB，然后保存到文件中心。接口不接受图片 URL 或文件 ID。
+
+## 6. 认证方式（待墨家确认）
+
+业务字段和处理流程已确定，认证方式需要墨家确认设备能力。推荐使用：
+
+- 固定 `X-App-Key`；
+- 固定 `Secret`；
+- 每次动态生成 `X-Timestamp`、`X-Nonce` 和 `X-Signature`；
+- `X-Signature` 使用 HMAC-SHA256，根据本次请求原文计算。
+
+如果设备只能发送一个永远不变的静态 Key，无法计算动态 HMAC 签名，请墨家明确说明。届时需要另行评估固定 API Key、HTTPS、防重和 IP 白名单方案，不能直接套用动态签名协议。
+
+## 7. 需要墨家确认
+
+1. `boxCode` 是否可以直接作为上传字段，并保持完整二维码文本不变。
+2. `picture` 是否可以按 Data URL JPEG Base64 发送。
+3. `weight` 的单位是否为 kg，精度和是否必传。
+4. `machineNo` 是否每台设备固定且唯一。
+5. 设备是否支持动态 HMAC-SHA256 签名。
+6. 网络重试时是否可以携带同一个业务请求标识，避免重复处理。
+
+柏悦侧会另行提供正式接口地址、固定 AppKey、Secret、测试入库单和测试唛头。本文不包含任何真实密钥。