优化

src/modules/overseas-warehouse/CONTRACT_GAPS.md

@@ -1,11 +1,10 @@
 # 四期海外仓前端待补契约
 
-第一批正式页面只冻结路由、权限、字段与操作承载方式。后端服务边界现已确认：浏览器请求统一进入 `gateway-overseas/`（RS256/JWKS，Audience=`lastleg-api`）；尾程订单、入仓计划、换标、产品/箱号快照和库存业务归 `lastleg-service/`；海外仓库、地址、能力、库位、实物托盘和资源锁归 `warehouse-overseas-service/`。国内 `warehouse/` 只维护“海外仓合作仓”公共主数据类型。
+正式页面已开始接入真实海外接口。后端服务边界现已确认：浏览器请求统一进入 `gateway-overseas/`（RS256/JWKS，Audience=`lastleg-api`）；尾程订单、入仓计划、换标、产品/箱号快照和库存业务归 `lastleg-service/`；海外仓库、地址、能力、库位、实物托盘和资源锁归 `warehouse-overseas-service/`。国内 `warehouse/` 只维护“海外仓合作仓”公共主数据类型。逐页现状见 `API_INTEGRATION_MATRIX.md`。
 
 以下前端适配或页面级契约补齐前，页面不得用演示数据或本地成功提示替代真实调用：
 
-- 统一认证/HTTP 层对海外 API Base、短时海外 Access Token 的存储、刷新和自动选择，以及与现有国内 `http` 客户端一致的错误处理；业务页面不得自行读写 Token，也不得把请求发往国内 `gateway/`、`firstleg/` 或 `warehouse/`。
-- 尾程订单分页查询、详情、导入模板、批量导入、异步导出、批量转仓和入库计划接口；分页查询需明确“全部 / 待分配”页签的请求映射，以及出库单号、派送单号只读关联字段。
+- 尾程订单导入模板、批量导入、异步导出任务及对应独立权限。现有同步 CSV 导出不等同于 Admin 下载中心异步导出。尾程分页与详情已经接入；“待分配”映射为 `PENDING_ASSIGNMENT`，出库单号、派送单号仅展示既有只读关联事实。
 - 入库单分页查询、详情、创建、编辑、预约、智能排车接口，以及状态机、幂等键和操作权限。
 - 库存汇总、分页查询、详情、库位库存、托盘箱号和进销存记录接口。
 - 换标单分页、详情、创建、编辑/审核、文件上传与费用明细接口，以及状态机和幂等约定。
@@ -15,6 +14,16 @@
 - 四期权限资源在 IAM 初始化数据中的正式登记。前端暂按本模块 `permissions.ts` 的稳定编码装配。
 - 所有分页响应、错误码、`requestId`/`traceId`、时间/金额精度和长整型 ID 字符串传输约定。
 
+## 当前缺口的精确请求形状
+
+- 入库单列表：缺 `GET /api/platform/v1/last-leg/inbound-plans`；至少需要 `customerId,page,size,planNo,inboundCode,warehouseId,fbaWarehouseCode,status,appointmentStatus`，响应需返回 `records/page/size/total/pages` 及原型列表字段。现有状态起点为 `PENDING_ASSIGNMENT`，转换端点 `POST /convert` 不能代替列表。
+- 产品库：缺平台 `GET/POST/PUT /api/platform/v1/last-leg/products[/{id}]`；查询/响应至少覆盖客户、SKU、中英文品名、品类、长宽高、重量，写入需 SKU 唯一性、精度、幂等和状态约束。
+- 箱号：缺平台 `GET/POST/PUT /api/platform/v1/last-leg/cartons[/{id}]`；查询/响应至少覆盖客户、箱号、FBA 仓、SKU、产品名、数量、重量、库存状态、托盘、入库单及只读出库关联。内部 `/internal/v1/lastleg/dropship/receive` 不得暴露给浏览器。
+- 库存：现有 `GET /api/platform/v1/last-leg/inventory/balances|ledger` 需增加 SKU/产品快照维度，或另提供与原型一致的 SKU 聚合端点；响应需覆盖现有量、可用量、暂扣、散板、在途、采购、状态和更新时间。状态流转仍只能由入库/库内事实驱动，不增加离仓操作。
+- 换标：当前列表响应需补 `productName,labelRequirement,relabelFile,budgetTotal/relabelCost`，或产品明确调整原型字段；写接口必须补正式 `create/edit` 权限。现有状态机为 `PENDING_PROCESSING -> PROCESSING/REJECTED/CANCELLED`、`PROCESSING -> COMPLETED/REJECTED/CANCELLED`。
+- 托盘：需先收敛资源作用域。产品要求平台公共查询全部客户/仓库，现接口 `GET /api/platform/v1/warehouse-admin/{warehouseId}/pallets?customerId=...` 强制客户绑定；响应还需明确 FBA 仓与采购价如何对应当前 `locationId/unitPrice`。在此冲突解决前不把客户筛选错误地当作公共资源范围。
+- 权限：尾程、入库、换标、库存、海外仓、库位、托盘相关 Controller 均需为列表/详情使用各资源 `*:list`，写操作分别使用 `*:create`、`*:edit` 等稳定权限；当前仅有应用范围与客户隔离，不能以页面按钮权限替代服务端鉴权。
+
 范围排除：海外仓出库、退货出库、海外派送和其他库存离仓接口。
 
 `lastleg-service` 已提供尾程订单、入仓计划、库存查询等 Controller，`warehouse-overseas-service` 已提供平台海外仓、库位和托盘 Controller；接入时以这些服务的 Controller/DTO/OpenAPI 为准。当前 `types.ts` 只冻结原型派生的页面展示字段，不是海外 API DTO；不得据此推导未覆盖页面的分页包络、URL、请求参数、时间/金额精度或写接口。统一区域客户端和对应页面契约完成后再建立实际 API 适配层，并逐页替换空态数据源。