订单 v2 详情接口补齐档位信息 (tierSeq/tierName/tierDescription) - PR #878

2026-04-18 23:40:07 +08:00 · 2026-04-18 23:40:07 +08:00 · 1d1db6e27c
--- a/changelogs/2026-04/2026-04-18_order-v2_detail-tier-info.md
+++ b/changelogs/2026-04/2026-04-18_order-v2_detail-tier-info.md
@ -0,0 +1,103 @@
+# 订单 v2 详情接口补齐档位信息（tierSeq / tierName / tierDescription）
+
+- **日期**: 2026-04-18
+- **PR**: [#878](https://git.1814.love:8443/wx/HL/pulls/878)
+- **类型**: FIX（字段补齐，🟢 非 Breaking，只加不改）
+- **状态**: 已合并到 dev + 待测试环境部署
+- **服务**: hl-order-service-v2 + hl-mp-service（BFF 镜像）
+
+---
+
+## 一、背景
+
+订单 v2 的三个详情接口此前返回的 VO 中 **没有档位信息**（产品线下多档位场景，如「标准档 / 舒适档 / 豪华档」），导致订单详情页无法展示用户购买的具体档位名称，只能看到总价。
+
+数据层已经齐全（`order_info.tier_seq` + `product_snapshot.tiers` JSON 都存得好好的），纯粹是响应 VO 层遗漏。本次仅补齐 VO 字段 + 装配层填充，数据源零改动。
+
+---
+
+## 二、新增字段（三字段一致，分别加在三个 VO 中）
+
+| 字段 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| `tierSeq` | `Integer` | 档位序号，默认 `1` | `2` |
+| `tierName` | `String` | 档位名称 | `"舒适档"` |
+| `tierDescription` | `String` | 档位描述 | `"升级双早+SPA"` |
+
+容错：老订单如果 `productSnapshot` 结构老、`tiers` 数组不存在或找不到对应 `tierSeq`，`tierName / tierDescription` 返回 `null`（`tierSeq` 仍返回）。前端请按需兜底显示（可用 `tierSeq` 数字或「默认档」占位）。
+
+---
+
+## 三、影响接口清单
+
+| # | 方法 | 路径 | 返回 VO | 说明 |
+|---|------|------|---------|------|
+| 1 | GET | `/admin/order/{orderId}` | `OrderDetailVO` | 管理端订单详情 |
+| 2 | POST | `/admin/order/create` | `OrderDetailVO` | 管理端下单回显 |
+| 3 | GET | `/mp/order/{orderId}` | `MpOrderDetailVO`（BFF 镜像） | 小程序订单详情 |
+| 4 | POST | `/mp/order/create`（经 BFF 透传） | `MpOrderDetailVO` | 小程序下单回显 |
+| 5 | PUT | `/mp/order/{orderId}/edit`（经 BFF 透传） | `MpOrderDetailVO` | 小程序订单编辑回显 |
+
+内部 Feign 接口（`/internal/mp/order/*`）同步增加字段，BFF 和 order-service 字段完全对齐。
+
+---
+
+## 四、前端对接建议
+
+### 管理端
+- 订单详情页 / 订单列表点详情时，`tierName` 作为「档位」列展示（如「舒适档」）
+- 如果 `tierName` 为 `null`（老订单），可展示 `"档位 ${tierSeq}"` 或「默认档」
+
+### 小程序
+- 订单详情页主信息区新增「档位」一行
+- 「再次下单 / 复制订单」场景中，`tierSeq` 可用于预选档位
+
+### 响应结构示例（以 `GET /mp/order/{orderId}` 为例）
+
+```json
+{
+  "code": 0,
+  "data": {
+    "orderId": "1234567890",
+    "orderNo": "HL20260418001",
+    "productName": "稻城亚丁6日游",
+    "tierSeq": 2,
+    "tierName": "舒适档",
+    "tierDescription": "升级双早+SPA",
+    "totalAmount": "3999.00",
+    "createTime": "2026-04-18 12:00:00"
+  }
+}
+```
+
+---
+
+## 五、非变更项
+
+- ❌ 不改任何旧字段的类型、名称、含义
+- ❌ 不改请求参数
+- ❌ 不动老 v1 `hl-order-service`（仍在下线流程中）
+- ❌ 不改订单表结构（`tier_seq` 列已存在）
+
+---
+
+## 六、测试
+
+- 单元测试 71 通过（TierInfoResolver 15 个边界用例 + QueryService +3 + Assembler +4）
+- 编译：order-v2 + mp-service 全通过
+- 端到端：测试环境部署后由 QA 实测管理端 / 小程序三条链路
+
+---
+
+## 七、重启
+
+本次变更合并后，测试环境需重启：
+- `hl-order-service-v2`
+- `hl-mp-service`（BFF 镜像 VO 同步增字段，Feign 反序列化需新 class）
+
+---
+
+## 八、风险
+
+- 迁移前老订单的 `productSnapshot` 结构若不同 → `tierName / tierDescription` 返回 `null`（已容错），前端兜底展示
+- 字段顺序：BFF 镜像 `MpOrderDetailVO` 与 order-service 内部 VO 字段一致（「基础信息」段末尾，紧跟 `createTime`）