From 59932b6048cb8313b14f149f60a1e7ca7bea02d2 Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Fri, 19 Jun 2026 09:57:14 +0800
Subject: [PATCH] =?UTF-8?q?feat(changelog):=20=E8=AE=A2=E5=8D=95=E8=AF=A6?=
 =?UTF-8?q?=E6=83=85=E8=A1=A5=E4=BA=A7=E5=93=81=E5=B0=81=E9=9D=A2=E5=AD=97?=
 =?UTF-8?q?=E6=AE=B5=20productCoverImg=20(#4026)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

GET /v3/admin/order/{id} 的 main 块新增出参字段 productCoverImg，
与订单列表同名同义，历史订单无快照时返回 null，前端做占位图降级即可。
---
 ...补产品封面productCoverImg-修改接口-管理后台.md | 204 ++++++++++++++++++
 1 file changed, 204 insertions(+)
 create mode 100644 changelogs-v2/2026-06/19_4025_订单详情补产品封面productCoverImg-修改接口-管理后台.md

diff --git a/changelogs-v2/2026-06/19_4025_订单详情补产品封面productCoverImg-修改接口-管理后台.md b/changelogs-v2/2026-06/19_4025_订单详情补产品封面productCoverImg-修改接口-管理后台.md
new file mode 100644
index 0000000..1d87f5b
--- /dev/null
+++ b/changelogs-v2/2026-06/19_4025_订单详情补产品封面productCoverImg-修改接口-管理后台.md
@@ -0,0 +1,204 @@
+# 订单详情补产品封面字段 productCoverImg
+
+- **变更类型**：修改接口
+- **端类型**：管理后台
+- **日期**：2026-06-19
+- **Issue**：[#4025](https://git.1814.love:8443/wx/HL/issues/4025)
+- **PR**：[#4026](https://git.1814.love:8443/wx/HL/pulls/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 有值）
+
+**请求**
+
+```http
+GET /v3/admin/order/1923800000000001 HTTP/1.1
+Authorization: Bearer <admin-token>
+```
+
+**响应（仅展示 data.main 核心字段，其余 Tab 略）**
+
+```json
+{
+  "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`，前端需做占位图降级处理。
+
+**响应片段**
+
+```json
+{
+  "code": 200,
+  "data": {
+    "main": {
+      "id": "1800000000000001",
+      "orderNo": "HL2025120001",
+      "productCoverImg": null
+    }
+  }
+}
+```
+
+### 8.3 业务失败（订单不存在）
+
+**请求**
+
+```http
+GET /v3/admin/order/9999999999999999 HTTP/1.1
+Authorization: Bearer <admin-token>
+```
+
+**响应**
+
+```json
+{
+  "code": 580101,
+  "msg": "订单不存在"
+}
+```
+
+---
+
+## 9. 业务边界
+
+| 场景 | 行为 |
+|------|------|
+| 正常下单（有产品封面） | `productCoverImg` 返回产品封面 OSS URL |
+| 历史订单（无封面快照） | `productCoverImg` 返回 `null`，前端需做占位图降级 |
+| URL 为完整路径 | 直接赋值给 img src，无需拼接域名前缀 |
+
+---
+
+## 10. 修改前后对比
+
+### 字段级对比（data.main 块）
+
+| 字段 | 修改前 | 修改后 |
+|------|--------|--------|
+| `productCoverImg` | **不存在**（详情不返回） | ✨ 新增，String，可为 null |
+
+### 行为级对比
+
+| 场景 | 修改前 | 修改后 |
+|------|--------|--------|
+| 管理后台详情页封面展示 | 无法在详情获取封面，只能在列表展示 | 详情 `main.productCoverImg` 直接可用 |
+
+---
+
+## 11. 影响评估 / 回滚
+
+| 项目 | 说明 |
+|------|------|
+| **破坏兼容性** | 否。纯新增字段，旧前端代码忽略即可，不影响已有功能 |
+| **前端同步上线** | 非必须同步。前端可按需接入此字段以展示封面 |
+| **回滚方案** | 后端回滚 PR #4026 即可；前端无需回滚（该字段缺失时原逻辑不受影响） |
+
+---
+
+## 12. 注意事项
+
+1. `productCoverImg` 可为 `null`，前端渲染时**必须**做判空处理（img 设置 fallback 占位图，避免空 src 报错）。
+2. 与订单列表接口（`GET /v3/admin/order/list`）的 `productCoverImg` **完全同名同义**，前端可提取公共渲染组件复用。
+3. OSS URL 已是完整路径，不需要拼接域名前缀。
+
+---
+
+## 13. 关联 / 联系人
+
+| 项目 | 链接 |
+|------|------|
+| Issue | https://git.1814.love:8443/wx/HL/issues/4025 |
+| PR | https://git.1814.love:8443/wx/HL/pulls/4026 |
+| 后端负责人 | 腰苏图 |