docs(admin): 通知派车按日车费日期契约 (#5158)

2026-07-22 18:30:22 +08:00 · 2026-07-22 18:30:22 +08:00 · 8f08de40b6
--- a/changelogs-v2/2026-07/87_5158_派车按行程日标记车费日期-修改接口-前端待处理-管理后台.md
+++ b/changelogs-v2/2026-07/87_5158_派车按行程日标记车费日期-修改接口-前端待处理-管理后台.md
@ -0,0 +1,174 @@
+---
+schema: "hl-changelog/v1"
+ticket: "5158"
+title: "派车按行程日标记车费日期"
+consumer: "admin"
+backend: "verified"
+gateway: "verified"
+frontend: "pending"
+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`；前端按“前端处理清单”接入即可。