hl-api-changelog/changelogs-v2/2026-08/06_5610_核单完毕车辆费用写入fleet对账（实际结算取消手动录入）-新增接口-管理后台.md

schema, ticket, title, consumer, author, 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	author	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	5610	核单完毕车辆费用写入fleet对账（实际结算取消手动录入）	admin	wx	新增接口	deployed	verified	implemented	mmg	hl-admin@d4ac54f5c0b756fc49ce7efa907d81912a7cfd58		2026-08-06		2026-08-07	origin/dev-v3	2026-08-06T19:42:24+08:00

🚗 核单完毕车辆费用写入 fleet 对账（实际结算取消手动录入）

• 日期: 2026-08-06
• 服务: hl-order-service-v3（核单）→ hl-fleet-service（车队对账）
• PR: #5622 + 补丁 #5624
• Issue: #5610
• Merge commit: fd67c16a7 + 973953481
• 作者: wx
• 设计: hl-backend-changelog 06_5597 写模式数据流设计
• 影响范围: 车队对账页（admin）「实际结算」列数据供给与录入方式变更；PUT /admin/fleet/reconciliation/actual 删除

变更接口

方法	路径	来源
POST	/internal/fleet/reconciliation/vehicle-fee	新增（fleet internal，Feign 直连）
PUT	/admin/fleet/reconciliation/actual	删除（实际结算改读核单写入）
GET	/admin/fleet/reconciliation/cars	修改（actualTotal 数据源变更 + 新增退款列）

新增 internal 接口 POST /internal/fleet/reconciliation/vehicle-fee 的前置说明

1. 变更内容

写模式：核单完毕 → order 调 fleet 写入接口 → fleet 对账本地读。

接口	位置	改前	改后
POST /internal/fleet/reconciliation/vehicle-fee（新增）	fleet internal，Feign 直连	不存在	核单完毕写入该订单车辆实际费用（逐车逐日）
PUT /admin/fleet/reconciliation/actual（删除）	fleet admin	车管手工录入实际结算	已删除（404），实际结算改读核单写入数据
GET /admin/fleet/reconciliation/cars	fleet admin	fleets[].actualTotal = 手工录入值	fleets[].actualTotal = SUM(vehicle_fee.actual_amount)，新增 fleets[].refundTotal、vehicles[].actualAmount/refundAmount、grandTotal.refundTotal

新增 internal 接口 POST /internal/fleet/reconciliation/vehicle-fee

• 调用方：hl-order-service-v3（核单完毕 finalize 事务内登记 Fleet 命令 Outbox SETTLEMENT_VEHICLE_FEE_WRITE，提交后重放调用；不在核单事务内同步 Feign，可重放补偿）。
• 幂等：orderId + assignmentId + serviceDate 唯一键，重核覆盖写（金额/退款/核单时间全量覆盖）。
• 服务日所在对账期已关账（period CLOSED）拒绝（605600），与 prep 冻结口径一致；须超管 reopen 后重核。
• items[] 为空（无车订单）直接成功不落行。

请求体 SettlementVehicleFeeWriteDTO（Feign 契约，hl-common）：

字段	类型	说明
orderId / orderNo	Long / String	订单标识（必填）
settledAt	LocalDateTime	核单完成时间（必填）
items[]	Array	逐车逐日明细（必填，可空数组）

item：

字段	类型	说明
assignmentId	Long	派单 ID（fleet_assignment.assignment_id，必填；order 侧取核单冻结行 sourceDetailId）
vehicleId / vehiclePlate / vehicleModelName / seats / driverName	—	车辆/司机展示快照（order 核单冻结快照）
serviceDate	LocalDate	服务日期（必填）
actualAmount	BigDecimal	核单实际车费（必填，≥0，605611）
refundAmount / refundedAt	BigDecimal / LocalDateTime	终止退款金额/完成时间（可空；仅订单首行携带防对账重复计数）

响应：Result<Void>（200 成功；605600 已关账 / 605610 参数非法 / 605611 金额为负）。

删除 PUT /admin/fleet/reconciliation/actual

• 车队对账「实际结算」不再手工录入：fleet_reconciliation_actual 表停止写入（历史数据保留，遗留待定另行处理）。
• 关账前置 605603「对账期实际金额未录入」改为校验对账车辆费用表该期至少一行。

2. Feign 接口变更

调用方向	Controller	方法与路径	请求类型	响应类型	变更类型
order-v3 → fleet	ReconciliationVehicleFeeInternalController	POST /internal/fleet/reconciliation/vehicle-fee	SettlementVehicleFeeWriteDTO	Result<Void>	新增
前端 → fleet	ReconciliationController	PUT /admin/fleet/reconciliation/actual	ReconActualSaveReqVO	ReconActualSaveRespVO	删除

internal 接口为内网 Feign LB 直连，不经 Gateway；调用方由公共 Feign 拦截器注入 X-Internal-Token。order-v3 侧 Feign 方法 FleetAssignmentExpandFeignClient#writeSettlementVehicleFee（contextId fleetAssignmentExpand）。

3. 统一响应包络与错误

正常和参数错误响应使用 Result<T>（code/message/data/traceId/success）。新增/复用错误码：

code	说明
605600	服务日所在对账期已关账，重核须先重开账
605610	核单车辆费用写入参数非法（幂等键缺失）
605611	核单实际车费不能为负

4. 前端/调用方动作（车队对账页）

• ❌ 删除「实际结算」手动录入入口（PUT /actual 已 404）；实际结算列改展示核单写入值（只读）。
• 保留展示：actualTotal（车队级）、diff（= actualTotal − payableTotal）；新增可空展示：fleets[].refundTotal、vehicles[].actualAmount、vehicles[].refundAmount、grandTotal.refundTotal。
• 金额为字符串（BigDecimal @JsonSerialize ToStringSerializer），前端按既有金额处理。

验证证据

• 定向测试：ReconciliationVehicleFeeServiceTest 9 例（幂等/重核覆盖/已关账拒绝/负数/参数非法/teamNo 取车辆车队归属）、ReconciliationQueryServiceTest 11 例（actual 读对账车辆费用表）、ReconciliationPeriodServiceTest 17 例（close 前置改造）、SettlementVehicleFeeReconciliationPublisherTest 4 例、SettlementFinalizeTxServiceTest 5 例（核单完毕登记 outbox）、OrderFleetCommandOutboxProcessorTest 26 例（SETTLEMENT_VEHICLE_FEE_WRITE 分发）、MapperBoundaryArchTest 25 例（settlement 域经 RequirementService 契约）。
• fleet verify：3196 tests 0 失败 + spotless:check 通过（含 Release E 门禁参数）。
• 网关验证（TEST）：internal 写入 200 ×3（首写/幂等/重核覆盖），DB 复查 fleet_reconciliation_vehicle_fee 3 行金额随覆盖更新；PUT /actual 404；对账页 GET /admin/fleet/reconciliation/cars 200 显示核单写入实际结算。
• order 全量 verify 失败集合（8F+95E）与干净 dev-v3 基线完全一致（#5599 H2 schema 未同步 / #5603 架构违规 / MySQL 集成环境），非本变更引入。
• 兼容性结论：fleet_reconciliation_actual 历史数据保留未迁移（遗留待定）；GET /admin/fleet/reconciliation/cars 响应新增字段向后兼容；删除 PUT /actual 为破坏性变更，前端须同步移除录入入口。