docs(changelog): #8446 订单列表 productType 查询参数 + 前端订单类型改页签
changelog-filename-gate / validate (push) Failing after 1s

- 接口:GET /v3/admin/order(含 /list 别名)与 /status-group-counts 新增 productType,测试服实测样本与读数
- 前端:订单列表「订单类型」下拉改为核心 / 定制 / 团期页签(交 mmg)

Refs wx/HL#8446

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
这个提交包含在:
API Changelog Bot
2026-09-27 21:40:09 +08:00
共同撰写人 Claude Opus 5.5
父节点 110dc3ff89
当前提交 2f02fbb3a3
共修改 2 个文件,包含 496 行新增和 0 行删除
@@ -0,0 +1,375 @@
---
schema: "hl-changelog/v2"
ticket: "8446"
title: "订单列表与状态计数新增查询参数 productType(核心 / 定制 / 团期页签)"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: "mmg"
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "PR #8454 已合入 dev-v3(22145977d),order-v3 已部署测试服,经网关实测三个端点。新增查询参数 productType,与其他条件取 AND;只传 productType、不传 orderKind 时不按团属性过滤。前端改动见同日前端 changelog。"
updated_at: "2026-09-27"
base: "dev-v3"
---
# 订单服务(order-v3): 订单列表与状态计数新增查询参数 productType
> **服务**: hl-order-service-v3(端口 8086/8186)
> **PR**: #8454(合并提交 `22145977d`)
> **Issue**: #8446
> **日期**: 2026-09-27
> **影响范围**: 管理后台「订单管理v2 › 订单列表」的列表与状态计数接口
---
## ⚠️ 关键变化
1. 列表 `GET /v3/admin/order`(别名 `/v3/admin/order/list`)与状态计数 `GET /v3/admin/order/status-group-counts` 新增查询参数 **`productType`**:`CORE` / `ROUTE` / `CUSTOM` / `GROUP`,英文逗号多值,空串等同不传。
2. **只传 `productType`、不传(或传空串)`orderKind` 时,不再缺省 `orderKind=NORMAL`,不按「是否挂团期」过滤。** 页签「团期」因此能查到团期订单。
3. 其余组合行为不变:显式传 `orderKind` 与 `productType` 取 AND;传 `groupBatchId` / `groupBatchKeyword` 时仍强制按团期,再与 `productType` 取 AND。两个参数都不传时仍缺省 NORMAL。
4. 非法值(如 `productType=XYZ`)返回 HTTP 200 + `code=100001`,与 `orderKind` 非法值同码。
5. 响应结构不变。
---
## 一、背景
wx 2026-09-27 要求订单列表的「订单类型」下拉(散客 / 团单 / 全部)改成「核心 / 定制 / 团期」页签。页签按**产品类型**切分,而原 `orderKind` 按「订单有没有挂运营团期」切分,两者不是同一口径,所以新增 `productType`,`orderKind` 保留原语义不废弃。
---
## 二、变更接口清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 订单列表 | GET | `/v3/admin/order` | 新增参数 | `productType`,别名路径 `/v3/admin/order/list` 同样生效 |
| 2 | 订单列表 Tab 分组计数 | GET | `/v3/admin/order/status-group-counts` | 新增参数 | `productType`,与列表同口径 |
---
## 三、接口详情
### 1. 订单列表 `GET /v3/admin/order`
**VO**: `OrderListReqVO` → `Result<PageResult<OrderListItemRespVO>>`
#### 使用场景
订单列表页签「核心 / 定制 / 团期」切换时,按当前页签传 `productType=CORE|CUSTOM|GROUP` 取列表。
#### 入参字段表
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| productType | query | String | 否 | `CORE`/`ROUTE`/`CUSTOM`/`GROUP`,多值用英文逗号分隔(如 `CORE,CUSTOM`),空串等同不传 | **新增**。按订单产品类型过滤,与其他条件取 AND |
| orderKind | query | String | 否 | `ALL`/`GROUP`/`NORMAL`,空串等同不传 | 原有。未传时缺省 NORMAL;**例外**:传了 productType 而本参数未传或为空串时不缺省、不按团属性过滤 |
其余参数(`keyword`、`orderStatus`、`statusGroup`、`groupBatchId`、`groupBatchKeyword`、`page`、`pageSize` 等)不变,`pageSize` 上限 100。
#### 出参字段表
| 字段 | 类型 | 说明 |
|------|------|------|
| data.records[] | Array | 订单行(前端 `request.js` 拦截器会同步映射为 `list`) |
| data.records[].id | String | 订单 ID |
| data.records[].productType | String | 产品类型 CORE/ROUTE/CUSTOM/GROUP |
| data.total | Number | 符合条件的总条数 |
| data.page | Number | 当前页 |
| data.pageSize | Number | 每页条数 |
订单行其余字段不变。
#### 请求示例
```http
GET /v3/admin/order?productType=CORE&page=1&pageSize=100
```
#### 响应示例
测试服 2026-09-27 实测,节选前 2 条、每条只保留关键字段:
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"total": 71,
"page": 1,
"pageSize": 100,
"records": [
{
"id": "2104192144560553985",
"orderNo": "HL20260927205115753",
"productType": "CORE",
"groupBatchId": null,
"orderStatus": "CUSTOMIZING"
},
{
"id": "2104161383220457474",
"orderNo": "HL20260927184901765",
"productType": "CORE",
"groupBatchId": null,
"orderStatus": "CUSTOMIZING"
}
]
}
}
```
#### 空数据 / 降级响应
没有符合条件的订单时 `records` 为空数组、`total` 为 0,例如 `productType=CORE` 加一个只挂了团期订单的团期关键词。
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"total": 0,
"page": 1,
"pageSize": 20,
"records": []
}
}
```
#### 错误响应
非法值返回 HTTP 200,`code=100001`(测试服实测原文):
```json
{
"code": 100001,
"message": "productType 非法,可选值: CORE, ROUTE, CUSTOM, GROUP(多值用逗号分隔)",
"data": null,
"traceId": null,
"success": false
}
```
#### 业务边界
- 多值用英文逗号,命中任一即返回;空串等同不传。
- 只传 `productType` 时不按团属性过滤;默认仍排除已取消订单,传 `statusGroup=ALL` 才含已取消(与原口径一致)。
- 显式传 `orderKind` 时与 `productType` 取 AND,例如 `productType=GROUP&orderKind=NORMAL` 恒为空。
- 传 `groupBatchId` / `groupBatchKeyword` 时强制按团期,再与 `productType` 取 AND;在「核心 / 定制」页签下填团期关键词,只会查到挂了该团期、且产品类型是核心 / 定制的订单。
- `ROUTE`(自驾路书)后端接受,本次前端不设页签。
- 别名 `/v3/admin/order/list` 入参出参完全相同。
---
### 2. 订单列表 Tab 分组计数 `GET /v3/admin/order/status-group-counts`
**VO**: `OrderListReqVO` → `Result<List<StatusGroupCountVO>>`
#### 使用场景
页签切换时与列表一起请求,传同一个 `productType`,刷新顶部状态分组徽标。
#### 入参字段表
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| productType | query | String | 否 | `CORE`/`ROUTE`/`CUSTOM`/`GROUP`,多值用英文逗号分隔,空串等同不传 | **新增**。与列表同口径 |
| orderKind | query | String | 否 | `ALL`/`GROUP`/`NORMAL`,空串等同不传 | 原有。与列表同口径,含上面的例外 |
其余参数与列表相同(不传 `statusGroup` / `orderStatus` / `page` / `pageSize`)。
#### 出参字段表
| 字段 | 类型 | 说明 |
|------|------|------|
| data[].group | String | 分组标识,固定 6 项,顺序 ALL、BEFORE_TRIP、ON_TRIP、SETTLEMENT、ABNORMAL、AFTERSALE |
| data[].label | String | 分组中文名:全部 / 出行前 / 出行中 / 核单 / 异常/取消 / 售后 |
| data[].orderCount | Number | 该分组订单数 |
#### 请求示例
```http
GET /v3/admin/order/status-group-counts?productType=GROUP
```
#### 响应示例
测试服 2026-09-27 实测原文:
```json
{
"code": 200,
"message": "成功",
"data": [
{ "group": "ALL", "label": "全部", "orderCount": 14 },
{ "group": "BEFORE_TRIP", "label": "出行前", "orderCount": 14 },
{ "group": "ON_TRIP", "label": "出行中", "orderCount": 0 },
{ "group": "SETTLEMENT", "label": "核单", "orderCount": 0 },
{ "group": "ABNORMAL", "label": "异常/取消", "orderCount": 8 },
{ "group": "AFTERSALE", "label": "售后", "orderCount": 0 }
],
"traceId": null,
"success": true
}
```
#### 空数据 / 降级响应
没有符合条件的订单时 6 项仍全部返回,`orderCount` 均为 0。
```json
{
"code": 200,
"message": "成功",
"data": [
{ "group": "ALL", "label": "全部", "orderCount": 0 },
{ "group": "BEFORE_TRIP", "label": "出行前", "orderCount": 0 },
{ "group": "ON_TRIP", "label": "出行中", "orderCount": 0 },
{ "group": "SETTLEMENT", "label": "核单", "orderCount": 0 },
{ "group": "ABNORMAL", "label": "异常/取消", "orderCount": 0 },
{ "group": "AFTERSALE", "label": "售后", "orderCount": 0 }
],
"traceId": null,
"success": true
}
```
#### 错误响应
与列表相同,非法值返回 HTTP 200 + `code=100001`(测试服实测原文):
```json
{
"code": 100001,
"message": "productType 非法,可选值: CORE, ROUTE, CUSTOM, GROUP(多值用逗号分隔)",
"data": null,
"traceId": null,
"success": false
}
```
#### 业务边界
- 与列表共用 `OrderListReqVO` 和同一套过滤,页签徽标与列表条数同口径。
- 「全部」= 出行前 + 出行中 + 核单,**不含**「异常/取消」,只有显式 `orderKind=ALL` 或 `cancelled=true` 时才计入。只传 `productType` 时不含,与两个参数都不传时一致。上例 14 = 14 + 0 + 0。
- 「售后」是横切计数,任何情况下都不计入「全部」。
---
## 四、契约约束与正确调用方式
- 页签「核心 / 定制 / 团期」→ 列表与计数都传 `productType=CORE|CUSTOM|GROUP`,**不传 `orderKind`**。
- 如果仍带着旧的 `orderKind=NORMAL`,会与 `productType` 取 AND,「团期」页签恒为空。
- 旧调用方(只传 `orderKind` 或都不传)行为不变。
| 组合 | 结果 |
|------|------|
| `productType=CORE` | 核心产品订单,不看是否挂团期 |
| `productType=CORE,CUSTOM` | 核心 + 定制 |
| `productType=GROUP&orderKind=NORMAL` | 恒为空 |
| 两个都不传 | 缺省 NORMAL(未挂团期的订单),与改动前一致 |
| `productType=XYZ` | HTTP 200,`code=100001` |
---
## 五、数据库行为
无数据库变更,只新增查询条件 `product_type IN (...)`。
---
## 六、边界行为
1. `productType` 是独立追加的 AND 条件,不进团属性判断链,所以不会和 `groupBatchId` / `groupBatchKeyword` 互相吞掉(`OrderListScopeFilter.java:44`、`:54-55`)。
2. 只传 `productType` 时 Service 把 `orderKind` 置 null 而不是 `ALL`:置 `ALL` 会让「全部」徽标计入已取消(`OrderService.java:529`)。
3. `ROUTE` 测试服当前产品与订单都是 0 条,后端已支持,将来加页签无需改后端。
---
## 六.5、枚举 / 数据字典
### productType(产品类型)
**所属字段**: 入参 `OrderListReqVO.productType`、出参 `records[].productType` | **类型**: `String`
| 值 | 中文 | 页签 |
|----|------|------|
| `CORE` | 核心 | 核心 |
| `CUSTOM` | 定制 | 定制 |
| `GROUP` | 团期 | 团期 |
| `ROUTE` | 自驾路书 | 本次不设 |
---
## 六.6、修改前后对比
| 场景 | 改前 | 改后 |
|------|------|------|
| 入参 `productType` | 无 | 新增,多值 |
| 只传 `productType`、不传 `orderKind` | —(参数不存在) | 不缺省 NORMAL,不按团属性过滤 |
| 只传 `orderKind` 或都不传 | 都不传时缺省 NORMAL | 不变 |
---
## 六.7、影响评估
- **向后兼容**:是。不传 `productType` 的调用方行为不变。
- **前端是否必须同步**:前端改页签时列表与计数都要改传 `productType`、删掉 `orderKind`;不改前端时现有下拉照常可用。
---
## 七、不影响范围
- 订单详情、创建、编辑等其他接口不变。
- 定制师待办列表(`DesignerOrderListService`)、财务订单查询(`FinanceOrderQueryApiImpl`)复用同一查询对象但不设 `productTypes`,行为不变。
- 小程序(`MpOrderListReqVO`)、H5 不涉及。
---
## 八、测试环境已验证
测试服 order-v3 `22145977d`,经网关、测试专用 ADMIN 账号,逐条与同条件 SQL(`hl_order_service_v3.order_main`,`deleted_at IS NULL`,默认排除已取消)比对,全部一致:
| 请求 | total / 计数 | SQL |
|------|------|------|
| `productType=CORE` / `CUSTOM` / `GROUP` | 71 / 2 / 14,逐条 productType 全匹配 | 71 / 2 / 14 |
| 同上 + `statusGroup=ALL` | 86 / 2 / 22 | 86 / 2 / 22 |
| `/v3/admin/order/list?productType=GROUP` | 14 | 与主路径相同 |
| `productType=CORE,CUSTOM` | 73 | 71 + 2 |
| `productType=`(空串)/ 都不传 | 73 / 73 | NORMAL 口径 73 |
| `orderKind=GROUP` / `orderKind=ALL` | 14 / 87 | 14 / 87 |
| 计数 `productType=GROUP` | 全部 14、出行前 14、出行中 0、核单 0、异常/取消 8、售后 0 | 逐组一致 |
| 计数不传 productType | 全部 73、出行前 43、出行中 0、核单 30、异常/取消 15、售后 0 | 与上一行不同,参数生效 |
| 团期关键词 / + `productType=GROUP` / + `productType=CORE` | 12 / 12 / 0 | 该团期 CORE 订单 0 条 |
| `productType=XYZ`(列表、计数) | HTTP 200,`code=100001` | — |
单测:OrderServiceTest 323、OrderListScopeFilterTest 18、OrderListReqVOValidationTest 16、OrderGlobalExceptionHandlerTest 9、OrderControllerTest 56、OrderInfoMapperIT 30(Testcontainers 真库),全绿。
---
## 十、相关文档
- 接口文档:`docs/order-v3/api/API-SPEC.html`(订单列表参数表、orderKind 例外、§1.11 计数口径)
- 入参:`hl-order-service-v3/src/main/java/com/hulalv/order/core/controller/admin/vo/OrderListReqVO.java:91-104`(productType)、`:59-63`(orderKind 例外说明)
- 过滤:`hl-order-service-v3/src/main/java/com/hulalv/order/core/mapper/OrderListScopeFilter.java:54-55`
- 错误码:`hl-order-service-v3/src/main/java/com/hulalv/shared/exception/OrderGlobalExceptionHandler.java:104-110`
---
## 关联 / 联系人
### 链接
- **Issue**: [#8446](https://git.1814.love/wx/HL/issues/8446)
- **PR**: [#8454](https://git.1814.love/wx/HL/pulls/8454)
- **前端 changelog**: `27_frontend_订单列表订单类型改页签-前端优化-管理后台.md`
### 联系人
- **后端负责人**: @wx
- **前端负责人**: @mmg
@@ -0,0 +1,121 @@
---
schema: "hl-changelog/v2"
ticket: "8446"
title: "订单列表「订单类型」下拉改为「核心 / 定制 / 团期」页签"
consumer: "admin"
author: "wx(GIT)"
change_type: "前端优化"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: "mmg"
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "后端查询参数 productType 已部署测试服并实测(#8446,PR #8454)。前端:订单列表「订单类型」下拉改为「核心 / 定制 / 团期」页签,默认核心;列表与状态计数请求传 productType,不再传 orderKind。"
updated_at: "2026-09-27"
base: "dev-v3"
---
# 前端优化:订单列表「订单类型」下拉改为「核心 / 定制 / 团期」页签
## ⚠️ 关键变化
1. **订单管理v2 › 订单列表**:删除搜索区「订单类型」下拉(散客 / 团单 / 全部,默认散客),改为表格工具栏左侧的页签「核心 / 定制 / 团期」,默认「核心」。样式同「财务管理 › 核单列表」的「常规产品 / 团期产品」页签。
2. **列表请求与状态计数请求都传当前页签的 `productType=CORE|CUSTOM|GROUP`,不再传 `orderKind`。**
- 限定:如果请求里还带着 `orderKind=NORMAL`,后端会与 `productType` 取 AND,「团期」页签恒为空(团期订单都挂了团期)。
---
## 一、背景
wx 2026-09-27:「把订单列表的页面的类型也换成tab 也是 核心/定制/团期」。页签按订单**产品类型**切分,与同日房务管家订单列表的页签口径一致。原「散客 / 团单」按「订单有没有挂团期」切分,和产品类型不是一回事。
后端新增查询参数 `productType`(#8446,PR #8454),契约详见同日接口 changelog `27_8446_订单列表按产品类型筛选-修改接口-管理后台.md`。
---
## 二、现状(hl-ui `origin/v2.1` @ `1c555f5`,逐行核过)
文件 `src/views/order-v2/list/index.vue`:
| 位置 | 现状 |
|------|------|
| `:55-64` | 搜索区「订单类型」`n-select`:`v-model:value="searchForm.orderKind"`、`:options="orderKindOptions"`、`@update:value="handleSearch"` |
| `:139` | `import { …, ORDER_KIND_OPTIONS } from '@/api/orderV2'` |
| `:234-235` | `const orderKindOptions = ORDER_KIND_OPTIONS` 及 #7635 注释 |
| `:236-255` | `adaptedApi.getPage`:`searchForm` 除日期 / 定制师 / 标签外的字段经 `...rest` 原样透传给 `getOrderPage` |
| `:279-280` | `useListPage` 的 `searchFields`:`{ key: 'orderKind', default: 'NORMAL' }` |
| `:306-308`、`:322-323` | `fetchGroupCounts` 手工拼参数:`if (searchForm.orderKind) params.orderKind = searchForm.orderKind`,以及描述入参的注释 |
| `:344-347` | `handleSearch()`:`doSearch()` 刷列表 + `fetchGroupCounts()` 刷状态计数 |
| `:103-120` | ProTable `#toolbar`:左「共 N 条」,右「新增订单」按钮 |
`src/api/orderV2.js`:`:25-33` 定义 `ORDER_KIND` / `ORDER_KIND_OPTIONS`;`getOrderPage`(`:114`)与 `getOrderStatusGroupCounts`(`:137`)的 jsdoc 列了 `orderKind`(`:108`、`:133`)。
---
## 三、改动要点
1. **删除下拉**:删掉 `index.vue:55-64` 整个「订单类型」`form-item`、`:234-235` 的 `orderKindOptions`、`:139` 的 `ORDER_KIND_OPTIONS` import。
2. **搜索字段**:`:279-280` 的 `{ key: 'orderKind', default: 'NORMAL' }` 改为 `{ key: 'productType', default: 'CORE' }`。列表请求经 `...rest` 自动带上 `productType`,`adaptedApi.getPage` 不用改。
3. **状态计数**:`:322-323` 改为 `if (searchForm.productType) params.productType = searchForm.productType`,`:306-308` 注释里的 `orderKind` 同步改成 `productType`。
4. **页签**:放在 ProTable `#toolbar` 左侧,写法照核单列表 `src/views/finance/settlement/index.vue:52-66`:外层 `<n-flex justify="space-between" align="center" class="table-summary">`,左边页签,右边放现有的「共 N 条」和「新增订单」按钮。样式照该文件 `:213-219`:`.table-summary { width: 100%; }`、`.product-tabs { width: 280px; }`。
```vue
<n-tabs
:value="searchForm.productType"
type="line"
size="small"
class="product-tabs"
@update:value="onProductTypeChange"
>
<n-tab name="CORE">核心</n-tab>
<n-tab name="CUSTOM">定制</n-tab>
<n-tab name="GROUP">团期</n-tab>
</n-tabs>
```
```js
// 切页签 = 原下拉的 @update:value="handleSearch":列表与状态计数一起刷新
function onProductTypeChange(v) {
searchForm.productType = v
handleSearch()
}
```
核单列表用的是 `v-model:value`,切换时不发请求,这里不能照抄。
5. **重置**:「重置」走 `doReset`,按 `searchFields` 默认值把页签恢复为「核心」,与原下拉重置回「散客」同构,不用额外处理。
6. **`src/api/orderV2.js`**:`getOrderPage` 与 `getOrderStatusGroupCounts` 的 jsdoc 补 `productType`。`ORDER_KIND` / `ORDER_KIND_OPTIONS` 列表页不再使用;如果删除,同步删 `src/api/__tests__/orderV2.spec.js:444-448` 的断言,保留也不影响功能。
---
## 四、调用时会撞上的限定
- `productType` 取 `CORE` / `CUSTOM` / `GROUP`。后端还接受 `ROUTE`(自驾路书),本次不设页签。非法值返回 HTTP 200 + `code=100001`。
- 不传 `orderKind` 时,后端不再按「是否挂团期」过滤,只按产品类型分。状态计数「全部」的取消口径与不传 `productType` 时一致。
- **「团期」关键词输入框**(`groupBatchKeyword`,`index.vue:67-76`):填了关键词时,后端只查挂了命中团期的订单,再与 `productType` 取 AND。在「核心 / 定制」页签下填团期关键词,结果基本为空(测试服当前没有「核心产品却挂了团期」的订单)。建议该输入框只在「团期」页签显示,由前端决定。
- 响应结构不变:列表后端返回 `{ records, total, page, pageSize }`,`src/utils/request.js:445` 拦截器已映射为 `list`,前端照旧读 `res.list`;状态计数 `[{ group, label, orderCount }]` 固定 6 项。
---
## 五、验证清单(前端改完自查)
- [ ] 订单列表不再有「订单类型」下拉,工具栏左侧出现「核心 / 定制 / 团期」页签,默认「核心」
- [ ] 切换页签时,列表与顶部状态分组计数一起刷新;两个请求的 query 都带 `productType`,不带 `orderKind`
- [ ] 「团期」页签有数据;「核心」页签不再混入团期订单
- [ ] 点「重置」回到「核心」
- [ ] 若删了 `ORDER_KIND_OPTIONS`,`orderV2.spec.js` 断言同步删除,单测绿
---
## 六、不影响范围
- 订单详情、出团管理、房务管家订单列表不涉及
- 小程序、H5 不涉及
---
## 联系人
- **后端负责人**: @wx
- **前端负责人**: @mmg