# 业务实现边界

角色：按主题读取的跨端实现约束正文，承接原业务快速索引中的边界说明；不作为启动必读或部署进度来源。已知目标代码时直接工作，只有接口、状态、权限或业务归属不明确时才读取命中章节。

用 `rg -n -F '主题词' docs/业务实现边界.md` 定位标题，只读该标题到下一个同级标题。路径从工作区根或文中注明的应用 `src/` 起算；专题正式契约优先，新增专题规则只在其主文档维护，本文件保留必要的实现引用。

公共架构按主题选择[部署契约](测试环境单机部署与配置契约.md)或[认证与通信契约](统一认证与服务通信契约.md)，不因读取本文件而同时加载两份契约，也不在本文另建环境、会话或投递规则。

## 登录认证

范围依据：`docs/订单与客户/README.md`。

Admin `modules/auth/`、`core/auth/`；Client `modules/auth/`；Backend `auth/`、`iam/`。统一 Token 不携带角色或权限集；各端读取 Auth 登录/刷新响应的顶层授权快照用于展示，Gateway 与业务服务通过统一会话及 Auth 权威校验执行授权，不再依赖 Lastleg 安全投影

## 客户与企业

范围依据：`docs/订单与客户/README.md`、`docs/订单与客户/订单与客户头程订单闭环设计.md`。

Admin `modules/customers/`；Client `modules/tenant-management/`、`modules/account/`；Backend `iam/`、`auth/`、`file/`。公司联系电话/邮箱是企业资料，不作为成员登录标识且不要求跨企业唯一；成员登录手机号归账号链路，修改时同步 Auth 并撤销该账号会话。审核必填资质仅营业执照与统一社会信用代码；法人身份证选填，可在已有营业执照后单独补传或替换，营业执照仍须与统一社会信用代码整包提交；默认尺寸配置由 IAM 持久任务异步调用 `firstleg/`，未就绪不得审核通过

## 供应商与国内整柜

范围依据：`docs/国内货柜履约/国内货柜履约需求确认表.md`。

Admin `modules/suppliers/`、`modules/domestic-containers/`；Backend `warehouse/`；OpenAPI `supplier-v1.yaml`、`domestic-container-v1.yaml`

## 平台收货仓

范围依据：`docs/订单与客户/订单与客户头程订单闭环设计.md`。

Admin `modules/warehouses/`；Client `modules/first-leg/`；Backend `warehouse/`

## 头程订单、批量审核预览与入仓码关系

范围依据：`docs/订单与客户/README.md`、头程订单闭环设计。

Admin `modules/first-leg-orders/`、`modules/unified-orders/`；Client `modules/first-leg/api/inboundCodeAssociations.ts`、`modules/first-leg/`；Backend `order/` 的 `InboundCodeAssociationService`、`UnifiedOrderQueryService`、`BatchOrderReviewPreviewService` 与 `firstleg/`。Order 为 `SUBMITTED` 时，即使 Firstleg 已存在准备中入库投影，统一列表仍固定显示 `PENDING_REVIEW` 并提供审核动作；批量审核弹框只调用 `/orders/first-leg/batch-review-preview` 一次获取按请求顺序返回的快照，不逐票查询详情，主要展示入仓码而非内部订单 ID

## 客户头程订单批量导入

范围依据：当前 Order 契约。

Client `modules/first-leg/views/FirstLegOrdersView.vue`、`api/firstLeg.ts`；Backend `order/` 的 `MerchantBatchImportService`、`MerchantWarehouseCatalogClient`、`MerchantPricingCatalogClient` 与 `order-v1.yaml`。中文 XLSX 模板按当前客户动态生成地址、全部有效仓库和渠道下拉；导入时重新校验动态选项与客户归属，最多 50 行，只创建草稿，支持部分成功或整批原子模式

## 平台旧系统订单导入

范围依据：当前 Order 契约。

Admin `modules/unified-orders/pages/UnifiedOrdersView.vue`、`api/unifiedOrders.ts`；Backend `order/` 的 `PlatformLegacyOrderImportService` 与 `/api/platform/v1/orders/first-leg/legacy-import`。固定归属启用客户“IT测试公司”，保留旧入仓码，按当前公共仓库和客户价格簿逐行校验，成功行进入待审核

## 平台修改客户原始申报与履约渠道

范围依据：当前 Order/Firstleg 契约。

Admin `modules/unified-orders/components/OrderDeclarationEditorDialog.vue`、`api/unifiedOrders.ts`；Backend `order/` 的 `OrderDeclarationUpdateService` 与 `order-v1.yaml`，通过 `ORDER_DECLARATION_UPDATED_V1` 同步 `firstleg/` 的 `OrderDeclarationSyncService`。只修改申报快照，不覆盖仓库/PDA 实测、测量审核、箱码或已确认费用；渠道变化额外校验分柜、同柜、装柜可逆性与重新计价，国内收货仓或中转仓变化必须重新下单

## 脚本管理、全量验证与测试造数

范围依据：`baiyue-firstleg/scripts/AGENTS.md`、`baiyue-firstleg/scripts/README.md`。

本机重型检查经 `scripts/local-check.ps1` 统一限流，规则见 `docs/AI工程执行与协作约束.md`；Backend `scripts/` 为仓库级入口，`scripts/admin-test-env-modules/` 为 Admin HTTP 内部模块；服务局部脚本留在 `<service>/scripts/`，不得散落到 `src/test/scripts/`；真实 HTTP、部署或环境写入仍须当前轮明确授权

## 平台/企业 RBAC

范围依据：订单与客户契约；公共语义见 `docs/平台客户层级与权限契约.md`。

Admin `modules/iam/`、`core/access/`；Client `modules/tenant-management/`；Backend `iam/`、`auth/`

## 消息中心与站内通知

范围依据：触发业务的阶段/专题契约，收件箱以 IAM OpenAPI 为准。

Admin/Client `modules/notifications/`；Backend `iam/.../notification/`；生产者留在所属服务

## PDA 拣货与柜级装柜证据

范围依据：国内 PDA README、拣货原型、国内货柜履约需求确认。

PDA `pages/picking/`、`stores/picking.js`、`api/pda-loading.js`；证据以 `taskId + warehouseId` 进入任务专用 API，业务所有权固定真实 `containerBookingId`，不得按入仓单或客户拆分；上传以幂等键绑定包含文件内容的请求哈希，完全重放直接返回已有结果且不得重复上传 File；Backend `firstleg/`、`warehouse/`、`file/`

## 到仓测量、测量库位、箱规策略与头程计费

范围依据：`docs/入库测量与计费/README.md`；规则查 `baiyue-firstleg/firstleg/AGENTS.md` 对应入口。

Admin `modules/inbounds/measurement/InboundMeasurementDialog.vue`、`InboundMeasurementPanel.vue`，称重 `modules/inbounds/weight/components/WeightOcrPanel.vue`；Backend `firstleg/` 的 `InboundMeasurementService`、`MeasurementLocationOccupationService`、`FbaPricingService`。库位归 `warehouse/`，图片归 `file/`，OCR 归 `integration-service/`；只按实际调用增加服务指引

## 客户专属报价、柜级阶梯运费与费用调整

范围依据：当前 Firstleg 计价契约、`docs/入库测量与计费/README.md`。

Admin `modules/fba-pricing/carrier-rates/`、`modules/inbounds/fee/`、`modules/unified-orders/components/InboundFeeDetailManager.vue`；Backend `firstleg/` 的 `PlatformPriceBookService`、`ActivePriceBookEstimator`、`FbaPricingService`、`ContainerTierAmountAllocator`、`InboundFeeDetailService` 与 `fba-pricing-v1.yaml`。公共报价使用 `customerId=0`，客户专属报价按客户独立版本化并优先于公共 ACTIVE 版本；柜级区域重量阶梯只聚合同柜同客户中费用快照同为 `REGION_WEIGHT_TIER` 的成员并守恒分摊，混柜的固定仓价等其他模型不参与阶梯且保持原费用，装柜成员变化只重算未锁定的区域阶梯费用。人工调整计费量限系统基准上下 10% 且必须带版本、原因和二次确认；`PRIVATE_LAST_MILE_DELIVERY` 只允许私人目的仓；一件代发在预装确认前完成计价，`WAIT_PALLETIZE` 试算不得回退托盘化状态

## 箱唛、箱码与单箱测量

范围依据：`docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`、`docs/墨家设备测量上传接口说明-V3.md`。

Admin `modules/inbounds/measurement/`；Client `modules/first-leg/`；Backend 按 `firstleg/AGENTS.md` 的箱唛与测量入口

## 称重确认、整票库位块与部分拣货资源结算

范围依据：`baiyue-firstleg/firstleg/AGENTS.md` 的称重入口、`baiyue-firstleg/warehouse/AGENTS.md` 的 A0/资源结算规则。

Admin `modules/inbounds/weight/components/WeightOcrPanel.vue`；Backend Firstleg `MeasurementLocationOccupationService`、`InboundMeasurementService`、`MeasurementSubmissionService` → Warehouse `LocationBlockService`。国内整票资源结算按 `reservationId` 定位；称重、槽位容量和部分拣货的详细门禁留在所属服务指引

## 入库扣货、解除与凭证

范围依据：入库测量与计费、国内货柜履约契约。

Admin `modules/unified-orders/pages/UnifiedOrdersView.vue`、`modules/inbounds/core/api.ts`；Backend `firstleg/` 的 `InboundHoldService`、`InboundHoldGuard`、`InboundHoldEvidenceService`，文件归 `file/` 的 `INBOUND_HOLD_EVIDENCE`。扣货状态必须阻断后续物理履约写入；已发生拣货、装柜或出仓时禁止手工扣货/解除，命令携带版本与幂等键，只有进入不可变历史的凭证可下载

## 财务管理与柜级公共费用分摊

范围依据：`docs/财务管理/` 产品确认、五页验收契约、Firstleg-Finance 跨服务契约。

Admin `modules/finance/`、`modules/loading-lists/components/ContainerFeesPanel.vue`；Client `modules/finance/views/FinanceBillsView.vue`，账单行按 `inboundCode` 复用头程入仓关系详情；Backend `finance/`、`firstleg/`，契约 `container-fees-v1.yaml`；导出与凭证归 `file/`。跨客户公共柜费按柜内真实客户与订单归属原子建组，金额合计等于柜费总额，审核、驳回、调整和作废整组处理，单行入口不得破坏组一致性

## 客户资金账户、充值、授信与业务扣费

范围依据：[客户资金账户规则](财务管理/财务对账结算P1闭环.md#客户资金账户)；资金指令投递查[统一通信契约](统一认证与服务通信契约.md#b-逐事件直接投递与结果确认)。

Admin `modules/finance/pages/FinanceCustomerAccountsView.vue`；Client `modules/finance/views/FinanceAccountView.vue`；Backend `finance/` 的 `FinanceWalletService` 与三类 Wallet Controller。充值申请经 File 保存凭证，平台审核或手工充扣；余额、授信、冻结、结算和释放以 Finance 主账为准。海外业务经 `WALLET_COMMAND_REQUESTED/COMPLETED` Outbox 直接投递往返，不跨区同步调用钱包

## 订单编排、分柜、同柜不可拆组与柜次

范围依据：`docs/国内货柜履约/README.md`、`docs/国内货柜履约/国内货柜履约需求确认表.md`、`docs/统一订单主状态与操作契约.md`。

Admin `modules/unified-orders/api/coLoadGroups.ts`、`modules/unified-orders/`、`container-loading/`；Client `modules/first-leg/`；Backend `firstleg/loading/coload/`、`firstleg/split/`、`firstleg/loading/`、`order/`；同柜组按订单创建，由服务端冻结每票全部可用入仓片段，仅要求同国内仓、同渠道，允许跨客户及不同目的仓港

## 全局智能排柜、预装与真实集装箱号后补

范围依据：`docs/国内货柜履约/README.md`、`docs/国内货柜履约/国内货柜履约需求确认表.md`、`docs/统一订单主状态与操作契约.md`。

Admin `modules/container-loading/components/SmartLoadingDialog.vue` 内嵌 `pages/GlobalSmartLoadingView.vue`，柜次页 `SmartLoadingWorkbenchView.vue`，预装详情 `loading-lists/pages/PreloadPlanDetailView.vue`；PDA `pages/picking/`；Backend `firstleg/` 的 `PlatformSmartLoadingController`、`SmartLoadingService`、`PendingReviewOrderClient`、`loading/`，待审核事实来自 Order `PendingReviewOrderQueryService`。全局候选覆盖 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING`，状态只用于筛选展示，能否加入以服务端 `canAssign` 为准；待审核/待测量可提前占位，但确认预装或启动 PDA 前必须进入 `WAIT_SPLIT`。暂估明细的 `totalPackageCount/remainingPackageCount` 在测量前取 Order 原始申报箱数，测量完成后取最新已审核测量箱数，读取补充失败只回退当前已分配数，写入调整仍重新校验权威数量。同柜不可拆组仅在全员命中状态集合时作为一个分页与分配单元；人工加入允许跨渠道，智能推荐仍按柜次渠道。计划可一次性移除全部未拣明细，但任一成员已拣的同柜组必须整组保留。创建柜次时原子生成唯一预装计划，加入入仓码即建立关联；真实集装箱号不阻塞订舱关联，但确认预装和创建 PDA 任务前必须补齐。历史缺号任务允许在预装详情首次补录，保存后恢复 PDA 可进入状态

## 客户入库结果与头程费用确认

范围依据：入库测量与计费主流程、当前 Firstleg 契约。

Client `modules/first-leg/components/InboundBillingPanel.vue`、`api/inboundBilling.ts`；Backend `firstleg/` 的 `MerchantInboundBillingController`、`MerchantInboundBillingService`、`FbaPricingService` 与 `firstleg-v1.yaml`。客户仅能确认本客户 `SENT` 的最新费用版本，提交 `expectedFeeVersion` 与幂等键；确认记录当前成员和时间并永久锁定该版本，平台不得再修改

## 订舱资料、放舱、出仓前船期与订舱级拖车

范围依据：国内货柜履约 README、需求确认和实施边界。

Admin `modules/ocean-bookings/`、`port-schedules/`、`trucking/`；Backend `firstleg/oceanbooking/`、`firstleg/portschedule/`、`TruckAppointmentService`。拖车预约由 `RELEASED` 订舱拥有，不按客户、柜次、装柜计划或真实柜号归属；每个订舱最多一张非终态拖车单，创建候选由服务端排除缺提单/有效订舱文件或已有有效拖车单的订舱；PDA 装柜完成不推进拖车状态；全部要求货柜确认国内离仓后自动完成，人民币拖车费按实装体积分摊为柜次应付并经 Finance Outbox 入池

## 目的港码头拖车与还空预警

范围依据：`docs/海外仓业务/README.md`。

与订舱级拖车预约是不同生命周期。Admin 海外清关提柜列表/详情 `modules/container-loading/pages/OverseasContainersView.vue`、`modules/container-loading/pages/OverseasContainerDetailView.vue`；Firstleg 拖车 API `api/terminalDrayages.ts`，柜级到仓 API `api/containerArrivalTimes.ts`。原预约/实际提柜列改为预计/实际到仓：预计时间由平台在列表快捷选择并同步 Lastleg 整柜尾程订单，实际时间取海外 PDA 首次开始收货；车队、邮件、还柜与 `unloadingCompletedAt + 72h` 预警仍归 `firstleg/terminaldrayage/`。

## 整柜报关资料与完成文件

范围依据：国内货柜履约契约。

装柜完成后由 Admin `modules/container-loading/components/ContainerCustomsPanel.vue` 管理整柜报关，Client `modules/first-leg/components/CustomsDocumentsDialog.vue`、`api/customs.ts` 按订单处理本客户退税资料；Backend `firstleg/customs/container/`、`customs-v1.yaml`，文件归 `file/`。客户资料可覆盖同柜多个退税入仓码，开始报关后冻结；平台逐资料回传完成文件，全买单柜走平台确认与明细导出

## 国内出仓确认

范围依据：国内货柜履约契约。

Admin `modules/outbound-dispatch/`；Backend `firstleg/outbound/dispatch/`

## 客户统计与平台日志

范围依据：[客户统计指引](../apps/admin-web/src/modules/customers/AGENTS.md)、[操作审计指引](../apps/admin-web/src/modules/audit/AGENTS.md)，按对象选一项。

Admin `modules/customers/`、`modules/audit/`；Backend `firstleg/customerstatistics/`、`audit-service/`

## 客户工作台账户与设置

范围依据：订单与客户契约。

Client `modules/account/`、`system/`、`tenant-management/`；Backend `iam/`、`auth/`

## 企业订单与跨境业务

范围依据：订单与客户、国内货柜履约契约。

Client `modules/order-management/`、`cross-border/`；Backend `order/`、`firstleg/`、`integration-service/`

## 海外接柜、入库与库内库存

范围依据：`docs/海外仓业务/README.md`。

Admin 按 `apps/admin-web/AGENTS.md` 海外模块入口；海外入口 `gateway/`；尾程/入仓/换标/库存 `lastleg-service/`；仓库主档归国内 `warehouse/`，库位/托盘/锁归 `warehouse-overseas-service/` 并只引用国内 warehouseId；与排车、出库、派送共同组成海外仓全流程

## 尾程订单控制与柜级入仓计划转换

范围依据：`docs/海外仓业务/README.md`。

Admin `modules/overseas-warehouse/pages/LastMileOrdersView.vue`、`LastMileOrderDetailView.vue`、`api/lastMileOrders.ts`；Backend `lastleg-service/` 的 `LastlegOrderController`、`LastlegOrderCommandService`、`InboundPlanService`、`ContainerInboundPlanConversionCoordinator`，资源归 `warehouse-overseas-service/` 的 `WarehousePalletBatchService`。`orders/container-summaries` 按 `sourceContainerBookingId` 跨客户聚合并分页返回全部稳定来源柜，已完成计划转换的柜仍保留用于接柜仓查询与修改；生成动作只消费 `allPlansReady/pendingPlanCount/resourcePendingPlanCount`，详情不受列表分页截断。确认前从 `/inbound-plans/container-preview` 读取服务端分组、托数、阻断项与 `snapshotVersion/snapshotHash`；`convert-container` 锁柜重算后先批量预留真实托盘，再本地原子生成剩余独立计划并确认资源，失败仅补偿未确认资源，同柜重放不得产生第二批资源。单票手工计划保存后，全柜计划齐全且预览就绪时自动生成并绑定托盘资源，一票柜立即触发；`resourcePendingPlanCount` 表示自动生成异常后的重试入口，资源未齐不得进入 PDA 接柜。自动入口见 Lastleg `ContainerInboundPlanConversionCoordinator.convertManualAndAutoMaterialize`。单票可维护完整入库计划、暂扣/解除及八行人工节点快照；命令提交订单版本与幂等键，新增暂扣只允许完成入库后执行并仅阻断该票后续排车/出库，不阻断入库计划或入库作业；人工节点首次保存后固定 `MANUAL` 来源且不得回退柜级节点

### Admin 入仓计划页面约束

代码路径相对 `apps/admin-web/src/modules/overseas-warehouse/`，含 `../` 的路径按模块关系解析。

柜子工作台按 `sourceContainerBookingId` 消费 `/orders/container-summaries`；服务端分页返回全部稳定来源柜，计划已经齐全的柜仍保留用于接柜仓查询和修改，并按冻结 `plannedArrivalAt` 升序、空值最后排序。详情返回全柜订单且不受列表分页截断；单票手工计划保存后，由服务端在整柜最后一票计划齐全时自动生成并绑定全柜托盘码，一票柜立即生成；`resourcePendingPlanCount` 只表示自动生成异常的重试入口，不是正常人工步骤。柜级确认弹框先调用 `/inbound-plans/container-preview`，按服务端 FBA/一件代发/私人地址分组展示头程已有、海外仓补充和最终托数以及 `readiness/blockers`；散货最终托数不得少于头程已有托盘码，差额连续补码且不阻断流程；一件代发必须严格按不可变头程封托托盘数整体入库，单票表单托数锁定且服务端再次失败关闭校验。前端不计算托数、不逐票建计划、不预占托盘，再把同一 `snapshotVersion/snapshotHash` 原样提交 `/inbound-plans/convert-container`，快照冲突后重新获取预览。服务端只为剩余订单逐票生成独立计划，并为异常遗留的人工计划补齐真实托盘，整批原子且重放不得产生第二批资源。单票完整入库计划、暂扣/解除和八行人工节点均从 `api/lastMileOrders.ts` 提交订单版本与幂等键；入库弹框每次打开通过 `/orders/container-arrival-times/query` 读取柜级权威到仓结果，不使用订单列表旧快照作为显示或提交门禁；优先展示人工时间，未维护且未建计划时展示服务端按到港当地日期加两个自然日返回的 `plannedDate/isDefault`，默认日期不补零点，首个计划生成后沿用冻结日期。加载中、读取失败、缺失或同柜不一致时阻止提交；预计到仓时间不进入人工计划请求，服务端按整柜校验并写入同一日期；入仓码只读展示并提交订单冻结值，不允许人工改写。新增暂扣只在 `INBOUND_COMPLETED` 开放，解除暂扣保持可用；暂扣不阻断入库计划，只限制后续排车和出库。人工节点一经保存不得回退柜级节点。转仓候选只取 `../iam/api/platformIam.ts` 的平台公共 `ACTIVE + FBA` 仓主档；Backend `lastleg-service/`

## 海外仓 PDA

范围依据：`apps/pda-overseas-uniapp/AGENTS.md`；执行规则查 `baiyue-firstleg/lastleg-service/AGENTS.md`，跨模块流程才查海外仓 README。

入仓 `src/pages/operation/`、`src/api/inbound.js`；排车与出库 `src/pages/dispatch/`、`src/pages/outbound/`、`src/api/fulfillment.js`。Backend `lastleg-service/inboundplan/pda/`、`dispatch/pda/`、`delivery/`；统一经 `gateway/`。柜级收货与单票客户隔离按 Lastleg“PDA 入仓”规则核对

## 海外采购、本土卡车与散板

范围依据：`docs/海外仓业务/README.md`。

Admin `modules/overseas-business/`；Client `modules/cross-border/`；Backend `lastleg-service/` 的 `procurement/`、`trucking/`、`looseboard/`；统一经 `gateway/`

## 采购样品、货款、装箱清单、面单、预估快递费、国内收货寄客户

范围依据：`docs/海外仓业务/采购订单样品履约流程变更需求.md`。

采购流程变更入口；代码从上述采购模块进入

## 海外仓库与通用资料

范围依据：主档查 [Warehouse 指引](../baiyue-firstleg/warehouse/AGENTS.md)，海外库位、托盘与锁查 [Warehouse Overseas 指引](../baiyue-firstleg/warehouse-overseas-service/AGENTS.md)。

全部仓库主档进入 Admin `modules/warehouses/` 与国内 `warehouse/`；海外库位/托盘/锁进入 `warehouse-overseas-service/` 并引用国内 warehouseId；报价、汇率、车辆按海外服务实际契约

## 车辆管理、司机证照、保养加油、车辆维修/故障/救援/异常、外接货与车次

范围依据：`apps/admin-web/src/modules/overseas-master-data/AGENTS.md`、`baiyue-firstleg/lastleg-service/AGENTS.md`；原型范围有疑问时查 `docs/海外仓业务/车辆管理原型梳理与任务规划.md`。

Admin `modules/overseas-master-data/`；Backend `lastleg-service/fleet/`，接口 `lastleg-service/src/main/resources/openapi/fleet-drivers-v1.yaml`、`fleet-trips-v1.yaml`、`fleet-vehicle-records-v1.yaml`；证照与运维照片存储查 `file/AGENTS.md`

## 拼车需求池、车次余位、销售拼车意向

范围依据：`docs/海外仓业务/内部拼车需求池首版开发契约.md`、`apps/admin-web/src/modules/overseas-master-data/AGENTS.md`。

复用 Lastleg Fleet 与本土业务；区分车次余位发布和客户订单，不从需求池生成第二套库存或费用

## 国内出仓后船节点

范围依据：`docs/海外仓业务/README.md`。

Admin `modules/port-schedules/`、`ocean-bookings/`、货柜详情；Backend `firstleg/portschedule/`、`integration-service/`；从确认国内出仓查询至目的港到达、提柜和还柜。节点按 `containerBookingId` 柜级聚合，跨区事件使用 `tenantId=0` 平台技术范围，不携带或校验客户

## 海外出库、排车、派送、异常与回访

范围依据：排车改造查[排车列表统一作业改造契约](海外仓业务/排车列表统一作业改造契约.md)；既有缺陷修复查[排车流程修复规划](海外仓业务/排车流程修复规划.md)。

Admin `modules/overseas-warehouse/pages/DispatchesView.vue`、`DispatchDetailView.vue`、`OutboundsView.vue`、`DeliveryOrdersView.vue`、`ExceptionOrdersView.vue`、`CustomerVisitsView.vue`；Backend `lastleg-service/dispatch/`、`delivery/`、`dropship/`、`exceptionorder/`、`customervisit/`；统一经 `gateway/`

以下 Admin 条款来自模块指引，按具体页面选读；排车状态、照片门禁及自动发车时机以本节排车现行契约为准。代码路径相对 `apps/admin-web/src/modules/overseas-warehouse/`，含 `../` 的路径按模块关系解析。

### Admin 出库与派送页面约束

`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/`

### Admin 排车审核附件

- 排车调度／理货审核分区仅显示审核、详情；审核弹框的车辆图片、司机照片和驾驶证照片通过既有本车附件接口上传，随 `ReviewCommand.attachments` 保存，不调用资源编辑命令。已有资源与审核附件只读预览，详情合并展示；当前审核权限与服务端 Gate 控制上传及提交，列表查看权限控制读取。

### Admin 一件代发出库候选

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

### Admin 货物计划与装车命令

- 装车完成通过`completeDispatchLoading`一次提交，返回状态、照片可上传阶段与自动推进条件按本节排车现行契约消费；原请求恢复不重建单据。未知费用保持未确认，由既有后台费用管理维护，不按金额推断覆盖或重复记费。已有排车加货和移货仅从`SmartDispatchDialog.vue`内的`SmartDispatchExistingCargo.vue`进入；移货必须使用`GET items`返回的真实dispatchItemId及逐项remove Gate；路线仅重排`GET route`返回的既有全部目的地，包含外接点，不能新增或猜测目的地。附件沿`DispatchEvidenceFiles.vue`的本车鉴权上传/读取，上传与主单引用保存分开。

- 排车列表车辆信息编辑、BOL PDF 和装车完成从 `pages/DispatchesView.vue` → `api/dispatches.ts` 进入；列表和详情不另设添加／移除货物入口。货物计划统一由 `components/SmartDispatchDialog.vue` 承载：新建使用候选、草稿及托盘锁，已有排车经 `components/SmartDispatchExistingCargo.vue` 读取实际明细并按版本增减；两类服务端命令不得混用。原加货／移货未知请求也在智能排车恢复。回归为对应组件测试、`pages/DispatchesView.test.ts`、`pages/DispatchDetailView.test.ts` 及 `pages/prototypeContract.test.ts`。

### Admin 取消与费用展示

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

### Admin 业务导出

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

### Admin 装车照片与资料入口

- 装车照片与资料从 `components/DispatchDocumentsDialog.vue` → `DispatchLoadingDocuments.vue` → `api/dispatchLoadingDocuments.ts` 进入；五框按整车保存，不依赖派送权限或派送单。原上传/绑定结果未知保留原文件、版本及键；明确版本冲突后刷新再用原文件保存。两端共享及自动推进规则唯一见排车正式契约。

## 海外业务费用来源与客户财务

范围依据：当前实现查财务契约与统一认证与服务通信契约；阶段 0A—0E 开发再读 `docs/财务管理/海外仓费用统一接入阶段0技术契约.md`。

当前 V1 由 `lastleg-service/financefee/` 校验海外入仓、采购、美国卡车、本土散板和海外仓服务费，通过完整快照和 Outbox 直接投递 Finance 内部入口入池；阶段 0 目标改为收费身份/候选版本、Finance 接受或拒绝结果事件及版本化资金计划。必须沿代码确认落地范围，不把技术契约当成已实现状态；Client 仍只读取获准客户财务

## 自营销量与领星统计

范围依据：`docs/自营业务/README.md`。

领星 WMS 自研系统（OMP）、经营总览图表、自营 SKU 日销量、热销与滞销排行、分仓产品库存与可售天数、库存周转、数据采集：先读 `apps/admin-web/src/modules/self-operated/AGENTS.md`；查询与采集编排查 `baiyue-firstleg/lastleg-service/AGENTS.md` 的自营入口，签名/限流/供应商分页问题才读 `baiyue-firstleg/integration-service/AGENTS.md`。区别于整箱库存和客户 WMS 作业库存。

自营专题按任务选择：总览图形/下钻查 `docs/自营业务/经营总览图表设计.md`，库存周转查 `docs/自营业务/库存周转视图设计.md`，采集交互查 `docs/自营业务/数据采集页面设计.md`，查询性能查 `docs/自营业务/领星统计查询性能优化方案.md`，外部接口联调查 `docs/自营业务/领星WMS接口联调手册.md`。架构/表结构不明时从 `docs/自营业务/README.md` 定位一期方案，不默认同时读取所有专题。

## 预约管理与工作日历

范围依据：`docs/海外仓业务/预约工作日历V13变更说明.md`（业务规则）；`docs/海外仓业务/预约工作日历开发协作契约.md`（接口与文件边界），按本次问题选一项。

美国各类预约统一总览、提柜/用车/送仓预约梳理：`docs/海外仓业务/美国预约管理统一总览与优化方案.md`（设计建议）；实际维护仍按下述来源模块进入。

预约工作日历、多客户共车、中转分批后送、改期取消、重新预约和未定日期事项：先读 `docs/海外仓业务/预约工作日历V13变更说明.md`（正式业务规则与验收），再读 `docs/海外仓业务/预约工作日历开发协作契约.md`（接口与文件边界）；权威业务事实仍由下述来源模块维护。

预约管理、预约列表、到港/排车/还柜/计划到仓四类日历：Admin `apps/admin-web/src/modules/appointment-calendar/`，当前入口与日期规则见 `docs/海外仓业务/预约工作日历V13变更说明.md` 的“2026-10-19 当前预约列表收敛规则”；原送仓业务仍从 `docs/海外仓业务/README.md` 的“预约送仓”进入。排车只取海外仓送往 FBA/客户仓的真实车次，区别于订舱级拖车和港口提柜。

## 退货预报、签收、库存与合箱

范围依据：`baiyue-firstleg/lastleg-service/docs/business-index.md` 的退货入口。

退货预报、签收、库存与合箱：Client `modules/overseas-warehouse/views/ReturnOrdersView.vue`、`ReturnInventoryView.vue`；Admin `modules/overseas-warehouse/pages/ReturnInventoryManagementView.vue`；海外 PDA `src/pages/return-receipt/return-receipt.vue`、`src/pages/return-packing/return-packing.vue`，API 与检查入口见 `apps/pda-overseas-uniapp/AGENTS.md`；Backend `lastleg-service/returnreceipt/`，执行规则先读 `baiyue-firstleg/lastleg-service/AGENTS.md`，详细接口与状态按需查 `baiyue-firstleg/lastleg-service/docs/business-index.md` 的退货入口，OpenAPI 为 `overseas-business-v1.yaml`。客户预报 → 平台审核 → PDA 签收 → 退货箱/SKU 库存 → 同客户合箱 → `delivery/` 退货出库；两个 PDA 页面均在 `src/pages.json` 注册，由 `src/data/overseas-workbench.js` 提供入口，真机验收另取证。派送异常退回仍归 `exceptionorder/`。

## 散货托盘码生成、打印与跨区传递

范围依据：`docs/打印标签维护/README.md`；各应用/服务最近指引。

散货托盘码生成、打印与跨区传递：Admin `modules/loading-lists/components/PalletLabelPrintDialog.vue`；Firstleg `LoadingPalletLabelService`、`LoadingCompletedOutboxService`；Lastleg `LastlegSourcePalletMapper`、`InboundPlanService`。从各项目最近指引继续定位；散货 FBA 标签与一件代发实装托盘分别取各自冻结事实。