From 4620642b9f142c6c9a654fad4b74fc209607699c Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Wed, 17 Jun 2026 18:10:37 +0800 Subject: [PATCH] =?UTF-8?q?feat(order-v3):=20=E6=8E=A8=E9=80=81=E8=AE=A2?= =?UTF-8?q?=E5=8D=95=E5=88=97=E8=A1=A83=E4=B8=AA=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=E5=8F=98=E6=9B=B4changelog(#3923/#3930/#3938)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 修改接口: 待支付订单flowStatusName/flowDisplayText返null(#3923) - 新增接口: GET /v3/admin/order/status-options 订单状态下拉(#3930) - 新增接口: GET /v3/admin/order/status-group-counts Tab分组计数(#3939) - 修改接口: GET /v3/admin/order 新增入参statusGroup Tab过滤(#3939) --- ...待支付流程状态文案返空-修改接口-管理后台.md | 269 ++++++++++++++++++ ...单状态筛选下拉选项端点-新增接口-管理后台.md | 149 ++++++++++ ...表Tab分组计数与分组过滤-新增接口-管理后台.md | 215 ++++++++++++++ 3 files changed, 633 insertions(+) create mode 100644 changelogs-v2/2026-06/17_3923_订单待支付流程状态文案返空-修改接口-管理后台.md create mode 100644 changelogs-v2/2026-06/17_3930_订单状态筛选下拉选项端点-新增接口-管理后台.md create mode 100644 changelogs-v2/2026-06/17_3938_订单列表Tab分组计数与分组过滤-新增接口-管理后台.md diff --git a/changelogs-v2/2026-06/17_3923_订单待支付流程状态文案返空-修改接口-管理后台.md b/changelogs-v2/2026-06/17_3923_订单待支付流程状态文案返空-修改接口-管理后台.md new file mode 100644 index 0000000..d9a66c4 --- /dev/null +++ b/changelogs-v2/2026-06/17_3923_订单待支付流程状态文案返空-修改接口-管理后台.md @@ -0,0 +1,269 @@ +# 待支付订单流程状态文案返空（与步骤条对齐）— 修改接口 — 管理后台 + +> 变更类型：🔧 接口行为变更（出参字段值规则调整） +> 端类型：管理后台 +> 日期：2026-06-17 +> 服务：hl-order-service-v3 +> PR：https://git.1814.love:8443/wx/HL/pulls/3926 + +--- + +## 1. 接口背景 + +**功能页面**：管理后台「订单列表」页 + 「订单详情」页。 + +**用在哪**： +- **订单列表**：每一行订单卡片上显示「业务流程状态」的文字标签（如"资源准备""待出行"等）。 +- **订单详情**：详情 main 区域顶部的「当前步文案」（与步骤条联动显示，前端通常拼为"2/6 · 资源准备"格式）。 + +**修复了什么问题**：待支付订单（`orderStatus=PENDING_PAY`）的流程状态文案之前返回"待支付"，但详情步骤条（`progressStepper`）在待支付时 `flowStep=0`、6 个节点全为 `WAITING`（步骤条未点亮）。两者语义冲突——流程尚未开始，不应在流程状态位置显示文案。 + +**修复后**：待支付时 `flowStatusName`、`flowDisplayText` 均返 `null`，与步骤条未点亮保持一致。"待支付"由 `orderStatus`/`orderStatusName` 字段表达，语义不丢。 + +--- + +## 2. 变更清单 + +| 接口 | 字段 | 变更前 | 变更后 | 影响范围 | +|---|---|---|---|---| +| `GET /v3/admin/order`（列表） | `flowStatusName` | `"待支付"`（当 PENDING_PAY 时） | `null` | 订单列表行流程状态标签 | +| `GET /v3/admin/order`（列表） | `flowDisplayText` | `"待支付"`（当 PENDING_PAY 时） | `null` | 订单列表行当前步文案 | +| `GET /v3/admin/order/{id}`（详情 main） | `flowStatusName` | `"待支付"`（当 PENDING_PAY 时） | `null` | 详情页流程状态名 | +| `GET /v3/admin/order/{id}`（详情 main） | `flowDisplayText` | `"待支付"`（当 PENDING_PAY 时） | `null` | 详情页当前步文案 | + +**其他字段不变**：`flowStep` 仍为 `0`，`flowStatus` 仍为 `"AWAITING_PAY"`，`progressStepper` 仍为 6 节点全 `WAITING`，`orderStatusName` 仍为 `"待支付"`。 + +--- + +## 3. 接口详情 + +### 3.1 订单列表 + +- **方法 + 路径**：`GET /v3/admin/order`（别名 `GET /v3/admin/order/list`） +- **认证**：需要 JWT（管理后台登录 token，Gateway 注入 `X-Admin-Id`） +- **幂等性**：查询接口，天然幂等 +- **限流**：无独立限流规则 + +### 3.2 订单详情 + +- **方法 + 路径**：`GET /v3/admin/order/{id}` +- **认证**：需要 JWT（同上） +- **幂等性**：查询接口，天然幂等 +- **限流**：无独立限流规则 + +--- + +## 4. 接口入参 + +### 4.1 订单列表 Query 参数（与本次变更无关，无入参改动） + +| 参数 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `orderStatus` | String | 否 | 粗状态过滤 | +| `keyword` | String | 否 | 关键字模糊搜索 | +| `departureDateFrom` | LocalDate | 否 | 出发日期起始 | +| `departureDateTo` | LocalDate | 否 | 出发日期结束 | +| `createSource` | String | 否 | 订单来源 | +| `consultantName` | String | 否 | 定制师姓名 | +| `page` | Integer | 否 | 页码，默认 1 | +| `pageSize` | Integer | 否 | 每页条数，默认 10 | + +### 4.2 订单详情路径参数 + +| 参数 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `id` | Long | 是 | 订单 ID（雪花 ID 字符串） | + +--- + +## 5. 出参字段（受本次影响的关键字段） + +### 5.1 订单列表 OrderListItemRespVO（变更字段） + +| 字段 | 类型 | 说明 | 本次变化 | +|---|---|---|---| +| `orderStatus` | String | 粗状态枚举值，如 `PENDING_PAY` | **不变** | +| `orderStatusName` | String | 粗状态中文名，如 `"待支付"` | **不变**，仍返"待支付" | +| `flowStatus` | String | 细状态枚举值，如 `AWAITING_PAY` | **不变** | +| `flowStatusName` | String | 细状态中文名 | ⚠️ **变更**：PENDING_PAY 时从"待支付"改为 `null` | +| `flowStep` | Integer | 线性 6 步当前步序号（0=待支付未开始） | **不变**，仍为 `0` | +| `flowStepTotal` | Integer | 总步数，固定 `6` | **不变** | +| `flowDisplayText` | String | 当前步中文名 | ⚠️ **变更**：PENDING_PAY 时从"待支付"改为 `null` | + +### 5.2 订单详情 OrderMainVO（变更字段） + +| 字段 | 类型 | 说明 | 本次变化 | +|---|---|---|---| +| `orderStatus` | String | 粗状态枚举值 | **不变** | +| `orderStatusName` | String | 粗状态中文名 | **不变**，仍返"待支付" | +| `flowStatusName` | String | 细状态中文名 | ⚠️ **变更**：PENDING_PAY 时从"待支付"改为 `null` | +| `flowStep` | Integer | 当前步序号 | **不变**，仍为 `0` | +| `flowDisplayText` | String | 步骤展示文案 | ⚠️ **变更**：PENDING_PAY 时从"待支付"改为 `null` | +| `progressStepper` | List | 6 节点步骤条 | **不变**，仍为 6 节点全 `WAITING` | + +--- + +## 6. 枚举 / 数据字典 + +### 订单粗状态 orderStatus + +| 值 | 中文名 | +|---|---| +| `PENDING_PAY` | 待支付 | +| `CUSTOMIZING` | 定制中 | +| `PENDING_DEPARTURE` | 待出行 | +| `TRAVELLING` | 出行中 | +| `COMPLETED` | 已完成 | +| `CANCELLED` | 已取消 | + +### 订单细状态 flowStatus（PENDING_PAY 对应值） + +| 值 | 中文名（本次改动前） | 中文名（本次改动后） | +|---|---|---| +| `AWAITING_PAY` | 待支付 | `null`（不算流程状态） | + +--- + +## 7. 错误码 + +本次为出参字段值规则调整，无新增错误码。通用错误码： + +| code | 含义 | +|---|---| +| `200` | 成功 | +| `401` | 未登录 / token 过期 | +| `404` | 订单不存在（详情接口） | + +--- + +## 8. 示例 + +### 8.1 典型成功——待支付订单列表项 + +```json +GET /v3/admin/order?orderStatus=PENDING_PAY&page=1&pageSize=1 + +{ + "code": 200, + "data": { + "total": 33, + "list": [ + { + "id": "1234567890001", + "orderNo": "HL20260617143025001", + "orderStatus": "PENDING_PAY", + "orderStatusName": "待支付", + "flowStatus": "AWAITING_PAY", + "flowStatusName": null, + "flowStep": 0, + "flowStepTotal": 6, + "flowDisplayText": null, + "currentSubFlows": null, + "productName": "长白山天池3日深度游", + "customerName": "张三", + "departureDate": "2026-07-01" + } + ] + } +} +``` + +### 8.2 边界——其他状态订单（flowStatusName 有值，不受影响） + +```json +GET /v3/admin/order?orderStatus=CUSTOMIZING&page=1&pageSize=1 + +{ + "code": 200, + "data": { + "list": [ + { + "orderStatus": "CUSTOMIZING", + "orderStatusName": "定制中", + "flowStatus": "RESOURCE_PREPARING", + "flowStatusName": "资源准备", + "flowStep": 1, + "flowDisplayText": "资源准备" + } + ] + } +} +``` + +### 8.3 业务失败——订单不存在（详情接口） + +```json +GET /v3/admin/order/9999999999999 + +{ + "code": 404, + "msg": "订单不存在" +} +``` + +--- + +## 9. 业务边界 + +**适用**： +- 仅影响 `orderStatus=PENDING_PAY` 的订单（即刚创单、尚未完成订金支付的订单）。 + +**不适用**： +- `CUSTOMIZING`、`PENDING_DEPARTURE`、`TRAVELLING`、`COMPLETED` 状态的订单，`flowStatusName`/`flowDisplayText` 仍正常有值，不受影响。 +- `CANCELLED` 状态的订单，`flowDisplayText` 仍为 `"已取消"`，不受影响。 + +**特殊边界**： +- 前端若之前对 `flowDisplayText=null` 有防空处理，本次直接兼容，无需额外改动。 +- 若前端之前硬判 `flowDisplayText === "待支付"` 来识别待支付状态，需改为读 `orderStatus === "PENDING_PAY"` 或 `orderStatusName`。 + +--- + +## 10. 修改前后对比 + +### 字段级对比（仅 PENDING_PAY 状态） + +| 字段 | 修改前 | 修改后 | +|---|---|---| +| `flowStatusName`（列表 + 详情） | `"待支付"` | `null` | +| `flowDisplayText`（列表 + 详情） | `"待支付"` | `null` | +| `orderStatusName`（列表 + 详情） | `"待支付"` | `"待支付"`（不变） | +| `flowStep` | `0` | `0`（不变） | +| `progressStepper` | 6 节点全 WAITING | 6 节点全 WAITING（不变） | + +### 行为级对比 + +| 场景 | 修改前 | 修改后 | +|---|---|---| +| 列表行「流程状态」标签 | 显示"待支付"（来自 flowStatusName） | 为 null，前端显示为空或不展示该标签 | +| 详情当前步文案 | "待支付" | null，前端步骤条未点亮，文案区域为空或不展示 | +| "待支付"文字入口 | 同时出现在 orderStatusName 和 flowStatusName | 仅由 orderStatusName 表达，语义唯一 | + +--- + +## 11. 影响评估 / 回滚 + +**破坏兼容性**：⚠️ 是——`flowStatusName`/`flowDisplayText` 在 PENDING_PAY 时从字符串变为 `null`，前端需要做好 null 防空。 + +**前端需同步操作**： +1. **订单列表**：渲染「流程状态标签」时判断 `flowStatusName !== null` 再显示；`null` 时不显示标签（或显示空）。 +2. **订单详情**：渲染「当前步文案」时判断 `flowDisplayText !== null` 再拼"X/6 · xxx"格式；`null` 时步骤条未点亮、文案区域留空。 +3. **若有 `flowDisplayText === "待支付"` 的硬判逻辑**，改为 `orderStatus === "PENDING_PAY"` 判断。 + +**回滚方案**：后端回退 PR #3926 即可恢复为旧行为（`null` 改回 `"待支付"`）。后端回滚后前端无需改动。 + +--- + +## 12. 注意事项 + +- `flowStatus` 字段本身仍为 `"AWAITING_PAY"`（原始枚举值保留），只是 `flowStatusName`（中文名映射）返 `null`。 +- 步骤条 `progressStepper` 6 节点全 `WAITING` 行为不变，本次只影响文案字段。 +- 已取消订单（`CANCELLED`）的 `flowDisplayText` 仍为 `"已取消"`，本次不涉及。 + +--- + +## 13. 关联 / 联系人 + +- Issue：https://git.1814.love:8443/wx/HL/issues/3923 +- PR：https://git.1814.love:8443/wx/HL/pulls/3926 +- Commit：https://git.1814.love:8443/wx/HL/commit/6f0648a28a17daafc4e6ebafdd36fb8c7a3b8e6b +- 后端负责人：腰苏图 diff --git a/changelogs-v2/2026-06/17_3930_订单状态筛选下拉选项端点-新增接口-管理后台.md b/changelogs-v2/2026-06/17_3930_订单状态筛选下拉选项端点-新增接口-管理后台.md new file mode 100644 index 0000000..91ce77a --- /dev/null +++ b/changelogs-v2/2026-06/17_3930_订单状态筛选下拉选项端点-新增接口-管理后台.md @@ -0,0 +1,149 @@ +# 订单状态筛选下拉选项端点 — 新增接口 — 管理后台 + +> 变更类型：✨ 新增接口 +> 端类型：管理后台 +> 日期：2026-06-17 +> 服务：hl-order-service-v3 +> PR：https://git.1814.love:8443/wx/HL/pulls/3934 + +--- + +## 1. 接口背景 + +**功能页面**：管理后台「订单列表」页的**筛选栏 — "订单状态"下拉框**。 + +**用在哪**：订单列表顶部筛选区域，用户点"订单状态"下拉时渲染选项列表（6 个状态），选中后把对应的 `value` 作为 `orderStatus` 参数传给列表接口过滤。 + +**为什么新增**：之前前端硬编码 6 个订单状态选项。订单状态是后端状态机枚举，未来若调整（改名/增减），前端需同步手动改。现改为后端派生，前端从此端点取选项，单一真相源在枚举，改状态前端自动跟随，无需手动维护。 + +--- + +## 2. 变更清单 + +| 变更类型 | 接口 | 说明 | +|---|---|---| +| ✨ 新增 | `GET /v3/admin/order/status-options` | 返回 6 个订单状态枚举选项（value + label），供订单列表状态筛选下拉使用 | + +--- + +## 3. 接口详情 + +- **方法 + 路径**：`GET /v3/admin/order/status-options` +- **接口名**：订单状态枚举选项（下拉） +- **认证**：需要 JWT（管理后台登录 token，Gateway 注入 `X-Admin-Id`） +- **幂等性**：查询接口，天然幂等 +- **限流**：无独立限流规则 +- **说明**：路径为字面量，Spring 路由优先于 `/{id}` 动态路径，不会冲突 + +--- + +## 4. 接口入参 + +无入参（无 Query 参数、无请求体）。 + +--- + +## 5. 出参字段 + +返回类型：`Result>` + +| 字段 | 类型 | 说明 | 示例 | +|---|---|---|---| +| `value` | String | 订单状态枚举值，传给列表接口 `orderStatus` 参数 | `"PENDING_PAY"` | +| `label` | String | 订单状态中文名，用于下拉展示 | `"待支付"` | + +返回固定 6 项，**按生命周期顺序**： + +| 序号 | value | label | +|---|---|---| +| 1 | `PENDING_PAY` | 待支付 | +| 2 | `CUSTOMIZING` | 定制中 | +| 3 | `PENDING_DEPARTURE` | 待出行 | +| 4 | `TRAVELLING` | 出行中 | +| 5 | `COMPLETED` | 已完成 | +| 6 | `CANCELLED` | 已取消 | + +--- + +## 6. 枚举 / 数据字典 + +本接口出参即为订单状态枚举的完整映射（见出参字段表），无额外枚举依赖。 + +--- + +## 7. 错误码 + +| code | 含义 | +|---|---| +| `200` | 成功（data 为 6 个选项数组） | +| `401` | 未登录 / token 过期 | + +--- + +## 8. 示例 + +### 8.1 典型成功 + +```http +GET /v3/admin/order/status-options +Authorization: Bearer +``` + +```json +{ + "code": 200, + "data": [ + { "value": "PENDING_PAY", "label": "待支付" }, + { "value": "CUSTOMIZING", "label": "定制中" }, + { "value": "PENDING_DEPARTURE", "label": "待出行" }, + { "value": "TRAVELLING", "label": "出行中" }, + { "value": "COMPLETED", "label": "已完成" }, + { "value": "CANCELLED", "label": "已取消" } + ] +} +``` + +### 8.2 边界——未来状态机新增/改名后的自动适配 + +后端枚举新增状态后，本接口返回的数组会自动多出对应项，前端无需感知，下拉自动展示新选项。 + +### 8.3 业务失败——未登录 + +```json +{ + "code": 401, + "msg": "未登录或 token 已过期" +} +``` + +--- + +## 9. 业务边界 + +**适用**： +- 管理后台订单列表「订单状态」下拉框选项渲染。 +- 选中某选项后，把 `value` 作为 `GET /v3/admin/order` 的 `orderStatus` 参数传入。 + +**不适用**： +- 不适用于小程序端（小程序无订单列表状态筛选下拉）。 +- 不适用于流程状态（`flowStatus`）筛选，本接口仅覆盖粗状态（`orderStatus`）。 + +**特殊边界**： +- 本接口返回所有状态（含 `CANCELLED` 已取消），如需在下拉中排除已取消，前端自行过滤，后端不做删减。 + +--- + +## 12. 注意事项 + +- 前端调用此端点后，**不再需要在代码里硬编码 6 个状态**；选中 value 直接传给列表接口 `orderStatus` 参数即可。 +- 本接口无分页，永远返回完整枚举列表，前端可在应用启动时预加载缓存。 +- `value` 与列表接口 `orderStatus` 参数完全对应，可直接作为传参值。 + +--- + +## 13. 关联 / 联系人 + +- Issue：https://git.1814.love:8443/wx/HL/issues/3930 +- PR：https://git.1814.love:8443/wx/HL/pulls/3934 +- Commit：https://git.1814.love:8443/wx/HL/commit/ece0d86edb94053fc077b04272c4193b9f0755fd +- 后端负责人：腰苏图 diff --git a/changelogs-v2/2026-06/17_3938_订单列表Tab分组计数与分组过滤-新增接口-管理后台.md b/changelogs-v2/2026-06/17_3938_订单列表Tab分组计数与分组过滤-新增接口-管理后台.md new file mode 100644 index 0000000..b33b495 --- /dev/null +++ b/changelogs-v2/2026-06/17_3938_订单列表Tab分组计数与分组过滤-新增接口-管理后台.md @@ -0,0 +1,215 @@ +# 订单列表 Tab 分组计数与分组过滤 — 新增接口 — 管理后台 + +> 变更类型：✨ 新增接口 + 修改接口（列表新增入参） +> 端类型：管理后台 +> 日期：2026-06-17 +> 服务：hl-order-service-v3 +> PR：https://git.1814.love:8443/wx/HL/pulls/3939 + +--- + +## 1. 接口背景 + +**功能页面**：管理后台「订单列表」页的**顶部 Tab 栏**（出行前 / 出行中 / 核单 / 异常·取消 / 全部）。 + +**用在哪**： + +1. **Tab 计数徽标**：页面加载 / 筛选条件变更时，调 `GET /v3/admin/order/status-group-counts` 取每个 Tab 上显示的订单数量角标（如"出行前 33"、"异常/取消 5"）。 +2. **点击 Tab 过滤列表**：用户点某个 Tab，前端只需把该 Tab 的 `group` 值作为 `statusGroup` 参数传给列表接口（`GET /v3/admin/order`），后端内部把 group 展开为对应状态集合过滤，前端无需自己维护"哪个 Tab 对应哪些状态"的映射。 + +**设计意图**：把 6 个粗状态按出行阶段折叠成 4 组+全部，让定制师快速聚焦当前阶段的订单，Tab 计数单独一个端点供徽标独立刷新，点击 Tab 与列表接口通过 `statusGroup` 解耦。 + +--- + +## 2. 变更清单 + +| 变更类型 | 接口 | 说明 | +|---|---|---| +| ✨ 新增 | `GET /v3/admin/order/status-group-counts` | Tab 分组计数，返回 5 项（ALL + 4 组），每项含 group/label/orderCount | +| ⚠️ 修改 | `GET /v3/admin/order`（列表） | 新增可选入参 `statusGroup`，前端传 group key 触发 Tab 过滤 | + +--- + +## 3. 接口详情 + +### 3.1 Tab 分组计数 + +- **方法 + 路径**：`GET /v3/admin/order/status-group-counts` +- **接口名**：订单列表 Tab 分组计数 +- **认证**：需要 JWT（管理后台登录 token） +- **幂等性**：查询接口，天然幂等 +- **限流**：无独立限流规则 +- **语义**：计数值尊重其他筛选条件（keyword/出发日期/定制师名/来源/标签），但与当前选中 Tab 无关（faceted 计数，ALL 恒含已取消） + +### 3.2 订单列表（新增 statusGroup 入参） + +- **方法 + 路径**：`GET /v3/admin/order`（别名 `GET /v3/admin/order/list`） +- **接口名**：订单列表 +- **认证**：需要 JWT +- **幂等性**：查询接口，天然幂等 +- **限流**：无独立限流规则 + +--- + +## 4. 接口入参 + +### 4.1 Tab 分组计数 Query 参数（复用列表筛选条件，不传 orderStatus / statusGroup） + +| 参数 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `keyword` | String | 否 | 关键字模糊搜索（团号/客户姓名/产品名/订单号） | +| `departureDateFrom` | LocalDate | 否 | 出发日期起始（格式 `yyyy-MM-dd`） | +| `departureDateTo` | LocalDate | 否 | 出发日期结束（格式 `yyyy-MM-dd`） | +| `consultantName` | String | 否 | 定制师姓名 LIKE 匹配 | +| `createSource` | String | 否 | 订单来源（`CONSULTANT` / `CUSTOMER`） | +| `tagNames` | List\ | 否 | 标签名列表过滤（AND） | + +> 注：不传 `orderStatus`（按 group 内部统计）、不传 `statusGroup`（计数接口自己统计所有组）、不传 `page`/`pageSize`（计数接口无分页）。 + +### 4.2 订单列表新增入参 + +| 参数 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `statusGroup` | String | 否 | Tab 分组 key，取值见下方枚举表；后端内部展开为 orderStatus 集合；与 `orderStatus` 下拉并存时取 AND；不传或传 `ALL` 时含已取消 | + +--- + +## 5. 出参字段 + +### 5.1 Tab 分组计数 StatusGroupCountVO + +返回类型：`Result>`，共 5 项，ALL 在首位，后跟 4 组，按固定顺序。 + +| 字段 | 类型 | 说明 | 示例 | +|---|---|---|---| +| `group` | String | 分组标识 key，对应 `statusGroup` 入参 | `"BEFORE_TRIP"` | +| `label` | String | 分组中文标签，用于 Tab 展示 | `"出行前"` | +| `orderCount` | Long | 该分组订单数（满足其他筛选条件的计数） | `33` | + +### 5.2 订单列表（本次只新增入参，出参字段不变，无需修改） + +订单列表 `OrderListItemRespVO` 出参字段无变化（参考现有接口文档）。 + +--- + +## 6. 枚举 / 数据字典 + +### Tab 分组 group 值（statusGroup 参数取值 + 分组计数返回 group 值） + +| group 值 | 中文标签 | 含义（包含的 orderStatus） | +|---|---|---| +| `ALL` | 全部 | 全部状态（含已取消） | +| `BEFORE_TRIP` | 出行前 | `PENDING_PAY`（待支付）+ `CUSTOMIZING`（定制中）+ `PENDING_DEPARTURE`（待出行） | +| `ON_TRIP` | 出行中 | `TRAVELLING`（出行中） | +| `SETTLEMENT` | 核单 | `COMPLETED`（已完成，横跨核单+结算两子阶段） | +| `ABNORMAL` | 异常/取消 | `CANCELLED`（已取消） | + +> 前端只需感知 group 值，状态枚举的内部映射由后端维护，前端不用硬编码。 + +--- + +## 7. 错误码 + +| code | 含义 | +|---|---| +| `200` | 成功 | +| `401` | 未登录 / token 过期 | +| `400` | `statusGroup` 传了非法值（后端宽松处理：未知 group 忽略，不抛 400；但建议传枚举定义值） | + +--- + +## 8. 示例 + +### 8.1 典型成功——获取 Tab 分组计数 + +```http +GET /v3/admin/order/status-group-counts +Authorization: Bearer +``` + +```json +{ + "code": 200, + "data": [ + { "group": "ALL", "label": "全部", "orderCount": 38 }, + { "group": "BEFORE_TRIP","label": "出行前", "orderCount": 33 }, + { "group": "ON_TRIP", "label": "出行中", "orderCount": 0 }, + { "group": "SETTLEMENT", "label": "核单", "orderCount": 0 }, + { "group": "ABNORMAL", "label": "异常/取消", "orderCount": 5 } + ] +} +``` + +### 8.2 边界——带筛选条件的计数（Faceted，计数随筛选条件变化） + +```http +GET /v3/admin/order/status-group-counts?departureDateFrom=2026-07-01&departureDateTo=2026-07-31 +``` + +返回值中每组 `orderCount` 仅统计出发日期在 7 月的订单，即使当前 Tab 已选 BEFORE_TRIP，ALL 和其他组也只统计 7 月内的。 + +```json +{ + "code": 200, + "data": [ + { "group": "ALL", "label": "全部", "orderCount": 12 }, + { "group": "BEFORE_TRIP","label": "出行前", "orderCount": 10 }, + { "group": "ON_TRIP", "label": "出行中", "orderCount": 1 }, + { "group": "SETTLEMENT", "label": "核单", "orderCount": 0 }, + { "group": "ABNORMAL", "label": "异常/取消", "orderCount": 1 } + ] +} +``` + +### 8.3 业务失败——点击 Tab 后列表 statusGroup 传了未知值 + +```http +GET /v3/admin/order?statusGroup=UNKNOWN_GROUP&page=1&pageSize=10 +``` + +```json +{ + "code": 200, + "data": { + "total": 38, + "list": [ ... ] + } +} +``` + +> 后端宽松处理：未知 group 忽略，等同于不传 statusGroup（返回默认不含已取消的全部订单）。前端避免传枚举定义之外的值。 + +--- + +## 9. 业务边界 + +**适用**： +- 管理后台订单列表顶部 Tab 计数徽标渲染。 +- 用户点击 Tab 触发列表按分组过滤。 + +**不适用**： +- 分组计数不适用于精确状态统计（`SETTLEMENT` 组包含 `COMPLETED`，横跨核单和结算两个子阶段，不区分子状态）。 +- 分组计数的 `ALL` 恒含已取消订单（不可排除）；其他接口参数 `cancelled=false` 对分组计数无效。 + +**特殊边界**： +- `statusGroup=ALL` 与不传 `statusGroup` 行为不同：传 `ALL` 时含已取消；不传时默认不含已取消（`cancelled` 默认 `false`）。 +- `statusGroup` 与 `orderStatus` 下拉可同时传，取 AND 逻辑（例：`statusGroup=BEFORE_TRIP&orderStatus=CUSTOMIZING` 只返定制中的订单）。 +- 分组计数与当前选中 Tab 的 `statusGroup` 无关（Faceted 设计），每次只要其他筛选条件变了就重新调计数接口。 + +--- + +## 12. 注意事项 + +- **计数接口与列表接口分开调**：Tab 徽标数字调 `status-group-counts`，Tab 点击过滤调 `GET /v3/admin/order?statusGroup=...`，两者分开请求。 +- **`statusGroup=ALL` 传参覆盖默认排除取消**：前端若需要"全部"含取消，用 `statusGroup=ALL` 而不是 `cancelled=true`（两者效果等同，但 `statusGroup=ALL` 更语义明确）。 +- **分组映射由后端维护**：前端不要在代码里硬编码"BEFORE_TRIP = [PENDING_PAY, CUSTOMIZING, PENDING_DEPARTURE]"这样的映射表——这是后端内部逻辑，后端调整分组时前端自动跟随。 +- 已实测（2026-06-17，测试服 dev-v3）：`statusGroup=BEFORE_TRIP` 返 33 单、无越界；`ALL` 组计数 = 4 组之和。 + +--- + +## 13. 关联 / 联系人 + +- Issue：https://git.1814.love:8443/wx/HL/issues/3938 +- PR：https://git.1814.love:8443/wx/HL/pulls/3939 +- Commit（refactor review 后）：https://git.1814.love:8443/wx/HL/commit/5eca8d67b0432dfc19e2b6d2c67ef7e6eac6ec02 +- 后端负责人：腰苏图