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 的 GET /tenant-counts、service/OrderApplicationService.countByTenantIds、repository/OrderRepository.countByTenantIds、dto/TenantOrderCountResponse.java
Firstleg 查询订单货物明细	controller/InternalOrderCargoController.java（GET /internal/order/v1/cargoes/{tenantId}/{orderId}/{cargoId}）→ repository/OrderRepository.findCargo；契约测试 controller/InternalOrderCargoControllerTest.java
内部备注与快递信息	PlatformFirstLegOrderController.java
核心编排与状态机	service/OrderApplicationService.java、entity/OrderStatus.java
企业下单资格	service/OrderEligibilityGuard.java、client/TenantEligibilityClient.java
仓库/往来单位有效性	service/OrderMasterDataGuard.java、client/WarehouseClient.java、PartnerClient.java；往来单位响应同时包含多值 types 与兼容字段 partnerType
客户归属与访问范围	service/OrderScopeGuard.java；类内 tenant 命名为历史兼容
请求与详情响应	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/

修改与验证

• 所有商户查询和写入必须执行客户归属/访问范围校验；业务表 tenant_id 当前承载客户 ID。平台操作必须验证平台技术作用域、目标客户、权限及合法状态迁移。
• 查询接口同样必须校验权限码；沿用 IAM 已初始化的权限资源，新增权限码时同步补充 IAM 初始化脚本与角色授权。
• 已提交订单中的仓库、往来单位等快照不能随主数据修改而变化。
• 客户列表中的真实运单数归 Order，不得写回 IAM。历史接口 GET /api/platform/v1/orders/first-leg/tenant-counts?tenantIds=... 仅允许平台 platform:order:list，一次接收 1 至 200 个有效客户 ID，并对没有订单的客户返回 0；路径和参数名保持兼容。
• Warehouse 往来单位已支持多类型；下单校验优先使用 PartnerClient.Partner.types，partnerType 只作为旧数据兼容。类型语义变化需同步 Warehouse 的 wh_partner_type、Order 客户端契约与快照测试。
• 往来单位是平台统一维护、供所有客户共享的公共主数据，Order 调用 Warehouse 内部接口时固定使用公共作用域 tenant_id=0；订单自己的 tenant_id 仍是客户隔离键，不能拿来查询往来单位。
• 跨服务只通过 client/ 或事件演进，不跨库查询 IAM/Warehouse；跨域通知优先使用 Outbox。
• 二期第三方测量绑定订单货物时，Firstleg 只能通过 InternalOrderCargoController 校验 tenantId + orderId + cargoId 并读取必要快照；该接口必须保留内部令牌校验，不能暴露到 Gateway，也不能返回 Order Entity。
• Order 到 Warehouse 的内部调用使用 Nacos 服务名 warehouse-service，不经过 Gateway；只有隔离端口回归显式设置 WAREHOUSE_SERVICE_URL。内部接口返回 403 时应将外部响应规范化为 S0503，并提示核对内部服务凭证，禁止输出真实令牌。
• 新增状态或动作时同步修改 Controller、Service 状态机、历史记录、DTO、SQL、前端消费者和测试。
• 创建草稿和提交订单必须接收 Idempotency-Key；幂等范围按客户、操作者和操作隔离，请求指纹包含资源，并由数据库唯一键保证并发安全。
• 订单创建会落库收货仓地址、收货时间和主数据名称快照；既有库必须执行 phase1-order-extension.sql，否则实体字段与表结构漂移会在草稿落库时产生 HTTP 200 + S0500，真实原因只记录在服务日志。
• 从父目录运行 mvn -pl order -am test，再运行 scripts/order-warehouse-real-api-regression.ps1 或对应一期回归。
• 普通业务失败使用 HTTP 200 + body code；Feign 收到 HTTP 非 200 代表鉴权、协议或基础设施异常，应归一为 S0503，不能用 Feign 状态码推断 404/409 业务语义。

平台代客接口补充

• 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；后者包含幂等表创建，必须在部署订单写接口前完成。

分期快速索引

• 一期：订单创建/提交/审核/接单/取消入口均在 MerchantFirstLegOrderController、PlatformFirstLegOrderController；先读 ../../docs/一期/README.md、../../docs/一期/一期开发进度表.md 和 ../../docs/一期/一期头程订单闭环设计.md。订单主状态由 OrderStatus 管理，提交资格由 IAM 审核与必填资质决定。
• 二期：Order 仅提供 InternalOrderCargoController 供 Firstleg 校验订单货物和快照，不承载入库测量、计费或托盘状态；先读 ../../docs/二期/README.md 与主流程文档。二期终点停在 WAIT_SPLIT，不得在此模块加入分柜/装柜状态。
• 三期：当前 NO-GO；国内出仓状态机和排柜/订舱契约待 ../../docs/三期/三期需求确认表.md 确认后再扩展，暂复用现有订单主数据和快照能力，不把原型动作当已确定 API。