baiyue-firstleg/firstleg/AGENTS.md

Firstleg Service 模块指引

职责与边界

• 负责履约任务/分配，以及二期入库单、测量/OCR 结果、审核、FBA 计费、完成入库编排。
• 订单主数据归 order/，托盘/库位归 warehouse/，文件对象归 file/，OCR 供应商归 integration-service/；通过客户端 DTO 和内部令牌协作。
• 入库终点为 WAIT_SPLIT + APPROVED + CONFIRMED；二期不实现分柜、装柜、PDA 或完整财务。

模块入口

目标	入口
履约任务/分配	controller/PlatformFulfillmentAssignmentController.java、service/FulfillmentTaskService.java
入库单查询/聚合	controller/PlatformInboundOrderController.java、service/InboundOrderQueryService.java
平台测量/OCR	controller/PlatformInboundMeasurementController.java、service/InboundMeasurementService.java、service/CartonMeasurementService.java
墨家设备测量上传	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
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
费用项目与价格簿	controller/PlatformFeeItemController.java、PlatformPriceBookController.java、MerchantPriceBookController.java
财务费用来源快照	controller/InternalFinanceFeeSourceController.java；入库费用与柜次费用分别按来源 ID、版本向 Finance 提供不可变快照
柜次费用明细	controller/PlatformContainerFeeDetailController.java、service/ContainerFeeDetailService.java、dto/ContainerFeeDetailDtos.java；Admin 消费端见 ../../apps/admin-web/src/modules/loading-lists/api/containerFees.ts
财务整柜成本分摊快照	loading/controller/InternalFinanceCostSnapshotController.java、loading/service/FinanceCostSnapshotService.java
分柜与预装	split/controller/PlatformSplitPreloadController.java、controller/PlatformLoadingListController.java
货柜与智能排柜	controller/PlatformContainerController.java、PlatformSmartLoadingController.java、loading/
PDA 拣货与装柜	controller/PlatformLoadingPdaController.java、loading/controller/PlatformLoadingDeliveryController.java
海运订舱与船期	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
SQL/OpenAPI	src/main/resources/db/phase2-*.sql、src/main/resources/openapi/；部署统一 ../deploy/sql/头程数据库统一增量-MySQL8.sql
测试/验证	src/test/java/com/baiyue/firstleg/；mvn -pl firstleg -am test

修改约束

• 平台接口必须校验目标客户、权限、乐观锁、幂等键、历史和审计；商户查询只能使用登录态客户。
• 第三方回传必须签名、时间窗、防重放、请求哈希，并绑定订单货物和 File 证据；不得信任外部客户字段。
• 测量审核→计费确认→费用发布→入库完成不得跳过门禁；状态或 DTO 变更时逐个检查 Order/Warehouse/File/Integration 消费者。
• Firstleg 只拥有业务费用及履约事实；Finance 拥有费用入池、账期、账单、收款、成本分摊结果和财务状态。修改费用来源版本、发布条件、柜次归属或体积快照时同步检查 ../finance/src/main/java/com/baiyue/finance/client/FirstlegFeeSourceClient.java、同目录 FirstlegCostSnapshotClient.java 及双方契约测试，不在 Firstleg 复制财务状态机。

三期装柜与 PDA 资源结算

• 智能装柜候选只能按同一国内中转仓合柜；推荐顺序按入库时间先进先出。装柜计划状态为 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。
• 头程快照必须保存仓库 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。

分期导航

• 一期：履约任务与分配；先读 ../../docs/一期/README.md。
• 二期：入库、测量、审核、计费闭环；先读 ../../docs/二期/README.md、主流程和联调报告。
• 三期：负责订单履约编排、柜次、智能排柜、订舱、拖车、PDA 作业与 LOADED 门禁；先读 ../../docs/三期/三期开工门禁.md。已确认范围按 Controller、DTO、OpenAPI、迁移和调用方共同实现；PDA 按 uni-app 在线更新安排开发与验收，不另设设备型号门禁。