# [修改接口·管理后台] 订单详情枚举统一 + service-standard 修复 (#2867 #2868)

> **PR**: #2869 #2874 | **服务**: hl-order-service-v3 | **更新时间**: 2026-05-22

## 1. 接口背景

本次修复合并两个 PR，均针对订单详情页管理后台接口的静默 bug：

- **PR #2869（Issue #2868）枚举统一 + null 兑底**：contractStatus / insuranceStatus 两个字段历史上枚举値定义不完整（少了中间过渡态和 NONE 初始态），且在订单还未进入合同/保险流程时后端直接返回 null，前端字典无法匹配导致显示空白或"未知"。本次统一枚举値集并将 null 兑底为 "NONE"。

- **PR #2874（Issue #2867）service-standard Tab 修复**：hasServiceStandard 字段原来只判断快照记录是否存在（行存在即返回 true），未校验反序列化是否成功、itinerary 是否非空，导致前端收到 hasServiceStandard=true 后调 GET /service-standard 接口却收到 data=null 的矛盾。根因是快照 itinerary 字段类型 List<String> 与源头 List<DayItem> 不匹配，反序列化失败被静默吞掉。

## 2. 变更清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 订单详情 | GET | `/v3/admin/order/{id}` | 修改接口 | contractStatus/insuranceStatus 枚举统一；hasServiceStandard 判定逻辑修复 |
| 2 | 合同&保险 Tab | GET | `/v3/admin/order/{id}/contract-insurance` | 修改接口 | contractStatus/insuranceStatus 枚举统一，null 兑底为 NONE |
| 3 | 服务标准 Tab | GET | `/v3/admin/order/{id}/service-standard` | 修改接口（行为修复） | 原来 data 永远 null；现在能正常返回完整数据 |

## 3. 接口详情

### 3.1 GET /v3/admin/order/{id} —— 订单详情

- **使用场景**：管理后台订单详情页首次加载，获取订单主信息
- **认证**：需要管理后台 JWT（Bearer token），role=ADMIN
- **幂等性**：是（只读）
- **限流**：无

**本次变更字段**：
- `data.main.contractStatus`：枚举値扩展（4→6 値），null → `"NONE"`
- `data.main.insuranceStatus`：枚举値扩展（4→5 値），null → `"NONE"`
- `data.main.hasServiceStandard`：判定逻辑修复（见 §9）

### 3.2 GET /v3/admin/order/{id}/contract-insurance —— 合同&保险 Tab

- **使用场景**：管理后台订单详情页切换到 "合同&保险" Tab 时调用
- **认证**：需要管理后台 JWT（Bearer token），role=ADMIN
- **幂等性**：是（只读）
- **限流**：无

**本次变更字段**：
- `data.contract.contractStatus`：枚举値扩展（4→6 値），null → `"NONE"`
- `data.insurance.insuranceStatus`：枚举値扩展（4→5 値），null → `"NONE"`

### 3.3 GET /v3/admin/order/{id}/service-standard —— 服务标准 Tab

- **使用场景**：管理后台订单详情页切换到 "服务标准" Tab 时调用；应在 `hasServiceStandard=true` 时才调此接口
- **认证**：需要管理后台 JWT（Bearer token），role=ADMIN
- **幂等性**：是（只读）
- **限流**：无

**本次变更**：行为修复。修复前 data 永远为 null；修复后在有效快照时返回完整结构。

## 4. 接口入参

### 4.1 路径参数

三个接口入参相同，无变化。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | Long（String） | 是 | 订单 ID（snowflake，JSON 传 String 防精度丢失） |

### 4.2 请求体字段

三个接口均为 GET，无请求体。

## 5. 出参（响应）

### 5.1 GET /v3/admin/order/{id} —— 变更字段

| 字段路径 | 类型 | 说明 |
|----------|------|------|
| `data.main.contractStatus` | String（枚举） | 合同状态，见 §6.1。**本次扩展枚举値 + null 兑底** |
| `data.main.insuranceStatus` | String（枚举） | 保险状态，见 §6.2。**本次扩展枚举値 + null 兑底** |
| `data.main.hasServiceStandard` | Boolean | 是否有服务标准快照。**本次修复判定逻辑** |

### 5.2 GET /v3/admin/order/{id}/contract-insurance —— 变更字段

| 字段路径 | 类型 | 说明 |
|----------|------|------|
| `data.contract.contractStatus` | String（枚举） | 合同状态，见 §6.1。**本次扩展枚举値 + null 兑底** |
| `data.insurance.insuranceStatus` | String（枚举） | 保险状态，见 §6.2。**本次扩展枚举値 + null 兑底** |

### 5.3 GET /v3/admin/order/{id}/service-standard —— ServiceStandardVO（完整）

| 字段 | 类型 | 说明 |
|------|------|------|
| `data.itinerary` | List<String> | 行程列表，元素格式："Day{n} {title}"，如 "Day1 抵达成都"。**修复前恒为 null，修复后正常返回** |
| `data.notice` | String | 出行须知。可为 null |
| `data.refundPolicy` | String | 退款政策说明。可为 null |

当订单无服务标准快照时（`hasServiceStandard=false`），整个 `data` 为 null。

## 6. 枚举 / 数据字典

### 6.1 contractStatus（合同状态）

**所属字段**：`data.main.contractStatus`（OrderMainVO）、`data.contract.contractStatus`（ContractInsuranceVO）| **类型**：`String`

| 値 | 中文 | 说明 |
|----|------|------|
| `NONE` | 无合同 | 订单尚未进入签约流程（修复前此状态返回 null） |
| `GENERATING` | 生成中 | 合同正在后台生成 |
| `GENERATED` | 已生成 | 合同已生成，待客户签署 |
| `SIGNED` | 已签署 | 客户已完成签署 |
| `VOIDED` | 已作废 | 合同已作废 |
| `RESIGNING` | 重签中 | 合同正在重新发起签署 |

**修复前仅有4 値**：PENDING / GENERATED / SIGNED / VOIDED（PENDING 已废弃，NONE / GENERATING / RESIGNING 为本次新增枚举値）

### 6.2 insuranceStatus（保险状态）

**所属字段**：`data.main.insuranceStatus`（OrderMainVO）、`data.insurance.insuranceStatus`（ContractInsuranceVO）| **类型**：`String`

| 値 | 中文 | 说明 |
|----|------|------|
| `NONE` | 无保险 | 订单尚未进入投保流程（修复前此状态返回 null） |
| `ISSUING` | 投保中 | 保险正在后台出单 |
| `ISSUED` | 已出单 | 保险已成功出单 |
| `CANCELLED` | 已取消 | 保险已取消 |
| `FAILED` | 出单失败 | 保险出单失败 |

**修复前仅有4 値**：PENDING / ACTIVE / FAILED / CANCELLED（旧値已废弃重命名，全部替换为上表5 値）

## 7. 错误码

本次修复无新增错误码。

| code | 含义 | 触发场景 |
|------|------|----------|
| `200` | 成功 | 正常响应 |
| `1000400` | 参数异常 | 路径参数 `id` 格式错误 |
| `1000404` | 订单不存在 | 指定 id 的订单不存在或已删除 |
| `1000403` | 无权限 | 非管理员 token 访问 |

## 8. 示例

### 8.1 典型成功 —— 新建订单 contractStatus 返 NONE（修复前返 null）

**请求**：

```
GET /v3/admin/order/1921234567890123456
Authorization: Bearer <admin-jwt-token>
```

**响应**：

```json
{
  "code": 200,
  "data": {
    "main": {
      "orderId": "1921234567890123456",
      "orderNo": "ORD20260522001",
      "contractStatus": "NONE",
      "insuranceStatus": "NONE",
      "hasServiceStandard": false
    }
  },
  "message": "ok",
  "success": true
}
```

> 修复前：contractStatus: null，insuranceStatus: null，前端字典无法匹配显示空白。

### 8.2 边界情况 —— service-standard 接口有快照时返完整数据（修复前永远 null）

**请求**：

```
GET /v3/admin/order/1921234567890123456/service-standard
Authorization: Bearer <admin-jwt-token>
```

**响应（修复后）**：

```json
{
  "code": 200,
  "data": {
    "itinerary": [
      "Day1 抵达成都，入住民宿",
      "Day2 前往峨眉山景区",
      "Day3 返程"
    ],
    "notice": "请携带身份证原件，到达后联系导游",
    "refundPolicy": "出发7天以上全额退款，7天内收取50%手续费"
  },
  "message": "ok",
  "success": true
}
```

**响应（修复前）**：

```json
{
  "code": 200,
  "data": null,
  "message": "ok",
  "success": true
}
```

### 8.3 业务失败 —— hasServiceStandard=false 时 service-standard 返 data=null（正常行为）

**场景说明**：订单未绑定产品行程快照，调 service-standard 接口返 data=null 是正常行为。

**请求**：

```
GET /v3/admin/order/1921111111111111111/service-standard
Authorization: Bearer <admin-jwt-token>
```

**响应**：

```json
{
  "code": 200,
  "data": null,
  "message": "ok",
  "success": true
}
```

## 9. 业务边界

**hasServiceStandard 判定逻辑（修复后）**：

同时满足以下三个条件，`hasServiceStandard` 才返回 `true`：
1. 订单关联的产品行程快照记录存在
2. 快照 JSON 反序列化成功（无类型错误）
3. 快照中 `itinerary` 字段非空（至少有1天行程）

任意一个条件不满足，`hasServiceStandard` 返回 `false`，此时调 `GET /service-standard` 将返回 `data=null`。

**contractStatus / insuranceStatus 兑底规则**：
- 订单刚创建、尚未发起签约/投保时，两个字段返回 "NONE"（修复前返回 null）
- 字段値随后端状态机流转更新，不需要前端轮询，刷新页面即可获取最新値

## 10. 修改前后对比

### 10.1 字段级对比

| 字段 | 修复前 | 修复后 |
|------|--------|--------|
| `contractStatus`（初始态） | null | "NONE" |
| `contractStatus`（枚举集合） | PENDING / GENERATED / SIGNED / VOIDED（4 値，含PENDING已废弃） | NONE / GENERATING / GENERATED / SIGNED / VOIDED / RESIGNING（6 値） |
| `insuranceStatus`（初始态） | null | "NONE" |
| `insuranceStatus`（枚举集合） | PENDING / ACTIVE / FAILED / CANCELLED（4 値，均已废弃重命名） | NONE / ISSUING / ISSUED / CANCELLED / FAILED（5 値） |
| `hasServiceStandard` | 只判断快照行存在，partial 快照也返 true | 快照存在 + 反序列化成功 + itinerary 非空，三条件全满足才返 true |
| GET /service-standard data | 永远为 null（反序列化失败被吐） | 有效快照时返回完整 {itinerary, notice, refundPolicy} |

### 10.2 行为级对比

| 行为 | 修复前 | 修复后 |
|------|--------|--------|
| 新建订单合同/保险状态 | 返回 null，前端字典无法匹配 | 返回 "NONE"，字典正常匹配显示"无合同"/"无保险" |
| hasServiceStandard=true 但 Tab 内容空 | 会出现（快照反序列化失败时） | 不再出现；hasServiceStandard=true 一定能拿到有效数据 |
| insuranceStatus 枚举 ACTIVE / PENDING | 后端可能返回这两个値 | 后端不再返回，统一替换为新枚举値集合 |

## 11. 影响评估 / 回滚

### 11.1 影响评估

- **是否破坏向后兼容**：是（枚举値重命名）。旧字典如只有 PENDING / ACTIVE（保险）或 PENDING（合同）等旧値，遇到新値会显示 "未知"。
- **前端是否必须同步上线**：建议同步更新枚举字典（§6.1 和 §6.2 完整値表）再上线；若前端能容忍旧値显示 "未知" 可先不同步。

### 11.2 回滚方案

- **回滚方式**：revert PR #2869 / PR #2874，重新打包部署 hl-order-service-v3
- **回滚后影响**：contractStatus / insuranceStatus 恢复返回 null 和旧枚举値；service-standard Tab 恢复返回 null

## 12. 注意事项

- **枚举字典必须更新**：旧前端字典仅有4 値/4 値（含已废弃的 PENDING / ACTIVE），遇到新枚举値（如 NONE / GENERATING / RESIGNING / ISSUING / ISSUED）会显示 "未知"。请按 §6.1 和 §6.2 完整値表更新本地枚举字典。
- **旧枚举値已废弃**：contractStatus 的 PENDING、insuranceStatus 的 PENDING 和 ACTIVE 后端不再返回，前端字典保留无害但不会再出现。
- **service-standard workaround 清理**：如果前端之前针对 hasServiceStandard=true 但 data=null 的矛盾做过兑底处理（如显示固定占位文案、屏蔽Tab），修复后可以移除该 workaround。

## 13. 关联 / 联系人

### 13.1 链接

- **Issue（枚举统一）**: [#2868](https://git.1814.love:8443/wx/HL/issues/2868)
- **Issue（service-standard 修复）**: [#2867](https://git.1814.love:8443/wx/HL/issues/2867)
- **PR（枚举统一）**: [#2869](https://git.1814.love:8443/wx/HL/pulls/2869)
- **PR（service-standard 修复）**: [#2874](https://git.1814.love:8443/wx/HL/pulls/2874)
- **Merge commit（枚举统一）**: [bb4c41969](https://git.1814.love:8443/wx/HL/commit/bb4c41969)
- **Merge commit（service-standard 修复）**: [442fdf089](https://git.1814.love:8443/wx/HL/commit/442fdf089)

### 13.2 联系人

- **后端负责人**: @yst