优化

墨家设备测量上传接口说明-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、认证参数和测试数据。本说明不包含任何真实密钥或柏悦内部业务处理规则。