# Client 海外仓模块指引

## 路径基准与读取顺序

- 本文件适用于 `src/modules/overseas-warehouse/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，页面与字段细则见 `../../../docs/business-index.md`。
- 五类自助业务共用三个页面文件：`WarehouseServiceView.vue`（贴标、仓储转运、货物废弃）、`ReturnOrdersView.vue`（退货预报与签收）、`ReturnInventoryView.vue`（退货库存与箱号）；按路由区分模式。
- 后端只查 `lastleg-service/` 的 `relabel/`、`transfer/`、`discard/`、`returnreceipt/`；资源与库位归 `warehouse-overseas-service/`；纯页面与文案不读后端。

## 页面与入口

| 目标 | 页面/路由 | API 与后端 |
|---|---|---|
| 贴标申请列表、新建、详情 | `views/WarehouseServiceView.vue`；`overseas-warehouse/labeling`、`.../create`、`.../:detailNo/detail` | `api/warehouseServices.ts`；`lastleg-service/relabel/` |
| 仓储转运列表、详情与入库测量 | `views/WarehouseServiceView.vue`；`overseas-warehouse/storage-transfer`、`.../:detailNo/detail` | `api/warehouseServices.ts`、`api/transferPickups.ts`；`components/TransferPickupProgressPanel.vue`；`lastleg-service/transfer/` |
| 货物废弃列表、新建与详情 | `views/WarehouseServiceView.vue`；`overseas-warehouse/cargo-disposal`、`.../:detailNo/detail` | `api/warehouseServices.ts`、`utils/discardDocuments.ts`；`lastleg-service/discard/` |
| 退货预报、新建与签收详情 | `views/ReturnOrdersView.vue`；`overseas-warehouse/return-relabel`、`.../create`、`.../:returnNo/detail` | `api/returnOrders.ts`、`utils/returnReceiptDisplay.ts`；`lastleg-service/returnreceipt/` |
| 退货库存查询 | `views/ReturnInventoryView.vue`；`overseas-warehouse/return-inventory` | `api/returnInventory.ts` |
| 退货箱号与箱内明细 | `views/ReturnInventoryView.vue`；`overseas-warehouse/return-cartons`、`.../:cartonMark/detail` | `api/returnInventory.ts`、`utils/returnReceiptDisplay.ts` |
| 换标完工确认与驳回提示 | `components/CompletionConfirmationDialog.vue`、`components/ReviewRejectionNotice.vue`、`components/RelabelDocumentsPanel.vue` | `api/warehouseServices.ts`、`utils/relabelSkuDisplay.ts` |

`views/LabelingView.vue`、`views/ReturnInboundView.vue`、`views/ReturnOutboundView.vue` 当前未在 `routes.ts` 注册；改动前先确认是否已废弃或仅被内嵌，不要据此认定页面开放。

## 关键边界

- 换标申请必须提交正数 CNY `chargeAmount`；金额与资金状态以服务端返回为准，不在客户端模拟冻结成功。
- 退货预报与签收只消费服务端状态与箱号；退货库存按箱号和 SKU 查询，箱内明细以服务端实收为准，不按预报箱数推算。
- 仓储转运的测量与打托由仓库侧完成，客户端只读展示与确认；转运进度以 `TransferPickupProgressPanel.vue` 消费的服务端事实为准。
- 货物废弃在待审锁定与实际确认扣减之间不可回退，前端只按服务端允许动作开放按钮。
- 页面承载方式按已确认原型：贴标、转运、废弃为独立路由页面，退货预报为独立页面，不擅自改为弹框或抽屉。

## 验证

- 定向：`pnpm test src/modules/overseas-warehouse/<目标测试>`；接口或类型变化同时运行 `pnpm typecheck`。
- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。