baiyue-firstleg/order/AGENTS.md

Order Service 模块指引

职责与边界

• 负责头程订单主数据、货物明细、快照、状态编排、幂等、Outbox 和内部货物查询。
• 订单交易状态归本模块；履约/入库状态归 firstleg/，仓储资源归 warehouse/，不得跨库读取。
• tenant_id 是客户隔离键；customer_id 是业务客户/往来单位快照，不能替代前者。

模块入口

目标	入口
平台订单 API	controller/PlatformFirstLegOrderController.java
订单编排/状态/幂等	service/OrderApplicationService.java、entity/OrderStatus.java
统一订单七状态与操作映射	../../docs/统一订单主状态与操作契约.md；LOADED 硬门禁和 DELIVERED 可信回传同时核对三期需求确认表与开工门禁
货物内部查询	controller/InternalOrderCargoController.java
快照/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；状态变更保留幂等、历史、审计和并发控制。
• Warehouse 往来单位、Firstleg 入库协作只通过客户端 DTO/内部令牌；修改契约需同步消费者。

分期导航

• 一期：订单下单与交易状态闭环；先读 ../../docs/一期/README.md 与闭环设计。
• 二期：仅提供货物内部查询，不承载入库状态；先读 ../../docs/二期/README.md。
• 三期：在 firstleg 编排契约稳定后，负责父子订单、数量守恒、订单主状态、幂等和时间线所需的主数据扩展；先读 ../../docs/三期/三期开工门禁.md。不得自行创建独立出仓单或绕过 LOADED 服务端门禁。