Merge release/test and preserve pickup execution and photo workflows

2026-10-21 17:35:43 +08:00
parent fde16235ea 22e60248d2
commit c367fadf09
39 changed files with 1093 additions and 120 deletions
@@ -22,11 +22,12 @@
 | 退货预报审核、退货驳回 | `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/` |
+| 仓储转运审核、审核通过 | `pages/LastMileOrdersView.vue`、`components/WarehouseTransferReviewDialog.vue` | `permissions.ts` 的 `warehouseTransferApprove`；仅 `WAREHOUSE_TRANSFER + PENDING_REVIEW` 行开放。当前弹框仅提交 `APPROVE`，携带该行客户和转运单号；无驳回按钮 |
+| 转运驳回、REJECT 接口能力 | `api/warehouseTransfers.ts` 的 `reviewWarehouseTransfer` | API 支持 `APPROVE/REJECT` 与 `remark`；不据此推定当前弹框提供驳回操作，界面能力沿上一行组件核对 |
+| 尾程订单控制与柜级入仓计划转换 | `pages/LastMileOrdersView.vue`、`pages/LastMileOrderDetailView.vue` | `api/lastMileOrders.ts`；[入仓计划页面约束](../../../../../docs/业务实现边界.md#admin-入仓计划页面约束)，仅计划/状态/请求行为变化时查 |
 | 入仓单、入仓计划、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/SmartDispatchExistingCargo.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/DispatchesView.vue`、`pages/DispatchDetailView.vue`、`components/SmartDispatchDialog.vue`、`components/SmartDispatchExistingCargo.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`；[出库与派送页面约束](../../../../../docs/业务实现边界.md#admin-出库与派送页面约束)，候选选择另查下表 |
 | 异常退回与客户回访 | `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` 的库位维护/删除入口 |
@@ -34,24 +35,33 @@

 ## 履约硬边界

- 排车详情固定四个彩色图标页签：车辆信息、排车信息、单据信息、关联订单明细。四个作业阶段及审核分区、逐动作Gate由服务端返回；取消独立于阶段。装车完成须真实PDA拣货核平，装车完成自动生成派送单并直接进入派送中，无独立安排派送或发车确认；Admin和PDA共用正式版本化命令。已有单写入提交recordVersion（0合法）、原幂等键和完整载荷；未知结果保留原请求核对，成功后另读当前事实。
+- 排车详情固定四个彩色图标页签：车辆信息、排车信息、单据信息、关联订单明细。五个作业阶段及审核分区、逐动作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`。不在前端生成标签、改码或维护第二套模板。
+- 托盘标签从 `pages/PalletsView.vue` → `api/pallets.ts` 的 `getPalletLabelPdf` 下载服务端 PDF，传该行仓库与托盘 ID，复用列表权限；不在前端生成标签或维护模板、尺寸、编码。模板/接口变化才查 [Print 指引](../../../../../baiyue-firstleg/print/AGENTS.md)的托盘入口及[标签维护](../../../../../docs/打印标签维护/README.md)，纯按钮文案不追加打印资料。

- API 为 `api/dispatches.ts`、`api/outbounds.ts`、`api/deliveryOrders.ts`；Backend `lastleg-service/dispatch/`、`delivery/`、`dropship/`。一件代发独立出库，从服务端库存位置选择并携带幂等键；换标只有平台卡车进入排车，普通自提、亚马逊自提、客户自提及快递由客户确认直接创建出库任务。整车派送在装车完成事务内自动生成；每客户一张出库单，每客户每目的地一张派送单，公开完整数组，不能回退为单个outboundNo或按客户拆排车头。
+- API 为 `api/dispatches.ts`、`api/outbounds.ts`、`api/deliveryOrders.ts`；Backend `lastleg-service/dispatch/`、`delivery/`、`dropship/`。一件代发独立出库，从服务端库存位置选择并携带幂等键；换标只有平台卡车进入排车，普通自提、亚马逊自提、客户自提及快递由客户确认直接创建出库任务。出库/派送建单时机按[排车现行契约](../../../../../docs/海外仓业务/排车列表统一作业改造契约.md)执行；每客户一张出库单，每客户每目的地一张派送单，公开完整数组，不能回退为单个outboundNo或按客户拆排车头。
 - API 为 `api/exceptionOrders.ts`、`api/customerVisits.ts`；Backend `lastleg-service/exceptionorder/`、`customervisit/`。异常处理只消费服务端 `allowedActions/version`；完成时至少上传一份异常证据。派送退回先从服务端原出库拣货事实选择入仓单和可退箱数，不允许自由填写 SKU/数量；退回海外仓时必须选择服务端校验的目标托盘和库位，库存恢复、异常完成与派送 `RETURNED` 由服务端原子推进。回访附件和派送完成/状态均走海外真实 API

+## 作业细则按需入口
+
+仅接口、状态、权限或业务行为变化时读命中段；纯文案、样式沿当前代码，不逐条读取。
+
+| 任务 | 规则正文 |
+|---|---|
+| 排车审核附件 | [对应条款](../../../../../docs/业务实现边界.md#admin-排车审核附件) |
+| 一件代发出库候选 | [对应条款](../../../../../docs/业务实现边界.md#admin-一件代发出库候选) |
+| 货物计划与装车命令 | [对应条款](../../../../../docs/业务实现边界.md#admin-货物计划与装车命令) |
+| 取消与费用展示 | [对应条款](../../../../../docs/业务实现边界.md#admin-取消与费用展示) |
+| 业务导出 | [对应条款](../../../../../docs/业务实现边界.md#admin-业务导出) |
+| 装车照片与资料入口 | [对应条款](../../../../../docs/业务实现边界.md#admin-装车照片与资料入口) |
+
 ## 验证

 - 排车调度／理货审核分区仅显示审核、详情；车辆图片、司机照片和驾驶证照片在维护车辆司机时通过既有本车附件接口上传，随资源编辑命令保存，司机照片使用 `driver.evidence.photoFileIds`。三类照片横向并排、名称显示在照片下方；审核弹框只读预览，合并展示资源照片及历史审核附件。维护权限与服务端 Gate 控制上传及保存，审核权限控制审核提交，列表查看权限控制读取。

- 一件代发出库候选选择：`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 与审核入口权限、状态。
- 装车完成通过`completeDispatchLoading`一次提交，结果仅接受`DELIVERING`；原请求恢复不重建单据。未知费用保持未确认，由既有后台费用管理维护，不按金额推断覆盖或重复记费。已有排车加货和移货仅从`SmartDispatchDialog.vue`内的`SmartDispatchExistingCargo.vue`进入；移货必须使用`GET items`返回的真实dispatchItemId及逐项remove Gate；路线仅重排`GET route`返回的既有全部目的地，包含外接点，不能新增或猜测目的地。附件沿`DispatchEvidenceFiles.vue`的本车鉴权上传/读取，上传与主单引用保存分开。
- 出库取消提示先解除车次关联，取消后仍须在排车列表释放原排车占用；不提示库存已自动回滚。派送详情费用读取reviewStatus/sourceStatus/voidStatus，同一详情响应展示待财务确认、待财务处理、确认作废，不逐行查询，也不把取消成功视为费用作废。货柜费用面板直接消费同一费用来源接口，待确认时同样禁止调整和重复作废，沿用原页面/弹框承载。
- 排车列表车辆信息编辑、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`。
- 从应用根按目标页面选择相邻测试：`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。
+- 纯文案/纯展示只核对差异；业务逻辑变化选择直接对应测试，不因文档引用某测试就自动执行。
+- 转运审核组件/请求逻辑变化：定向选择 `components/WarehouseTransferReviewDialog.test.ts`、`api/warehouseTransfers.test.ts`；入口、权限或状态变化再加 `pages/prototypeContract.test.ts`。
+- 出库候选/选择变化选 `pages/OutboundsView.selection.test.ts`；状态/取消变化选 `pages/OutboundsView.test.ts`、`pages/OutboundDetailView.test.ts`。排车选择受影响组件或详情页测试，入口变化再加原型合同。
+- 命令从应用根按 `pnpm test src/modules/overseas-warehouse/<目标测试路径>` 运行，并经工作区限流入口；类型关系、模板绑定或模块引用受影响时按应用根选择最小类型检查，不自动升级全量。
+- 指引/索引修改后从后端根运行一次 `./scripts/agents-index-contract.ps1`；不以离线结果代替真实 HTTP 或人工截图验收。