admin-web/src/modules/overseas-warehouse/AGENTS.md

Admin 海外仓模块指引

读取与路径基准

• 本文件适用于 src/modules/overseas-warehouse/，路径默认相对此目录；其他模块以 ../ 开头。应用公共规则见 ../../../AGENTS.md。
• 先按下表定位页面，再沿 routes.ts、页面 import 与 api/ 追踪；页面是否开放以正式路由、权限和测试为准。后台接口与状态进入 ../../../../../baiyue-firstleg/lastleg-service/AGENTS.md，不扩大扫描其他业务模块。
• 请求统一使用 ../../shared/api/overseasHttp.ts；不以 PROTOTYPE_MATRIX.md 或 CONTRACT_GAPS.md 代替代码与服务端契约。

页面与业务快速索引

退货库存与退货箱号：pages/ReturnInventoryManagementView.vue、api/returnInventory.ts，由 routes.ts 的 return-inventory/return-cartons 分别以 mode=inventory/cartons 进入；只消费 Lastleg returnreceipt/ 的平台库存、箱号、流水和标签接口。退货出库从 pages/OutboundsView.vue 进入，区别于 pages/ExceptionOrdersView.vue 的派送异常退回。

关键词	页面/路由入口	API 与联查
尾程订单控制与柜级入仓计划转换	pages/LastMileOrdersView.vue、pages/LastMileOrderDetailView.vue	柜子工作台按 sourceContainerBookingId 消费 /orders/container-summaries；服务端分页返回全部稳定来源柜，计划已经齐全的柜仍保留用于接柜仓查询和修改，并按冻结 plannedArrivalAt 升序、空值最后排序。详情返回全柜订单且不受列表分页截断；单票手工计划保存后，由服务端在整柜最后一票计划齐全时自动生成并绑定全柜托盘码，一票柜立即生成；resourcePendingPlanCount 只表示自动生成异常的重试入口，不是正常人工步骤。柜级确认弹框先调用 /inbound-plans/container-preview，按服务端 FBA/一件代发/私人地址分组展示头程已有、海外仓补充和最终托数以及 readiness/blockers；最终托数不得少于头程已有托盘码，差额连续补码且不阻断流程。前端不计算托数、不逐票建计划、不预占托盘，再把同一 snapshotVersion/snapshotHash 原样提交 /inbound-plans/convert-container，快照冲突后重新获取预览。服务端只为剩余订单逐票生成独立计划，并为异常遗留的人工计划补齐真实托盘，整批原子且重放不得产生第二批资源。单票完整入库计划、暂扣/解除和八行人工节点均从 api/lastMileOrders.ts 提交订单版本与幂等键；入仓码只读展示并提交订单冻结值，不允许人工改写，暂扣资格、接柜仓锁定原因和操作能力只消费服务端结果，人工节点一经保存不得回退柜级节点。转仓候选只取 ../iam/api/platformIam.ts 的平台公共 ACTIVE + FBA 仓主档；Backend lastleg-service/
入仓单、入仓计划、FBA 预约	pages/InboundOrdersView.vue、pages/InboundOrderDetailView.vue	列表/预约 api/inboundOrders.ts，计划列表/详情 api/inboundPlans.ts；Backend lastleg-service/inboundplan/
排车查询、智能预排与转派送	pages/DispatchesView.vue、pages/DispatchDetailView.vue、components/SmartDispatchDialog.vue	api/dispatches.ts；Backend lastleg-service/dispatch/、delivery/；覆盖详情、候选、草稿柜、托盘锁、pre-arrange 和 transfer-delivery。页面能力必须由正式路由、API 调用和测试共同证明
海外出库与派送	pages/OutboundsView.vue、pages/OutboundDetailView.vue、pages/DeliveryOrdersView.vue、pages/DeliveryOrderDetailView.vue	api/outbounds.ts、api/deliveryOrders.ts；出库列表按类型筛选并展示中文类型。一件代发新建弹窗直接跨客户加载服务端可用候选，不单独展示客户筛选，海外仓必选并优先默认洛杉矶仓；订单条件可按订单号、入库单号、客户、托盘号、SKU 或品名查询/重置，以托盘+SKU 行分页多选。提交时从所选行解析唯一客户，并校验所选行属于当前唯一海外仓，不要求先选客户。退货出库客户下拉同时展示客户名称与联系电话并支持手机号检索，客户和仓库选项独立容错加载；选择客户后须立即按当前默认/已选海外仓加载库存。SKU 与箱号查询均使用输入态/已查询态分离，只允许点击查询按钮后生效；支持英文逗号批量条件，查询时清除空格并按任一条件命中，左右列表分别提供每页 5/10/20/50 条选择。SKU 列表只展示 availableQuantity > 0 的未占用可用数量，合箱后已扣减为零的 SKU 不再作为可选库存显示，实际作业以可用箱唛选择和箱内 SKU 明细扣减为准。取消、派送列表/详情及退回入口对应 Backend lastleg-service/delivery/、dropship/
异常退回与客户回访	pages/ExceptionOrdersView.vue、pages/CustomerVisitsView.vue	api/exceptionOrders.ts、api/customerVisits.ts；异常关系解析、异常建档、派送退回、完成/状态和回访附件对应 Backend lastleg-service/exceptionorder/、customervisit/
库存余额、库位与流水	pages/InventoryView.vue、pages/InventoryDetailView.vue、pages/InventoryTransactionsView.vue	api/inventory.ts；业务库存归 lastleg-service/inventory/，实物资源归 warehouse-overseas-service/
托盘、箱唛、产品与换标	pages/PalletsView.vue、pages/CartonsView.vue、pages/ProductsView.vue、pages/RelabelOrdersView.vue 及详情页	api/pallets.ts、api/relabelOrders.ts；换标详情展示 PDA 完工照片与复核人，状态区分待客户确认和待出库；路由是否公开以 routes.ts 为准

履约硬边界

• API 为 api/dispatches.ts、api/outbounds.ts、api/deliveryOrders.ts；Backend lastleg-service/dispatch/、delivery/、dropship/。一件代发独立出库，从服务端库存位置选择并携带幂等键；普通出库及换标单经头程排车转出库，按托盘快照绑定头程箱唛，PDA 按托盘作业，详情展示箱唛与已拣数量；排车转派送按稳定 dispatchNo 进入服务端命令，可在 PENDING_DEPARTURE、PICKING、READY_TO_DEPART 状态执行并须在 PDA 发车前生成待出库单
• API 为 api/exceptionOrders.ts、api/customerVisits.ts；Backend lastleg-service/exceptionorder/、customervisit/。异常处理只消费服务端 allowedActions/version；完成时至少上传一份异常证据。派送退回先从服务端原出库拣货事实选择入仓单和可退箱数，不允许自由填写 SKU/数量；退回海外仓时必须选择服务端校验的目标托盘和库位，库存恢复、异常完成与派送 RETURNED 由服务端原子推进。回访附件和派送完成/状态均走海外真实 API

验证

• 从应用根按目标页面选择相邻测试：pnpm test src/modules/overseas-warehouse/<目标测试路径>；API 或类型变化同时运行 pnpm typecheck。应用完整门禁继续遵循上层指引。
• 索引变更从后端根运行 ./scripts/agents-index-contract.ps1。离线检查不代替真实 HTTP 和人工截图验收。