baiyue-firstleg/firstleg/AGENTS.md

# Firstleg Service 模块指引

## 职责边界

- 负责订单提交后的国内头程履约任务、操作分配和分配历史，以及二期入库单、测量、审核、FBA 计费、费用发布和完成入库状态编排。
- 订单主单、商户草稿和交易状态属于 `order/`；不要把订单模型复制进本服务。
- 订单货物明细归 `order/`，托盘和库位资源归 `warehouse/`，图片对象归 `file/`，OCR 供应商适配归 `integration-service/`；本服务只保存业务快照、逻辑引用和自身状态。

## 快速索引

| 功能 | 入口 |
|---|---|
| 应用入口 | `src/main/java/com/baiyue/firstleg/BaiyueFirstlegApplication.java` |
| 平台履约任务查询与分配 API | `controller/PlatformFulfillmentAssignmentController.java`（`/api/platform/v1/first-leg/tasks`） |
| 任务列表、详情、按订单查询、分配历史 | `FulfillmentTaskService.java`、`FulfillmentTaskRepository.java`；只读权限码见控制器 `@PreAuthorize` |
| 服务状态 | `controller/FirstlegHealthController.java` |
| 查询与分配请求 | `dto/FulfillmentTaskQuery.java`、`dto/AssignRequest.java` |
| 履约与分配编排 | `service/FulfillmentTaskService.java` |
| 任务与历史持久化 | `entity/`、`mapper/`、`repository/FulfillmentTaskRepository.java` |
| 表结构与查询索引迁移 | `src/main/resources/db/firstleg.sql`、`src/main/resources/db/phase1-firstleg-task-list-index.sql` |
| OpenAPI 与测试 | `src/main/resources/openapi/firstleg-v1.yaml`、`service/FulfillmentTaskServiceTest.java`、`controller/FulfillmentTaskControllerContractTest.java`（测试路径均从 `src/test/java/com/baiyue/firstleg/` 起算） |
| 本地/Nacos 配置 | `src/main/resources/application.yml`、`../config/nacos/{local,cn}/firstleg-service.yml` |

## 二期入库快速索引

以下 Java 包路径从 `src/main/java/com/baiyue/firstleg/` 起算，测试路径从 `src/test/java/com/baiyue/firstleg/` 起算。

| 功能 | API 与业务入口 | 持久化、协作与测试 |
|---|---|---|
| 入库单列表、状态页签和聚合详情 | `controller/PlatformInboundOrderController.java` → `service/InboundOrderQueryService.java` | `repository/InboundOrderRepository.java`、`mapper/InboundAllocationQueryMapper.java`；测试 `service/InboundOrderQueryServiceTest.java`、`controller/InboundOrderControllerContractTest.java` |
| 平台测量草稿、提交和重量结果 | `controller/PlatformInboundMeasurementController.java` → `service/InboundMeasurementService.java`、`MeasurementSubmissionService.java` | `repository/InboundMeasurementRepository.java`；图片 `client/MeasurementImageClient.java`，托盘库位 `client/WarehousePalletLocationClient.java`；测试 `service/InboundMeasurementServiceTest.java`、`MeasurementSubmissionServiceTest.java` |
| 第三方尺寸测量回传 | `controller/OpenApiInboundMeasurementController.java` → `security/MeasurementRequestAuthenticator.java` → `service/InboundMeasurementOpenApiService.java` | 货物明细 `client/OrderCargoClient.java`，证据图片 `client/MeasurementImageClient.java`；配置 `config/MeasurementOpenApiProperties.java`；测试 `service/InboundMeasurementOpenApiServiceTest.java`、`controller/OpenApiInboundMeasurementControllerContractTest.java` |
| 测量审核、驳回和异常放行 | `controller/PlatformInboundMeasurementReviewController.java` → `service/MeasurementReviewService.java` | 自动后续流程 `service/AutomaticInboundCompletionService.java`；测试 `service/MeasurementReviewServiceTest.java`、`controller/InboundMeasurementReviewContractTest.java` |
| 客户规则和承运商价格版本 | `controller/PlatformFbaMasterDataController.java` → `service/FbaMasterDataService.java` | `repository/FbaPricingRepository.java`、`src/main/resources/openapi/fba-pricing-v1.yaml`；测试 `service/FbaMasterDataServiceTest.java` |
| 费用计算、确认、发布与快照 | `controller/PlatformFbaPricingController.java` → `service/FbaPricingService.java` | 自动计费和完成入库 `AutomaticInboundCompletionService.java`、`InboundCompletionOrchestrator.java`；测试 `service/FbaPricingServiceTest.java`、`InboundCompletionOrchestratorTest.java` |
| 商户入库费用查询 | `controller/MerchantInboundBillingController.java` → `service/MerchantInboundBillingService.java` | 测试 `service/MerchantInboundBillingServiceTest.java`、`controller/MerchantInboundBillingControllerContractTest.java` |
| 状态、幂等、历史和 Outbox | `domain/InboundProcessStatus.java`、`service/InboundIdempotencyService.java` | `repository/InboundWorkflowRepository.java`、`entity/Inbound*.java`、`mapper/Inbound*.java`；测试 `service/InboundIdempotencyServiceTest.java`、`repository/InboundWorkflowSqlContractTest.java` |
| 二期表结构和增量 | `src/main/resources/db/phase2-inbound-schema.sql`、`phase2-inbound-workflow-migration.sql`、`phase2-inbound-measurement-maintenance.sql`、`phase2-measurement-openapi.sql`、`phase2-third-party-single-measurement-migration.sql`、`phase2-fba-pricing-migration.sql` | 测试/存量环境统一入口为 `../deploy/sql/2026-08-04-二期入库新增表字段-MySQL8一键执行.sql`，执行说明见 `../deploy/sql/README.md` |

## 修改与验证

- 任务状态与订单状态保持领域分离；需要联动时使用稳定 DTO 或事件，不共享 Order Entity 或数据库。
- 分配操作要保留历史、操作者、时间和幂等语义；平台端接口必须执行权限校验。
- 所有客户归属查询必须带目标客户并按兼容字段 `tenant_id` 在仓储层过滤；列表和分配历史使用统一分页响应，详情不存在使用 HTTP 200 + body code `A0404`。
- 普通任务不存在、状态冲突和参数错误均遵循 HTTP 200 + body code，平台 Security 拒绝仍保留真实 403。
- 新建库由 `firstleg.sql` 创建查询索引；既有库必须再执行可重复部署的 `phase1-firstleg-task-list-index.sql`，不能只依赖 `CREATE TABLE IF NOT EXISTS`。
- 修改任务查询、状态或分配逻辑时同步扩展 Service 测试和 Controller 契约测试，不以模块构建代替行为验证。
- 二期入库所有平台查询和写入必须显式校验目标客户；接口中的 `tenantId` 当前是客户隔离兼容字段。商户费用查询只能使用登录态客户归属。状态推进、审核、计费和完成入库必须保留乐观锁、幂等键、历史和审计语义。
- 第三方测量入口必须执行签名、时间窗、防重放和请求哈希校验；一条回传绑定一条订单货物明细及一张 File 证据图片，不得信任第三方直接提交的客户隔离字段或订单快照。
- Firstleg 调用 Order、Warehouse、File 的内部接口统一使用共享 `INTERNAL_SERVICE_TOKEN`，只通过客户端 DTO 协作；任何内部接口、Feign DTO 或状态变化都要同步检查被调用模块和契约测试。
- 测量审核通过后的自动链路依次完成计费、确认、费用发布与入库完成；异常放行必须受配置开关、权限和审核历史共同约束，不能跳过测量门禁直接改状态。
- 从父目录运行 `mvn -pl firstleg -am test`。
- 数据库执行顺序：新库执行 `firstleg.sql`；已有库在此后执行 `phase1-firstleg-task-list-index.sql`，为任务列表、按订单查询和分配历史分页补齐索引。
- 二期数据库不得只执行单个建表脚本覆盖存量库；测试/存量环境按 `../deploy/sql/README.md` 使用 8 月 4 日统一脚本，并确认末尾核验全部为 `PASS`。