# 订单 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`）
