添加AGENTS.md 快速索引

firstleg/AGENTS.md

@@ -2,8 +2,9 @@
 
 ## 职责边界
 
-- 负责订单提交后的国内头程履约任务、操作分配和分配历史。
+- 负责订单提交后的国内头程履约任务、操作分配和分配历史，以及二期入库单、测量、审核、FBA 计费、费用发布和完成入库状态编排。
 - 订单主单、商户草稿和交易状态属于 `order/`；不要把订单模型复制进本服务。
+- 订单货物明细归 `order/`，托盘和库位资源归 `warehouse/`，图片对象归 `file/`，OCR 供应商适配归 `integration-service/`；本服务只保存业务快照、逻辑引用和自身状态。
 
 ## 快速索引
 
@@ -20,6 +21,22 @@
 | 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 或数据库。
@@ -28,5 +45,10 @@
 - 普通任务不存在、状态冲突和参数错误均遵循 HTTP 200 + body code，平台 Security 拒绝仍保留真实 403。
 - 新建库由 `firstleg.sql` 创建查询索引；既有库必须再执行可重复部署的 `phase1-firstleg-task-list-index.sql`，不能只依赖 `CREATE TABLE IF NOT EXISTS`。
 - 修改任务查询、状态或分配逻辑时同步扩展 Service 测试和 Controller 契约测试，不以模块构建代替行为验证。
+- 二期入库所有平台查询和写入必须显式校验目标租户；商户费用查询只能使用登录态租户。状态推进、审核、计费和完成入库必须保留乐观锁、幂等键、历史和审计语义。
+- 第三方测量入口必须执行签名、时间窗、防重放和请求哈希校验；一条回传绑定一条订单货物明细及一张 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`。