Order Service 模块指引

职责边界

功能	入口
商户订单创建、编辑、列表、详情、提交、取消	`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。
Order 到 Warehouse 的内部调用使用 Nacos 服务名 warehouse-service，不经过 Gateway；只有隔离端口回归显式设置 WAREHOUSE_SERVICE_URL。内部接口返回 403 时应将外部响应规范化为 S0503，并提示核对内部服务凭证，禁止输出真实令牌。
新增状态或动作时同步修改 Controller、Service 状态机、历史记录、DTO、SQL、前端消费者和测试。
创建草稿和提交订单必须接收 Idempotency-Key；幂等范围按租户、操作者和操作隔离，请求指纹包含资源，并由数据库唯一键保证并发安全。
订单创建会落库收货仓地址、收货时间和主数据名称快照；既有库必须执行 phase1-order-extension.sql，否则实体字段与表结构漂移会在草稿落库时产生 500。
从父目录运行 mvn -pl order -am test，再运行 scripts/order-warehouse-real-api-regression.ps1 或对应一期回归。

POST /api/platform/v1/orders/first-leg?tenantId={tenantId}：平台代客创建草稿，校验 platform:order:create，必须携带 Idempotency-Key。
PUT /api/platform/v1/orders/first-leg/{id}?tenantId={tenantId}：平台编辑草稿，校验 platform:order:edit。
POST /api/platform/v1/orders/first-leg/{id}/submit?tenantId={tenantId}：平台代客提交订单，校验 platform:order:submit，必须携带 Idempotency-Key。
src/main/resources/openapi/order-v1.yaml 是静态 OpenAPI 入口；ord_idempotency_record 以租户、操作人、操作和幂等键建立唯一约束。
数据库执行顺序：新库先执行 order.sql，已有库执行 phase1-order-extension.sql；后者包含幂等表创建，必须在部署订单写接口前完成。