优化

2026-08-14 14:50:39 +08:00
parent 261a8bf2df
commit 36a048a2bc
34 changed files with 263 additions and 120 deletions
@@ -2,7 +2,7 @@

 ## 职责与边界

- 负责履约任务/分配、入库单、测量/OCR、审核、FBA 计费、完成入库编排、客户在途柜量统计及国内出仓履约链路。
+- 负责履约任务/分配、入库单、测量/OCR、审核后初始计价、FBA 计费、客户在途柜量统计及国内出仓履约链路。
 - 订单主数据归 `order/`，托盘/库位归 `warehouse/`，文件对象归 `file/`，OCR 供应商归 `integration-service/`；通过客户端 DTO 和内部令牌协作。
 - 入库、分柜、装柜、PDA 和出仓能力均在本模块按对应服务端契约协作；`WAIT_SPLIT + APPROVED + CONFIRMED` 是入库链路状态节点，不是全量验收的范围终点。财务状态仍归 `finance`，本模块只生产不可变费用来源和柜次成本快照。

@@ -15,7 +15,7 @@
 | 平台测量/OCR | `controller/PlatformInboundMeasurementController.java`、`service/InboundMeasurementService.java`、`service/CartonMeasurementService.java` |
 | 箱唛箱码生成与版本化 | `repository/InboundCartonLabelRepository.java`、`service/InboundCartonLabelService.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` |
-| 审核/自动完成 | `controller/PlatformInboundMeasurementReviewController.java`、`service/MeasurementReviewService.java`、`InboundCompletionOrchestrator.java` |
+| 审核与初始计价 | `controller/PlatformInboundMeasurementReviewController.java`、`service/MeasurementReviewService.java`、`service/InitialInboundPricingService.java`、`dto/MeasurementApprovalResponse.java` |
 | FBA 主数据/计费 | `controller/PlatformFbaMasterDataController.java`、`PlatformFbaPricingController.java`、`service/FbaPricingService.java` |
 | 入库费用明细 | `controller/PlatformInboundFeeDetailController.java`、`service/InboundFeeDetailService.java`、`dto/InboundFeeDetailDtos.java`；Admin 消费端见 `../../apps/admin-web/src/modules/unified-orders/api/inboundFeeDetails.ts` |
 | 客户费用查询 | `controller/MerchantInboundBillingController.java`、`service/MerchantInboundBillingService.java` |
@@ -27,11 +27,12 @@
 | 分柜与预装 | `split/controller/PlatformSplitPreloadController.java`、`controller/PlatformLoadingListController.java` |
 | 货柜与智能排柜 | `controller/PlatformContainerController.java`、`PlatformSmartLoadingController.java`、`loading/` |
 | PDA 拣货与装柜 | `controller/PlatformLoadingPdaController.java`、`loading/controller/PlatformLoadingDeliveryController.java` |
+| 装柜完成跨区事件 | `service/LoadingCompletedOutboxService.java`、`LoadingCompletedOutboxRelay.java`、`repository/LoadingCompletedOutboxRepository.java`、`client/EventBridgeClient.java`；事件模型见 `../common-event-contract/AGENTS.md` |
 | 海运订舱与船期 | `oceanbooking/controller/PlatformOceanBookingController.java`、`portschedule/controller/PlatformCarrierScheduleQueryController.java`、`PlatformPortScheduleController.java` |
 | 拖车与出仓调度 | `controller/PlatformTruckAppointmentController.java`、`outbound/dispatch/controller/PlatformOutboundDispatchController.java` |
 | 报关协同 | `customs/controller/PlatformCustomsController.java`、`MerchantCustomsController.java` |
-| 跨模型兼容桥 | `loading/bridge/controller/PlatformLoadingModelBridgeController.java` |
-| 跨服务客户端 | `client/OrderCargoClient.java`、`WarehousePalletLocationClient.java`、`MeasurementImageClient.java` |
+| 跨模型桥接 | `loading/bridge/controller/PlatformLoadingModelBridgeController.java` |
+| 跨服务客户端 | `client/OrderCargoClient.java`、`WarehousePalletLocationClient.java`、`MeasurementImageClient.java`、`LoadingEvidenceFileClient.java`、`EventBridgeClient.java` |
 | SQL/OpenAPI | `src/main/resources/db/phase2-*.sql`、`src/main/resources/db/phase3-*.sql`、`src/main/resources/openapi/`；部署统一 `../deploy/sql/头程数据库统一增量-MySQL8.sql` |
 | 测试/验证 | `src/test/java/com/baiyue/firstleg/`；`mvn -pl firstleg -am test` |

@@ -47,11 +48,11 @@
 - 智能装柜候选只能按同一国内中转仓合柜；推荐顺序按入库时间先进先出。装柜计划状态为 `EDITING -> LOADING -> COMPLETED`，PDA 全部明细处理完成后自动完成。
 - PDA 拣货以 `fl_inbound_carton_label.box_code` 对应的稳定箱唛箱码为扫描身份；首次打印冻结箱码映射，重复打印和墨家测量复用同一箱码，版本字段只用于并发控制，不进入扫码文本。一个有效且未重复的箱码扫描表示拣出一箱，不得以 SKU、商品件数或页面展示字段替代箱码。任务下发与提交契约见 `src/main/resources/openapi/phase3-pda-convergence-v1.yaml`。
 - PDA 部分拣货生成二级子入库单时，数量必须守恒：`已拣数量 + 子单数量 = 拣货前主单可用数量`。子单只允许一层，不能继续拆分。
- `releaseMode=AUTO` 时，释放资源数为 `ceil(实际拣货箱数 × 原资源数 / 原可用箱数)`；`MANUAL` 按 `locationIds` 选择，空数组表示明确释放 0 个。未传模式时，`locationIds=null` 兼容为 AUTO。
+- `releaseMode=AUTO` 时，释放资源数为 `ceil(实际拣货箱数 × 原资源数 / 原可用箱数)`；`MANUAL` 按 `locationIds` 选择，空数组表示明确释放 0 个。当前契约中未传模式且 `locationIds=null` 时按 AUTO 处理。
 - 头程快照必须保存仓库 `reservation_id`。A0 是共享临时库位，多个托盘可具有相同 `location_id`，跨服务结算、转移、释放必须使用 `reservationId`，不得把 `locationId` 当作唯一资源标识。
 - 部分拣货资源结算必须调用 Warehouse 的 `/internal/warehouse/v1/pallet-locations/settlements` 原子接口；禁止拆成独立释放和转移调用。全部释放但子单仍有数量时，由仓库服务重新选择同仓普通库位，不足才落 A0。
- 数据库字段变更同时维护 `src/main/resources/db/phase3-pda-release-allocation-migration.sql` 和 `../deploy/sql/头程数据库统一增量-MySQL8.sql`。
+- 数据库字段变更直接维护当前模块基线与 `../deploy/sql/头程数据库统一增量-MySQL8.sql`；已有 `phase3-pda-release-allocation-migration.sql` 只作为当前结构来源，不为历史开发数据再新增兼容迁移。

 ## 全量验收导航

-本模块承载一期履约、二期入库测量计费、三期订单编排/柜次/排柜/订舱/拖车/PDA/`LOADED` 门禁等全量链路；按本次验收范围读取对应阶段文档、Controller、DTO、OpenAPI、迁移和调用方，不以历史阶段终点阻断联调。PDA 按 uni-app 在线更新安排开发与验收，不另设设备型号门禁。
+本模块承载一期履约、二期入库测量计费、三期订单编排/柜次/排柜/订舱/拖车/PDA/`LOADED` 门禁等全量链路；按本次验收范围读取对应阶段文档、Controller、DTO、OpenAPI、当前 SQL 定义和调用方，不以历史阶段终点阻断联调。PDA 按 uni-app 在线更新安排开发与验收，不另设设备型号门禁。