订单 v2 详情接口补齐档位信息（tierSeq / tierName / tierDescription）

日期: 2026-04-18
PR: #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}` 为例）

{
  "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）

3.8 KiB 原始文件 Blame 文件历史 Unescape Escape