baiyue-firstleg/order/AGENTS.md

Order Service 模块指引

职责边界

• 负责头程订单主数据、草稿、提交、平台处理状态、货物、参与方快照、状态历史、内部备注和 Outbox。
• 履约作业与分配属于 firstleg/；仓库和往来单位主数据属于 warehouse/；订单只保存必要业务快照。

功能快速索引

功能	入口
商户订单创建、编辑、列表、详情、提交、取消	controller/MerchantFirstLegOrderController.java；列表校验 merchant:order:list，详情校验 merchant:order:view
平台订单列表、详情、审核、接单、开始、完成、取消	controller/PlatformFirstLegOrderController.java；列表和详情校验 platform:order:list
内部备注与快递信息	PlatformFirstLegOrderController.java
核心编排与状态机	service/OrderApplicationService.java、entity/OrderStatus.java
企业下单资格	service/OrderEligibilityGuard.java、client/TenantEligibilityClient.java
仓库/往来单位有效性	service/OrderMasterDataGuard.java、client/WarehouseClient.java、PartnerClient.java
租户与访问范围	service/OrderScopeGuard.java
请求与详情响应	dto/OrderRequests.java、OrderDetailResponse.java
主单、货物、参与方、历史、备注、Outbox、幂等记录	entity/、mapper/、repository/OrderRepository.java
表结构与一期扩展	src/main/resources/db/order.sql、phase1-masterdata-extension.sql、phase1-order-extension.sql
模块说明	README-ORDER.md
状态、主数据与接口权限测试	src/test/java/com/baiyue/order/service/、src/test/java/com/baiyue/order/controller/

修改与验证

• 所有商户查询和写入必须执行租户/访问范围校验；平台操作必须验证权限及合法状态迁移。
• 查询接口同样必须校验权限码；沿用 IAM 已初始化的权限资源，新增权限码时同步补充 IAM 初始化脚本与角色授权。
• 已提交订单中的仓库、往来单位等快照不能随主数据修改而变化。
• 跨服务只通过 client/ 或事件演进，不跨库查询 IAM/Warehouse；跨域通知优先使用 Outbox。
• 新增状态或动作时同步修改 Controller、Service 状态机、历史记录、DTO、SQL、前端消费者和测试。
• 创建草稿和提交订单必须接收 Idempotency-Key；幂等范围按租户、操作者和操作隔离，请求指纹包含资源，并由数据库唯一键保证并发安全。
• 从父目录运行 mvn -pl order -am test，再运行 scripts/order-warehouse-real-api-regression.ps1 或对应一期回归。