优化

2026-09-04 14:41:23 +08:00
parent 760c7b561d
commit 5e013489e0
3 changed files with 36 additions and 6 deletions
@@ -18,12 +18,12 @@
 | 平台测量/OCR 与箱规计费快照 | `controller/PlatformInboundMeasurementController.java`、`service/InboundMeasurementService.java`、`CartonMeasurementService.java`、`CustomerDimensionWeightingService.java`；手工单箱测量保存实际尺寸、可选外箱修正、`chargeRuleId` 与 `coefficientMode`，计算结果以服务端返回值为准 |
 | 箱唛箱码生成、打印与测量绑定 | 审核建单生成钩子 `controller/InternalInboundOrderController.java`；生成/解析 `service/InboundCartonLabelService.java`、`repository/InboundCartonLabelRepository.java`；平台与客户打印 `controller/PlatformInboundOrderController.java`、`MerchantInboundCartonLabelController.java`、`service/InboundCartonLabelPrintService.java`；基线/升级 SQL 为 `src/main/resources/db/phase2-inbound-carton-label.sql`、`phase2-carton-label-versioning-migration.sql` |
 | 墨家设备测量上传 | `controller/OpenApiInboundMeasurementController.java`、`dto/MojiaMeasurementDtos.java`、`service/MojiaMeasurementOpenApiService.java`、`security/MeasurementRequestAuthenticator.java`；接口契约见 `src/main/resources/openapi/firstleg-v1.yaml` 与 `../../docs/墨家设备测量上传接口说明-V3.md` |
+| 称重确认与整票库位块 | `service/MeasurementLocationOccupationService.java`、`InboundMeasurementService.java`、`MeasurementSubmissionService.java`、`client/WarehousePalletLocationClient.java`；Warehouse 块服务见 `../warehouse/src/main/java/com/baiyue/warehouse/service/LocationBlockService.java`，接口与上架引导见 `src/main/resources/openapi/firstleg-v1.yaml` |
 | 审核与初始计价 | `controller/PlatformInboundMeasurementReviewController.java`、`service/MeasurementReviewService.java`、`service/InitialInboundPricingService.java`、`dto/MeasurementApprovalResponse.java` |
 | 客户四档箱规与默认算法 | `controller/PlatformCustomerDimensionConfigController.java`、`service/CustomerDimensionConfigService.java`、`repository/CustomerDimensionConfigRepository.java`；固定 `SMALL/MEDIUM/LARGE/EXTRA_LARGE`，默认算法只允许 `ADD/MULTIPLY` |
 | FBA 主数据/计费与客户规则 | `controller/PlatformFbaMasterDataController.java`、`PlatformFbaPricingController.java`、`service/FbaPricingService.java`、`repository/FbaPricingRepository.java`；客户规则可保存多个版本，但每个客户仅一条默认规则，计算请求可提交已确认的重量/体积选择值 |
 | 入库费用明细 | `controller/PlatformInboundFeeDetailController.java`、`service/InboundFeeDetailService.java`、`dto/InboundFeeDetailDtos.java`；Admin 消费端见 `../../apps/admin-web/src/modules/unified-orders/api/inboundFeeDetails.ts` |
 | 入库/柜次直接已付快照与凭证校验 | `service/FeePaymentSnapshotValidator.java`、`client/FeePaymentVoucherFileClient.java`；写入入口分别为 `InboundFeeDetailService.java`、`ContainerFeeDetailService.java`，File 业务类型固定 `FINANCE_VOUCHER` |
-| 客户费用查询 | `controller/MerchantInboundBillingController.java`、`service/MerchantInboundBillingService.java` |
 | 客户运营统计/在途柜量 | `customerstatistics/controller/PlatformCustomerTransitStatisticsController.java`、`customerstatistics/service/CustomerTransitStatisticsService.java`；契约见 `src/main/resources/openapi/customer-statistics-v1.yaml` |
 | 费用项目与价格簿 | `controller/PlatformFeeItemController.java`、`PlatformPriceBookController.java`、`MerchantPriceBookController.java` |
 | 客户入库结果与头程费用确认 | `controller/MerchantInboundBillingController.java`、`service/MerchantInboundBillingService.java`、`FbaPricingService.java`；查询与确认接口为 `/api/merchant/v1/first-leg/orders/{orderId}/inbound-billing`、`/confirm`，契约 `src/main/resources/openapi/firstleg-v1.yaml` |
@@ -77,14 +77,14 @@

 ## 三期装柜与 PDA 资源结算

- 智能装柜全局工作台由服务端把业务渠道分组映射为实际渠道，并分别分页查询候选与 `WAIT_LOADING/EDITING/LOADING` 柜次；候选状态筛选使用最多四项的 `orderStatuses`，未传表示 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING` 全部未完成状态。状态只用于搜索和展示，能否加入以响应 `canAssign` 为准，由有效柜次占用、剩余箱数、国内中转仓、容量、组锁和版本等事实决定；人工加入允许订单渠道与柜次渠道不同，智能推荐仍只选择柜次渠道。容积和重量均允许达到柜型额定值的 150%，超过即拒绝。待审核事实必须经 `PendingReviewOrderClient` 重新核验 Order 权威 `SUBMITTED` 订单，待审核或待测量可先占位，但确认预装和启动 PDA 前仍必须进入 `WAIT_SPLIT`。同柜不可拆组只有全部成员命中状态集合时才返回，且必须成员完整、满箱并作为单个分页与分配单元，不能跨页或拆分。一次性移除未拣明细时，普通未拣项直接移除；同柜组仅全组未拣时整组移除，任一成员已拣则整组保留，单事务只递增一次计划版本。推荐顺序按入库时间先进先出。装柜计划状态为 `EDITING -> LOADING -> COMPLETED`，PDA 全部明细处理完成后自动完成。
+- 智能装柜全局工作台由服务端把业务渠道分组映射为实际渠道，并分别分页查询候选与 `WAIT_LOADING/EDITING/LOADING` 柜次；候选状态筛选使用最多四项的 `orderStatuses`，未传表示 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING` 全部未完成状态。状态只用于搜索和展示，能否加入以响应 `canAssign` 为准，由有效柜次占用、剩余箱数、国内中转仓、容量、组锁和版本等事实决定；人工加入允许订单渠道与柜次渠道不同，智能推荐仍只选择柜次渠道。容积和重量均允许达到柜型额定值的 150%，超过即拒绝。待审核事实必须经 `PendingReviewOrderClient` 重新核验 Order 权威 `SUBMITTED` 订单，待审核或待测量可先占位，但确认预装和启动 PDA 前仍必须进入 `WAIT_SPLIT`。计划明细通过 `totalPackageCount/remainingPackageCount` 返回可调总量和余量：测量前取 Order 原始申报箱数，进入 `WAIT_SPLIT/LOADING` 后取最新已审核测量箱数；只读补充失败时保守回退当前已分配数，调整写入仍重新查询并校验权威数量。同柜不可拆组只有全部成员命中状态集合时才返回，且必须成员完整、满箱并作为单个分页与分配单元，不能跨页或拆分。一次性移除未拣明细时，普通未拣项直接移除；同柜组仅全组未拣时整组移除，任一成员已拣则整组保留，单事务只递增一次计划版本。推荐顺序按入库时间先进先出。装柜计划状态为 `EDITING -> LOADING -> COMPLETED`，PDA 全部明细处理完成后自动完成。
 - 客户入库费用只在登录客户范围、测量审核通过、`feeStatus=SENT` 且存在已发布明细时可见；确认必须具备 `merchant:order:edit`，携带当前 `expectedFeeVersion` 与幂等键。成功后记录确认成员和时间并将该费用版本永久锁定，平台不得再调整；旧版本、未发送或重复异参确认均返回冲突，不做兼容覆盖。
 - PDA 拣货以 `fl_inbound_carton_label.box_code` 对应的稳定箱唛箱码为扫描身份；审核建单、重复打印、手工测量和墨家测量复用同一映射，版本字段只用于并发控制，不进入扫码文本。一个有效且未重复的箱码扫描表示拣出一箱，不得以 SKU、商品件数或页面展示字段替代箱码。任务下发与提交契约见 `src/main/resources/openapi/phase3-pda-convergence-v1.yaml`。
 - PDA 部分拣货生成二级子入库单时，数量必须守恒：`已拣数量 + 子单数量 = 拣货前主单可用数量`。子单只允许一层，不能继续拆分。
- 首张称重图片确认时按 `max(已确认称重图片数, ceil(实测体积 / 默认托盘容量))` 预留并确认整票库位块；后续确认绑定最小空槽，所需槽数增长时通过 Warehouse `/blocks/expand` 原子追加，既有 `blockId/slotNo/reservationId/locationId` 不得变化。测量提交只校验并复用已存在权威块，不得首次分配。Firstleg 必须显式保存 `weightResultId -> blockId/slotNo/reservationId/locationId/locationCode`，按 `confirmedAt + weightResultId` 稳定顺序绑定，禁止按列表下标推断；普通连续位不足的新增槽由 Warehouse 放入共享 A0，不阻断确认。
+- 首张称重图片确认时按 `max(已确认称重图片数, ceil(有效体积 / 默认托盘容量))` 预留并确认整票库位块；有效体积严格依次取墨家/人工测量实测体积、测量批次冻结申报体积、Order 最新客户申报体积，全部无效才拒绝，不得把后两级回退冒充实测。后续确认绑定最小空槽，所需槽数增长时通过 Warehouse `/blocks/expand` 原子追加，既有 `blockId/slotNo/reservationId/locationId` 不得变化。测量提交只校验并复用已存在权威块，不得首次分配。Firstleg 必须显式保存 `weightResultId -> blockId/slotNo/reservationId/locationId/locationCode`，按 `confirmedAt + weightResultId` 稳定顺序绑定，禁止按列表下标推断；普通连续位不足的新增槽由 Warehouse 放入共享 A0，不阻断确认。
 - 删除称重图片只解除图片和托盘快照绑定，将槽位恢复为 `RESERVED_EMPTY`；槽位和整票块继续归当前入仓码。解绑失败时不得调用文件删除，文件删除失败时本地解绑和重量结果删除必须回滚。
 - 头程快照必须保存 Warehouse `blockId + slotNo + reservationId`；A0 可被多个整票块共享 `locationId`，业务资源身份始终使用 `reservationId`，不得把 `locationId` 当作唯一标识。
- PDA 部分拣货不得释放块内单槽；存在余量子单时通过 `/internal/warehouse/v1/pallet-locations/blocks/transfer` 将整段转移给子单。整票全部拣完时只通过 `/internal/warehouse/v1/pallet-locations/blocks/release` 一次性释放全部普通位和 A0 预约，禁止恢复逐槽 `settlements/release-selected` 协议。
+- PDA 部分拣货不得释放块内单槽；存在余量子单时通过 `/internal/warehouse/v1/pallet-locations/blocks/transfer` 将整段转移给子单，源单与余量子单可各自保留同一块槽及称重快照，因此 `fl_inbound_pallet_allocation` 的槽位与称重唯一键必须包含 `inbound_id`。整票全部拣完时只通过 `/internal/warehouse/v1/pallet-locations/blocks/release` 一次性释放全部普通位和 A0 预约，禁止恢复逐槽 `settlements/release-selected` 协议。
 - 数据库字段变更直接维护当前模块基线与 `../deploy/sql/头程数据库统一增量-MySQL8.sql`；已有 `phase3-pda-release-allocation-migration.sql` 只作为当前结构来源，不为历史开发数据再新增兼容迁移。

 ## 全量验收导航