# 小程序订单 - 保险弹窗接口 + hotels/serviceItems 字段修复

- **日期**: 2026-04-19
- **PR**:
  - [#885](https://git.1814.love:8443/wx/HL/pulls/885) hotels coverUrl 回填
  - [#936](https://git.1814.love:8443/wx/HL/pulls/936) 保险弹窗 + clickable=true + 过滤 CANCELLED + 被保人
- **类型**: FEATURE + BUGFIX
- **状态**: 已合并到 dev + 测试环境部署中
- **服务**: hl-mp-service + hl-order-service-v2

---

## 一、接口变更清单

| # | 方法 | 路径 | 变更类型 | 影响位置 | 变更内容 |
|---|------|------|---------|---------|---------|
| 1 | GET | `/mp/order/{orderId}/insurance` | 🟢 **新增接口** | — | 保险详情弹窗 |
| 2 | GET | `/mp/order/{orderId}/hotels` | 🔴 **出参修复** | `data.items[].coverUrl` | 已分配路径此前硬编码 null, 现从产品快照反查返回图片 URL |
| 3 | POST `/mp/order/create`<br>GET `/mp/order/{id}`<br>PUT `/mp/order/{id}/edit` | 🔴 **出参字段值变化** | `data.serviceItems[type=INSURANCE].clickable` | 此前 INCLUDED 时返回 false, 现统一返回 true |

所有接口**入参无变化**。

---

## 二、接口详情

### 1. 🟢 新增: `GET /mp/order/{orderId}/insurance`

保险详情弹窗数据。

#### 鉴权
- Header: `Authorization: Bearer {mp-token}`
- 订单必须属于当前用户, 否则返回 `code=403`

#### 路径参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| `orderId` | path | Long | 是 | 订单 ID |

#### Query 参数
无。

#### Request Body
无。

#### 响应 Schema

```typescript
{
  code: number;           // 200 成功 / 403 无权 / 404 订单不存在
  message: string;
  data: MpInsuranceDetailVO | null;   // 订单无保险时为 null
  success: boolean;
}

interface MpInsuranceDetailVO {
  // ===== 方案基础信息 =====
  schemeId: string;             // 方案 ID (String 防 JS 大数丢精度)
  schemeName: string;           // 方案名
  description: string | null;   // 方案描述
  isOverseas: boolean;          // 境内/境外
  totalDays: number;            // 适用行程天数
  notice: 'INCLUDED' | 'OPTIONAL';   // INCLUDED=必含, OPTIONAL=可选

  // ===== 保障分段(方案配置, 与订单无关) =====
  segments: CoverageSegment[];

  // ===== 投保记录(订单付款后才有) =====
  policies: PolicyItem[];
}

interface CoverageSegment {
  segmentName: string;     // 分段名 "低风险"/"高风险"
  dayOffsetStart: number;  // 起始天(1 起)
  dayOffsetEnd: number;    // 结束天(-1 表示最后一天)
  productName: string;     // 保险产品名
  planName: string;        // 保障计划名
}

interface PolicyItem {
  insuranceOrderId: string;     // 保险订单 ID (String, 用于下载单张保单)
  policyNo: string;             // 保单号
  productName: string;
  planName: string;
  premium: number;              // 保费(元)
  insuredCount: number;         // 被保人数
  coverageStartDate: string;    // 起保日 yyyy-MM-dd
  coverageEndDate: string;      // 截止日
  status: 'PENDING' | 'INSURING' | 'INSURED' | 'FAILED';  // CANCELLED 不返回
  statusLabel: string;          // 状态中文
  insuredPersons: InsuredPerson[];
}

interface InsuredPerson {
  name: string;                   // 姓名
  idCardType: 'ID_CARD' | 'PASSPORT';
  idCardNo: string;               // 证件号(后端已脱敏: 110***********1234)
  birthday: string;               // 生日 yyyy-MM-dd
  gender: 'MALE' | 'FEMALE';
  phone: string;                  // 手机号(后端已脱敏: 138****5678)
}
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "schemeId": "2028762847782060034",
    "schemeName": "测试3日方案",
    "description": null,
    "isOverseas": false,
    "totalDays": 3,
    "notice": "INCLUDED",
    "segments": [
      { "segmentName": "低风险", "dayOffsetStart": 1, "dayOffsetEnd": 2,
        "productName": "山河令(太保山东新)", "planName": "10万计划" },
      { "segmentName": "高风险", "dayOffsetStart": 3, "dayOffsetEnd": 3,
        "productName": "平安保游万里行马术专属保险(互联网)", "planName": "计划一" }
    ],
    "policies": [
      {
        "insuranceOrderId": "9100000000001001",
        "policyNo": "BY202604190001",
        "productName": "山河令(太保山东新)",
        "planName": "10万计划",
        "premium": 50.00,
        "insuredCount": 2,
        "coverageStartDate": "2026-05-28",
        "coverageEndDate": "2026-05-29",
        "status": "INSURED",
        "statusLabel": "已承保",
        "insuredPersons": [
          { "name": "张三", "idCardType": "ID_CARD",
            "idCardNo": "110***********2222", "birthday": "1990-01-01",
            "gender": "MALE", "phone": "138****8001" },
          { "name": "李四", "idCardType": "ID_CARD",
            "idCardNo": "110***********3333", "birthday": "1995-02-02",
            "gender": "FEMALE", "phone": "138****8002" }
        ]
      }
    ]
  },
  "success": true
}
```

#### 几种特殊返回

| 场景 | 返回 |
|------|------|
| 订单不存在 | `code=404, data=null, message="订单不存在"` |
| 订单不属于当前用户 | `code=403, data=null, message="无权查看此订单"` |
| 订单未配保险 (`insuranceNotice=EXCLUDED`) 或无 INSURANCE 服务项 | `code=200, data=null` |
| 订单配了保险但**未付款** | `code=200, data.policies=[]` (只有方案+分段, 无保单) |
| 订单已付款, 正在投保中 | `code=200, data.policies` 含 `status=PENDING` 或 `INSURING` 的条目 |
| 一订单多保单 (分段投保 / 退保重保) | `code=200, data.policies` 返回多条, **CANCELLED 已过滤不返回** |
| 方案在数据库被删 | `code=200, data=null` (兜底) |

---

### 2. 🔴 修复: `GET /mp/order/{orderId}/hotels`

#### 变更位置
出参 `data.items[].coverUrl`

#### 变更前
已分配路径 (订单已确认实际入住酒店时) 返回:
```json
{
  "items": [
    { "hotelId": "xxx", "hotelName": "某酒店", "coverUrl": null,
      "assignmentDate": "2026-05-28", "roomType": "大床房", "hotelType": "HOTEL" }
  ]
}
```

#### 变更后
```json
{
  "items": [
    { "hotelId": "xxx", "hotelName": "某酒店",
      "coverUrl": "https://cdn.../hotel-cover.jpg",
      "assignmentDate": "2026-05-28", "roomType": "大床房", "hotelType": "HOTEL" }
  ]
}
```

#### 变更原因
订单分配表 `order_hotel_assignment` 不存 coverUrl, 此前硬编码 null. 现按 hotelId 从产品快照 `hotels[]` 里反查图片 URL. 未分配路径行为不变.

#### 其他字段
无变化 (`hotelId`/`hotelName`/`assignmentDate`/`roomType`/`hotelType` 及同级 `nightCount`/`roomTypeStats` 均无改动)。

---

### 3. 🔴 字段值变化: `serviceItems[type=INSURANCE].clickable`

#### 影响接口
- `POST /mp/order/create` 返回 `data.serviceItems`
- `GET /mp/order/{orderId}` 返回 `data.serviceItems`
- `PUT /mp/order/{orderId}/edit` 返回 `data.serviceItems`

#### 变更位置
`data.serviceItems` 数组中 `type === 'INSURANCE'` 的元素的 `clickable` 字段。

#### 变更前

| `insuranceNotice` | `clickable` |
|---|---|
| `EXCLUDED` | 条目不返回 |
| `INCLUDED` (必含保险) | **false** |
| `OPTIONAL` (可选加保) | true |

#### 变更后

| `insuranceNotice` | `clickable` |
|---|---|
| `EXCLUDED` | 条目不返回 (不变) |
| `INCLUDED` | **true** (与 OPTIONAL 统一) |
| `OPTIONAL` | true (不变) |

#### 变更原因
新增了保险弹窗接口 `/mp/order/{id}/insurance` 后, INCLUDED 也有点击交互需求 (查看方案 + 保单列表), 不再需要前端禁用这个条目。

#### 历史订单
在本次改动之前已下单的订单, `order_service_item` 表里固化的 `clickable` 仍是原值 (可能 false), 新下单的订单起是 true。如果需要批量修正历史数据, 可提 Issue 加补偿脚本。

---

## 三、不兼容变更

**无**。
- 新增接口: 老前端不调用不影响
- hotels `coverUrl`: 从 null 变为有值, 前端原本 null 态处理代码仍然正确
- `clickable`: 从 false 变为 true 只是让条目变可点, 旧代码不点它也不会出错
