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、OpenApiInboundMeasurementController.java、service/InboundMeasurementService.java
审核/自动完成	controller/PlatformInboundMeasurementReviewController.java、service/MeasurementReviewService.java、InboundCompletionOrchestrator.java
FBA 主数据/计费	controller/PlatformFbaMasterDataController.java、PlatformFbaPricingController.java、service/FbaPricingService.java
客户费用查询	controller/MerchantInboundBillingController.java、service/MerchantInboundBillingService.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 消费者。

分期导航

• 一期：履约任务与分配；先读 ../../docs/一期/README.md。
• 二期：入库、测量、审核、计费闭环；先读 ../../docs/二期/README.md、主流程和联调报告。
• 三期：NO-GO；待 P3 阻断解除后重新定义出仓状态机。