---
schema: "hl-changelog/v1"
ticket: "5158"
title: "派车按行程日标记车费日期"
consumer: "admin"
backend: "verified"
gateway: "verified"
frontend: "implemented"
frontend_status: "implemented"
frontend_owner: "hl-ui-codex"
frontend_ref: "mmg/hl-ui@5eb8a46bee9a5a101371313e2088decd9ea843f2"
updated_at: "2026-07-25T03:03:38.490Z"
base: "dev-v3"
generated: "2026-07-22T18:00:00+08:00"
---

# 【修改接口·前端待处理·管理后台】派车按行程日标记车费日期

## 目标前端

- 端类型：管理后台（Web）
- 目标仓库：`mmg/hl-ui`
- 目标分支：`v2.1`
- 联调/验收环境：<http://192.168.100.160:9527>
- 小程序：无需处理

> **服务**: hl-fleet-service
>
> **后端 PR**: [wx/HL#5166](https://git.1814.love:8443/wx/HL/pulls/5166)、[wx/HL#5167](https://git.1814.love:8443/wx/HL/pulls/5167)
>
> **工单**: [wx/HL#5158](https://git.1814.love:8443/wx/HL/issues/5158)
>
> **影响范围**: 管理后台派单创建、修改派单、派单详情及待司机确认通知预览

## 关键变化

派单的“服务日”和“收取车费日”现在是两个不同概念。未勾选车费的日期仍然是正常派车服务日，继续占用司机和车辆并按原规则处理保险，只把当天车费记为 `0`；不要把未勾选日期当成取消派车。

历史派单及未传新字段的调用均按“全部服务日收取车费”处理，不改变旧数据金额。

## 变更接口

| 方法 | 路径 | 变更类型 | 说明 |
| --- | --- | --- | --- |
| POST | `/admin/fleet/assignments` | 请求新增字段 | 创建排车/直接派车时冻结计费服务日 |
| POST | `/admin/fleet/assignments/{assignmentId}/change` | 请求能力扩展 | 支持不换车、不换司机，仅修改已确认派单的计费日 |
| GET | `/admin/fleet/board/orders/{orderId}` | 响应新增字段 | 当前有效派车组返回计费日、免费服务日及说明 |
| POST | `/admin/fleet/message-templates/{templateId}/render` | 请求与模板变量新增 | 预览计费安排；默认待确认模板已增加车费安排 |

## 创建派单

`POST /admin/fleet/assignments` 的原字段不变，新增：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `chargeableServiceDates` | `LocalDate[]/null` | 否 | 收取车费的服务日期；不传或 `null` 表示全部服务日，空数组表示全部免费 |
| `vehicleFeeWaiverReason` | `String/null` | 条件必填 | 免费服务日说明，最长 256 字；全部免费时必填 |
| `confirmAllServiceDatesFree` | `Boolean/null` | 条件必填 | `chargeableServiceDates=[]` 时必须显式传 `true` |

部分日期计费示例：

```json
{
  "orderId": "2046400000000000001",
  "startDate": "2026-07-29",
  "endDate": "2026-07-31",
  "vehicleId": "2046400000000000101",
  "driverId": "2046400000000000201",
  "holdMode": 1,
  "chargeableServiceDates": ["2026-07-30"],
  "vehicleFeeWaiverReason": "首尾接送已包含在团费中",
  "requestId": "dispatch-5158-example"
}
```

全部免费示例：

```json
{
  "chargeableServiceDates": [],
  "vehicleFeeWaiverReason": "本团车费由合作方统一结算",
  "confirmAllServiceDatesFree": true
}
```

校验规则：

- 所有日期必须属于本次派车组的服务日期，否则返回参数错误。
- 空数组但未二次确认，返回“全部服务日免费时必须二次确认”。
- 空数组但未填写说明，返回“全部服务日免费时必须填写原因”。
- `null` 与不传保持兼容，默认所有服务日计费。

## 修改已确认派单的计费日

`POST /admin/fleet/assignments/{assignmentId}/change` 复用同名三个字段。仅调整车费时可以不传 `newVehicleId/newDriverId`，但必须：

- `holdMode=0`；
- `effectiveDate` 指定修改生效日；
- `reason` 填写本次修改原因；
- `chargeableServiceDates` 表示从 `effectiveDate` 起目标切片中仍收车费的日期，不能包含生效日前日期。

```json
{
  "effectiveDate": "2026-07-29",
  "holdMode": 0,
  "chargeableServiceDates": ["2026-07-30"],
  "vehicleFeeWaiverReason": "首尾接送已包含在团费中",
  "reason": "按实际结算范围调整",
  "requestId": "change-fee-5158-example"
}
```

已确认派单会原地更新计费标记并写操作审计，不取消/重建派单，不改变司机、车辆、占用和保险。对应月份已经关账时返回 `605600`，前端应提示先由有权限人员重开账期。

## 派单详情新增字段

`GET /admin/fleet/board/orders/{orderId}` 的 `data.currentAssignment` 与 `data.activeAssignments[]` 新增：

```json
{
  "chargeableServiceDates": ["2026-07-30"],
  "freeServiceDates": ["2026-07-29", "2026-07-31"],
  "vehicleFeeWaiverReason": "首尾接送已包含在团费中"
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `chargeableServiceDates` | `LocalDate[]` | 收取车费的服务日，按日期升序 |
| `freeServiceDates` | `LocalDate[]` | 仍提供车辆服务但车费为 0 的日期，按日期升序 |
| `vehicleFeeWaiverReason` | `String/null` | 免费服务日说明 |

## 待确认通知与模板预览

`POST /admin/fleet/message-templates/{templateId}/render` 请求新增：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `serviceDates` | `LocalDate[]/null` | 本次派车的实际服务日期；不传时按订单起止日生成 |
| `chargeableServiceDates` | `LocalDate[]/null` | 预览中的计费日期；不传表示全部计费 |
| `vehicleFeeWaiverReason` | `String/null` | 免费服务日说明 |

新增模板变量：

| 变量 | 示例 |
| --- | --- |
| `{{assignment.vehicleFeeSummary}}` | `收取车费：7月30日；免费服务日：7月29日、7月31日` |
| `{{assignment.chargeableServiceDates}}` | `7月30日` |
| `{{assignment.freeServiceDates}}` | `7月29日、7月31日` |
| `{{assignment.vehicleFeeWaiverReason}}` | `首尾接送已包含在团费中` |

全部免费时摘要固定为“本团服务日均不计车费”，全部计费时为“全部服务日收取车费”。派单待确认通知会读取落库后的逐日切片并冻结正文；运营修改模板后不会追改已生成的通知。

系统默认“排车待确认”模板已增加“车费安排”和“免车费说明”。运营自行修改过的默认模板不会被数据库迁移覆盖，如需显示新内容，应在车管模板页面自行加入上述变量。

## 前端处理清单

- [ ] 派单页用订单实际行程服务日期生成多选项，默认全选，并明确标题为“收取车费日期”。
- [ ] 未选日期标为“免费服务日（仍派车、仍占用、仍按规则投保）”，不得触发取消派车逻辑。
- [ ] 全部取消勾选时显示二次确认并要求填写免费原因，提交 `confirmAllServiceDatesFree=true`。
- [ ] 修改已确认派单时调用既有 `/change` 接口，不直接复用创建接口；提交 `holdMode=0`、`reason` 和完整目标日期集合。
- [ ] 派单详情读取 `chargeableServiceDates/freeServiceDates` 回显，不根据车费金额反推。
- [ ] 待确认短信预览把同一组 `serviceDates/chargeableServiceDates/vehicleFeeWaiverReason` 传给模板渲染接口。
- [ ] 雪花 ID 继续按字符串处理，日期继续使用 `yyyy-MM-dd`。

## 验证证据

- 创建派单默认全计费、部分计费及全部免费二次确认均有单元测试。
- 免费服务日仅车费归零，保险成本字段与派车占用保持不变。
- 已确认派单变更写可靠 Outbox，失败可重试；已关账期在变更落库前拦截。
- 待司机确认通知从实际逐日派车切片生成并冻结计费摘要。
- `FleetServiceApplicationTest` 以 H2 真 Flyway 执行 65 条迁移通过；`spotless:check` 与 fleet `verify` 通过。
- 测试环境部署任务 `784326bb` 成功，`hl-fleet-service` 8087/8187 双实例健康。
- 以 `admin` 车务身份经测试网关实测模板列表、部分计费预览、全部免费预览、看板列表与详情，HTTP/业务码均为 200。
- 部分计费正文实际包含“收取车费：7月30日；免费服务日：7月29日、7月31日”；全部免费正文实际包含“本团服务日均不计车费”和免费原因。
- 看板详情 `currentAssignment` 已实际返回 `chargeableServiceDates/freeServiceDates/vehicleFeeWaiverReason` 契约字段。

> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`；前端按“前端处理清单”接入即可。