src/modules/overseas-warehouse/CONTRACT_GAPS.md

# 四期海外仓前端待补契约

正式页面已开始接入真实海外接口。后端服务边界现已确认：浏览器请求统一进入 `gateway-overseas/`（RS256/JWKS，Audience=`lastleg-api`）；尾程订单、入仓计划、换标、产品/箱号快照和库存业务归 `lastleg-service/`；海外仓库、地址、能力、库位、实物托盘和资源锁归 `warehouse-overseas-service/`。国内 `warehouse/` 只维护“海外仓合作仓”公共主数据类型。逐页现状见 `API_INTEGRATION_MATRIX.md`。

以下前端适配或页面级契约补齐前，页面不得用演示数据或本地成功提示替代真实调用：

- 尾程订单导入模板、批量导入、异步导出任务及对应独立权限。现有同步 CSV 导出不等同于 Admin 下载中心异步导出。尾程分页与详情已经接入；“待分配”映射为 `PENDING_ASSIGNMENT`，出库单号、派送单号仅展示既有只读关联事实。
- 入库单分页与详情已接入。详情 DTO 仍缺预约状态/时间、排车状态/时间、创建更新时间、备注和应收费用；创建、预约及补托只在原型承载和完整幂等/打印语义冻结后接入。
- 库存汇总、SKU 分页、库位位置和进销存已接入。流水 DTO 仍缺 SKU、产品名、客户名和海外仓名称；详情也没有按 `balanceId` 直接查询余额主记录的端点。
- 换标单分页、详情、创建、编辑/审核、文件上传与费用明细接口，以及状态机和幂等约定。
- 托盘分页、详情、新增、编辑已接入公共资源接口。剩余缺口是独立公共仓库候选接口、FBA 仓字段、业务绑定/关联箱数只读汇总；删除未在原型定义，不新增入口。
- 箱号、产品库本期暂缓并已从模块正式路由移除；既有源码保留，相关平台查询/写接口不再作为本期交付阻断。
- 四期权限资源在 IAM 初始化数据中的正式登记。前端暂按本模块 `permissions.ts` 的稳定编码装配。
- 所有分页响应、错误码、`requestId`/`traceId`、时间/金额精度和长整型 ID 字符串传输约定。

## 当前缺口的精确请求形状

- 入库详情：`GET /api/platform/v1/last-leg/inbound-plans/{planNo}` 需补预约/排车/时间/费用，或提供对应只读辅助接口；`sourceOrderId` 已按字符串接入。
- 库存流水：`GET /api/platform/v1/last-leg/inventory/ledger` 需补 `skuCode/productName/customerName/overseasWarehouseName`，并支持 SKU 过滤，才能完整还原进销存和 SKU 详情流水。
- 换标：当前列表响应需补 `productName,labelRequirement,relabelFile,budgetTotal/relabelCost`，或产品明确调整原型字段；写接口必须补正式 `create/edit` 权限。现有状态机为 `PENDING_PROCESSING -> PROCESSING/REJECTED/CANCELLED`、`PROCESSING -> COMPLETED/REJECTED/CANCELLED`。
- 托盘：资源接口已固定公共作用域且不再传客户参数；仍缺无需客户遍历即可获取所有实际海外仓的公共候选接口，以及 FBA 仓和业务绑定汇总字段。
- 权限：入仓、库存、仓库资源已切换 canonical `platform:overseas-warehouse:*`；前端已同步本模块权限常量。换标写弹框字段与后端 Create DTO 仍不一致，因此不开放提交。

范围排除：海外仓出库、退货出库、海外派送和其他库存离仓接口。

`lastleg-service` 已提供尾程订单、入仓计划、库存查询等 Controller，`warehouse-overseas-service` 已提供平台海外仓、库位和托盘 Controller；接入时以这些服务的 Controller/DTO/OpenAPI 为准。当前 `types.ts` 只冻结原型派生的页面展示字段，不是海外 API DTO；不得据此推导未覆盖页面的分页包络、URL、请求参数、时间/金额精度或写接口。统一区域客户端和对应页面契约完成后再建立实际 API 适配层，并逐页替换空态数据源。
-											优化
										
										
											2026-08-19 16:45:51 +08:00
+								# 四期海外仓前端待补契约
-											优化
										
										
											2026-08-20 09:10:36 +08:00
+								正式页面已开始接入真实海外接口。后端服务边界现已确认：浏览器请求统一进入 `gateway-overseas/`（RS256/JWKS，Audience=`lastleg-api`）；尾程订单、入仓计划、换标、产品/箱号快照和库存业务归 `lastleg-service/`；海外仓库、地址、能力、库位、实物托盘和资源锁归 `warehouse-overseas-service/`。国内 `warehouse/` 只维护“海外仓合作仓”公共主数据类型。逐页现状见 `API_INTEGRATION_MATRIX.md`。
-											优化
										
										
											2026-08-19 16:45:51 +08:00
-											优化
										
										
											2026-08-19 17:08:45 +08:00
+								以下前端适配或页面级契约补齐前，页面不得用演示数据或本地成功提示替代真实调用：
-											优化
										
										
											2026-08-20 09:10:36 +08:00
+								- 尾程订单导入模板、批量导入、异步导出任务及对应独立权限。现有同步 CSV 导出不等同于 Admin 下载中心异步导出。尾程分页与详情已经接入；“待分配”映射为 `PENDING_ASSIGNMENT`，出库单号、派送单号仅展示既有只读关联事实。
-											优化
										
										
											2026-08-20 18:02:52 +08:00
+								- 入库单分页与详情已接入。详情 DTO 仍缺预约状态/时间、排车状态/时间、创建更新时间、备注和应收费用；创建、预约及补托只在原型承载和完整幂等/打印语义冻结后接入。
 								- 库存汇总、SKU 分页、库位位置和进销存已接入。流水 DTO 仍缺 SKU、产品名、客户名和海外仓名称；详情也没有按 `balanceId` 直接查询余额主记录的端点。
-											优化
										
										
											2026-08-19 16:45:51 +08:00
+								- 换标单分页、详情、创建、编辑/审核、文件上传与费用明细接口，以及状态机和幂等约定。
-											优化
										
										
											2026-08-20 18:02:52 +08:00
+								- 托盘分页、详情、新增、编辑已接入公共资源接口。剩余缺口是独立公共仓库候选接口、FBA 仓字段、业务绑定/关联箱数只读汇总；删除未在原型定义，不新增入口。
 								- 箱号、产品库本期暂缓并已从模块正式路由移除；既有源码保留，相关平台查询/写接口不再作为本期交付阻断。
-											优化
										
										
											2026-08-19 16:45:51 +08:00
+								- 四期权限资源在 IAM 初始化数据中的正式登记。前端暂按本模块 `permissions.ts` 的稳定编码装配。
 								- 所有分页响应、错误码、`requestId`/`traceId`、时间/金额精度和长整型 ID 字符串传输约定。
-											优化
										
										
											2026-08-20 09:10:36 +08:00
+								## 当前缺口的精确请求形状
-											优化
										
										
											2026-08-20 18:02:52 +08:00
+								- 入库详情：`GET /api/platform/v1/last-leg/inbound-plans/{planNo}` 需补预约/排车/时间/费用，或提供对应只读辅助接口；`sourceOrderId` 已按字符串接入。
 								- 库存流水：`GET /api/platform/v1/last-leg/inventory/ledger` 需补 `skuCode/productName/customerName/overseasWarehouseName`，并支持 SKU 过滤，才能完整还原进销存和 SKU 详情流水。
-											优化
										
										
											2026-08-20 09:10:36 +08:00
+								- 换标：当前列表响应需补 `productName,labelRequirement,relabelFile,budgetTotal/relabelCost`，或产品明确调整原型字段；写接口必须补正式 `create/edit` 权限。现有状态机为 `PENDING_PROCESSING -> PROCESSING/REJECTED/CANCELLED`、`PROCESSING -> COMPLETED/REJECTED/CANCELLED`。
-											优化
										
										
											2026-08-20 18:02:52 +08:00
+								- 托盘：资源接口已固定公共作用域且不再传客户参数；仍缺无需客户遍历即可获取所有实际海外仓的公共候选接口，以及 FBA 仓和业务绑定汇总字段。
 								- 权限：入仓、库存、仓库资源已切换 canonical `platform:overseas-warehouse:*`；前端已同步本模块权限常量。换标写弹框字段与后端 Create DTO 仍不一致，因此不开放提交。
-											优化
										
										
											2026-08-20 09:10:36 +08:00
-											优化
										
										
											2026-08-19 16:45:51 +08:00
+								范围排除：海外仓出库、退货出库、海外派送和其他库存离仓接口。
-											优化
										
										
											2026-08-19 17:08:45 +08:00
+								`lastleg-service` 已提供尾程订单、入仓计划、库存查询等 Controller，`warehouse-overseas-service` 已提供平台海外仓、库位和托盘 Controller；接入时以这些服务的 Controller/DTO/OpenAPI 为准。当前 `types.ts` 只冻结原型派生的页面展示字段，不是海外 API DTO；不得据此推导未覆盖页面的分页包络、URL、请求参数、时间/金额精度或写接口。统一区域客户端和对应页面契约完成后再建立实际 API 适配层，并逐页替换空态数据源。