yaosutu
父节点
b140269132
当前提交
ac06376f48
@ -0,0 +1,892 @@
|
|||||||
|
---
|
||||||
|
schema: "hl-changelog/v2"
|
||||||
|
ticket: "5310"
|
||||||
|
title: "核单其他收支保存即确认"
|
||||||
|
consumer: "admin"
|
||||||
|
change_type: "修改接口"
|
||||||
|
backend_status: "deployed"
|
||||||
|
gateway_status: "verified"
|
||||||
|
frontend_status: "pending"
|
||||||
|
frontend_owner: ""
|
||||||
|
frontend_ref: ""
|
||||||
|
target_release: ""
|
||||||
|
verified_at: ""
|
||||||
|
status_note: "其他收入、其他支出保存类接口改为保存即确认；两个独立确认接口已删除，等待管理后台前端停止调用确认接口并处理存量未确认记录重存。"
|
||||||
|
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
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户