# API 变更通知

**更新时间**: 2026-05-19 03:00
**PR**: #2569 feat(order-v3): admin 订单列表加 consultantName 模糊筛选

## ✨ 订单列表接口新增「定制师姓名」筛选参数

### 变了什么（前端视角）

管理后台订单列表接口 `GET /v3/admin/order` 新增一个**可选查询参数** `consultantName`，支持按定制师姓名模糊筛选订单。

传入后，接口会对数据库 `consultant_name` 列做 `LIKE %xxx%` 匹配；不传（或传 `null`/空字符串）则不过滤，行为与之前完全一致。

**对照表**：

| 参数 | 原来 | 现在 |
|------|------|------|
| `consultantName` | 不存在，传了被忽略 | 支持，做 LIKE 模糊匹配 |

### 前端要改的地方

1. **订单列表顶部「定制师」筛选框**：将用户输入的定制师姓名作为 `consultantName` 参数拼到请求 query string 里，随其他已有筛选条件一起传给后端。
2. **清空筛选框时**：将 `consultantName` 置为 `undefined`（不传该字段）或传空字符串均可，后端两种情况都不过滤。

### 涉及的接口 / 模块

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 订单列表分页 | GET | `/v3/admin/order` | ✨ 新增请求参数 | 加 `consultantName` 可选筛选字段 |

### 接口详细定义

#### 订单列表分页

- **使用场景**：管理后台订单列表页，支持多条件组合筛选
- **请求参数（完整）**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | Integer | 是 | 页码，从 1 开始 |
| pageSize | Integer | 是 | 每页条数，建议 10 / 20 |
| keyword | String | 否 | 关键词模糊匹配（团号 / 客户姓名 / 产品名 / 订单号任一） |
| status | String | 否 | 订单状态枚举，见枚举表 |
| createSource | String | 否 | 创建来源枚举 |
| departureDateFrom | String | 否 | 出发日期起（yyyy-MM-dd） |
| departureDateTo | String | 否 | 出发日期止（yyyy-MM-dd） |
| cancelled | Boolean | 否 | 是否含已取消（默认 false） |
| tagNames | List\<String\> | 否 | 按标签名过滤（多选） |
| **consultantName** | **String** | **否** | **定制师姓名模糊匹配（LIKE %xxx%）。空/null 不过滤（本次新增）** |

- **请求示例（带定制师筛选）**：
```
GET /v3/admin/order?page=1&pageSize=20&consultantName=李定制
Authorization: Bearer {token}
```

- **请求示例（组合筛选）**：
```
GET /v3/admin/order?page=1&pageSize=20&status=CONFIRMED&consultantName=王
Authorization: Bearer {token}
```

- **响应示例（完整）**：
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "records": [
      {
        "id": 1234567890,
        "orderNo": "HL20260519001",
        "status": "CONFIRMED",
        "productName": "云南大理 7 日游",
        "consultantName": "李定制",
        "consultantId": 100001,
        "customerName": "张三",
        "departDate": "2026-06-01",
        "headCount": 4,
        "totalAmount": 12800.00,
        "createTime": "2026-05-19T10:00:00"
      }
    ],
    "total": 5,
    "page": 1,
    "pageSize": 20
  }
}
```

- **响应字段说明**（本次无变化，仅供参考）：

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 订单 ID |
| orderNo | String | 订单号 |
| status | String | 订单状态，见枚举表 |
| productName | String | 产品名称 |
| consultantName | String | 定制师姓名 |
| consultantId | Long | 定制师 ID |
| customerName | String | 客户姓名 |
| departDate | String | 出发日期（yyyy-MM-dd） |
| headCount | Integer | 出行人数 |
| totalAmount | BigDecimal | 订单总金额 |
| createTime | String | 创建时间（ISO 8601） |
| total | Long | 满足条件的总记录数 |
| page | Integer | 当前页码 |
| pageSize | Integer | 每页条数 |

### 业务规则 / 校验规则

- `consultantName` 为空字符串或 null 时，SQL 不追加该条件，等价于不筛选
- 匹配方式：`LIKE %{consultantName}%`（前后都带通配符），输入"李"可匹配"李定制"、"王李明"等
- 筛选字段作用于订单表 `consultant_name` 列（存的是定制师的真实姓名，非企微名）
- 与其他筛选条件（keyword、status、departureDateFrom 等）是 AND 关系，可自由组合

### 向后兼容性说明

- 本次变更**完全向后兼容**：`consultantName` 为可选参数，不传则行为与改动前完全一致
- 响应结构 / 字段无任何变化
- 无需数据迁移，无需重启网关
