hl-api-changelog/changelogs-v2/2026-07/22_5158_派车按行程日标记车费日期-修改接口-管理后台.md

schema, ticket, title, consumer, backend, gateway, frontend, frontend_status, frontend_owner, frontend_ref, updated_at, base, generated

schema	ticket	title	consumer	backend	gateway	frontend	frontend_status	frontend_owner	frontend_ref	updated_at	base	generated
hl-changelog/v1	5158	派车按行程日标记车费日期	admin	verified	verified	claimed	claimed	hl-ui-codex		2026-07-25T02:59:34.137Z	dev-v3	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、wx/HL#5167

工单: wx/HL#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

部分日期计费示例：

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

全部免费示例：

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

校验规则：

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

修改已确认派单的计费日

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

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

{
  "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[] 新增：

{
  "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；前端按“前端处理清单”接入即可。