baiyue-firstleg/order/README-ORDER.md

头程订单订单与客户 / First-leg Order Phase 1

数据库归属 / Database ownership

• baiyue_order：订单主数据、货物、收发货快照、目的仓快照、内部备注、状态历史和事务发件箱。 / Order master data, cargo, sender/receiver and destination snapshots, internal notes, status history, and transactional outbox.
• baiyue_firstleg：头程履约任务、指派历史与事件消费幂等。 / First-leg fulfillment tasks, assignment history, and event-consumer idempotency.
• 两个服务仅通过 tenant_id + order_id + order_no 逻辑关联，不建立跨库外键。 / Services use logical tenant_id + order_id + order_no references and never create cross-database foreign keys.
• 当前 tenant_id 是客户归属与隔离兼容字段；接口、表和类型中的 tenant 命名保持兼容，不表示真实上级租户。tenant_id=0 只用于平台技术作用域，客户订单必须使用大于 0 的客户 ID。

接口隔离 / API separation

• 商户端 /api/merchant/v1/orders/first-leg：草稿、编辑、提交、查询、详情、取消。 / Merchant draft, edit, submit, query, detail, and cancel APIs.
• 平台端 /api/platform/v1/orders/first-leg：跨客户订单列表、详情、审核、驳回、受理、取消、开始处理、完成、内部备注。 / Platform cross-customer list, detail, review, rejection, acceptance, cancellation, processing, completion, and internal notes.
• 平台指派 /api/platform/v1/first-leg/tasks/{taskId}/assignment。 / Platform fulfillment assignment.

商户接口要求 appCode=MERCHANT，客户归属从 JWT 的兼容字段取得。平台列表接口要求 appCode=PLATFORM，省略 tenantId 时查询全部客户，传入时按单个客户筛选；平台详情和写操作仍必须显式传入代表目标客户的 tenantId。

Merchant APIs require appCode=MERCHANT and derive the customer scope from the JWT compatibility field. The platform list requires appCode=PLATFORM: omitting tenantId queries all customers, while supplying it filters one customer. Platform detail and write operations still require an explicit tenantId representing the target customer.

状态与审计 / State and audit

主流程为 DRAFT → SUBMITTED → APPROVED → ACCEPTED → PROCESSING → COMPLETED，驳回路径为 SUBMITTED → REJECTED → DRAFT，处理前可取消。状态变化追加写入 ord_order_status_history；创建、提交、审核、驳回、受理、取消、状态推进、备注和指派使用 @BusinessAudit 记录。

The main flow is DRAFT → SUBMITTED → APPROVED → ACCEPTED → PROCESSING → COMPLETED; rejection follows SUBMITTED → REJECTED → DRAFT, and cancellation is permitted before processing. Status changes append to ord_order_status_history; key operations use @BusinessAudit.

验证 / Verification

mvn -pl order,firstleg -am -DskipTests clean compile

已通过 Java 17 干净编译。 / Verified with a clean Java 17 compilation.