diff --git 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 new file mode 100644 index 0000000..45af0a9 --- /dev/null +++ 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\ | 否 | 按标签名过滤(多选) | +| **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` 为可选参数,不传则行为与改动前完全一致 +- 响应结构 / 字段无任何变化 +- 无需数据迁移,无需重启网关