# Order Service 模块指引

## 职责与边界

- 负责头程订单主数据、货物明细、快照、状态编排、幂等、Outbox 和内部货物查询。
- 订单交易状态归本模块；履约/入库状态归 `firstleg/`，仓储资源归 `warehouse/`，不得跨库读取。
- `tenant_id` 是客户隔离键；`customer_id` 是客户/企业账号 ID，商户下单时固定来自认证上下文，不得指向 Warehouse 往来单位。发货单位、收货单位只保存为订单 Party 引用与业务快照。

## 模块入口

| 目标 | 入口 |
|---|---|
| 平台订单 API | `controller/PlatformFirstLegOrderController.java` |
| 订单编排/状态/幂等 | `service/OrderApplicationService.java`、`entity/OrderStatus.java` |
| 商户订单列表与批量草稿 | `service/MerchantInboundOrderListService.java`、`service/MerchantBatchDraftService.java`、`service/MerchantBatchDraftItemService.java` |
| 入库号生成 | `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` 可信回传同时核对三期需求确认表与开工门禁 |
| 货物内部查询与箱唛绑定来源 | `controller/InternalOrderCargoController.java` 向 Firstleg 提供箱唛生成的 SKU 快照来源；`CargoLabelBinding.skuNo` 对 `ONE_CLICK_DROPSHIP` 为强制字段。Firstleg 消费端为 `../firstleg/src/main/java/com/baiyue/firstleg/client/OrderCargoClient.java`，变更两端 DTO 必须同步。 |
| 快照/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 不可用时失败关闭，不回退到旧快照或模拟数据。
- Warehouse 往来单位、Firstleg 入库协作只通过客户端 DTO/内部令牌；修改契约需同步消费者。
- 对 `ONE_CLICK_DROPSHIP`，货物明细 SKU 是箱唛绑定及海外一件代发库存追踪的前置条件，不得依赖货名、箱规或其他展示字段推导 SKU。修改 `CargoLabelBinding` 时同步更新 Firstleg 客户端、相关测试与服务间契约。

## 全量验收导航

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