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.

接口隔离 / 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-tenant 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 tenant from JWT. The platform list requires appCode=PLATFORM: omitting tenantId queries all customer tenants, while supplying it filters one tenant. Platform detail and write operations still require an explicit target tenantId.

状态与审计 / 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.