feat(order-v3): 订单列表新增定制师姓名模糊筛选参数 consultantName（PR #2569）

2026-05-19 02:49:53 +08:00 · 2026-05-19 02:49:53 +08:00 · 9dfe5b270d
--- a/changelogs/2026-05/19_feat_admin_order_list_consultant_name_filter.md
+++ b/changelogs/2026-05/19_feat_admin_order_list_consultant_name_filter.md
@ -0,0 +1,121 @@
+# 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` 为可选参数，不传则行为与改动前完全一致
+- 响应结构 / 字段无任何变化
+- 无需数据迁移，无需重启网关