diff --git a/changelogs-v2/2026-07/28_5310_核单其他收支保存即确认-修改接口-管理后台.md b/changelogs-v2/2026-07/28_5310_核单其他收支保存即确认-修改接口-管理后台.md new file mode 100644 index 0000000..fd63156 --- /dev/null +++ b/changelogs-v2/2026-07/28_5310_核单其他收支保存即确认-修改接口-管理后台.md @@ -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`** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `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 +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 +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`** + +| 字段 | 类型 | 说明 | +|------|------|------| +| `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 +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 +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