From d5f8f64bcb2e078a06e35e79af4560f815f27660 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 7 Aug 2026 11:36:13 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=2006=5F5610=20=E6=A0=B8?= =?UTF-8?q?=E5=8D=95=E5=AE=8C=E6=AF=95=E8=BD=A6=E8=BE=86=E8=B4=B9=E7=94=A8?= =?UTF-8?q?=E5=86=99=E5=85=A5fleet=E5=AF=B9=E8=B4=A6=EF=BC=88=E4=BB=8E=20b?= =?UTF-8?q?ackend-changelog=20=E7=A7=BB=E5=85=A5=EF=BC=8C=E7=AE=A1?= =?UTF-8?q?=E7=90=86=E5=90=8E=E5=8F=B0=E5=89=8D=E7=AB=AF=E4=BA=A4=E6=8E=A5?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...eet对账（实际结算取消手动录入）-新增接口-管理后台.md | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 changelogs-v2/2026-08/06_5610_核单完毕车辆费用写入fleet对账（实际结算取消手动录入）-新增接口-管理后台.md diff --git a/changelogs-v2/2026-08/06_5610_核单完毕车辆费用写入fleet对账（实际结算取消手动录入）-新增接口-管理后台.md b/changelogs-v2/2026-08/06_5610_核单完毕车辆费用写入fleet对账（实际结算取消手动录入）-新增接口-管理后台.md new file mode 100644 index 0000000..c2701ce --- /dev/null +++ b/changelogs-v2/2026-08/06_5610_核单完毕车辆费用写入fleet对账（实际结算取消手动录入）-新增接口-管理后台.md @@ -0,0 +1,115 @@ +--- +schema: "hl-changelog/v2" +ticket: "5610" +title: "核单完毕车辆费用写入fleet对账（实际结算取消手动录入）" +consumer: "admin" +author: "wx" +change_type: "新增接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "2026-08-06" +status_note: "" +updated_at: "2026-08-06" +base: "origin/dev-v3" +generated: "2026-08-06T19:42:24+08:00" +--- + +# 🚗 核单完毕车辆费用写入 fleet 对账（实际结算取消手动录入） + +- **日期**: 2026-08-06 +- **服务**: `hl-order-service-v3`（核单）→ `hl-fleet-service`（车队对账） +- **PR**: [#5622](https://git.1814.love:8443/wx/HL/pulls/5622) + 补丁 [#5624](https://git.1814.love:8443/wx/HL/pulls/5624) +- **Issue**: [#5610](https://git.1814.love:8443/wx/HL/issues/5610) +- **Merge commit**: [fd67c16a7](https://git.1814.love:8443/wx/HL/commit/fd67c16a74aedaac9f4869c089a03d30ab3d5466) + [973953481](https://git.1814.love:8443/wx/HL/commit/97395348127b766cfa9957664dff853546a38e28) +- **作者**: wx +- **设计**: hl-backend-changelog [06_5597 写模式数据流设计](./06_5597_hl-order-service-v3_hl-fleet-service_核单完毕车辆费用车队对账数据流设计.md) +- **影响范围**: 车队对账页（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`（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` | 新增 | +| 前端 → 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`（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 为破坏性变更，前端须同步移除录入入口。