docs: document overseas request URL contract

2026-09-04 16:28:45 +08:00
parent a386c50d9f
commit 4f314fa3cf
1 changed files with 1 additions and 0 deletions
@@ -56,6 +56,7 @@
 ## 海外业务接口边界

 - `src/api/inbound.js` 已接入待卸柜候选、柜详情/prepare、current 恢复、三类照片签收、统一箱码定位入仓码、实物托盘解析、FBA bulk/OVERSEAS carton 收货及整柜完成；FBA bulk 不提交 `skuCode`，库存分配由服务端按计划明细完成；响应与 404/409 判定集中在 `src/api/receiving-adapter.js`，双 Token 刷新与海外 401 单次重放由 `src/api/overseas.js` 统一处理。
+- `src/api/overseas.js` 的 `overseasUrl` 统一拼接普通请求、上传和下载地址：先移除运行时 `apiBase` 末尾斜杠；当基址已以 `/api` 或 `/overseas-api` 结尾时，再移除业务路径重复的 `/api` 前缀。各业务 API 不得自行拼接 `session.apiBase`，也不得依赖双斜杠或重复 `/api` 被网关容错。
 - 待卸柜候选保留服务端返回的未齐全柜并严格消费 `allPlansReady`、`operable`、`blockReason`、`plannedArrivalAt` 与柜级计划统计；`operable=false` 只能查看只读摘要，不得调用 prepare。候选顺序沿用服务端“可操作优先、同组计划到仓时间升序、时间为空最后”的排序，前端不得用入仓码/计划数组长度自行推导就绪或把预计到港冒充计划到仓。
 - `src/api/pallet.js` 只调用 Lastleg 托盘专用 PDA Controller；前端提交服务端扫码返回的 `palletVersion`、`positionVersion` 和随机幂等键，不提交客户、仓库或库位标识。409 后必须重新扫码获取最新版本，禁止用旧库存快照继续作业。
 - 请求身份和资源范围只取 Token 与 current 会话；前端不得提交 `customerId`、`planNo`、`allocationId`、`warehouseId` 或 `locationId`。409 必须引导账号恢复当前柜，完成前不得切柜。