docs: simplify backend changelog guide

修改原因：hl-ui changelog loop 需要把前端消费进度回写到契约源，避免领取、实现状态与实际交付脱节。

修改内容：将 frontend_status 与已有 legacy frontend 同步为 implemented，记录负责人 hl-ui-codex，并关联 mmg/hl-ui@41f307090eccfdf3d06deabce8bc4f3d2be9a99a；发布和验收字段保持不变。

实际验证：回写器已校验目标文件、状态单调性、提交范围和 Front Matter 内容，提交只包含当前 changelog。

Frontend-Status: tools/mcp-api-sync/.changelog-repo/changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-前端待处理-管理后台.md

BACKEND_CHANGELOG_DELIVERY_GUIDE.md

@@ -1,85 +1,40 @@
-# 后端 API Changelog 推送与交接指南
+# 后端 API Changelog 推送说明
 
-> 本文可直接发送给后端同事。适用于 `wx/HL` 的管理后台与小程序接口变更。
+接口发生新增、修改或删除时，在 `hl-api-changelog` 仓库提交一份 changelog。
 
-## 一、什么时候必须推送 changelog
+## 1. 放在哪里
 
-以下变化需要 changelog：
+- 管理后台：`changelogs-v2/YYYY-MM/`
+- 小程序：`changelogs-v2-mp/YYYY-MM/`
 
-- Controller 路径、HTTP 方法或权限边界变化；
+文件名：
-- DTO、VO、BO、Feign 请求或响应字段变化；
-- 字段必填性、枚举、状态、金额、空值或兼容行为变化；
-- 新增、修改、废弃或删除管理后台/小程序接口；
-- 前端或其他调用方需要调整请求、解析或页面行为。
-
-纯后端内部重构且外部契约完全不变时，可不创建；必须在工单中说明 `frontend_status: not_required` 的判断依据。
-
-## 二、准备条件
-
-1. 已有关联的合格 Gitea 工单。
-2. 已确认目标端：
-   - 管理后台：`changelogs-v2/`
-   - 小程序端：`changelogs-v2-mp/`
-3. 已确认变更类型：`新增接口`、`修改接口` 或 `删除接口`。
-4. `D:/work2/hl-ui` 保持只读，不在前端仓库创建配合工单。
-5. changelog 仓库使用独立任务分支或 worktree，不把其他线程的未跟踪文件一起提交。
-
-## 三、生成草稿
-
-预览：
-
-```powershell
-hl changelog draft 5205 "车务首页汇总状态补全" `
-  --repo D:/work2/HL-v3-worktrees/5205 `
-  --base dev-v3 `
-  --track v3 `
-  --consumer admin `
-  --change-type 修改接口
-```
-
-确认目标路径和检测到的 Controller/DTO/VO/Feign 文件后写入：
-
-```powershell
-hl changelog draft 5205 "车务首页汇总状态补全" `
-  --repo D:/work2/HL-v3-worktrees/5205 `
-  --base dev-v3 `
-  --track v3 `
-  --consumer admin `
-  --change-type 修改接口 `
-  --write
-```
-
-`--write` 会自动获取 `changelog` 单写租约。手工创建或修改 changelog 时，应先执行：
-
-```powershell
-hl resource acquire changelog --ticket 5205 --ttl 1800
-```
-
-## 四、文件名
-
-管理后台：
 
 ```text
-changelogs-v2/YYYY-MM/DD_issue_业务标题-{新增接口|修改接口|删除接口}-管理后台.md
+DD_issue_业务标题-{新增接口|修改接口|删除接口}-{管理后台|小程序端}.md
 ```
 
-小程序：
+例如：
 
 ```text
-changelogs-v2-mp/YYYY-MM/DD_issue_业务标题-{新增接口|修改接口|删除接口}-小程序端.md
+changelogs-v2/2026-07/24_5205_车务首页汇总状态补全-修改接口-管理后台.md
 ```
 
-年月日必须使用提交时 `Asia/Shanghai` 的真实日期。状态不得写入文件名，不要增加“前端待处理”“已完成”等额外片段。
+日期使用提交时的上海日期；不要把“前端待处理”“已完成”等状态写进文件名。
 
-## 五、填写 v2 元数据
+## 2. 写什么
+
+可以复制仓库根目录的 `CHANGELOG_TEMPLATE.md`，至少写清：
+
+- 关联的 Issue 和后端 PR；
+- 接口路径和 HTTP 方法；
+- 新增、修改或删除的请求/响应字段；
+- 字段必填性、枚举、状态、空值、金额和兼容规则；
+- 前端需要做什么；
+- 后端测试、部署和网关验证结果。
+
+元数据中：
 
 ```yaml
----
-schema: "hl-changelog/v2"
-ticket: "5205"
-title: "车务首页汇总状态补全"
-consumer: "admin"
-change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "verified"
 frontend_status: "pending"
@@ -87,37 +42,15 @@ frontend_owner: ""
 frontend_ref: ""
 target_release: ""
 verified_at: ""
-status_note: ""
-updated_at: "2026-07-24"
-base: "dev-v3"
----
 ```
 
-规则：
+- 需要前端修改：`frontend_status: "pending"`
+- 不需要前端修改：`frontend_status: "not_required"`
+- 后端不要代替前端填写 `implemented`、`released` 或 `verified`
 
-- 自动草稿从 `backend_status: pending`、`gateway_status: pending` 开始。
+## 3. 校验
-- 后端实际部署完成后才能改为 `backend_status: deployed`。
-- 经网关验证后填写 `gateway_status: verified`；确实无需网关验证时使用 `not_required`。
-- 需要前端配合时初始化 `frontend_status: pending`。
-- 不需要前端修改时使用 `frontend_status: not_required`。
-- 后端不得代替前端填写 `implemented`、`released` 或 `verified`。
 
-## 六、正文必须写清
+在 `hl-api-changelog` 仓库执行：
-
-- 关联 Issue 和 PR；
-- 变更接口清单；
-- 请求与响应字段；
-- 枚举、状态、空值、ID 和金额规则；
-- 老数据和兼容行为；
-- 前端/调用方需要采取的动作；
-- 定向测试、网关验证和兼容性证据；
-- 不影响范围。
-
-页面展示、列表、汇总、看板、状态标签或颜色变化，还必须在后端工单中准备展示矩阵，明确数据来源、状态范围、空态、颜色和守恒规则。
-
-## 七、本地校验
-
-在 changelog 仓库执行：
 
 ```powershell
 npm test
@@ -125,57 +58,18 @@ npm run check:filenames -- --base origin/main --head HEAD
 npm run check:frontmatter -- --base origin/main --head HEAD
 ```
 
-单文件还可以执行：
+确保正文没有 `TODO`、`待补充` 或模板占位符。
 
-```powershell
+## 4. 提交和推送
-hl changelog lint D:/path/changelog.md
-```
 
-发布前 lint 允许前端仍是 `pending`，但要求：
+只暂存本次 changelog 文件：
-
-- `backend_status: deployed`；
-- `gateway_status` 不再是 `pending`；
-- 正文不存在 `TODO`、`待补充` 或模板占位符。
-
-## 八、提交和推送
-
-只暂存本任务文件，禁止使用会卷入其他线程文件的宽泛命令：
 
 ```powershell
 git status --short
 git add -- changelogs-v2/2026-07/24_5205_车务首页汇总状态补全-修改接口-管理后台.md
 git diff --cached --check
-git commit -m "docs: hand off fleet dashboard contract (#5205)"
+git commit -m "docs: hand off API contract (#5205)"
 git push -u origin <任务分支>
 ```
 
-随后向 `main` 创建 PR。合并前再次检查上海日期；跨越上海零点且仍未合并时，按贡献规则重命名为当天日期。
+然后向 `main` 创建 PR。不要提交其他任务的 changelog、`.tmp-*` 文件或任何凭据。
-
-不要直接提交：
-
-- 其他线程的 changelog；
-- `.tmp-*` 文件；
-- token、密码、证书、真实隐私数据；
-- `hl-ui` 代码。
-
-## 九、回写后端任务
-
-合并后在后端工单和任务台账记录：
-
-- changelog 文件路径；
-- changelog 提交或 PR；
-- 当前 `frontend_status`；
-- 后端部署和网关验证证据。
-
-```powershell
-hl task update 5205 `
-  --changelog D:/path/changelog.md
-```
-
-后端工单可以按后端验收范围关闭；前端继续在同一 changelog 中推进消费状态。
-
-手工持有租约时，完成后释放：
-
-```powershell
-hl resource release changelog --ticket 5205
-```

changelogs-v2/2026-07/24_5209_出行人省份与分批大交通关联-修改接口-管理后台.md

@@ -5,7 +5,11 @@ title: "出行人省份与分批大交通关联"
 consumer: "admin"
 backend: "verified"
 gateway: "verified"
-frontend: "pending"
+frontend: "implemented"
+frontend_status: "implemented"
+frontend_owner: "hl-ui-codex"
+frontend_ref: "mmg/hl-ui@4424375ef9180e69f22a4f5f6b0b80c9ec2062b7"
+updated_at: "2026-07-24T07:15:16.554Z"
 base: "dev-v3"
 generated: "2026-07-24T11:58:00+08:00"
 ---

changelogs-v2/2026-07/24_5211_派单通知预览补齐接送与行程数据-修改接口-管理后台.md

@@ -1,3 +1,9 @@
+---
+frontend_status: "implemented"
+frontend_owner: "hl-ui-codex"
+frontend_ref: "mmg/hl-ui@06f9d4dce58ef64c3e5de96e44754c0793286d06"
+updated_at: "2026-07-24T07:15:17.169Z"
+---
 # 车务：派单通知预览补齐接送与行程数据
 
 > **服务**: hl-fleet-service（8087/8187）  

changelogs-v2/2026-07/24_5215_车务首页未完成状态独立汇总-修改接口-管理后台.md

@@ -5,7 +5,11 @@ title: "车务首页未完成状态独立汇总"
 consumer: "admin"
 backend: "verified"
 gateway: "verified"
-frontend: "pending"
+frontend: "implemented"
+frontend_status: "implemented"
+frontend_owner: "hl-ui-codex"
+frontend_ref: "mmg/hl-ui@a48846a3e35c06df3aef422e538d5cd198002c2c"
+updated_at: "2026-07-24T07:15:17.828Z"
 base: "dev-v3"
 generated: "2026-07-24T14:25:00+08:00"
 ---

changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-前端待处理-管理后台.md

@@ -0,0 +1,195 @@
+---
+schema: "hl-changelog/v1"
+ticket: "5216"
+title: "派车看板补充槽位接送路线与就绪摘要"
+consumer: "admin"
+backend: "verified"
+gateway: "verified"
+frontend: "implemented"
+frontend_status: "implemented"
+frontend_owner: "hl-ui-codex"
+frontend_ref: "mmg/hl-ui@41f307090eccfdf3d06deabce8bc4f3d2be9a99a"
+updated_at: "2026-07-24T07:25:59.029Z"
+base: "dev-v3"
+generated: "2026-07-24T14:24:00+08:00"
+---
+
+# 【修改接口·前端待处理·管理后台】派车看板补充槽位接送路线与就绪摘要
+
+## 目标前端
+
+- 端类型：管理后台（Web）
+- 目标仓库：`mmg/hl-ui`
+- 目标分支：`v2.1`
+- 联调/验收环境：<http://192.168.100.160:9527>
+- 小程序：无需处理
+
+> **服务**: hl-order-service-v3、hl-fleet-service
+>
+> **工单**: [wx/HL#5216](https://git.1814.love:8443/wx/HL/issues/5216)
+>
+> **影响范围**: 车务管理 → 派车看板卡片
+
+## 业务口径
+
+派车看板卡片本身应足够车务完成日常派车判断，详情页只用于查看更深信息。每张卡对应一个稳定车辆槽位，
+同时显示当前需求全部槽位的派车进度、该槽位服务范围、接送批次、路线和资料就绪风险。
+
+- 看板仍按车辆槽位维度返回，不改为订单维度。
+- 只统计订单当前有效用车需求，不混入已驳回、已失活或旧版本需求。
+- 行程或大交通缺失只作风险提示，`readiness.blocksAssignment` 固定为 `false`，不改变 `canAssign`。
+- 卡片接送摘要不返回出行人、接送备注或大交通自由文本备注。
+
+## 变更接口
+
+```http
+GET /admin/fleet/board/orders
+```
+
+请求参数、筛选、排序、分页和 `records[]` 维度不变；每条 `records[]` 新增以下字段：
+
+```json
+{
+  "assignmentSlotId": "2080200000000000001",
+  "slotSummary": {
+    "assignmentSlotId": "2080200000000000001",
+    "slotIndex": 2,
+    "totalSlots": 3,
+    "serviceStartDate": "2026-07-29",
+    "serviceEndDate": "2026-07-31",
+    "serviceDays": 3,
+    "requiredVehicleType": "mpv",
+    "requiredVehicleTypeLabel": "商务车",
+    "requiredSeats": 7
+  },
+  "assignmentProgress": {
+    "totalSlots": 3,
+    "unassignedSlots": 1,
+    "holdingSlots": 1,
+    "assignedSlots": 1,
+    "completedSlots": 0,
+    "canceledSlots": 0
+  },
+  "pickupSummary": {
+    "required": true,
+    "statusCode": "PARTIAL",
+    "statusLabel": "接客信息部分缺失",
+    "batchCount": 2,
+    "readyBatchCount": 1,
+    "transportNos": ["MU8345", "K7091"],
+    "earliestTime": "2026-07-29T10:30:00",
+    "latestTime": "2026-07-29T15:20:00",
+    "stations": ["海拉尔机场"]
+  },
+  "dropoffSummary": {
+    "required": true,
+    "statusCode": "READY",
+    "statusLabel": "送客信息已齐",
+    "batchCount": 1,
+    "readyBatchCount": 1,
+    "transportNos": ["CA1234"],
+    "earliestTime": "2026-07-31T18:00:00",
+    "latestTime": "2026-07-31T18:00:00",
+    "stations": ["海拉尔站"]
+  },
+  "routeSummary": "海拉尔区 → 额尔古纳市 → 满洲里市",
+  "daysUntilDeparture": 5,
+  "readiness": {
+    "statusCode": "PARTIAL",
+    "statusLabel": "部分信息待补",
+    "itineraryStatusCode": "READY",
+    "itineraryStatusLabel": "行程已完整",
+    "itineraryDayCount": 3,
+    "itineraryExpectedDayCount": 3,
+    "missingItemCodes": ["PICKUP_TRANSFER"],
+    "missingItemLabels": ["接客信息"],
+    "blocksAssignment": false
+  }
+}
+```
+
+### 当前槽位 `slotSummary`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `assignmentSlotId` | `String` | 稳定车辆槽位 ID，按雪花 ID 字符串处理 |
+| `slotIndex` | `Integer/null` | 当前槽位序号，**从 1 开始** |
+| `totalSlots` | `Integer` | 当前有效需求车辆槽位总数 |
+| `serviceStartDate/serviceEndDate` | `LocalDate/null` | 当前槽位实际服务范围 |
+| `serviceDays` | `Integer/null` | 服务范围闭区间天数 |
+| `requiredVehicleType` | `String/null` | 当前槽位车型规范编码 |
+| `requiredVehicleTypeLabel` | `String` | 当前槽位车型中文标签 |
+| `requiredSeats` | `Integer/null` | 当前槽位要求座位数 |
+
+不要用既有整单 `requiredVehicles[]` 的数组位置猜当前卡片车型；当前卡片只读取 `slotSummary`。
+
+### 整单进度 `assignmentProgress`
+
+`assignmentProgress` 基于当前有效需求的全部稳定槽位计算，不受本次列表状态、车型、日期或关键词筛选影响。
+前端可直接展示“3 车：待派 1 / 排车中 1 / 已派 1”，不要用当前页 `records[]` 自行计数。
+
+### 接送摘要 `pickupSummary/dropoffSummary`
+
+| `statusCode` | 含义 |
+| --- | --- |
+| `READY` | 所有批次时间和站点均完整 |
+| `PARTIAL` | 至少一个批次完整，但仍有批次缺时间或站点 |
+| `MISSING` | 当前要求该方向接送，但没有完整批次 |
+| `NOT_REQUIRED` | 当前用车需求明确不要求该方向接送 |
+| `SOURCE_UNAVAILABLE` | order-v3 暂不可用，不能把它显示成“无需接送”或“资料已齐” |
+
+`pickupAt/dropoffAt` 兼容字段继续保留；订单实时上下文可用时，优先回填对应方向第一个有效站点。
+
+### 行程与就绪度
+
+- `routeSummary` 按行程天顺序生成，并压缩连续重复地点；无地点时为 `null`。
+- `daysUntilDeparture` 是服务端当前日期到出团日的自然日数；负数表示已出团。
+- `readiness.statusCode` 为 `READY/PARTIAL/MISSING/SOURCE_UNAVAILABLE`。
+- `missingItemCodes` 当前可能包含：
+  - `ORDER_CONTEXT`：订单实时信息不可用；
+  - `ITINERARY_DAYS`：逐日行程缺失、天数不完整或日期仍是旧档期；
+  - `ROUTE_SUMMARY`：行程天没有可用地点；
+  - `PICKUP_TRANSFER`：要求接客但资料不完整；
+  - `DROPOFF_TRANSFER`：要求送客但资料不完整。
+
+页面使用后端 `statusLabel/missingItemLabels` 展示中文，不自行翻译状态码。
+
+## 前端处理清单
+
+- [ ] 卡片主信息区展示“第 `slotIndex/totalSlots` 车”、车型标签、座位数和槽位服务日期。
+- [ ] 展示 `assignmentProgress` 整单进度，不按当前页或筛选后记录重新计算。
+- [ ] 分别展示接客和送客摘要；多批次显示批次数、班次/车次、时间范围和站点。
+- [ ] `NOT_REQUIRED` 显示“无需接客/无需送客”，`SOURCE_UNAVAILABLE` 显示“信息暂不可用”。
+- [ ] 展示 `routeSummary`、`daysUntilDeparture` 和 `readiness` 风险提示。
+- [ ] 资料缺失时不得禁用派车按钮；操作能力继续只读 `canAssign/availableActionCodes`。
+- [ ] 不在卡片展示出行人、接送备注、大交通备注等敏感或自由文本信息。
+- [ ] `assignmentSlotId/assignmentId/assignmentGroupId/requirementId/orderId` 均按字符串处理。
+- [ ] 覆盖单车、多车、部分已派、多批次接送、无需接送、资料缺失和下游降级场景。
+
+## 不影响范围
+
+- 不修改派车看板请求参数、分页、筛选、排序和操作接口。
+- 不修改 `canAssign/canRejectRequirement/availableActionCodes` 计算。
+- 不修改派单详情、矩阵派单、司机车辆占用、保险和费用。
+- 不迁移数据库，不写入订单、行程、大交通或派单数据。
+
+## 验证证据
+
+- 后端提交：`e73740c57caf295cac96d964e540279f581f1fb0`；PR：
+  [wx/HL#5221](https://git.1814.love:8443/wx/HL/pulls/5221)。
+- `mvn -pl hl-fleet-service -am verify` 通过：2354 tests，0 failures/errors，skipped 1；
+  Spotless 603 files clean。
+- `OrderFleetProviderServiceTest` 33 项、`BoardOrderServiceTest` 48 项及
+  `AssignmentServiceTest` 稳定槽位聚合测试均通过。
+- `mvn -pl hl-order-service-v3 -am verify` 共执行 6643 tests，其中 6642 项通过；
+  唯一错误是上游 `SettlementFinancialChecksMigrationTest` 在当前环境无法发现 Docker，
+  与本次接口变更无关。Issue #5216 的对应验收项因此仍保持未勾选。
+- 功能分支部署任务：order-v3 `d0e26c90`、fleet `a4776dfa`，均成功完成双实例滚动部署。
+- 经测试网关实测 `GET /admin/fleet/board/orders?page=1&pageSize=20`：HTTP 200，返回 3 条真实记录；
+  8 个新增字段在 3 条记录中全部存在且非空，观测到就绪状态 `PARTIAL`，接送状态
+  `READY/MISSING`。
+- Nacos 实测：`hl-order-service-v3` 8086/8186、`hl-fleet-service` 8087/8187 均为 2/2 健康；
+  四个新实例均有正常启动记录，启动后的运行日志未发现新增 ERROR、FATAL、Exception 或
+  `Caused by`。
+
+> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`；前端按“前端处理清单”接入即可。