baiyue-firstleg/order/AGENTS.md

Order Service 模块指引

职责与边界

• Mapper 只由 BaiyueOrderApplication.java 对 com.baiyue.order 根包按 @Mapper 过滤扫描；新增或移动 Mapper 后从后端根运行 node scripts/mapper-scan-contract.mjs，不得增加子域扫描配置。
• 负责头程订单主数据、货物明细、快照、状态编排、幂等、Outbox 和内部货物查询。
• 订单交易状态归本模块；履约/入库状态归 firstleg/，仓储资源归 warehouse/，不得跨库读取。
• tenant_id 是客户隔离键；customer_id 是客户/企业账号 ID，商户下单时固定来自认证上下文，不得指向 Warehouse 往来单位。发货单位、收货单位只保存为订单 Party 引用与业务快照。

模块入口

目标	入口
平台订单 API	controller/PlatformFirstLegOrderController.java
统一订单查询、审核优先状态与稳定渠道编码	service/UnifiedOrderQueryService.java、dto/UnifiedOrderResponse.java、src/main/resources/openapi/order-v1.yaml；channelCode 直接来自 Order/Firstleg 权威快照，只用于业务校验，不得由 channelName 推导。Order 为 SUBMITTED 时即使已有 Firstleg 入库投影，统一主状态/下一动作仍固定为 PENDING_REVIEW/APPROVE_ORDER
平台版本化修改客户原始申报	controller/PlatformUnifiedOrderController.java 的 PUT /api/platform/v1/orders/{orderId}/declaration、service/OrderDeclarationUpdateService.java、dto/OrderDeclarationDtos.java；权限 platform:order:declaration:edit，货物以订单内 itemNo 定位并保持行集合完整，契约 src/main/resources/openapi/order-v1.yaml
申报同步、渠道履约/计价门禁	service/OrderFulfillmentChannelChangeGuard.java、OrderPricingChannelGuard.java、OrderInboundOutboxPublisher.java，内部客户端 FirstlegInboundClient.java、FirstlegPricingClient.java；审核后通过版本化 ORDER_DECLARATION_UPDATED_V1 同步 Firstleg
入仓码业务关系摘要	service/InboundCodeAssociationService.java、dto/InboundCodeAssociationSummary.java、平台/客户 FirstLegOrderController 的 /inbound-code-associations/{inboundCode}；客户入口必须按认证客户隔离
订单编排/状态/幂等	service/OrderApplicationService.java、entity/OrderStatus.java
商户订单列表、批量草稿与中文 XLSX 导入	service/MerchantInboundOrderListService.java、MerchantBatchDraftService.java、MerchantBatchDraftItemService.java、MerchantBatchImportService.java；动态目录客户端 client/MerchantWarehouseCatalogClient.java、MerchantPricingCatalogClient.java，客户地址由 CustomerAddressService.java 提供；接口见 controller/MerchantFirstLegOrderController.java 的 /batch-imports/template、/batch-imports
入库号生成	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 消费端为 ../firstleg/src/main/java/com/baiyue/firstleg/client/OrderCargoClient.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；状态变更保留幂等、历史、审计和并发控制。
• inbound_code 是跨客户全局唯一业务码；生成模式由 InboundCodeModeProvider 控制，序列与唯一约束不得退化为客户内唯一。修改格式、长度或生成时机时同步检查 Order SQL、Firstleg 入库快照、箱唛箱码、前端展示和全局唯一性契约测试。
• 下单和后续关键状态操作不得信任客户端仓库名称、类型或启用状态；公共仓库必须通过 Warehouse 内部接口按 ID 实时校验。私人地址不得伪装为公共目的仓，非私人目的地必须引用类型匹配的公共仓库；Warehouse 不可用时失败关闭，不回退到旧快照或模拟数据。
• Warehouse 往来单位、Firstleg 入库协作只通过客户端 DTO/内部令牌；修改契约需同步消费者。
• 中文批量模板按登录客户生成取货/私人地址、国内收货仓、目的仓和渠道下拉；仓库目录必须翻页读取全部候选，不得只取第一页。导入时重新读取并校验动态目录、客户归属和启用状态，不信任模板隐藏页；文件上限 5MB、有效数据最多 50 行，仅创建草稿，PARTIAL 允许单行失败、ATOMIC 任一行失败不得落单。
• 平台只能在 DRAFT/REJECTED/SUBMITTED/APPROVED 版本化修改客户原始申报；不得修改客户、国内收货仓、订单号、入仓码、状态或仓库/PDA/设备实测、测量审核和计费事实，不得增删或重排货物行。国内收货仓或中转仓变化必须重新下单。
• 只有渠道发生变化才同时调用 Firstleg 履约可逆性与重新计价门禁，任一内部校验不可用或失败均不写入；成功后 Outbox 必须携带完整申报快照和字段变化。Firstleg 消费按 eventId + payload hash 幂等、按订单版本单调推进，渠道变化才使未确认价格预估失效。

全量验收导航

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