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

Admin 海外仓模块指引

• 排车装车后车辆信息分区的路线地图，通过../overseas-master-data/index.ts公开组件按起运仓ID和目的仓精确仓码查询完整地址后展示规划路线；多目的仓独立选择，不推配送顺序。原型及字段边界见../overseas-master-data/PROTOTYPE_MATRIX.md“运输路线地图”。

样式入口

• 导航“海外仓”的 10 个菜单及关联详情/弹框采用公共密度样式，逐操作范围见 海外仓样式核对记录。不要扩展到客户服务、海外业务或未注册产品/箱号页面。
• 独立页面直接导入 @/styles/adminDensity.css；OverseasDetailShell、OverseasReadOnlyDetail 与共享 InboundCodeRelationshipDialog 仅为显式 dense 调用启用。正文在 el-tab-pane 内的页签必须同时使用 density-contained-tabs。

读取与路径基准

• 本文件适用于 src/modules/overseas-warehouse/，路径默认相对此目录；其他模块以 ../ 开头。应用公共规则见 ../../../AGENTS.md。
• 先按下表定位页面，再沿 routes.ts、页面 import 与 api/ 追踪；页面是否开放以正式路由、权限和测试为准。后台接口与状态进入 ../../../../../baiyue-firstleg/lastleg-service/AGENTS.md，不扩大扫描其他业务模块。
• 请求统一使用 ../../shared/api/http.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、api/lastMileOrders.ts 的 reviewReturnOrder	尾程订单内 RETURN_RELABEL + PENDING_REVIEW 行进入审核，来源退货号取 sourceOrderNo；请求 /platform/v1/last-leg/return-orders/{returnNo}/review 携带 X-Customer-Id，结论 APPROVE/REJECT，驳回必填原因。按钮权限入口为 permissions.ts 的 returnOrderReview；服务端归 returnreceipt/，通过后才能签收，不是仓储转运审核或换标完工确认
换标申请审核、待审核按钮与驳回原因	pages/RelabelOrdersView.vue、pages/RelabelOrderDetailView.vue、api/relabelOrders.ts	列表审核动作仅在 PENDING_REVIEW 显示，动作选择为审核通过/已驳回，驳回原因必填；审核后不再显示审核按钮。回归见 pages/RelabelOrdersView.test.ts、pages/RelabelOrderDetailView.test.ts；PDA 完工、客户确认与申请审核分别定位，不混用状态入口
排车资源、草稿容器与实际容量	components/DispatchResourceFields.vue、components/SmartDispatchDialog.vue、dispatchContracts.ts	车辆/司机分别选择已有档案或临时外配，容量取真实档案或本趟填写的托位、千克及立方米，不按车型名称推算。草稿容器容量不代替车辆实测或装载校验；取证、审核前补齐规则见当前排车正式契约
仓储转运审核、通过与驳回	pages/LastMileOrdersView.vue、components/WarehouseTransferReviewDialog.vue	api/warehouseTransfers.ts 的列表、详情及 /warehouse-transfers/{transferNo}/review；审核按钮要求 permissions.ts 的 warehouseTransferApprove 且行类型为 WAREHOUSE_TRANSFER、状态为 PENDING_REVIEW。请求携带该行客户范围和转运单号，审核结论为 APPROVE/REJECT，驳回原因必填；这是尾程订单内的审核弹框，不是独立审核路由或排车转派送入口
尾程订单控制与柜级入仓计划转换	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 提交订单版本与幂等键；预计到仓时间只读展示来源柜冻结值，不进入人工计划请求，服务端按整柜校验并写入同一日期；入仓码只读展示并提交订单冻结值，不允许人工改写。新增暂扣只在 INBOUND_COMPLETED 开放，解除暂扣保持可用；暂扣不阻断入库计划，只限制后续排车和出库。人工节点一经保存不得回退柜级节点。转仓候选只取 ../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、components/DispatchWorkflowDialog.vue	api/dispatches.ts、dispatchContracts.ts、dispatchCommandRecovery.ts；Backend lastleg-service/dispatch/、delivery/。一单一趟、同仓多客户多目的地，空单或先选货均可；候选使用来源版本，草稿走服务器token及公共版本，全部容器原子转换。当前规则见../../../../../docs/海外仓业务/排车列表统一作业改造契约.md，不恢复旧单客户预排协议
海外出库与派送	pages/OutboundsView.vue、pages/OutboundDetailView.vue、pages/DeliveryOrdersView.vue、pages/DeliveryOrderDetailView.vue	api/outbounds.ts、api/deliveryOrders.ts；出库详情使用 deliveries 展示按目的 FBA 仓拆出的全部派送单，派送列表和详情必须显示目的 FBA 仓。人工状态入口不提供完成派送；签收资料保存成功后提示自动完成并刷新列表。出库列表按类型筛选并展示中文类型，状态须覆盖 WAIT_PICK/待拣货、PICKING/拣货中、PICKED/已拣货、WAIT_OUTBOUND/待出库、OUTBOUNDED/已出库 和 CANCELLED/已取消；仅未开始的 WAIT_PICK/WAIT_OUTBOUND 允许取消。一件代发新建弹窗直接跨客户加载服务端可用候选，不单独展示客户筛选，海外仓必选并优先默认洛杉矶仓；订单条件可按订单号、入库单号、客户、托盘号、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/LocationsView.vue、api/locations.ts	按海外仓分页或多仓查询库位，支持库区/库位编码、类型和状态筛选；NORMAL 库位可编辑、停用或删除，A0/SHARED_OVERFLOW、VIRTUAL 由服务端事实保护，不能按普通库位修改。接口经 /platform/v1/warehouse-admin/{warehouseId}/locations，权限沿 permissions.ts 的库位维护/删除入口
托盘、箱唛、产品与换标	pages/PalletsView.vue、pages/CartonsView.vue、pages/ProductsView.vue、pages/RelabelOrdersView.vue 及详情页	api/pallets.ts、api/relabelOrders.ts；换标详情展示 PDA 完工照片与复核人，状态区分待客户确认和待出库；路由是否公开以 routes.ts 为准

履约硬边界

• 排车详情固定四个彩色图标页签：车辆信息、排车信息、单据信息、关联订单明细。五阶段及审核分区、逐动作Gate由服务端返回；取消独立于阶段。装车完成须真实PDA拣货核平，装车与实际发车分别确认；Admin和PDA共用正式版本化命令。已有单写入提交recordVersion（0合法）、原幂等键和完整载荷；未知结果保留原请求核对，成功后另读当前事实。

• 智能排车来源支持 RELABEL（待出库换标单），按服务端候选的selection.relabelNo/sourceVersion提交，不用展示订单号或原入仓号替代换标身份；沿用真实库存、托盘与箱唛，不生成新入库单。客户和仓库归属由服务端核验，不在前端拼接客户子排车。

• 托盘管理单张打印：pages/PalletsView.vue 每行“打印”经 api/pallets.ts 的 getPalletLabelPdf 下载当前托盘一页 PDF；使用该行仓库 ID 与托盘 ID，权限复用托盘列表。Backend warehouse-overseas-service 的 PalletLabelPrintService 读取公共托盘；有 FBA 仓码的托盘与国内统一使用 Print FBA_PALLET_A4_LANDSCAPE_V1（297×210 mm，FBA 仓码、完整托盘号 Code 128、托盘号文字），其他托盘使用 INBOUND_MARK_V1。不在前端生成标签、改码或维护第二套模板。

• API 为 api/dispatches.ts、api/outbounds.ts、api/deliveryOrders.ts；Backend lastleg-service/dispatch/、delivery/、dropship/。一件代发独立出库，从服务端库存位置选择并携带幂等键；换标只有平台卡车进入排车，普通自提、亚马逊自提、客户自提及快递由客户确认直接创建出库任务。整车派送安排在装车完成后、实际发车前进行；每客户一张出库单，每客户每目的地一张派送单，公开完整数组，不能回退为单个outboundNo或按客户拆排车头。

• API 为 api/exceptionOrders.ts、api/customerVisits.ts；Backend lastleg-service/exceptionorder/、customervisit/。异常处理只消费服务端 allowedActions/version；完成时至少上传一份异常证据。派送退回先从服务端原出库拣货事实选择入仓单和可退箱数，不允许自由填写 SKU/数量；退回海外仓时必须选择服务端校验的目标托盘和库位，库存恢复、异常完成与派送 RETURNED 由服务端原子推进。回访附件和派送完成/状态均走海外真实 API

验证

• 一件代发出库候选选择：pages/OutboundsView.vue 按 inventoryPositionId + skuCode 保留跨页选择，只提供本页全选；查询/重置回到第一页，切换海外仓清空选择。提交仍校验同客户、同海外仓，数量取所选行的 availablePackages（箱数），不能按 SKU 件数替代；候选同时展示当前可出箱数对应的毛重、材积重和体积，创建出库单时服务端按本次出库箱数占实际入库箱数的比例冻结三项测量快照。候选交互回归见 pages/OutboundsView.selection.test.ts；状态展示与取消门禁见 pages/OutboundsView.test.ts、pages/OutboundDetailView.test.ts。

• 转运审核定向测试：从应用根运行 pnpm test src/modules/overseas-warehouse/api/warehouseTransfers.test.ts src/modules/overseas-warehouse/pages/prototypeContract.test.ts，分别核对客户作用域/API 与审核入口权限、状态。

• 派送安排弹框通过getDispatchArrangement读取整车分组、实际货物、外接报价及原费用依据，DispatchArrangeFields.vue按真实客户目的地组提交；不逐行查费用，不按金额推断覆盖，不把原费用再次记入新费用行。移货必须使用GET items返回的真实dispatchItemId及逐项remove Gate；路线仅重排GET route返回的既有全部目的地，包含外接点，不能新增或猜测目的地。附件沿DispatchEvidenceFiles.vue的本车鉴权上传/读取，上传与主单引用保存分开。

• 出库取消提示先解除车次关联，取消后仍须在排车列表释放原排车占用；不提示库存已自动回滚。派送详情费用读取reviewStatus/sourceStatus/voidStatus，同一详情响应展示待财务确认、待财务处理、确认作废，不逐行查询，也不把取消成功视为费用作废。货柜费用面板直接消费同一费用来源接口，待确认时同样禁止调整和重复作废，沿用原页面/弹框承载。

• 排车列表编辑、托盘移除、BOL PDF 和转派送从 pages/DispatchesView.vue → api/dispatches.ts 进入；智能预排的候选、草稿柜与托盘锁从 components/SmartDispatchDialog.vue 进入。回归为 pages/DispatchesView.test.ts、pages/prototypeContract.test.ts，不要把列表操作与预排草稿当作同一入口。

• 从应用根按目标页面选择相邻测试：pnpm test src/modules/overseas-warehouse/<目标测试路径>；API 或类型变化同时运行 pnpm typecheck。应用完整门禁继续遵循上层指引。

• 索引变更从后端根运行 ./scripts/agents-index-contract.ps1。离线检查不代替真实 HTTP 和人工截图验收。

• 尾程订单、库存余额与进销存记录导出统一使用 ../downloads/ 的 useExportTask 创建 XLSX 任务；保留当前筛选和业务导出权限，并要求 platform:download:list。Lastleg 内部 Provider 契约为 lastleg-exports-v1.yaml，业务页面不再请求同步 CSV。