239 行
7.3 KiB
Markdown
239 行
7.3 KiB
Markdown
# mp-service: 订单保险详情独立接口契约梳理
|
||
|
||
> **服务**: hl-mp-service（端口 8085）→ 透传 hl-order-service-v2（端口 8094）
|
||
> **PR**: -（纯契约梳理，无代码变更）
|
||
> **Issue**: -
|
||
> **日期**: 2026-04-23
|
||
> **影响范围**: C 端「订单详情 - 服务包含 - 保险」子详情入口
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
**无接口变更**。本 changelog 只梳理 `GET /mp/order/{orderId}/insurance` 的入参/出参契约，方便前端对照接入。
|
||
|
||
⚠️ **路径提醒**：Controller 类名为 `MpOrderServiceDetailController`，但 `@RequestMapping` 是 `/mp/order`（不是 `/mp/order-service`）。完整路径以本文档为准。
|
||
|
||
---
|
||
|
||
## 一、接口基本信息
|
||
|
||
| 项 | 值 |
|
||
|----|----|
|
||
| 路径 | `/mp/order/{orderId}/insurance` |
|
||
| 方法 | GET |
|
||
| Controller | `MpOrderServiceDetailController#getInsurance` |
|
||
| 返回类型 | `Result<MpInsuranceDetailVO>` |
|
||
| 登录 | 需要（网关 token 解析 userId 透传）|
|
||
| 缓存 | 无 `@MpCache` 注解 |
|
||
|
||
---
|
||
|
||
## 二、调用时机与上下游关系
|
||
|
||
| 场景 | 推荐接口 |
|
||
|------|---------|
|
||
| 订单详情页首屏（聚合） | `GET /mp/order/{orderId}/dashboard` → 取 `.insurance` 字段 |
|
||
| 从「服务包含」列表点「保险」进子详情 | **`GET /mp/order/{orderId}/insurance`**（本接口）|
|
||
| 下载保单 PDF（整单合并） | `GET /mp/insurance/policy-pdf/{orderId}` |
|
||
| 下载单张保单 PDF | `GET /mp/insurance/policy/{insuranceOrderId}/download` |
|
||
|
||
两条路径返回同一个 VO（`MpInsuranceDetailVO`），字段结构一致。**不要在订单详情页同时调 dashboard 和本接口**。
|
||
|
||
`insuranceOrderId`（下载单张保单用）从本接口返回的 `policies[].insuranceOrderId` 取。
|
||
|
||
---
|
||
|
||
## 三、入参
|
||
|
||
### 路径参数
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| `orderId` | Path | Long | ✅ | 订单ID |
|
||
|
||
### Header
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| 登录 token | ✅ | 由网关校验并解析出 `userId`，前端无需手动传 `userId` |
|
||
|
||
---
|
||
|
||
## 四、出参 `Result<MpInsuranceDetailVO>`
|
||
|
||
### 顶层 `MpInsuranceDetailVO`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `schemeId` | Long | 方案ID |
|
||
| `schemeName` | String | 方案名称 |
|
||
| `description` | String | 方案描述 |
|
||
| `isOverseas` | Boolean | 是否境外 |
|
||
| `totalDays` | Integer | 适用行程天数 |
|
||
| `notice` | String | 保险告知状态：`INCLUDED` / `OPTIONAL` / `EXCLUDED` |
|
||
| `segments` | `List<CoverageSegment>` | 保障分段列表 |
|
||
| `policies` | `List<PolicyItem>` | 投保记录列表（未付款为空数组）|
|
||
|
||
### `CoverageSegment` — 保障分段（方案层）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `segmentName` | String | 分段名称 |
|
||
| `dayOffsetStart` | Integer | 起始天 |
|
||
| `dayOffsetEnd` | Integer | 结束天（`-1` = 最后一天）|
|
||
| `productName` | String | 保险产品名称 |
|
||
| `planName` | String | 保险计划名称 |
|
||
|
||
### `PolicyItem` — 投保记录（订单层，已付款才有）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `insuranceOrderId` | Long | 保险订单ID（下载单张保单用）|
|
||
| `policyNo` | String | 保单号 |
|
||
| `productName` | String | 保险产品名称 |
|
||
| `planName` | String | 保险计划名称 |
|
||
| `premium` | BigDecimal | 保费（元）|
|
||
| `insuredCount` | Integer | 被保人数 |
|
||
| `coverageStartDate` | LocalDate | 保障开始日期 |
|
||
| `coverageEndDate` | LocalDate | 保障结束日期 |
|
||
| `status` | String | `PENDING` / `INSURING` / `INSURED` / `FAILED`（`CANCELLED` 已由后端过滤不返回）|
|
||
| `statusLabel` | String | 状态中文标签 |
|
||
| `insuredPersons` | `List<InsuredPerson>` | 被保人列表 |
|
||
|
||
### `InsuredPerson` — 被保人（证件/电话已脱敏）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `name` | String | 姓名 |
|
||
| `idCardType` | String | `ID_CARD` / `PASSPORT` |
|
||
| `idCardNo` | String | 证件号码（脱敏）|
|
||
| `birthday` | LocalDate | 出生日期 |
|
||
| `gender` | String | `MALE` / `FEMALE` |
|
||
| `phone` | String | 手机号（脱敏）|
|
||
|
||
---
|
||
|
||
## 五、响应示例
|
||
|
||
### 已投保订单
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"schemeId": 101,
|
||
"schemeName": "境内 7 日综合保障",
|
||
"description": "含意外/医疗/行李/延误",
|
||
"isOverseas": false,
|
||
"totalDays": 7,
|
||
"notice": "INCLUDED",
|
||
"segments": [
|
||
{
|
||
"segmentName": "全程",
|
||
"dayOffsetStart": 1,
|
||
"dayOffsetEnd": -1,
|
||
"productName": "平安境内旅行险",
|
||
"planName": "豪华计划"
|
||
}
|
||
],
|
||
"policies": [
|
||
{
|
||
"insuranceOrderId": 20439,
|
||
"policyNo": "PICC2026042300001",
|
||
"productName": "平安境内旅行险",
|
||
"planName": "豪华计划",
|
||
"premium": 38.00,
|
||
"insuredCount": 2,
|
||
"coverageStartDate": "2026-05-01",
|
||
"coverageEndDate": "2026-05-07",
|
||
"status": "INSURED",
|
||
"statusLabel": "已生效",
|
||
"insuredPersons": [
|
||
{
|
||
"name": "张三",
|
||
"idCardType": "ID_CARD",
|
||
"idCardNo": "1101**********1234",
|
||
"birthday": "1990-01-01",
|
||
"gender": "MALE",
|
||
"phone": "138****5678"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 未付款订单（policies 为空数组）
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"schemeId": 101,
|
||
"schemeName": "境内 7 日综合保障",
|
||
"isOverseas": false,
|
||
"totalDays": 7,
|
||
"notice": "INCLUDED",
|
||
"segments": [ /* 方案分段仍有值 */ ],
|
||
"policies": []
|
||
}
|
||
}
|
||
```
|
||
|
||
### 订单不含保险（notice=EXCLUDED）
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"schemeId": null,
|
||
"schemeName": null,
|
||
"notice": "EXCLUDED",
|
||
"segments": [],
|
||
"policies": []
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、边界行为
|
||
|
||
- 未登录 → 401（网关拦截）
|
||
- `orderId` 不属于当前 userId → 业务异常，`Result.code != 200`
|
||
- 订单存在但未付款 → `policies=[]`，但 `segments` / `schemeName` 仍返回（方案信息属于产品快照）
|
||
- 订单不含保险（`notice=EXCLUDED`）→ `policies=[]` 且 `segments=[]`
|
||
- `status=CANCELLED` 的保单 → **后端已过滤**，不会出现在 `policies` 中
|
||
|
||
---
|
||
|
||
## 七、契约约束
|
||
|
||
- 下载单张保单时的 `insuranceOrderId` **必须**取自本接口返回的 `policies[].insuranceOrderId`，不要用 `orderId` 替代
|
||
- `dayOffsetEnd=-1` 是约定值，表示"保障到行程最后一天"，非真实天数
|
||
- `premium` 是 `BigDecimal`，JSON 序列化为数字（非字符串），精度 2 位小数
|
||
|
||
---
|
||
|
||
## 八、不影响范围
|
||
|
||
- **仅新增文档梳理**，代码零改动
|
||
- `/mp/order/{orderId}/dashboard` 聚合接口中的 `.insurance` 字段与本接口返回 VO 完全一致，两者**可互换取用**
|
||
- 保单 PDF 下载两个接口（`/mp/insurance/policy-pdf/{orderId}` 和 `/mp/insurance/policy/{insuranceOrderId}/download`）与本接口是上下游关系，未做变更
|
||
|
||
---
|
||
|
||
## 九、相关文档
|
||
|
||
- `MpOrderServiceDetailController.java`（hl-mp-service）
|
||
- VO：`MpInsuranceDetailVO`（hl-mp-service + hl-order-service-v2 镜像一致）
|
||
- 关联 changelog：
|
||
- `2026-04-23_mp-dashboard-endpoints-timing-guide.md`（订单/行程 5 个聚合接口调用时机梳理）
|
||
- `2026-04-23_mp-service_contract-insurance-api-inventory.md`（保险/合同详情 5 接口梳理）
|