# 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 阻断解除后重新定义出仓状态机。