# 订单列表筛选条件增强 - 前端对接指南

> **日期**: 2026-03-19
> **后端状态**: ✅ 已完成并部署测试环境
> **影响接口**: `GET /admin/order/list`

---

## 变更说明

订单列表查询接口新增5组筛选条件，方便管理员精确定位订单。所有新增参数均为可选，不影响现有查询。

---

## 新增筛选参数

| 参数名 | 类型 | 格式 | 说明 |
|--------|------|------|------|
| departureDateStart | String | yyyy-MM-dd | 出发日期起始（>=） |
| departureDateEnd | String | yyyy-MM-dd | 出发日期结束（<=） |
| createTimeStart | String | yyyy-MM-dd HH:mm:ss | 下单时间起始（>=） |
| createTimeEnd | String | yyyy-MM-dd HH:mm:ss | 下单时间结束（<=） |
| contactPhone | String | - | 联系电话（模糊搜索） |
| customizerName | String | - | 定制师名称（模糊搜索） |
| mchId | String | - | 商户号（字典：mch_id，精确匹配） |

---

## 完整参数列表（含原有参数）

| 参数名 | 类型 | 说明 | 新增 |
|--------|------|------|------|
| keyword | String | 搜索关键词（订单号/联系人姓名/产品名称） | |
| status | String | 订单状态，支持逗号分隔（字典：order_status） | |
| processStatus | String | 流程状态（字典：order_process_status） | |
| productType | String | 产品类型（字典：product_type） | |
| departureDateStart | String | 出发日期起始 yyyy-MM-dd | ✅ |
| departureDateEnd | String | 出发日期结束 yyyy-MM-dd | ✅ |
| createTimeStart | String | 下单时间起始 yyyy-MM-dd HH:mm:ss | ✅ |
| createTimeEnd | String | 下单时间结束 yyyy-MM-dd HH:mm:ss | ✅ |
| contactPhone | String | 联系电话（模糊搜索） | ✅ |
| customizerName | String | 定制师名称（模糊搜索） | ✅ |
| mchId | String | 商户号（字典：mch_id） | ✅ |
| sortBy | String | 排序字段：createTime/departureDate/totalPrice | |
| sortDir | String | 排序方向：desc/asc | |
| page | int | 页码（默认1） | |
| pageSize | int | 每页条数（默认20，最大100） | |

---

## 调用示例

### 按出发日期范围筛选
```
GET /admin/order/list?departureDateStart=2026-03-01&departureDateEnd=2026-03-31
```

### 按下单时间+状态组合筛选
```
GET /admin/order/list?createTimeStart=2026-03-01 00:00:00&createTimeEnd=2026-03-19 23:59:59&status=PAID,CONFIRMED
```

### 按定制师+联系电话筛选
```
GET /admin/order/list?customizerName=王骁&contactPhone=185
```

### 按商户号筛选
```
GET /admin/order/list?mchId=shanhe
```

---

## 前端对接要点

1. **出发日期筛选**：建议用日期范围选择器，传 `departureDateStart` 和 `departureDateEnd`
2. **下单时间筛选**：建议用日期时间范围选择器，格式 `yyyy-MM-dd HH:mm:ss`
3. **联系电话/定制师**：模糊搜索，输入部分内容即可匹配
4. **商户号**：下拉选择，精确匹配，值来自字典 `mch_id`
5. **所有新增参数可选**，不传则不过滤，与现有筛选条件可自由组合
