---
schema: "hl-changelog/v2"
ticket: "5310"
title: "核单其他收支保存即确认"
consumer: "admin"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "pi:019fadb7-dac9-74bf-9581-058835251208"
frontend_ref: "1444fc7f0bf34efaec0ee9f775f7d529b609b847"
target_release: "v2.1"
verified_at: "2026-07-29T20:43:00+08:00"
status_note: "管理后台已停止调用已删除的其他收支独立确认接口；保存行为按后续 #5320 最终契约显式提交确认状态，pnpm checkpoint 全部通过。"
updated_at: "2026-07-28"
base: "dev-v3"
generated: "2026-07-28T11:54:21+08:00"
---

# 【修改接口·管理后台】核单其他收支保存即确认 (#5310)

> **PR**: #5313 | **服务**: hl-order-service-v3 | **更新时间**: 2026-07-28 11:54

## 1. 接口背景

核单「其他收入」「其他支出」不再需要先保存、再单独点确认。保存成功即视为已确认，前端不再调用独立确认接口。

## 2. 变更清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 新增其他收入并原子创建订单增费 | POST | `/v3/admin/order/{orderId}/settlement/other-incomes` | 修改 | 保存成功后返回 `settlementConfirmStatus=CONFIRMED`、`settlementConfirmStatusName=已确认` |
| 2 | 修改其他收入；金额或项目名变化时原子冲销并重建订单增费 | PUT | `/v3/admin/order/{orderId}/settlement/other-incomes/{incomeId}` | 修改 | 保存成功后返回 `settlementConfirmStatus=CONFIRMED`、`settlementConfirmStatusName=已确认` |
| 3 | 新增其他支出 | POST | `/v3/admin/order/{orderId}/settlement/other-expenses` | 修改 | 保存成功后返回 `settlementConfirmStatus=CONFIRMED` |
| 4 | 修改其他支出 | PUT | `/v3/admin/order/{orderId}/settlement/other-expenses/{settlementId}` | 修改 | 保存成功后返回 `settlementConfirmStatus=CONFIRMED` |
| 5 | 批量确认其他收入 | POST | `/v3/admin/order/{orderId}/settlement/other-incomes/confirm` | 删除 | 接口删除；前端不要再调用 |
| 6 | 确认其他支出 | POST | `/v3/admin/order/{orderId}/settlement/other-expenses/confirm` | 删除 | 接口删除；前端不要再调用 |

## 3. 接口详情

### 3.1 新增其他收入

- **方法 + 路径**：`POST /v3/admin/order/{orderId}/settlement/other-incomes`
- **接口名**：新增其他收入并原子创建订单增费
- **使用场景**：在核单其他收入页新增一条其他收入。
- **认证**：需要管理后台登录态；需要资金写入权限。
- **幂等性**：是；同一订单内 `requestId` 永久唯一，相同 `requestId` 且请求载荷一致时返回同一条记录。
- **限流**：无接口专属限流。

**路径参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `orderId` | Long | 是 | 订单 ID，必须大于 0 |

**请求体字段**

| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|------|------|------|------|----------|
| `requestId` | String | 是 | 客户端生成的稳定幂等请求 ID，同订单内永久唯一 | 非空，最长 64 字符 |
| `incomeDate` | String(date) | 是 | 收入日期，格式 `YYYY-MM-DD` | 非空 |
| `projectName` | String | 是 | 项目名称 | 非空，最长 100 字符 |
| `projectCategory` | String | 是 | 项目类别 | 非空，最长 64 字符 |
| `specification` | String | 否 | 票种/规格 | 最长 100 字符 |
| `quantity` | Decimal | 是 | 数量 | >= 0，最多 8 位整数、4 位小数 |
| `unitPrice` | Decimal | 是 | 核算单价 | >= 0，最多 8 位整数、2 位小数 |
| `settlementAmount` | Decimal | 是 | 核算金额 | > 0，最多 8 位整数、2 位小数；必须等于 `quantity * unitPrice` 四舍五入到 2 位 |
| `paymentMethod` | String | 是 | 付款类型 | `CASH_PAID` / `COMPANY_PAID` / `SIGNED` |
| `voucherUrls` | String[] | 否 | 凭证 URL 列表 | 最多 9 项；每项最长 1024 字符；必须是 http/https |
| `remark` | String | 否 | 备注 | 最长 500 字符 |

**响应字段：`Result<SettlementOtherIncomeItemRespVO>`**

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Integer | 业务码，成功为 `200` |
| `msg` | String | 响应消息 |
| `data.id` | String | 其他收入 ID |
| `data.requestId` | String | 手工新增幂等请求 ID；自动投影为空 |
| `data.incomeDate` | String(date) | 收入日期 |
| `data.projectName` | String | 项目名称 |
| `data.projectCategory` | String | 项目类别 |
| `data.projectCategoryName` | String | 项目类别名称 |
| `data.specification` | String | 票种/规格 |
| `data.quantity` | Decimal | 数量 |
| `data.unitPrice` | Decimal | 核算单价 |
| `data.settlementAmount` | Decimal | 核算金额 |
| `data.paymentMethod` | String | 付款类型 |
| `data.paymentMethodName` | String | 付款类型名称 |
| `data.voucherUrls` | String[] | 凭证 URL 列表 |
| `data.settlementConfirmStatus` | String | 确认状态；本接口保存成功返回 `CONFIRMED` |
| `data.settlementConfirmStatusName` | String | 确认状态名称；本接口保存成功返回 `已确认` |
| `data.remark` | String | 备注 |
| `data.sourceType` | String | 来源类型 |
| `data.sourceTypeName` | String | 来源类型名称 |
| `data.sourceId` | String | 来源附加费 ID |

**错误码**

| code | 含义 | 触发场景 |
|------|------|----------|
| `400` | 参数校验失败 | 必填缺失、字段长度超限、枚举非法、凭证 URL 非 http/https、金额不等于数量乘单价 |
| `584074` | 当前核单状态不允许修改其他收入 | 订单核单状态不是待核单或核单中 |
| `584075` | 其他收入关联的附加费来源无效 | 保存后无法得到有效来源记录 |
| `584076` | 其他收入核算金额必须等于数量乘以核算单价 | `settlementAmount` 与 `quantity * unitPrice` 不一致 |
| `584087` | requestId 已用于另一笔其他收入 | 同订单重复使用 `requestId`，但请求载荷不同 |
| `584089` | 核单或结算已完成，资金数据不可再修改 | 订单资金数据已锁定 |

**示例：典型成功**

请求：

```http
POST /v3/admin/order/60001/settlement/other-incomes
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
  "requestId": "oi-20260728-0001",
  "incomeDate": "2026-07-28",
  "projectName": "临时加收房差",
  "projectCategory": "房差",
  "specification": "双人间",
  "quantity": 2,
  "unitPrice": 120.00,
  "settlementAmount": 240.00,
  "paymentMethod": "CASH_PAID",
  "voucherUrls": ["https://cdn.example.com/vouchers/income-1.jpg"],
  "remark": "现场补收"
}
```

响应：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "99001",
    "requestId": "oi-20260728-0001",
    "incomeDate": "2026-07-28",
    "projectName": "临时加收房差",
    "projectCategory": "房差",
    "projectCategoryName": "房差",
    "specification": "双人间",
    "quantity": 2,
    "unitPrice": 120.00,
    "settlementAmount": 240.00,
    "paymentMethod": "CASH_PAID",
    "paymentMethodName": "现付",
    "voucherUrls": ["https://cdn.example.com/vouchers/income-1.jpg"],
    "settlementConfirmStatus": "CONFIRMED",
    "settlementConfirmStatusName": "已确认",
    "remark": "现场补收",
    "sourceType": "ORDER_SURCHARGE",
    "sourceTypeName": "订单增费",
    "sourceId": "88001"
  }
}
```

**示例：边界成功**

请求：

```json
{
  "requestId": "oi-20260728-0002",
  "incomeDate": "2026-07-28",
  "projectName": "其他收入",
  "projectCategory": "其他",
  "quantity": 0.0001,
  "unitPrice": 100.00,
  "settlementAmount": 0.01,
  "paymentMethod": "SIGNED",
  "voucherUrls": [],
  "remark": null
}
```

响应：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "99002",
    "requestId": "oi-20260728-0002",
    "incomeDate": "2026-07-28",
    "projectName": "其他收入",
    "projectCategory": "其他",
    "projectCategoryName": "其他",
    "specification": null,
    "quantity": 0.0001,
    "unitPrice": 100.00,
    "settlementAmount": 0.01,
    "paymentMethod": "SIGNED",
    "paymentMethodName": "签单",
    "voucherUrls": [],
    "settlementConfirmStatus": "CONFIRMED",
    "settlementConfirmStatusName": "已确认",
    "remark": null,
    "sourceType": "ORDER_SURCHARGE",
    "sourceTypeName": "订单增费",
    "sourceId": "88002"
  }
}
```

**示例：业务失败**

请求：

```json
{
  "requestId": "oi-20260728-0003",
  "incomeDate": "2026-07-28",
  "projectName": "加收费用",
  "projectCategory": "其他",
  "quantity": 2,
  "unitPrice": 100.00,
  "settlementAmount": 199.00,
  "paymentMethod": "CASH_PAID"
}
```

响应：

```json
{
  "code": 584076,
  "msg": "其他收入核算金额必须等于数量乘以核算单价",
  "data": null
}
```

### 3.2 修改其他收入

- **方法 + 路径**：`PUT /v3/admin/order/{orderId}/settlement/other-incomes/{incomeId}`
- **接口名**：修改其他收入；金额或项目名变化时原子冲销并重建订单增费
- **使用场景**：修改已有其他收入；也用于把存量 `UNCONFIRMED` 记录重新保存为 `CONFIRMED`。
- **认证**：需要管理后台登录态；需要资金写入权限。
- **幂等性**：否。
- **限流**：无接口专属限流。

**路径参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `orderId` | Long | 是 | 订单 ID，必须大于 0 |
| `incomeId` | Long | 是 | 其他收入 ID，必须大于 0 |

**请求体字段**

同 §3.1，但不包含 `requestId`。

**响应字段**

同 §3.1；保存成功后 `data.settlementConfirmStatus=CONFIRMED`、`data.settlementConfirmStatusName=已确认`。

**错误码**

| code | 含义 | 触发场景 |
|------|------|----------|
| `400` | 参数校验失败 | 必填缺失、字段长度超限、枚举非法、金额不一致 |
| `584073` | 其他收入不存在或不属于当前订单 | `incomeId` 不存在或不属于 `orderId` |
| `584074` | 当前核单状态不允许修改其他收入 | 订单核单状态不是待核单或核单中 |
| `584076` | 其他收入核算金额必须等于数量乘以核算单价 | `settlementAmount` 与 `quantity * unitPrice` 不一致 |
| `584089` | 核单或结算已完成，资金数据不可再修改 | 订单资金数据已锁定 |

**示例：典型成功**

请求：

```http
PUT /v3/admin/order/60001/settlement/other-incomes/99001
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
  "incomeDate": "2026-07-28",
  "projectName": "临时加收房差",
  "projectCategory": "房差",
  "specification": "双人间",
  "quantity": 2,
  "unitPrice": 130.00,
  "settlementAmount": 260.00,
  "paymentMethod": "COMPANY_PAID",
  "voucherUrls": ["https://cdn.example.com/vouchers/income-2.jpg"],
  "remark": "修改金额"
}
```

响应：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "99001",
    "requestId": "oi-20260728-0001",
    "incomeDate": "2026-07-28",
    "projectName": "临时加收房差",
    "projectCategory": "房差",
    "projectCategoryName": "房差",
    "specification": "双人间",
    "quantity": 2,
    "unitPrice": 130.00,
    "settlementAmount": 260.00,
    "paymentMethod": "COMPANY_PAID",
    "paymentMethodName": "公司付款",
    "voucherUrls": ["https://cdn.example.com/vouchers/income-2.jpg"],
    "settlementConfirmStatus": "CONFIRMED",
    "settlementConfirmStatusName": "已确认",
    "remark": "修改金额",
    "sourceType": "ORDER_SURCHARGE",
    "sourceTypeName": "订单增费",
    "sourceId": "88003"
  }
}
```

**示例：边界成功（存量未确认重存）**

请求：

```json
{
  "incomeDate": "2026-07-20",
  "projectName": "历史其他收入",
  "projectCategory": "其他",
  "quantity": 1,
  "unitPrice": 88.00,
  "settlementAmount": 88.00,
  "paymentMethod": "CASH_PAID",
  "voucherUrls": [],
  "remark": "重存后确认"
}
```

响应：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "99010",
    "requestId": "oi-old-001",
    "incomeDate": "2026-07-20",
    "projectName": "历史其他收入",
    "projectCategory": "其他",
    "projectCategoryName": "其他",
    "specification": null,
    "quantity": 1,
    "unitPrice": 88.00,
    "settlementAmount": 88.00,
    "paymentMethod": "CASH_PAID",
    "paymentMethodName": "现付",
    "voucherUrls": [],
    "settlementConfirmStatus": "CONFIRMED",
    "settlementConfirmStatusName": "已确认",
    "remark": "重存后确认",
    "sourceType": "ORDER_SURCHARGE",
    "sourceTypeName": "订单增费",
    "sourceId": "88010"
  }
}
```

**示例：业务失败**

请求：

```json
{
  "incomeDate": "2026-07-28",
  "projectName": "不存在记录",
  "projectCategory": "其他",
  "quantity": 1,
  "unitPrice": 10.00,
  "settlementAmount": 10.00,
  "paymentMethod": "CASH_PAID"
}
```

响应：

```json
{
  "code": 584073,
  "msg": "其他收入不存在或不属于当前订单",
  "data": null
}
```

### 3.3 新增其他支出

- **方法 + 路径**：`POST /v3/admin/order/{orderId}/settlement/other-expenses`
- **接口名**：新增其他支出
- **使用场景**：在核单其他支出页新增一条其他支出。
- **认证**：需要管理后台登录态；需要资金写入权限。
- **幂等性**：否。
- **限流**：无接口专属限流。

**路径参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `orderId` | Long | 是 | 订单 ID，必须大于 0 |

**请求体字段**

| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|------|------|------|------|----------|
| `expenseType` | String | 是 | 支出类型 | `FUEL` / `TOLL` / `PARKING` / `RENTAL` / `MAINTENANCE` / `OTHER` |
| `projectName` | String | 是 | 项目名称 | 非空，最长 200 字符 |
| `expenseDate` | String(date) | 否 | 发生日期，格式 `YYYY-MM-DD` | 可空 |
| `actualAmount` | Decimal | 是 | 实际金额 | >= 0，最多 8 位整数、2 位小数 |
| `paymentMethod` | String | 是 | 付款类型 | `CASH_PAID` / `COMPANY_PAID` / `SIGNED` |
| `voucherUrls` | String[] | 否 | 凭证 URL 列表 | 最多 9 项；每项最长 1024 字符；必须是 http/https |
| `remark` | String | 否 | 备注 | 最长 512 字符 |

**响应字段：`Result<SettlementOtherExpenseRespVO>`**

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Integer | 业务码，成功为 `200` |
| `msg` | String | 响应消息 |
| `data.id` | String | 其他支出 ID |
| `data.expenseType` | String | 支出类型 |
| `data.projectName` | String | 项目名称 |
| `data.expenseDate` | String(date) | 发生日期 |
| `data.actualAmount` | String | 实际金额 |
| `data.paymentMethod` | String | 付款类型 |
| `data.voucherUrls` | String[] | 凭证 URL 列表 |
| `data.settlementConfirmStatus` | String | 确认状态；本接口保存成功返回 `CONFIRMED` |
| `data.remark` | String | 备注 |

**错误码**

| code | 含义 | 触发场景 |
|------|------|----------|
| `400` | 参数校验失败 | 必填缺失、字段长度超限、枚举非法 |
| `584095` | 其他支出字段超出允许范围 | `expenseType` 非法、项目名为空或超长、金额超范围、备注超长 |
| `584096` | 付款类型不合法 | `paymentMethod` 不是允许值 |
| `584097` | 凭证 URL 格式或数量不合法 | 凭证数量超限、非 http/https、单项超长 |
| `584307` | 当前核单状态不允许写入餐食或其他支出 | 订单核单状态不是待核单或核单中 |
| `584089` | 核单或结算已完成，资金数据不可再修改 | 订单资金数据已锁定 |

**示例：典型成功**

请求：

```http
POST /v3/admin/order/60001/settlement/other-expenses
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
  "expenseType": "TOLL",
  "projectName": "过路费",
  "expenseDate": "2026-07-28",
  "actualAmount": 50.00,
  "paymentMethod": "CASH_PAID",
  "voucherUrls": ["https://cdn.example.com/vouchers/toll.jpg"],
  "remark": "高速通行费"
}
```

响应：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "801",
    "expenseType": "TOLL",
    "projectName": "过路费",
    "expenseDate": "2026-07-28",
    "actualAmount": "50.00",
    "paymentMethod": "CASH_PAID",
    "voucherUrls": ["https://cdn.example.com/vouchers/toll.jpg"],
    "settlementConfirmStatus": "CONFIRMED",
    "remark": "高速通行费"
  }
}
```

**示例：边界成功**

请求：

```json
{
  "expenseType": "OTHER",
  "projectName": "0元备注支出",
  "expenseDate": null,
  "actualAmount": 0.00,
  "paymentMethod": "SIGNED",
  "voucherUrls": [],
  "remark": null
}
```

响应：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "802",
    "expenseType": "OTHER",
    "projectName": "0元备注支出",
    "expenseDate": null,
    "actualAmount": "0.00",
    "paymentMethod": "SIGNED",
    "voucherUrls": [],
    "settlementConfirmStatus": "CONFIRMED",
    "remark": null
  }
}
```

**示例：业务失败**

请求：

```json
{
  "expenseType": "BAD_TYPE",
  "projectName": "非法支出类型",
  "actualAmount": 10.00,
  "paymentMethod": "CASH_PAID"
}
```

响应：

```json
{
  "code": 584095,
  "msg": "其他支出字段超出允许范围",
  "data": null
}
```

### 3.4 修改其他支出

- **方法 + 路径**：`PUT /v3/admin/order/{orderId}/settlement/other-expenses/{settlementId}`
- **接口名**：修改其他支出
- **使用场景**：修改已有其他支出；也用于把存量 `UNCONFIRMED` 记录重新保存为 `CONFIRMED`。
- **认证**：需要管理后台登录态；需要资金写入权限。
- **幂等性**：否。
- **限流**：无接口专属限流。

**路径参数**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `orderId` | Long | 是 | 订单 ID，必须大于 0 |
| `settlementId` | Long | 是 | 其他支出 ID，必须大于 0 |

**请求体字段**

同 §3.3。

**响应字段**

同 §3.3；保存成功后 `data.settlementConfirmStatus=CONFIRMED`。

**错误码**

| code | 含义 | 触发场景 |
|------|------|----------|
| `400` | 参数校验失败 | 必填缺失、字段长度超限、枚举非法 |
| `584091` | 其他支出不存在或不属于当前订单 | `settlementId` 不存在或不属于 `orderId` |
| `584095` | 其他支出字段超出允许范围 | `expenseType` 非法、项目名为空或超长、金额超范围、备注超长 |
| `584096` | 付款类型不合法 | `paymentMethod` 不是允许值 |
| `584097` | 凭证 URL 格式或数量不合法 | 凭证数量超限、非 http/https、单项超长 |
| `584307` | 当前核单状态不允许写入餐食或其他支出 | 订单核单状态不是待核单或核单中 |
| `584089` | 核单或结算已完成，资金数据不可再修改 | 订单资金数据已锁定 |

**示例：典型成功**

请求：

```http
PUT /v3/admin/order/60001/settlement/other-expenses/801
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
  "expenseType": "PARKING",
  "projectName": "停车费",
  "expenseDate": "2026-07-28",
  "actualAmount": 35.00,
  "paymentMethod": "COMPANY_PAID",
  "voucherUrls": ["https://cdn.example.com/vouchers/parking.jpg"],
  "remark": "改为停车费"
}
```

响应：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "801",
    "expenseType": "PARKING",
    "projectName": "停车费",
    "expenseDate": "2026-07-28",
    "actualAmount": "35.00",
    "paymentMethod": "COMPANY_PAID",
    "voucherUrls": ["https://cdn.example.com/vouchers/parking.jpg"],
    "settlementConfirmStatus": "CONFIRMED",
    "remark": "改为停车费"
  }
}
```

**示例：边界成功（存量未确认重存）**

请求：

```json
{
  "expenseType": "OTHER",
  "projectName": "历史其他支出",
  "expenseDate": "2026-07-20",
  "actualAmount": 1.00,
  "paymentMethod": "CASH_PAID",
  "voucherUrls": [],
  "remark": "重存后确认"
}
```

响应：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "810",
    "expenseType": "OTHER",
    "projectName": "历史其他支出",
    "expenseDate": "2026-07-20",
    "actualAmount": "1.00",
    "paymentMethod": "CASH_PAID",
    "voucherUrls": [],
    "settlementConfirmStatus": "CONFIRMED",
    "remark": "重存后确认"
  }
}
```

**示例：业务失败**

请求：

```json
{
  "expenseType": "TOLL",
  "projectName": "不存在记录",
  "expenseDate": "2026-07-28",
  "actualAmount": 50.00,
  "paymentMethod": "CASH_PAID"
}
```

响应：

```json
{
  "code": 584091,
  "msg": "其他支出不存在或不属于当前订单",
  "data": null
}
```

### 3.5 已删除：批量确认其他收入

- **原方法 + 路径**：`POST /v3/admin/order/{orderId}/settlement/other-incomes/confirm`
- **原接口名**：批量确认其他收入
- **变更后**：接口已删除；新增/修改其他收入保存成功即确认。
- **请求体**：不再支持。旧请求体形如 `{"incomeIds":["99001"]}`，前端不要再发送。
- **响应**：不再返回原 `confirmedCount`；调用该路径按不存在接口处理。

**示例：删除后调用失败**

请求：

```json
{
  "incomeIds": ["99001"]
}
```

响应：

```json
{
  "code": 404,
  "msg": "Not Found",
  "data": null
}
```

### 3.6 已删除：确认其他支出

- **原方法 + 路径**：`POST /v3/admin/order/{orderId}/settlement/other-expenses/confirm`
- **原接口名**：确认其他支出
- **变更后**：接口已删除；新增/修改其他支出保存成功即确认。
- **请求体**：不再支持。旧接口无请求体。
- **响应**：不再返回 `Boolean`；调用该路径按不支持的方法处理。

**示例：删除后调用失败**

请求：

```json
{}
```

响应：

```json
{
  "code": 405,
  "msg": "Method Not Allowed",
  "data": null
}
```

## 4. 接口入参

各接口入参已在 §3 按接口自包含列出。

## 5. 出参字段

各接口出参已在 §3 按接口自包含列出。核心变化是保存类接口的确认状态返回值变为已确认：

| 接口 | 字段 | 类型 | 当前返回 |
|------|------|------|----------|
| POST/PUT 其他收入 | `data.settlementConfirmStatus` | String | `CONFIRMED` |
| POST/PUT 其他收入 | `data.settlementConfirmStatusName` | String | `已确认` |
| POST/PUT 其他支出 | `data.settlementConfirmStatus` | String | `CONFIRMED` |

## 6. 枚举 / 数据字典

### 6.1 paymentMethod（付款类型）

**所属字段**：`paymentMethod` | **类型**：`String` | **必填**：是

| 值 | 中文 | 说明 |
|----|------|------|
| `CASH_PAID` | 现付 | 现场现金或线下现付 |
| `COMPANY_PAID` | 公司付款 | 公司承担或公司支付 |
| `SIGNED` | 签单 | 签单结算 |

### 6.2 settlementConfirmStatus（确认状态）

**所属字段**：`settlementConfirmStatus` | **类型**：`String` | **必填**：响应字段

| 值 | 中文 | 说明 |
|----|------|------|
| `UNCONFIRMED` | 未确认 | 历史存量状态；本次变更后新增/修改保存不再产生该状态 |
| `CONFIRMED` | 已确认 | 新增/修改保存成功后的状态 |

### 6.3 expenseType（其他支出类型）

**所属字段**：`expenseType` | **类型**：`String` | **必填**：是

| 值 | 中文 | 说明 |
|----|------|------|
| `FUEL` | 油费 | 车辆类支出 |
| `TOLL` | 过路费 | 车辆类支出 |
| `PARKING` | 停车费 | 车辆类支出 |
| `RENTAL` | 租车费 | 车辆类支出 |
| `MAINTENANCE` | 维修费 | 车辆类支出 |
| `OTHER` | 其他 | 非上述类型的其他支出 |

### 6.4 sourceType（其他收入来源类型）

**所属字段**：`sourceType` | **类型**：`String` | **必填**：响应字段

| 值 | 中文 | 说明 |
|----|------|------|
| `ORDER_SURCHARGE` | 订单增费 | 其他收入关联的订单增费来源 |

## 7. 错误码

| code | 含义 | 触发场景 |
|------|------|----------|
| `400` | 参数校验失败 | 请求体格式错误、必填缺失、字段长度或格式非法 |
| `404` | 接口不存在 | 继续调用已删除的其他收入确认接口 |
| `405` | 方法不支持 | 继续调用已删除的其他支出确认接口 |
| `584073` | 其他收入不存在或不属于当前订单 | 修改其他收入时 `incomeId` 无效 |
| `584074` | 当前核单状态不允许修改其他收入 | 订单核单状态不是待核单或核单中 |
| `584075` | 其他收入关联的附加费来源无效 | 其他收入来源无效 |
| `584076` | 其他收入核算金额必须等于数量乘以核算单价 | 其他收入金额不一致 |
| `584087` | requestId 已用于另一笔其他收入 | 新增其他收入幂等键冲突 |
| `584089` | 核单或结算已完成，资金数据不可再修改 | 资金数据已锁定 |
| `584091` | 其他支出不存在或不属于当前订单 | 修改其他支出时 `settlementId` 无效 |
| `584095` | 其他支出字段超出允许范围 | 支出类型、项目名、金额或备注非法 |
| `584096` | 付款类型不合法 | `paymentMethod` 非法 |
| `584097` | 凭证 URL 格式或数量不合法 | 凭证 URL 非法 |
| `584098` | 餐食或其他支出存在未确认记录 | Step6 前仍有历史未确认餐食或其他支出 |
| `584307` | 当前核单状态不允许写入餐食或其他支出 | 订单核单状态不是待核单或核单中 |

## 8. 示例（3 组：典型 / 边界 / 异常）

典型成功、边界成功、业务失败示例已按接口内联在 §3.1 至 §3.6。

## 9. 业务边界

- **适用场景**：订单核单状态为待核单或核单中，且当前账号具备资金写入权限时，可以新增/修改其他收入和其他支出。
- **不适用场景**：核单或结算已完成后，不允许再保存资金数据。
- **特殊边界**：历史已存在的 `UNCONFIRMED` 其他收入/其他支出不会因为本次接口变更自动变为 `CONFIRMED`；需要前端对该行发起对应 `PUT` 保存，保存成功后才会返回 `CONFIRMED`。
- **删除接口边界**：不要再调用 `/other-incomes/confirm` 和 `/other-expenses/confirm`；保存类接口成功即可完成确认。

## 10. 修改前后对比

### 10.1 字段级对比

| 字段 | 改前 | 改后 |
|------|------|------|
| 其他收入 `settlementConfirmStatus` | POST/PUT 保存后返回 `UNCONFIRMED`，需再调确认接口变为 `CONFIRMED` | POST/PUT 保存成功直接返回 `CONFIRMED` |
| 其他收入 `settlementConfirmStatusName` | POST/PUT 保存后返回 `未确认` | POST/PUT 保存成功返回 `已确认` |
| 其他支出 `settlementConfirmStatus` | POST/PUT 保存后返回 `UNCONFIRMED`，需再调确认接口变为 `CONFIRMED` | POST/PUT 保存成功直接返回 `CONFIRMED` |
| 其他收入确认响应 `confirmedCount` | `POST /other-incomes/confirm` 返回确认数量 | 接口删除，不再返回 |
| 其他支出确认响应 `data` | `POST /other-expenses/confirm` 返回 `true` | 接口删除，不再返回 |

### 10.2 行为级对比

| 行为 | 改前 | 改后 |
|------|------|------|
| 新增其他收入 | 保存后仍是未确认，需要再调用确认接口 | 保存成功即确认 |
| 修改其他收入 | 修改后变为未确认，需要再调用确认接口 | 保存成功即确认 |
| 新增其他支出 | 保存后仍是未确认，需要再调用确认接口 | 保存成功即确认 |
| 修改其他支出 | 修改后变为未确认，需要再调用确认接口 | 保存成功即确认 |
| 存量未确认记录 | 可调用独立确认接口批量确认 | 需要逐条用 PUT 重存确认 |
| 独立确认按钮 | 调用确认接口 | 不再调用确认接口 |

## 11. 影响评估 / 回滚

### 11.1 影响评估

- **是否破坏向后兼容**：是。两个确认接口删除，继续调用会失败。
- **前端是否必须同步上线**：是。需要停止调用已删除确认接口，并以保存接口返回的 `settlementConfirmStatus` 作为确认结果。
- **影响已有数据**：历史 `UNCONFIRMED` 其他收入/其他支出不会自动确认；需要通过对应 PUT 保存后确认。

### 11.2 回滚方案

- **回滚方式**：如需恢复旧交互，回滚本次接口契约变更对应 PR。
- **回滚后清理**：无前端侧额外清理数据。
- **回滚耗时**：以后端发布节奏为准。

## 12. 注意事项

- 前端保存其他收入/其他支出成功后，不要再追加调用确认接口。
- 前端如有独立「确认其他收入」「确认其他支出」按钮或批量确认流程，需要改为保存即确认的交互。
- 前端如检测到历史 `UNCONFIRMED` 记录，需要提示用户重新保存该条记录；重存后响应会返回 `CONFIRMED`。
- 餐食费用确认接口 `POST /v3/admin/order/{orderId}/settlement/meals/confirm` 本次未删除，不属于本文变更范围。

## 13. 关联 / 联系人

### 13.1 链接

- **Issue**: [#5310](https://git.1814.love:8443/wx/HL/issues/5310)
- **PR**: [#5313](https://git.1814.love:8443/wx/HL/pulls/5313)
- **Merge commit**: [9b3af7c](https://git.1814.love:8443/wx/HL/commit/9b3af7c8587547fa7b1a0d4282bc4783dff98ea6)

### 13.2 联系人

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