2026-09-14 10:02:39 +08:00
# Admin 海外仓模块指引
2026-09-14 20:03:27 +08:00
## 样式入口
- 导航“海外仓”的 10 个菜单及关联详情/弹框采用公共密度样式，逐操作范围见 [海外仓样式核对记录 ](../../../../../docs/Admin海外仓样式核对记录.md )。不要扩展到客户服务、海外业务或未注册产品/箱号页面。
- 独立页面直接导入 `@/styles/adminDensity.css` ； `OverseasDetailShell` 、`OverseasReadOnlyDetail` 与共享 `InboundCodeRelationshipDialog` 仅为显式 `dense` 调用启用。正文在 `el-tab-pane` 内的页签必须同时使用 `density-contained-tabs` 。
2026-09-14 10:02:39 +08:00
## 读取与路径基准
- 本文件适用于 `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 与联查 |
|---|---|---|
2026-09-20 18:25:17 +08:00
| 退货预报审核、退货驳回 | `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 完工、客户确认与申请审核分别定位，不混用状态入口 |
2026-09-15 15:53:03 +08:00
| 排车车型、托位容量与限重提示 | `dispatchVehicleSpecs.ts` 、`components/SmartDispatchDialog.vue` 、`pages/DispatchesView.vue` | 预排车型与排车编辑选项共用规格入口：大车 30 托/40000 LB，小车 15 托/10000 LB；超重提示在预排组件，不能把前端提示当作服务端允许提交的依据。回归见 `pages/DispatchesView.test.ts` 、`pages/prototypeContract.test.ts` |
2026-09-14 12:00:54 +08:00
| 仓储转运审核、通过与驳回 | `pages/LastMileOrdersView.vue` 、`components/WarehouseTransferReviewDialog.vue` | `api/warehouseTransfers.ts` 的列表、详情及 `/warehouse-transfers/{transferNo}/review` ；审核按钮要求 `permissions.ts` 的 `warehouseTransferApprove` 且行类型为 `WAREHOUSE_TRANSFER` 、状态为 `PENDING_REVIEW` 。请求携带该行客户范围和转运单号，审核结论为 `APPROVE/REJECT` ，驳回原因必填；这是尾程订单内的审核弹框，不是独立审核路由或排车转派送入口 |
2026-09-18 09:59:12 +08:00
| 尾程订单控制与柜级入仓计划转换 | `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/` |
2026-09-14 10:02:39 +08:00
| 入仓单、入仓计划、FBA 预约 | `pages/InboundOrdersView.vue` 、`pages/InboundOrderDetailView.vue` | 列表/预约 `api/inboundOrders.ts` ，计划列表/详情 `api/inboundPlans.ts` ； `lastleg-service/inboundplan/` |
2026-09-15 14:30:50 +08:00
| 排车查询、智能预排与转派送 | `pages/DispatchesView.vue` 、`pages/DispatchDetailView.vue` 、`components/SmartDispatchDialog.vue` | `api/dispatches.ts` ； `lastleg-service/dispatch/` 、`delivery/` ；覆盖详情、候选、草稿柜、托盘锁、`pre-arrange` 和 `transfer-delivery` 。路线只读并由已排托盘关联的 FBA 仓去重后以英文逗号连接，预排和普通编辑均不接收人工路线。一次转派送仍生成一张车辆级出库单，响应的 `deliveries` 按目的 FBA 仓返回多张派送单。页面能力必须由正式路由、API 调用和测试共同证明 |
2026-09-15 21:05:09 +08:00
| 海外出库与派送 | `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/` |
2026-09-14 10:02:39 +08:00
| 异常退回与客户回访 | `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/` |
2026-09-23 17:46:01 +08:00
| 海外库位维护与状态 | `pages/LocationsView.vue` 、`api/locations.ts` | 按海外仓分页或多仓查询库位，支持库区/库位编码、类型和状态筛选；`NORMAL` 库位可编辑、停用或删除，`A0/SHARED_OVERFLOW` 、`VIRTUAL` 由服务端事实保护，不能按普通库位修改。接口经 `/platform/v1/warehouse-admin/{warehouseId}/locations` ，权限沿 `permissions.ts` 的库位维护/删除入口 |
2026-09-14 10:02:39 +08:00
| 托盘、箱唛、产品与换标 | `pages/PalletsView.vue` 、`pages/CartonsView.vue` 、`pages/ProductsView.vue` 、`pages/RelabelOrdersView.vue` 及详情页 | `api/pallets.ts` 、`api/relabelOrders.ts` ；换标详情展示 PDA 完工照片与复核人，状态区分待客户确认和待出库；路由是否公开以 `routes.ts` 为准 |
## 履约硬边界
2026-09-17 13:36:31 +08:00
- 智能排车来源支持 `RELABEL` （待出库换标单），切换后不传已选入库计划 ID，按客户已确认、卡车派送且未排车的换标库存查询。提交换标号从候选 `orderRefs` 读取，不能把展示的原入库单号 `orderNo` 当换标号；沿用来源库存、托盘与箱唛，不生成新入库单。
2026-09-16 15:21:01 +08:00
- 托盘管理单张打印：`pages/PalletsView.vue` 每行“打印”经 `api/pallets.ts` 的 `getPalletLabelPdf` 下载当前托盘一页 PDF；使用该行仓库 ID 与托盘 ID，权限复用托盘列表。Backend `warehouse-overseas-service` 的 `PalletLabelPrintService` 读取公共托盘；有 FBA 仓码的托盘与国内统一使用 Print `FBA_PALLET_A4_LANDSCAPE_V1` （ ， `INBOUND_MARK_V1` 。不在前端生成标签、改码或维护第二套模板。
2026-09-15 14:18:23 +08:00
2026-09-15 11:54:19 +08:00
- API 为 `api/dispatches.ts` 、`api/outbounds.ts` 、`api/deliveryOrders.ts` ； `lastleg-service/dispatch/` 、`delivery/` 、`dropship/` 。一件代发独立出库，从服务端库存位置选择并携带幂等键；普通出库及换标单经头程排车转出库，按托盘快照绑定头程箱唛，PDA 按托盘作业，详情展示箱唛与已拣数量；排车转派送按稳定 `dispatchNo` 进入服务端命令，可在 `PENDING_DEPARTURE` 、`PICKING` 、`READY_TO_DEPART` 状态执行并须在 PDA 发车前生成一张待出库单及按目的 FBA 仓拆分的派送单
2026-09-14 10:02:39 +08:00
- API 为 `api/exceptionOrders.ts` 、`api/customerVisits.ts` ； `lastleg-service/exceptionorder/` 、`customervisit/` 。异常处理只消费服务端 `allowedActions/version` ；完成时至少上传一份异常证据。派送退回先从服务端原出库拣货事实选择入仓单和可退箱数，不允许自由填写 SKU/数量；退回海外仓时必须选择服务端校验的目标托盘和库位，库存恢复、异常完成与派送 `RETURNED` 由服务端原子推进。回访附件和派送完成/状态均走海外真实 API
## 验证
2026-09-18 15:23:43 +08:00
- 一件代发出库候选选择：`pages/OutboundsView.vue` 按 `inventoryPositionId + skuCode` 保留跨页选择，只提供本页全选；查询/重置回到第一页，切换海外仓清空选择。提交仍校验同客户、同海外仓，数量取所选行的 `availablePackages` （箱数），不能按 SKU 件数替代；候选同时展示当前可出箱数对应的毛重、材积重和体积，创建出库单时服务端按本次出库箱数占实际入库箱数的比例冻结三项测量快照。候选交互回归见 `pages/OutboundsView.selection.test.ts` ；状态展示与取消门禁见 `pages/OutboundsView.test.ts` 、`pages/OutboundDetailView.test.ts` 。
2026-09-14 12:00:54 +08:00
- 转运审核定向测试：从应用根运行 `pnpm test src/modules/overseas-warehouse/api/warehouseTransfers.test.ts src/modules/overseas-warehouse/pages/prototypeContract.test.ts` ，分别核对客户作用域/API 与审核入口权限、状态。
- 排车列表编辑、托盘移除、BOL PDF 和转派送从 `pages/DispatchesView.vue` → `api/dispatches.ts` 进入；智能预排的候选、草稿柜与托盘锁从 `components/SmartDispatchDialog.vue` 进入。回归为 `pages/DispatchesView.test.ts` 、`pages/prototypeContract.test.ts` ，不要把列表操作与预排草稿当作同一入口。
2026-09-14 10:02:39 +08:00
- 从应用根按目标页面选择相邻测试：`pnpm test src/modules/overseas-warehouse/<目标测试路径>` ； `pnpm typecheck` 。应用完整门禁继续遵循上层指引。
- 索引变更从后端根运行 `./scripts/agents-index-contract.ps1` 。离线检查不代替真实 HTTP 和人工截图验收。
