# Admin 海外业务模块指引

## 路径基准与读取顺序

- 本文件适用于 `src/modules/overseas-business/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，采购与本土业务细则见 `../../../docs/business-index.md`。
- 本模块承载海外采购（`purchases`）、本土卡车（`trucks`）、本土散板（`looseboards`）和海外费用（`fees`）；卡车/散板复用页面，仓租库存位于费用页页签，无独立路由。
- 后端只查 `lastleg-service/` 的 `procurement/`、`trucking/`、`looseboard/`、`financefee/`、`storagerent/`；纯页面与文案不读后端。

## 页面与入口

| 目标 | 页面/路由 | API 与后端 |
|---|---|---|
| 海外采购订单列表与库存变化 | `pages/PurchaseOrdersView.vue`；`overseas-business/purchases` | `api/platformOverseasBusiness.ts`；`lastleg-service/procurement/` |
| 采购详情、分批收货/出库与签收 | `pages/PurchaseOrderDetailView.vue`、`components/ProcurementWorkflowPanel.vue`；`overseas-business/purchases/:purchaseId` | `api/platformOverseasBusiness.ts`、`api/procurementWorkflow.ts`、`api/procurementCommands.ts` |
| 采购订单编辑（采购商品、库存、快递） | `pages/PurchaseOrderEditView.vue`；`overseas-business/purchases/:purchaseId/edit` | `api/platformOverseasBusiness.ts`（`getOverseasPurchaseEditor`、`updateOverseasPurchase`） |
| 本土卡车订单列表 | `pages/TransportOrdersView.vue`；`overseas-business/trucks` | `api/platformOverseasBusiness.ts`；`lastleg-service/trucking/` |
| 本土卡车新增/编辑 | `pages/TransportOrderFormView.vue`；`overseas-business/trucks/new`、`overseas-business/trucks/:orderId/edit` | `api/platformOverseasBusiness.ts`；`components/TransportDemandForm.vue` |
| 本土散板订单列表与新增/编辑 | `pages/TransportOrdersView.vue`、`pages/TransportOrderFormView.vue`；`overseas-business/looseboards`、`.../new`、`.../:orderId/edit` | `api/platformOverseasBusiness.ts`；`lastleg-service/looseboard/` |
| 车次安排摘要 | `components/FleetArrangementSummary.vue` | 无直接请求；数据由 `fleetArrangement.ts` 与父页面传入 |
| 海外费用明细、审核、调价与资金/投递重试 | `pages/OverseasFeesView.vue`；`overseas-business/fees` | `api/overseasFees.ts`、`components/OverseasFeeRetryHistory.vue`；Backend `financefee/` |
| 业务单费用窗口与新增费用 | `components/BusinessDocumentFees.vue` → `BusinessOrderFees.vue`、`OverseasFeeEditor.vue` | `api/overseasFees.ts`；采购及其他业务单共用，不重建费用链路 |
| 仓租库存、计费明细与审核调价 | `components/StorageRentPanel.vue`、`StorageRentFeeDetails.vue`、`StorageRentFeeActions.vue` | `api/storageRent.ts`；Backend `storagerent/`，审核沿海外费用接口 |

## 关键边界

- 采购按 `baiyue-firstleg/lastleg-service/docs/procurement-workflow.md` 的七状态流程执行：审核、分批收货、客户确认、分批出库及签收扣采购库存；费用复用海外费用窗口，默认余额支付，不恢复旧两段样品节点。
- 本土卡车与散板是海外本地运输业务，区别于国内订舱拖车与客户排车；车型、司机与车队主数据归 `overseas-master-data`，本模块只消费。
- 费用、仓租及钱包/账单边界按 Lastleg 详细索引“海外业务费用来源”“自动仓租及出库资金门禁”核对；页面只消费返回状态和操作资格，不推定收付状态或重复记账。
- 列表与表单的客户、仓库、供应商候选一律取服务端结果，不从本地或名称推算；长整型 ID 按字符串透传。
- 同一路由组件的两种模式（卡车/散板）变更时，两侧都要回归，避免只改一侧。

## 验证

- 定向：`pnpm test src/modules/overseas-business/<目标测试>`；采购命令或费用变更同时核对 `lastleg-service` 合同。
- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。