# 【修改接口·管理后台】费用明细已收款拆分 (#5022)

> **PR**: #5025 | **服务**: hl-order-service-v3 | **更新时间**: 2026-07-18 00:00

## 1. 接口背景

管理后台订单费用明细需要区分展示已收订金、已收尾款、已收全款。原接口只返回 `paidAmount` 已收总额，无法直接区分不同收款类型。本次在订单费用接口响应 `data` 内新增 3 个拆分金额字段，`paidAmount` 仍表示已收总额。

## 2. 变更清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 订单费用信息 | GET | `/v3/admin/order/{id}/finance` | 修改接口 | 响应 `data` 新增 `depositPaidAmount`、`balancePaidAmount`、`fullPaidAmount` |

## 3. 接口详情

### 3.1 订单费用信息

- **使用场景**: 查询单个订单的费用汇总、优惠、加价、退款、线上支付交易明细。
- **认证**: 需要管理后台登录态 JWT。
- **幂等性**: 查询接口，幂等。
- **限流**: 无新增限流规则。

## 4. 接口入参

### 4.1 路径参数 / Query 参数

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | String | 是 | 订单 ID，路径参数。示例：`2077233785174179841` |

### 4.2 请求体字段

GET 请求，无请求体。

## 5. 出参字段

### 5.1 顶层响应字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Integer | 业务状态码，`200` 表示成功 |
| `message` | String | 响应消息 |
| `data` | Object | 订单费用信息 |
| `traceId` | String / null | 链路追踪 ID，可能为 `null` |
| `success` | Boolean | 请求是否成功 |

### 5.2 data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `totalAmount` | String | 订单总金额，金额字符串，单位元 |
| `payableAmount` | String | 应付金额，金额字符串，单位元 |
| `paidAmount` | String | 已收总额，包含成功线上收款和未撤销线下收款 |
| `depositPaidAmount` | String | 新增。实际已收订金金额，成功线上订金 + 未撤销线下订金 |
| `balancePaidAmount` | String | 新增。实际已收尾款金额，成功线上尾款 + 未撤销线下尾款 |
| `fullPaidAmount` | String | 新增。实际已收全款金额，成功线上全款 + 未撤销线下全款 |
| `balanceAmount` | String | 待收余额，金额字符串，单位元 |
| `discountAmount` | String | 优惠总额，金额字符串，单位元 |
| `surchargeAmount` | String | 加价总额，金额字符串，单位元 |
| `refundAmount` | String | 已退金额，金额字符串，单位元 |
| `payments` | Array | 线上支付交易明细；仍只表示线上交易，不包含线下收款明细 |
| `discounts` | Array | 优惠明细 |
| `surcharges` | Array | 加价明细 |

### 5.3 payments 字段项

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | String | 支付交易 ID |
| `paymentNo` | String | 支付流水号 |
| `amount` | String | 支付金额，单位元 |
| `paymentType` | String | 支付类型 |
| `status` | String | 支付状态 |
| `paidAt` | String / null | 支付成功时间，格式 `yyyy-MM-dd HH:mm:ss` |

> 本次未改变 `payments` 语义：它仍只表示线上支付交易明细。线下收款明细仍通过 `GET /v3/admin/order/{orderId}/payment/manual-receipt` 获取；线下金额已聚合进 `depositPaidAmount`、`balancePaidAmount`、`fullPaidAmount` 和 `paidAmount`。

### 5.4 discounts 字段项

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | String | 优惠明细 ID |
| `name` | String | 优惠名称 |
| `amount` | String | 优惠金额，单位元 |
| `type` | String | 优惠类型 |
| `source` | String | 优惠来源 |
| `createdAt` | String | 创建时间，格式 `yyyy-MM-dd HH:mm:ss` |

### 5.5 surcharges 字段项

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | String | 加价明细 ID |
| `name` | String | 加价名称 |
| `amount` | String | 加价金额，单位元 |
| `type` | String | 加价类型 |
| `createdAt` | String | 创建时间，格式 `yyyy-MM-dd HH:mm:ss` |

## 6. 枚举 / 数据字典

### 6.1 paymentType

**所属字段**: `payments[].paymentType` | **类型**: String

| 值 | 中文 | 说明 |
|----|------|------|
| `DEPOSIT` | 订金 | 订金支付 |
| `BALANCE` | 尾款 | 尾款支付 |
| `FULL` | 全款 | 全款支付 |

### 6.2 status

**所属字段**: `payments[].status` | **类型**: String

| 值 | 中文 | 说明 |
|----|------|------|
| `SUCCESS` | 支付成功 | 计入对应已收金额 |
| `PENDING` | 待支付 | 不计入对应已收金额 |
| `CLOSED` | 已关闭 | 不计入对应已收金额 |
| `FAILED` | 支付失败 | 不计入对应已收金额 |

### 6.3 type

**所属字段**: `discounts[].type`、`surcharges[].type` | **类型**: String

| 值 | 中文 | 说明 |
|----|------|------|
| `EARLY_BIRD` | 早鸟优惠 | 早鸟规则产生的优惠 |
| `MANUAL` | 手工调整 | 人工录入的优惠或加价 |
| `OTHER` | 其他 | 其他类型 |

### 6.4 source

**所属字段**: `discounts[].source` | **类型**: String

| 值 | 中文 | 说明 |
|----|------|------|
| `EARLY_BIRD_PLAN` | 早鸟方案 | 来源于早鸟优惠方案 |
| `MANUAL` | 手工录入 | 来源于人工录入 |

## 7. 错误码

| code | 含义 | 触发场景 |
|------|------|----------|
| `200` | 成功 | 订单费用信息查询成功 |
| `401` | 未登录或登录失效 | 未携带有效管理后台 JWT |
| `403` | 无权限 | 当前账号无权访问该订单费用信息 |
| `404` | 订单不存在 | 路径参数 `id` 对应订单不存在 |
| `500` | 系统异常 | 服务端处理异常 |

## 8. 示例

### 8.1 典型成功

**请求**:

```http
GET /v3/admin/order/2077233785174179841/finance HTTP/1.1
Authorization: Bearer <token>
```

无请求体。

**响应**:

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "totalAmount": "3105.00",
    "payableAmount": "2955.00",
    "paidAmount": "2500.00",
    "depositPaidAmount": "2000.00",
    "balancePaidAmount": "500.00",
    "fullPaidAmount": "0",
    "balanceAmount": "455.00",
    "discountAmount": "150.00",
    "surchargeAmount": "0.00",
    "refundAmount": "0.00",
    "payments": [],
    "discounts": [
      {
        "id": "2077233785199345666",
        "name": "早鸟优惠:早鸟-小团减150(适用人群:成人/儿童/小童)",
        "amount": "150.00",
        "type": "EARLY_BIRD",
        "source": "EARLY_BIRD_PLAN",
        "createdAt": "2026-07-15 11:28:22"
      }
    ],
    "surcharges": []
  },
  "traceId": null,
  "success": true
}
```

### 8.2 边界情况

**场景说明**: 订单暂无任何成功线上收款和未撤销线下收款时，所有已收拆分金额均返回 0 金额；明细数组可为空数组。

**请求**:

```http
GET /v3/admin/order/2077233785174179841/finance HTTP/1.1
Authorization: Bearer <token>
```

无请求体。

**响应**:

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "totalAmount": "3105.00",
    "payableAmount": "2955.00",
    "paidAmount": "0",
    "depositPaidAmount": "0",
    "balancePaidAmount": "0",
    "fullPaidAmount": "0",
    "balanceAmount": "2955.00",
    "discountAmount": "150.00",
    "surchargeAmount": "0.00",
    "refundAmount": "0.00",
    "payments": [],
    "discounts": [],
    "surcharges": []
  },
  "traceId": null,
  "success": true
}
```

### 8.3 业务失败

**场景说明**: 订单 ID 不存在。

**请求**:

```http
GET /v3/admin/order/9999999999999999999/finance HTTP/1.1
Authorization: Bearer <token>
```

无请求体。

**响应**:

```json
{
  "code": 404,
  "message": "订单不存在",
  "data": null,
  "traceId": null,
  "success": false
}
```

## 9. 业务边界

- **适用场景**: 管理后台查询订单费用明细时调用，订单存在且当前账号有访问权限。
- **不适用场景**: 用该接口获取线下收款明细列表；线下收款明细仍由 `GET /v3/admin/order/{orderId}/payment/manual-receipt` 返回。
- **特殊边界**: `payments` 为空不代表订单没有已收金额；可能存在未撤销线下收款，已聚合到本次新增的拆分金额和 `paidAmount`。
- **金额口径**: `paidAmount` 为已收总额；`depositPaidAmount`、`balancePaidAmount`、`fullPaidAmount` 为按收款类型拆分后的已收金额。

## 10. 修改前后对比

### 10.1 字段级对比

| 字段 | 改前 | 改后 |
|------|------|------|
| `data.depositPaidAmount` | 不返回 | 返回实际已收订金金额 |
| `data.balancePaidAmount` | 不返回 | 返回实际已收尾款金额 |
| `data.fullPaidAmount` | 不返回 | 返回实际已收全款金额 |
| `data.paidAmount` | 返回已收总额 | 继续返回已收总额，语义不变 |
| `data.payments` | 返回线上支付交易明细 | 继续只返回线上支付交易明细，语义不变 |

### 10.2 行为级对比

| 行为 | 改前 | 改后 |
|------|------|------|
| 已收金额拆分 | 只能读取 `paidAmount` 总额 | 可读取订金、尾款、全款 3 类已收金额 |
| 线下收款聚合 | `paidAmount` 中包含线下收款，无法按类型拆分 | 线下收款按类型聚合进新增拆分字段和 `paidAmount` |
| 线上支付明细 | `payments` 表示线上支付交易明细 | 保持不变，仍不包含线下收款明细 |

## 11. 影响评估 / 回滚

### 11.1 影响评估

- **是否破坏向后兼容**: 否。本次只新增响应字段，未删除或改名已有字段。
- **前端是否必须同步上线**: 否。旧前端继续读取 `paidAmount` 不受影响；需要区分已收订金、已收尾款、已收全款时读取新增字段。
- **影响已有数据**: 否。历史订单按成功线上收款和未撤销线下收款聚合返回。

### 11.2 回滚方案

- **回滚方式**: 回滚 PR #5025 后，接口不再返回 3 个新增字段。
- **回滚后兼容**: 只依赖 `paidAmount` 的旧逻辑不受影响；依赖新增字段的消费方需要兼容字段缺失。
- **回滚后清理**: 无需清理前端侧数据。

## 12. 注意事项

- `depositPaidAmount`、`balancePaidAmount`、`fullPaidAmount` 是金额字符串，单位元。
- 金额为 0 时可能返回 `"0"` 或 `"0.00"`，消费方不要依赖固定小数位判断金额语义。
- `payments` 为空时仍可能存在已收金额，因为线下收款不进入 `payments`。
- 线下收款明细列表仍由 `GET /v3/admin/order/{orderId}/payment/manual-receipt` 获取。

## 13. 关联 / 联系人

### 13.1 链接

- **Issue**: [#5022](https://git.1814.love:8443/wx/HL/issues/5022)
- **PR**: [#5025](https://git.1814.love:8443/wx/HL/pulls/5025)
- **Merge commit**: [aeb2d6d24](https://git.1814.love:8443/wx/HL/commit/aeb2d6d248fcc0fe49a540bfb3b864f06bc00123)

### 13.2 联系人

- **后端负责人**: 腰苏图