59932b6048
GET /v3/admin/order/{id} 的 main 块新增出参字段 productCoverImg，
与订单列表同名同义，历史订单无快照时返回 null，前端做占位图降级即可。
205 行
5.3 KiB
Markdown
205 行
5.3 KiB
Markdown
# 订单详情补产品封面字段 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 |
|
||
| 后端负责人 | 腰苏图 |
|