# 订单列表接口前端对接文档

## 通用说明

- 三个端各自独立的 `orderList` 接口，通过 `tab` 参数区分 Tab
- 返回格式统一：`{ code, msg, data: { records, total, page, size } }`
- `records` 中每条数据为 PosOrder 全字段，新增字段：
  - `deliveryStatus` — 配送状态（Long，自取/堂食为 null）
  - `payStatus` — 支付状态（Long）
  - `afterSaleStatus` — 售后状态（Long）
- **状态展示文字由前端根据 `type + state + deliveryStatus + payStatus + afterSaleStatus` 组合计算**，后端不返回 statusText
- 所有接口需要 `token` Header

---

## 一、用户端

**接口**: `GET /system/userOrder/orderList`

### 参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| token | Header | 是 | 用户身份 |
| page | int | 是 | 页码，从 1 开始 |
| size | int | 是 | 每页条数 |
| tab | String | 是 | 见下表 |
| type | String | 否 | 订单类型筛选：`0` 外送 / `1` 自取 / `2` 堂食，不传查所有 |

### Tab 列表

| Tab 名称 | tab 值 | 含义 | 请求示例 |
|----------|--------|------|---------|
| 待付款 | `unpaid` | 仅外送未支付订单 | `?tab=unpaid&page=1&size=10` |
| 进行中 | `active` | 进行中的订单 | `?tab=active&page=1&size=10` |
| 已完成 | `completed` | 已完成订单 | `?tab=completed&page=1&size=10` |
| 已取消 | `cancelled` | 已取消订单 | `?tab=cancelled&page=1&size=10` |
| 退款/售后 | `refund` | 有售后记录的订单 | `?tab=refund&page=1&size=10` |

### 前端展示文字对照表（对齐美团精简方案）

用户只关心关键节点，多个内部状态合并为一个展示文字。前端根据字段组合判断，`afterSaleStatus` 优先。

**外送 (type=0) 用户看到的文字**

| 原来的文字 | 美团方案 | 对应字段条件 |
|-----------|---------|-------------|
| 待付款 | 待支付 | payStatus=0 |
| 待商家确认 + 商家备餐中 | 商家已接单 | state=0/1, payStatus=1, afterSaleStatus=0 |
| 待骑手配送 + 骑手已接单 + 配送中 | 配送中 | state=2, deliveryStatus=0/1/2 |
| 已送达 | 已送达 | state=2, deliveryStatus=3 |
| 已完成 | 已完成 | state=3 |
| 已取消 | 已取消 | state=4, afterSaleStatus=0 |
| 退款申请中/退款中/已退款 | 退款中/已退款 | afterSaleStatus=1/2/3 |

**自取 (type=1) 用户看到的文字**

| 美团方案 | 条件 |
|---------|------|
| 待支付 | payStatus=0 |
| 商家已接单 | state=0/1 |
| 待取餐 | state=2 |
| 已完成 | state=3 |
| 已取消 | state=4 |

**堂食 (type=2) 用户看到的文字**

| 美团方案 | 条件 |
|---------|------|
| 待支付 | payStatus=0 |
| 商家已接单 | state=0/1 |
| 备餐完成 | state=2 |
| 已完成 | state=3 |
| 已取消 | state=4 |

---

## 二、商家端

**接口**: `GET /system/orderShOprate/orderList`

### 参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| token | Header | 是 | 商家身份 |
| page | int | 是 | 页码，从 1 开始 |
| size | int | 是 | 每页条数 |
| tab | String | 是 | 见下表 |
| mdId | Long | 是 | 门店 ID |
| type | String | 否 | 订单类型筛选：`0` / `1` / `2`，不传显示全部 |

### Tab 列表

| Tab 名称 | tab 值 | 含义 | 请求示例 |
|----------|--------|------|---------|
| 待受理 | `pending` | 已支付待接单（自取/堂食下单即可见） | `?tab=pending&page=1&size=10&mdId=100` |
| 待出餐 | `preparing` | 已接单备餐中 | `?tab=preparing&page=1&size=10&mdId=100` |
| 已出餐 | `ready` | 出餐完成待取/待配送 | `?tab=ready&page=1&size=10&mdId=100` |
| 已完成 | `completed` | 已完成订单 | `?tab=completed&page=1&size=10&mdId=100` |
| 已取消 | `cancelled` | 已取消订单 | `?tab=cancelled&page=1&size=10&mdId=100` |
| 退款/售后 | `refund` | 有售后记录的订单 | `?tab=refund&page=1&size=10&mdId=100` |

### 商家端操作接口

| 操作 | 接口 | 方法 | 参数 | 说明 |
|------|------|------|------|------|
| 接单 | `/system/orderShOprate/acceptOrder` | POST | `id`(订单ID) | state 0→1 |
| 出餐 | `/system/orderShOprate/dispatchOrder` | GET | `id`(订单ID) | state 1→2，外送额外设 deliveryStatus=0 |
| 完成(自取/堂食) | `/system/orderShOprate/completeOrder` | POST | `id`(订单ID) | state 2→3，payStatus 0→1 |
| 取消 | `/system/orderShOprate/cancelOrder` | POST | `id`(订单ID) | state→4，仅限 state=0 或 1 |

---

## 三、骑手端

**接口**: `GET /system/orderQsOprate/orderList`

### 参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| token | Header | 是 | 骑手身份（JwtUtil 解析即 qsId） |
| page | int | 是 | 页码，从 1 开始 |
| size | int | 是 | 每页条数 |
| tab | String | 是 | 见下表 |
| longitude | BigDecimal | 条件必填 | 骑手当前经度（**newTask Tab 必填**） |
| latitude | BigDecimal | 条件必填 | 骑手当前纬度（**newTask Tab 必填**） |

### Tab 列表

| Tab 名称 | tab 值 | 含义 | 排序 | 请求示例 |
|----------|--------|------|------|---------|
| 新任务 | `newTask` | 可抢的外送订单 | 距离从近到远 | `?tab=newTask&page=1&size=10&longitude=106.7&latitude=10.8` |
| 待取货 | `toPickup` | 已接单待取餐 | 时间从旧到新 | `?tab=toPickup&page=1&size=10` |
| 配送中 | `delivering` | 正在配送 | 时间从旧到新 | `?tab=delivering&page=1&size=10` |
| 已完成 | `completed` | 已完成订单 | 时间从新到旧 | `?tab=completed&page=1&size=10` |
| 已取消 | `cancelled` | 已取消订单 | 时间从新到旧 | `?tab=cancelled&page=1&size=10` |
| 退款/售后 | `refund` | 有售后记录的订单 | 时间从新到旧 | `?tab=refund&page=1&size=10` |

### 骑手端操作接口

| 操作 | 接口 | 方法 | 参数 | 说明 |
|------|------|------|------|------|
| 接单 | `/system/orderQsOprate/acceptOrder` | POST | `id`(订单ID) | deliveryStatus→1，绑定 qsId |
| 取餐 | `/system/orderQsOprate/pickupOrder` | POST | `id`(订单ID) | deliveryStatus→2 |
| 送达 | `/system/orderQsOprate/deliverOrder` | POST | `id`(订单ID) | deliveryStatus→3，state→3 |

---

## 四、字段值速查

### state（订单状态）

| 值 | 含义 |
|----|------|
| 0 | 待处理 |
| 1 | 已接单 |
| 2 | 已出餐 |
| 3 | 已完成 |
| 4 | 已取消 |

### deliveryStatus（配送状态，仅外送 type=0）

| 值 | 含义 |
|----|------|
| null | 自取/堂食不适用 |
| 0 | 待接单（等待骑手） |
| 1 | 骑手已接单 |
| 2 | 配送中 |
| 3 | 已送达 |

### payStatus（支付状态）

| 值 | 含义 |
|----|------|
| 0 | 未支付 |
| 1 | 已支付 |
| 2 | 已退款 |

### afterSaleStatus（售后状态）

| 值 | 含义 |
|----|------|
| 0 | 无售后 |
| 1 | 申请中 |
| 2 | 退款中 |
| 3 | 已退款 |
| 4 | 退款拒绝 |
| 5 | 客服介入 |
| 6 | 售后完成 |

### type（订单类型）

| 值 | 含义 |
|----|------|
| 0 | 外送 |
| 1 | 自取 |
| 2 | 堂食 |

---

## 五、商家端订单卡片状态显示规则

参考美团商家端：每个订单卡片只显示**一个状态文字**，用商家视角（"我该做什么"）。

### 外送订单 (type=0)

| 条件 | 显示文字 | 颜色 |
|------|---------|------|
| state=0, payStatus=0 | 待支付 | 灰色 |
| state=0, payStatus=1 | 待接单 | 橙色 |
| state=1 | 制作中 | 蓝色 |
| state=2, deliveryStatus=0/1 | 待骑手取餐 | 蓝色 |
| state=2, deliveryStatus=2 | 配送中 | 蓝色 |
| state=2, deliveryStatus=3 | 已送达 | 绿色 |
| state=3 | 已完成 | 灰色 |
| state=4 | 已取消 | 红色 |

### 自取 (type=1) + 堂食 (type=2) 统一

| 条件 | 显示文字 | 颜色 |
|------|---------|------|
| state=0 | 待接单 | 橙色 |
| state=1 | 制作中 | 蓝色 |
| state=2 | 备餐完成 | 橙色 |
| state=3 | 已完成 | 灰色 |
| state=4 | 已取消 | 红色 |

### 售后状态（所有类型，afterSaleStatus > 0 时覆盖上面的状态文字）

| 条件 | 显示文字 | 颜色 |
|------|---------|------|
| afterSaleStatus=1 | 退款申请中 | 橙色 |
| afterSaleStatus=2 | 退款中 | 橙色 |
| afterSaleStatus=3 | 已退款 | 红色 |
| afterSaleStatus=4 | 退款已拒绝 | 灰色 |

### 判断优先级

1. 先检查 afterSaleStatus，如果 > 0，显示售后状态文字
2. 否则根据 type + state + deliveryStatus 组合判断显示文字