文件

T

yaosutu 59932b6048 feat(changelog): 订单详情补产品封面字段 productCoverImg (#4026 )

GET /v3/admin/order/{id} 的 main 块新增出参字段 productCoverImg，
与订单列表同名同义，历史订单无快照时返回 null，前端做占位图降级即可。

2026-06-19 09:57:14 +08:00

5.3 KiB

原始文件 Blame 文件历史

订单详情补产品封面字段 productCoverImg

变更类型：修改接口
端类型：管理后台
日期：2026-06-19
Issue：#4025
PR：#4026
后端负责人：腰苏图

1. 接口背景

订单详情接口（GET /v3/admin/order/{id}）的 main 块此前不返回产品封面图，导致管理后台详情页无法展示封面，只能在订单列表页看到封面。本次补齐 productCoverImg 字段，与订单列表接口同名同义，前端可复用相同的图片渲染逻辑，无需额外适配。

2. 变更清单

序号	接口	变更点	变更类型
1	`GET /v3/admin/order/{id}`	`data.main` 新增出参字段 `productCoverImg`（产品封面图 URL）	✨ 新增字段

入参无变化，无 DDL 变更。

3. 接口详情

项目	说明
方法	GET
路径	`/v3/admin/order/{id}`
接口名	订单详情（9 Tab 聚合）
认证	Bearer JWT（管理后台 Token）
幂等性	查询接口，天然幂等
限流	无特殊限流
返回结构	`Result<OrderDetailRespVO>`，本次仅变更 `data.main` 块

4. 接口入参

4.1 路径参数

参数	类型	必填	说明
`id`	Long（字符串形式）	是	订单 ID（雪花 ID，前端需以字符串传递防精度丢失）

4.2 请求体

无请求体（GET 接口）。

5. 出参字段

本次仅列出 data.main 块的变更字段。其余 Tab（traveler / itinerary / requirement / contract / insurance / payment / refund / complaint）无变化。

data.main（OrderMainVO）新增字段

字段名	类型	可空	说明
`productCoverImg`	String	是（可为 null）	产品封面图 OSS URL。下单时从产品快照落库，历史订单（无封面快照）返回 null

与订单列表一致：GET /v3/admin/order/list 列表项 productCoverImg 字段同名同义，前端可复用相同渲染逻辑（img src 赋值、占位图降级处理）。

6. 枚举 / 数据字典

本次变更无枚举或字典变化。

7. 错误码

本次变更无新增错误码。接口原有错误码不变：

错误码	说明
`580101`	订单不存在

8. 示例

8.1 典型成功（productCoverImg 有值）

请求

GET /v3/admin/order/1923800000000001 HTTP/1.1
Authorization: Bearer <admin-token>

响应（仅展示 data.main 核心字段，其余 Tab 略）

{
  "code": 200,
  "data": {
    "main": {
      "id": "1923800000000001",
      "orderNo": "HL2026060001",
      "productName": "长白山 5 日精品游",
      "productCoverImg": "https://oss.hulalv.com/p/changbai-cover.jpg",
      "orderStatus": "PENDING_PAYMENT",
      "flowStepName": "待支付"
    }
  }
}

8.2 边界情况（历史订单，productCoverImg 为 null）

历史订单在 product_cover_img 列无快照数据时，字段返回 null，前端需做占位图降级处理。

响应片段

{
  "code": 200,
  "data": {
    "main": {
      "id": "1800000000000001",
      "orderNo": "HL2025120001",
      "productCoverImg": null
    }
  }
}

8.3 业务失败（订单不存在）

请求

GET /v3/admin/order/9999999999999999 HTTP/1.1
Authorization: Bearer <admin-token>

响应

{
  "code": 580101,
  "msg": "订单不存在"
}

9. 业务边界

场景	行为
正常下单（有产品封面）	`productCoverImg` 返回产品封面 OSS URL
历史订单（无封面快照）	`productCoverImg` 返回 `null`，前端需做占位图降级
URL 为完整路径	直接赋值给 img src，无需拼接域名前缀

10. 修改前后对比

字段级对比（data.main 块）

字段	修改前	修改后
`productCoverImg`	不存在（详情不返回）	✨ 新增，String，可为 null

行为级对比

场景	修改前	修改后
管理后台详情页封面展示	无法在详情获取封面，只能在列表展示	详情 `main.productCoverImg` 直接可用

11. 影响评估 / 回滚

项目	说明
破坏兼容性	否。纯新增字段，旧前端代码忽略即可，不影响已有功能
前端同步上线	非必须同步。前端可按需接入此字段以展示封面
回滚方案	后端回滚 PR #4026 即可；前端无需回滚（该字段缺失时原逻辑不受影响）

12. 注意事项

productCoverImg 可为 null，前端渲染时必须做判空处理（img 设置 fallback 占位图，避免空 src 报错）。
与订单列表接口（GET /v3/admin/order/list）的 productCoverImg 完全同名同义，前端可提取公共渲染组件复用。
OSS URL 已是完整路径，不需要拼接域名前缀。

13. 关联 / 联系人

项目	链接
Issue	https://git.1814.love:8443/wx/HL/issues/4025
PR	https://git.1814.love:8443/wx/HL/pulls/4026
后端负责人	腰苏图

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