# 订单模块（business-order）

## 全站统一订单重构（路线图）

本模块将演进为**全站统一订单域**；分阶段目标、数据模型、里程碑与风险见：

- **[doc/全站统一订单改造计划.md](doc/全站统一订单改造计划.md)**
- **M1 交付**：[doc/M1-订单类型与统一主单字段定稿.md](doc/M1-订单类型与统一主单字段定稿.md)
- **M2 交付**：[doc/M2-统一订单骨架说明.md](doc/M2-统一订单骨架说明.md)
- **M3 交付**：[doc/M3-休闲试点双写与影子读.md](doc/M3-休闲试点双写与影子读.md)
- **M4 交付**：[doc/M4-休闲试点读切换.md](doc/M4-休闲试点读切换.md)
- **M5 交付**：[doc/M5-美食线统一订单接入.md](doc/M5-美食线统一订单接入.md) · [doc/M5-休闲线统一订单接入.md](doc/M5-休闲线统一订单接入.md) · [doc/M5-讲解线统一订单接入.md](doc/M5-讲解线统一订单接入.md) · [doc/M5-景区线统一订单接入.md](doc/M5-景区线统一订单接入.md) · [doc/M5-酒店线统一订单接入.md](doc/M5-酒店线统一订单接入.md) · [doc/M5-商城线统一订单接入.md](doc/M5-商城线统一订单接入.md)
- **流程与代码引用（下单 / 支付 / 回调 / 售后）**：[doc/全链路订单支付与代码引用.md](doc/全链路订单支付与代码引用.md)

> 实施过程中请同步更新该文档顶部的变更记录（若启用）。

## 模块说明

`business-order` 当前聚焦**全站统一交易单**（`TradeOrder*`、`TradeOrderItem*`）及配套应用服务。

**商城垂直订单**（`MallOrder*`、`MallOrderLog*`、`MallMemberAddress*`、`MallFirstOrderConfig*`）已迁至 **`business-mall`**（Java 包名仍为 `com.jeesharp.business.modules.mall`，与商品域同仓编排）。注入 `MallOrderApplicationService` 等、后台/移动端 HTTP 路径、双写与读切换说明，请参阅：

- **[../business-mall/README.md](../business-mall/README.md)** — 第二节「商城订单与统一交易单」

商城线 M5 设计说明（含配置开关与行为摘要）：

- [doc/M5-商城线统一订单接入.md](doc/M5-商城线统一订单接入.md)

---

## 统一交易单（本模块）

| 内容 | 位置 |
|------|------|
| 领域与 Mapper | `business-order-service` → `com.jeesharp.business.modules.trade` |
| 应用服务 | `business-order-application` → `TradeOrderApplicationService` |
| 建表脚本 | `business-order-service/src/main/resources/sql/biz_trade_order.sql` |

酒店、景区、美食等业务线接入统一单时，依赖 **`business-order-application`** 即可。**商城订单**在支付落账后若需双写统一单，由 **`business-mall-application`** 编排（该模块已声明对 `business-order-application` 的依赖）。

---

## HTTP（统一单）

> 统一交易单主数据当前以内部应用服务为主（M2）；若以扩展形式对管理端/开放网关暴露 REST，请在 `business-order-controller` 增补并与本 README 同步。

---

## 附录：跨业务线订单状态与日志规范（参考）

以下语义适用于以**商城订单主表**为载体、多业务线共用状态码时的约定；枚举与常量实现位于 **`business-mall-bean`**（如 `MallOrderStatusEnum`、`MallOrderOperateTypeConstants`）。业务模块请依赖 **`business-mall-bean`** 或经 **`business-mall-application`** 间接引用，避免魔法值。

### A.1 订单主状态（建议）

| status | 枚举名（建议） | 含义 | 典型触发点 |
|--------|----------------|------|------------|
| 0 | `PENDING_PAY` | 待支付 | 下单完成，未支付 |
| 1 | `PAID` | 已支付 | 支付回调成功 |
| 2 | `TO_FULFILL` | 待履约 | 支付成功后等待核销/发货/预约确认 |
| 3 | `FULFILLING` | 履约中 | 发货中、核销中、服务进行中 |
| 4 | `FULFILLED` | 已完成 | 用户收货/核销完成/服务完成 |
| 5 | `CLOSED` | 已关闭 | 超时关单、系统关单 |
| 6 | `REFUNDING` | 退款中 | 发起退款申请后 |
| 7 | `REFUNDED` | 已退款 | 退款完成 |
| 8 | `REFUND_REJECTED` | 退款拒绝 | 退款审核拒绝 |
| 9 | `CANCELED` | 已取消 | 用户主动取消 |

说明：

1. 状态流转示例代码请使用 `MallOrderStatusEnum` 与 `MallOrderOperateTypeConstants`（定义于 `business-mall-bean`）。
2. 若已有线上状态值，请保持兼容映射，不建议直接改历史值。

### A.2 operateType（日志操作类型）建议

`MallOrderLogApplicationService.recordOrderStatusChange(...)` 的 `operateType` 建议统一取值：

- `CREATE`：创建订单
- `PAY`：支付成功
- `CANCEL`：取消订单
- `CLOSE`：系统关单
- `REFUND`：发起退款
- `REFUND_SUCCESS`：退款完成
- `REFUND_REJECT`：退款拒绝
- `FULFILL`：履约推进（发货/核销/服务执行）
- `COMPLETE`：订单完成

### A.3 跨业务线最小落地规范

1. 下单后统一写一条 `CREATE` 日志（`null -> 0`）。
2. 支付成功统一写一条 `PAY` 日志（`0 -> 1`）。
3. 用户取消统一写一条 `CANCEL` 日志（`0/1 -> 9`，按业务限制）。
4. 退款流程至少两条日志：`REFUND`（进入退款中）+ `REFUND_SUCCESS/REFUND_REJECT`（退款结果）。
5. 每次状态变更都要求带 `operatorId`、`operatorName`、`remark`，保证可审计。