From 8f08de40b6862b217e92a3c8e2074afe7a7e1b47 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Wed, 22 Jul 2026 18:30:22 +0800
Subject: [PATCH] =?UTF-8?q?docs(admin):=20=E9=80=9A=E7=9F=A5=E6=B4=BE?=
 =?UTF-8?q?=E8=BD=A6=E6=8C=89=E6=97=A5=E8=BD=A6=E8=B4=B9=E6=97=A5=E6=9C=9F?=
 =?UTF-8?q?=E5=A5=91=E7=BA=A6=20(#5158)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...‹æ—¥æ ‡è®°è½¦è´¹æ—¥æœŸ-修改接å�£-å‰�端待处ç�†-管ç�†å�Žå�°.md | 174 ++++++++++++++++++
 1 file changed, 174 insertions(+)
 create mode 100644 changelogs-v2/2026-07/87_5158_派车按行程日标记车费日期-修改接�-�端待处�-管���.md

diff --git a/changelogs-v2/2026-07/87_5158_派车按行程日标记车费日期-修改接�-�端待处�-管���.md b/changelogs-v2/2026-07/87_5158_派车按行程日标记车费日期-修改接�-�端待处�-管���.md
new file mode 100644
index 0000000..84b8afc
--- /dev/null
+++ 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`；�端按“�端处�清��接入��。