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

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

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