baiyue-firstleg/order/AGENTS.md

# Order Service 模块指引

## 数据库访问与中文注释约束

- 强制继承 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则；该节是分层、SQL 执行和方法/核心逻辑中文注释的唯一维护处，本模块不另设例外。

## 职责与边界

- Mapper 只由 `BaiyueOrderApplication.java` 对 `com.baiyue.order` 根包按 `@Mapper` 过滤扫描；新增或移动 Mapper 后从后端根运行 `node scripts/mapper-scan-contract.mjs`，不得增加子域扫描配置。
- 负责头程订单主数据、货物明细、快照、状态编排、幂等、Outbox 和内部货物查询。
- 订单交易状态归本模块；履约/入库状态归 `firstleg/`，仓储资源归 `warehouse/`，不得跨库读取。
- `tenant_id` 是客户隔离键；`customer_id` 是客户/企业账号 ID，商户下单时固定来自认证上下文，不得指向 Warehouse 往来单位。发货单位、收货单位只保存为订单 Party 引用与业务快照。

## 模块入口

| 目标 | 入口 |
|---|---|
| 平台订单 API | `controller/PlatformFirstLegOrderController.java` |
| 客户订单工作台分页与待办 | `controller/MerchantUnifiedOrderController.java` 的 `/workbench`、`service/MerchantOrderWorkbenchService.java`、`repository/MerchantOrderWorkbenchRepository.java`；客户取认证上下文，筛选后在 Order 计算总数并分页，Firstleg 经内部服务身份提供履约状态、费用确认和报关待上传范围；契约 `src/main/resources/openapi/order-v1.yaml` |
| 平台批量审核预览 | `controller/PlatformFirstLegOrderController.java` 的 `/batch-review-preview`、`service/BatchOrderReviewPreviewService.java`、`dto/BatchOrderReviewPreviewResponse.java`；按目标客户和请求顺序一次返回订单、中文货物摘要、渠道、目的仓及逐项 `canApprove/blockReason`，实现固定两次批量查询，禁止前端逐票读取详情 |
| 统一订单查询、审核优先状态与稳定渠道编码 | `service/UnifiedOrderQueryService.java`、`dto/UnifiedOrderResponse.java`、`src/main/resources/openapi/order-v1.yaml`；`channelCode` 直接来自 Order/Firstleg 权威快照，只用于业务校验，不得由 `channelName` 推导。Order 为 `SUBMITTED` 时即使已有 Firstleg 入库投影，统一主状态/下一动作仍固定为 `PENDING_REVIEW/APPROVE_ORDER` |
| Firstleg 智能装柜待审核候选 | `controller/InternalPendingReviewOrderController.java`、`service/PendingReviewOrderQueryService.java`、`dto/PendingReviewOrderDtos.java`、`repository/OrderRepository.java`；内部入口 `/internal/order/v1/pending-review-orders` 只接受服务令牌，只分页返回未删除的 `SUBMITTED` 头程订单并固定投影为 `PENDING_REVIEW`，按 `Asia/Shanghai` 自然日过滤、`created_at DESC, id DESC` 稳定排序；`POST /batch` 按最多 100 个订单 ID 批量核验待审核状态，供同柜建组幂等准备 Firstleg `PREPARING` 投影 |
| 平台版本化修改客户原始申报 | `controller/PlatformUnifiedOrderController.java` 的 `PUT /api/platform/v1/orders/{orderId}/declaration`、`service/OrderDeclarationUpdateService.java`、`dto/OrderDeclarationDtos.java`；权限 `platform:order:declaration:edit`，货物以订单内 `itemNo` 定位并保持行集合完整，契约 `src/main/resources/openapi/order-v1.yaml` |
| 申报同步、渠道履约/计价门禁 | `service/OrderFulfillmentChannelChangeGuard.java`、`OrderPricingChannelGuard.java`、`OrderInboundOutboxPublisher.java`，内部客户端 `FirstlegInboundClient.java`、`FirstlegPricingClient.java`；审核后通过版本化 `ORDER_DECLARATION_UPDATED_V1` 同步 Firstleg |
| 入仓码业务关系摘要 | `service/InboundCodeAssociationService.java`、`dto/InboundCodeAssociationSummary.java`、平台/客户 `FirstLegOrderController` 的 `/inbound-code-associations/{inboundCode}`；客户入口必须按认证客户隔离 |
| 订单编排/状态/幂等 | `service/OrderApplicationService.java`、`entity/OrderStatus.java` |
| 海外派送完成内部回写 | `controller/InternalOrderFulfillmentCompletionController.java`、`service/OrderFulfillmentCompletionService.java`；只接受 Firstleg 内部服务身份和已校验的来源订单/入仓码快照，幂等将对应订单推进为 `COMPLETED` 并写状态历史 |
| 商户订单列表、批量草稿与中文 XLSX 导入 | `service/MerchantInboundOrderListService.java`、`MerchantBatchDraftService.java`、`MerchantBatchDraftItemService.java`、`MerchantBatchImportService.java`；动态目录客户端 `client/MerchantWarehouseCatalogClient.java`、`MerchantPricingCatalogClient.java`，客户地址由 `CustomerAddressService.java` 提供；接口见 `controller/MerchantFirstLegOrderController.java` 的 `/batch-imports/template`、`/batch-imports` |
| 平台旧系统订单导入 | `controller/PlatformFirstLegOrderController.java` 的 `/legacy-import`、`service/PlatformLegacyOrderImportService.java`；固定按名称精确解析启用客户“IT测试公司”，保留旧入仓码，按内部仓库目录和该客户当前价格簿逐行校验，成功行直接进入 `SUBMITTED` 待审核；一件代发缺 SKU 的行失败，普通 FBA 缺 SKU 时使用稳定 `LEGACY-{入仓码}` 测试占位码 |
| 入库号生成 | `config/InboundCodeModeProvider.java`、`mapper/InboundCodeSequenceMapper.java`、`repository/OrderRepository.java`、`service/OrderApplicationService.java` |
| 下单计价渠道校验 | `service/OrderPricingChannelGuard.java`、`client/FirstlegPricingClient.java` |
| 下单仓库主数据守卫 | `service/OrderMasterDataGuard.java`、`client/WarehouseClient.java`；校验公共收货仓、目的仓类型、状态、地址与收货能力，并保存服务端快照 |
| 统一订单七状态与操作映射 | `../../docs/统一订单主状态与操作契约.md`；`LOADED` 硬门禁和 `DELIVERED` 可信回传按当前契约及 `firstleg` 装柜/出仓入口核对。国内货柜履约需求确认表与开工门禁仅用于历史追溯 |
| 货物内部查询与箱唛绑定来源 | `controller/InternalOrderCargoController.java` 向 Firstleg 批量提供箱唛生成的 SKU、尺寸与货件快照；`CargoLabelBinding.skuNo` 对 `ONE_CLICK_DROPSHIP` 为强制字段，`shipmentId` 只取对应货物行，不回退订单顶层字段。Firstleg 消费端为 `../firstleg/src/main/java/com/baiyue/firstleg/client/OrderCargoClient.java`，变更两端 DTO 必须同步。 |
| 智能装柜待审核候选内部查询 | `controller/InternalPendingReviewOrderController.java`、`service/PendingReviewOrderQueryService.java`、`dto/PendingReviewOrderDtos.java`；Firstleg 消费端为 `../firstleg/src/main/java/com/baiyue/firstleg/client/PendingReviewOrderClient.java`，契约 `src/main/resources/openapi/order-v1.yaml` |
| 快照/Outbox | `service/`、`repository/`、`event/` |
| DTO/持久化 | `dto/`、`entity/`、`mapper/`、`repository/` |
| SQL/OpenAPI | `src/main/resources/db/`、`src/main/resources/openapi/` |
| 测试/验证 | `src/test/java/com/baiyue/order/`；`mvn -pl order -am test` |

## 修改约束

- 所有客户查询在 Repository/Mapper 显式带 `tenant_id`；状态变更保留幂等、历史、审计和并发控制。
- `inbound_code` 是跨客户全局唯一业务码；生成模式由 `InboundCodeModeProvider` 控制，序列与唯一约束不得退化为客户内唯一。修改格式、长度或生成时机时同步检查 Order SQL、Firstleg 入库快照、箱唛箱码、前端展示和全局唯一性契约测试。
- 下单和后续关键状态操作不得信任客户端仓库名称、类型或启用状态；公共仓库必须通过 Warehouse 内部接口按 ID 实时校验。私人地址不得伪装为公共目的仓，非私人目的地必须引用类型匹配的公共仓库；Warehouse 不可用时失败关闭，不回退到旧快照或模拟数据。
- 客户提交订单时除 IAM 审核资格外，还必须通过 Finance 资金账户校验；实际余额小于 0 时拒绝提交并提示充值。草稿保存不触发资金门禁，Finance 不可用或响应无效时提交失败关闭。
- Warehouse 往来单位、Firstleg 入库协作只通过客户端 DTO/内部令牌；修改契约需同步消费者。
- 智能装柜待审核候选只返回 Order 权威 `SUBMITTED` 订单，并按服务身份、客户/仓库/渠道、入仓码、创建日期、预计到货日期和分页条件查询；Firstleg 可据此提前占位，但不得把该内部查询或申报数量当作审核、测量或可物理装柜完成的事实。
- 中文批量模板按登录客户生成取货/私人地址、国内收货仓、目的仓和渠道下拉；仓库目录必须翻页读取全部候选，不得只取第一页。导入时重新读取并校验动态目录、客户归属和启用状态，不信任模板隐藏页；文件上限 5MB、有效数据最多 50 行，仅创建草稿，`PARTIAL` 允许单行失败、`ATOMIC` 任一行失败不得落单。
- 平台只能在 `DRAFT/REJECTED/SUBMITTED/APPROVED` 版本化修改客户原始申报；不得修改客户、国内收货仓、订单号、入仓码、状态或仓库/PDA/设备实测、测量审核和计费事实，不得增删或重排货物行。国内收货仓或中转仓变化必须重新下单。
- 只有渠道发生变化才同时调用 Firstleg 履约可逆性与重新计价门禁，任一内部校验不可用或失败均不写入；成功后 Outbox 必须携带完整申报快照和字段变化。Firstleg 消费按 `eventId + payload hash` 幂等、按订单版本单调推进，渠道变化才使未确认价格预估失效。
- 对 `ONE_CLICK_DROPSHIP`，货物明细 SKU 是箱唛绑定及海外一件代发库存追踪的前置条件，不得依赖货名、箱规或其他展示字段推导 SKU。修改 `CargoLabelBinding` 时同步更新 Firstleg 客户端、相关测试与服务间契约。

## 全量验收导航

本模块承载订单下单、交易状态、货物查询、父子订单、数量守恒、主状态、幂等和时间线等全量订单契约；按本次验收链路读取对应业务域文档和 `firstleg` 编排契约，不创建独立出仓单，也不绕过 `LOADED` 服务端门禁。