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/头程数据库统一增量-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。

分期快速索引

• 一期：履约任务与分配入口为 PlatformFulfillmentAssignmentController，先读 ../../docs/一期/README.md、../../docs/一期/一期开发进度表.md 和 ../../docs/一期/一期头程订单闭环设计.md；订单交易状态仍归 order/，本模块只管理任务状态、分配历史和幂等。
• 二期：入库主线从 PlatformInboundOrderController、PlatformInboundMeasurementController、PlatformInboundMeasurementReviewController 到 PlatformFbaPricingController；先读 ../../docs/二期/README.md、主流程、需求确认清单及联调报告。验收终点为 WAIT_SPLIT + APPROVED + CONFIRMED，自动完成入库不得越过测量审核、计费确认和发布门禁。
• 三期：当前 NO-GO；后续国内出仓、分柜、装柜、PDA 拣货与船期协作需先解除 P3 阻断并重新定义状态机，不能把二期 WAIT_SPLIT 直接当作三期实现。