From 20032ec600d807bd0055976e2edf40007a474149 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Fri, 19 Jun 2026 09:19:12 +0800 Subject: [PATCH] =?UTF-8?q?feat(changelogs-v2):=20=E8=AE=A2=E5=8D=95?= =?UTF-8?q?=E5=88=97=E8=A1=A8/=E8=AF=A6=E6=83=85=E6=96=B0=E5=A2=9E=20produ?= =?UTF-8?q?ctType+productTypeName=20=E5=87=BA=E5=8F=82=E5=AD=97=E6=AE=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 影响接口: - GET /v3/admin/order/list - GET /v3/admin/order/{id} (data.main 节点) 枚举: CORE/ROUTE/CUSTOM/GROUP 四值 关联: Issue #4009 / PR #4010 --- ...列表详情加productType-修改接口-管理后台.md | 281 ++++++++++++++++++ 1 file changed, 281 insertions(+) create mode 100644 changelogs-v2/2026-06/19_4009_订单列表详情加productType-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/19_4009_订单列表详情加productType-修改接口-管理后台.md b/changelogs-v2/2026-06/19_4009_订单列表详情加productType-修改接口-管理后台.md new file mode 100644 index 0000000..f79e445 --- /dev/null +++ b/changelogs-v2/2026-06/19_4009_订单列表详情加productType-修改接口-管理后台.md @@ -0,0 +1,281 @@ +# 订单列表/详情新增 productType + productTypeName 字段 + +- **变更类型**: 修改接口（既有接口新增出参字段） +- **端类型**: 管理后台 +- **日期**: 2026-06-19 +- **Issue**: [#4009](https://git.1814.love:8443/wx/HL/issues/4009) +- **PR**: [#4010](https://git.1814.love:8443/wx/HL/pulls/4010) +- **Commit**: [36880d1e2](https://git.1814.love:8443/wx/HL/commit/36880d1e2) +- **后端负责人**: 腰苏图 + +--- + +## ① 接口背景 + +订单创建时，产品类型（核心/线路/定制/团队）会从产品快照固化到订单主表。此前该字段从未通过接口返回，前端无法在订单列表和详情中区分产品类型。本次在两个接口的出参中同时补充 `productType`（枚举码）和 `productTypeName`（中文名），方便前端按产品类型展示差异化 UI。 + +历史订单已完成回填，无快照的兜底为 `CORE`；理论上正常订单都有值，极少数脏数据可能为 `null`，前端需做防御处理。 + +--- + +## ② 变更清单 + +| 接口 | 变更内容 | +|------|---------| +| `GET /v3/admin/order/list` | 每条列表项新增出参字段 `productType`、`productTypeName` | +| `GET /v3/admin/order/{id}` | 详情 `data.main` 节点新增出参字段 `productType`、`productTypeName` | + +两个接口均为**向后兼容新增**，原有字段不变，前端不必修改已有调用逻辑，但需接线新字段用于 UI 渲染。 + +--- + +## ③ 接口详情 + +### 3.1 订单列表 + +- **方法 + 路径**: `GET /v3/admin/order/list` +- **描述**: 管理后台订单列表，支持分页与多条件筛选 +- **认证**: 必须携带管理后台 JWT Token（`Authorization: Bearer `） +- **幂等性**: 只读，天然幂等 +- **限流**: 无特殊限流 + +### 3.2 订单详情 + +- **方法 + 路径**: `GET /v3/admin/order/{id}` +- **描述**: 管理后台订单详情聚合接口，返回 main / travelers / itinerary 等多节点 +- **认证**: 必须携带管理后台 JWT Token（`Authorization: Bearer `） +- **幂等性**: 只读，天然幂等 +- **限流**: 无特殊限流 + +--- + +## ④ 接口入参 + +### 4.1 订单列表（Query 参数，节选常用） + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| pageNo | Integer | 否 | 页码，默认 1 | +| pageSize | Integer | 否 | 每页条数，默认 20 | +| keyword | String | 否 | 关键词搜索 | +| status | String | 否 | 订单状态筛选 | +| ... | ... | ... | 其余参数不变，本次无入参改动 | + +### 4.2 订单详情（路径参数） + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| id | Long | 是 | 订单 ID（雪花 ID，字符串形式传入） | + +--- + +## ⑤ 出参字段 + +### 5.1 订单列表（OrderListItemRespVO，新增字段） + +以下为本次新增字段，其余原有字段不变： + +| 字段名 | 类型 | 可空 | 说明 | +|--------|------|------|------| +| `productType` | String | 是（null 为极少数历史脏数据） | 产品类型枚举码，见枚举 § ⑥ | +| `productTypeName` | String | 是（与 productType 同步，null when productType null） | 产品类型中文名，如 `核心产品` | + +### 5.2 订单详情（data.main 节点，新增字段） + +新增字段位于 `data.main` 对象下： + +| 字段名 | 类型 | 可空 | 说明 | +|--------|------|------|------| +| `productType` | String | 是（null 为极少数历史脏数据） | 产品类型枚举码，见枚举 § ⑥ | +| `productTypeName` | String | 是（与 productType 同步，null when productType null） | 产品类型中文名，如 `定制产品` | + +--- + +## ⑥ 枚举 / 数据字典 + +### ProductType — 产品类型 + +| 枚举值（productType） | 中文名（productTypeName） | 说明 | +|-----------------------|--------------------------|------| +| `CORE` | 核心产品 | 核心旅游产品；历史无快照订单兜底此值 | +| `ROUTE` | 线路产品 | 固定线路产品 | +| `CUSTOM` | 定制产品 | 定制行程产品 | +| `GROUP` | 团队产品 | 团期/团队产品 | + +> `productType` 字段值固定为以上 4 个枚举码之一，或为 `null`（极少数历史脏数据，正常订单不会出现）。 + +--- + +## ⑦ 错误码 + +本次改动为新增出参字段，不引入新的错误码。常规接口错误码如下： + +| 错误码 | 说明 | +|--------|------| +| `200` | 成功 | +| `401` | 未认证，请检查 Token | +| `403` | 无权限 | +| `404` | 订单不存在（详情接口，id 错误时） | + +--- + +## ⑧ 示例 + +### 8.1 典型成功 — 订单列表 + +**请求**： +``` +GET /v3/admin/order/list?pageNo=1&pageSize=10 +Authorization: Bearer +``` + +**响应**（节选单条）： +```json +{ + "code": 200, + "data": { + "list": [ + { + "id": "1876543210000001", + "orderNo": "HL202606190001", + "status": "PENDING_PAYMENT", + "productName": "丽江深度定制5日", + "productType": "CUSTOM", + "productTypeName": "定制产品", + "totalAmount": "12800.00", + "createTime": "2026-06-19T10:00:00" + } + ], + "total": 100, + "pageNo": 1, + "pageSize": 10 + } +} +``` + +### 8.2 典型成功 — 订单详情 + +**请求**： +``` +GET /v3/admin/order/1876543210000001 +Authorization: Bearer +``` + +**响应**（节选 data.main）： +```json +{ + "code": 200, + "data": { + "main": { + "id": "1876543210000001", + "orderNo": "HL202606190001", + "status": "PENDING_PAYMENT", + "productType": "CUSTOM", + "productTypeName": "定制产品", + "totalAmount": "12800.00" + }, + "travelers": [], + "itinerary": null + } +} +``` + +### 8.3 边界情况 — 历史脏数据 productType 为 null + +极少数历史脏数据（无产品快照且未被回填）可能返回 null，前端需防御处理： + +```json +{ + "code": 200, + "data": { + "list": [ + { + "id": "1000000000000001", + "orderNo": "HL202501010001", + "productType": null, + "productTypeName": null + } + ] + } +} +``` + +> 前端建议：`productType === null` 时不渲染产品类型标签，或显示兜底文案「-」。 + +### 8.4 业务失败 — 详情接口 id 不存在 + +**请求**： +``` +GET /v3/admin/order/9999999999999999 +Authorization: Bearer +``` + +**响应**： +```json +{ + "code": 587010, + "msg": "订单不存在" +} +``` + +--- + +## ⑨ 业务边界 + +**适用**： +- 所有状态的订单（已完成、取消、退款中等）均会返回 `productType` 字段 +- `GROUP` 类型订单为团期产品，前端可据此渲染团期专属 UI（如团期编号、报名人数等） + +**不适用**： +- 此字段不影响订单的任何操作权限，不参与状态流转判断 + +**特殊边界**： +- 历史订单已全量回填，回填口径：有产品快照取快照值，无快照兜底 `CORE` +- 订单创建后 `productType` 不可变，与产品侧修改无关（固化快照） + +--- + +## ⑩ 修改前后对比 + +### 字段级对比 + +| 字段 | 修改前 | 修改后 | +|------|--------|--------| +| `productType` | 不返回（字段不存在） | 返回枚举字符串，如 `"CUSTOM"` | +| `productTypeName` | 不返回（字段不存在） | 返回中文名，如 `"定制产品"` | + +**影响接口**： +- `GET /v3/admin/order/list` → 列表每条 item 新增两字段 +- `GET /v3/admin/order/{id}` → 详情 `data.main` 节点新增两字段 + +--- + +## ⑪ 影响评估 / 回滚 + +**兼容性**： +- 向后兼容新增，前端零破坏，原有字段全部保留 +- 前端现有代码无需修改即可正常运行；如需渲染新字段，按需接线 + +**前端同步上线**： +- 不强制要求与前端同步，后端已部署前端可按节奏接线 + +**回滚方案**： +- 后端回滚只需撤回 PR #4010 对应提交，前端无感知（字段消失即可，不会报错） + +--- + +## ⑫ 注意事项 + +1. **防御 null**：`productType` 和 `productTypeName` 理论上有值，但请在渲染时做 null 判断，避免历史脏数据导致前端报错 +2. **两字段配套**：`productType` 为枚举码（用于逻辑判断），`productTypeName` 为中文名（用于展示），两者同步出现或同步为 null，无需前端自己做枚举映射 +3. **不可变字段**：`productType` 在订单层面不可变，前端无需考虑实时刷新或监听变化 + +--- + +## ⑬ 关联 / 联系人 + +- **Issue**: [#4009 订单列表/详情补充 productType 字段](https://git.1814.love:8443/wx/HL/issues/4009) +- **PR**: [#4010 feat(order-v3): order_main 加 product_type 列 + 列表/详情返回 productType](https://git.1814.love:8443/wx/HL/pulls/4010) +- **Feature Commit**: [849e3be9a](https://git.1814.love:8443/wx/HL/commit/849e3be9a) +- **Merge Commit**: [36880d1e2](https://git.1814.love:8443/wx/HL/commit/36880d1e2) +- **后端负责人**: 腰苏图