# 接口变更记录 — 2026-03-23 19:02

> **提交** `8b444a8` · **作者** wx · **时间** 2026-03-23 19:02:42 +0800
>
> fix: 退款金额显示+操作记录详细化+直接申诉+申诉金额校验

## 变更总览

- **保险服务**
  - InternalInsurance (+1)
- **小程序聚合服务**
  - MpRefund (+1)

---

## 保险服务

### InternalInsurance

> 📖 **接口文档**: [http://192.168.100.236:8098/doc.html](http://192.168.100.236:8098/doc.html) → 标签 **「【内部接口】保险（Feign调用）」**

### 🆕 `GET` /internal/insurance/coverage/{orderId} — 查询订单保险保障(含被保人详情,内部调用)

> 内部服务间调用。返回订单维度的保险保障汇总信息，包含每份保单的被保人明细。用于小程序端按出行人展示保险信息。

**参数**

  - `{orderId}` (`Long`) — 路径参数：旅行订单ID

**响应** `Result<InsuranceCoverageVO>`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `orderId` | `Long` | 旅行订单ID |
| `orderCount` | `Integer` | 保险单数量 |
| `insuranceOrders` | `List<InsuranceOrderDetailVO>` | 保险订单详情列表(含被保人) |

---

## 小程序聚合服务

### MpRefund

> 📖 **接口文档**: [http://192.168.100.236:8086/doc.html](http://192.168.100.236:8086/doc.html) → 标签 **「C端 - 退款接口」**

### 🆕 `POST` /mp/order/refund/{orderId}/direct-appeal — 直接申诉退款

> 用户对退款政策计算的金额不满意，跳过退款申请直接发起申诉。

**参数**

  - `{orderId}` (`Long`) — 路径参数：订单ID

**请求体** `MpRefundAppealRequest`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `appealReason` | `String` | 申诉原因 |
| `appealAmount` | `BigDecimal` | 申诉退款金额 |
| `evidence` | `List<String>` | 申诉凭证图片URL列表 |

**响应** `Result<MpRefundDetailVO>`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `applicationId` | `Long` | 退款申请ID |
| `orderId` | `Long` | 订单ID |
| `orderNo` | `String` | 订单号 |
| `productName` | `String` | 产品名称 |
| `refundType` | `String` | 退款类型: DEPOSIT(定金)/BALANCE(尾款)/FULL(全款) |
| `refundTypeLabel` | `String` | 退款类型中文标签 |
| `reasonId` | `Long` | 退款原因ID |
| `reasonText` | `String` | 退款原因 |
| `reasonDetail` | `String` | 补充说明 |
| `paidAmount` | `BigDecimal` | 已付金额 |
| `calculatedAmount` | `BigDecimal` | 计算退款金额 |
| `actualAmount` | `BigDecimal` | 实际退款金额（审核后确定） |
| `policyId` | `Long` | 退款政策ID |
| `policyName` | `String` | 退款政策名称 |
| `departureDate` | `LocalDate` | 出发日期 |
| `daysBeforeDept` | `Integer` | 距出发天数 |
| `refundRatio` | `Integer` | 退款比例（百分比） |
| `status` | `String` | 退款状态: PENDING(待审核)/APPROVED(已通过)/REJECTED(已拒绝)/REFUNDING(退款中)/REFUNDED(已退款)/CANCELLED(已撤回)/APPEALING(申诉中)/APPEAL_APPROVED(申诉通过)/APPEAL_REJECTED(申诉驳回) |
| `statusLabel` | `String` | 退款状态中文标签 |
| `reviewAdminId` | `Long` | 审批管理员ID |
| `reviewAdminName` | `String` | 审批管理员姓名 |
| `reviewRemark` | `String` | 审批备注 |
| `reviewedAt` | `LocalDateTime` | 审批时间 |
| `appealReason` | `String` | 申诉原因 |
| `appealAmount` | `BigDecimal` | 申诉退款金额 |
| `approvalNo` | `String` | 审批编号（企微OA审批编号） |
| `appealStatus` | `Integer` | 申诉状态: 1-处理中, 2-通过, 3-驳回 |
| `autoRefundDeadline` | `LocalDateTime` | 自动退款截止时间 |
| `appealStatusLabel` | `String` | 申诉状态中文标签 |
| `appealedAt` | `LocalDateTime` | 申诉时间 |
| `refundedAt` | `LocalDateTime` | 退款完成时间 |
| `applicantType` | `String` | 申请人类型: USER(用户)/ADMIN(管理员) |
| `applicantId` | `Long` | 申请人ID |
| `applicantName` | `String` | 申请人姓名 |
| `createTime` | `LocalDateTime` | 创建时间 |
| `updateTime` | `LocalDateTime` | 更新时间 |

---

## 📦 其他数据对象变更

> 以下变更未直接关联到本次接口变更，但可能影响现有接口的请求/响应

### 小程序聚合服务

#### ✏️ MpOrderDetailVO

  - 🆕 `refundPolicy` (`Map<String, Object>`) — 退款政策（含政策名称和退款规则列表）

#### ✏️ MpOrderListItemVO

  - 🆕 `refundAmount` (`BigDecimal`) — 实际退款金额

<details>
<summary>📁 全部变更文件 (点击展开)</summary>

```
M	hl-insurance-service/src/main/java/com/hulalv/insurance/controller/InternalInsuranceController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/controller/MpRefundController.java
M	hl-mp-service/src/main/java/com/hulalv/mp/dto/MpRefundAppealRequest.java
M	hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignClient.java
M	hl-mp-service/src/main/java/com/hulalv/mp/feign/MpOrderFeignFallbackFactory.java
M	hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderDetailVO.java
M	hl-mp-service/src/main/java/com/hulalv/mp/vo/MpOrderListItemVO.java
M	hl-order-service/src/main/java/com/hulalv/order/constant/OrderConstants.java
M	hl-order-service/src/main/java/com/hulalv/order/entity/OrderTraveler.java
M	hl-order-service/src/main/java/com/hulalv/order/feign/InsuranceFeignClient.java
M	hl-order-service/src/main/java/com/hulalv/order/feign/InsuranceFeignFallbackFactory.java
M	hl-order-service/src/main/java/com/hulalv/order/service/OrderPriceDiffService.java
M	hl-order-service/src/main/java/com/hulalv/order/service/OrderService.java
M	hl-payment-service/src/main/java/com/hulalv/payment/constant/PaymentConstants.java
M	hl-user-service/src/main/java/com/hulalv/user/controller/InternalUserController.java
```
</details>