changelog-filename-gate / validate (push) Failing after 1s

详情

修改原因：#5310、#5320、#5342、#5343 已由管理后台完成消费并通过最终验证。

修改内容：将四份 changelog 标记为 implemented，记录 v2.1 业务提交、目标版本、验证时间和最终契约说明。

实际验证：业务仓库 pnpm checkpoint 全部通过；业务提交 1444fc7f0bf34efaec0ee9f775f7d529b609b847 已推送 origin/v2.1。

Changelog：changelogs-v2/2026-07/28_5310_*；changelogs-v2/2026-07/29_5320_*、5342_*、5343_*。

2026-07-29 20:57:05 +08:00

28 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base, generated

schema	ticket	title	consumer	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base	generated
hl-changelog/v2	5310	核单其他收支保存即确认	admin	修改接口	deployed	verified	implemented	pi:019fadb7-dac9-74bf-9581-058835251208	1444fc7f0bf34efaec0ee9f775f7d529b609b847	v2.1	2026-07-29T20:43:00+08:00	管理后台已停止调用已删除的其他收支独立确认接口；保存行为按后续 #5320 最终契约显式提交确认状态，pnpm checkpoint 全部通过。	2026-07-28	dev-v3	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`	核单或结算已完成，资金数据不可再修改	订单资金数据已锁定

示例：典型成功

请求：

POST /v3/admin/order/60001/settlement/other-incomes
Authorization: Bearer <token>
Content-Type: application/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": "现场补收"
}

响应：

{
  "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"
  }
}

示例：边界成功

请求：

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

响应：

{
  "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"
  }
}

示例：业务失败

请求：

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

响应：

{
  "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`	核单或结算已完成，资金数据不可再修改	订单资金数据已锁定

示例：典型成功

请求：

PUT /v3/admin/order/60001/settlement/other-incomes/99001
Authorization: Bearer <token>
Content-Type: application/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": "修改金额"
}

响应：

{
  "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"
  }
}

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

请求：

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

响应：

{
  "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"
  }
}

示例：业务失败

请求：

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

响应：

{
  "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`	核单或结算已完成，资金数据不可再修改	订单资金数据已锁定

示例：典型成功

请求：

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

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

响应：

{
  "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": "高速通行费"
  }
}

示例：边界成功

请求：

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

响应：

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

示例：业务失败

请求：

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

响应：

{
  "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`	核单或结算已完成，资金数据不可再修改	订单资金数据已锁定

示例：典型成功

请求：

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

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

响应：

{
  "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": "改为停车费"
  }
}

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

请求：

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

响应：

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

示例：业务失败

请求：

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

响应：

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

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

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

示例：删除后调用失败

请求：

{
  "incomeIds": ["99001"]
}

响应：

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

3.6 已删除：确认其他支出

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

示例：删除后调用失败

请求：

{}

响应：

{
  "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 本次未删除，不属于本文变更范围。

28 KiB

原始文件 Blame 文件历史

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

1. 接口背景

2. 变更清单

3. 接口详情

3.1 新增其他收入

3.2 修改其他收入

3.3 新增其他支出

3.4 修改其他支出

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

3.6 已删除：确认其他支出

4. 接口入参

5. 出参字段

6. 枚举 / 数据字典

6.1 paymentMethod（付款类型）

6.2 settlementConfirmStatus（确认状态）

6.3 expenseType（其他支出类型）

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

7. 错误码

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

9. 业务边界

10. 修改前后对比

10.1 字段级对比

10.2 行为级对比

11. 影响评估 / 回滚

11.1 影响评估

11.2 回滚方案

12. 注意事项

13. 关联 / 联系人

13.1 链接

13.2 联系人

28 KiB 原始文件 Blame 文件历史 Unescape Escape

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

1. 接口背景

2. 变更清单

3. 接口详情

3.1 新增其他收入

3.2 修改其他收入

3.3 新增其他支出

3.4 修改其他支出

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

3.6 已删除：确认其他支出

4. 接口入参

5. 出参字段

6. 枚举 / 数据字典

6.1 paymentMethod（付款类型）

6.2 settlementConfirmStatus（确认状态）

6.3 expenseType（其他支出类型）

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

7. 错误码

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

9. 业务边界

10. 修改前后对比

10.1 字段级对比

10.2 行为级对比

11. 影响评估 / 回滚

11.1 影响评估

11.2 回滚方案

12. 注意事项

13. 关联 / 联系人

13.1 链接

13.2 联系人

28 KiB

原始文件 Blame 文件历史