diff --git a/changelogs/2026-03/2026-03-19_order_filter_enhance.md b/changelogs/2026-03/2026-03-19_order_filter_enhance.md new file mode 100644 index 0000000..04938fd --- /dev/null +++ b/changelogs/2026-03/2026-03-19_order_filter_enhance.md @@ -0,0 +1,81 @@ +# 订单列表筛选条件增强 - 前端对接指南 + +> **日期**: 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. **所有新增参数可选**,不传则不过滤,与现有筛选条件可自由组合