docs(fleet): 补全 #4935 派单回调验收契约

changelogs-v2/2026-07/59_4935_车务需求级派单完成回调与滚动发布契约-管理后台.md

@@ -2,11 +2,11 @@
 
 > Issue: [wx/HL#4935](https://git.1814.love:8443/wx/HL/issues/4935)
 >
-> PR: [wx/HL#4994](https://git.1814.love:8443/wx/HL/pulls/4994)
+> PR: [wx/HL#4994](https://git.1814.love:8443/wx/HL/pulls/4994)、[wx/HL#5009](https://git.1814.love:8443/wx/HL/pulls/5009)
 >
 > 服务: `hl-fleet-service` / `hl-order-service-v3`
 >
-> 日期: 2026-07-15
+> 日期: 2026-07-16
 >
 > 影响范围: 车务派单完成、用车需求驳回、订单资源状态、看板刷新与部署兼容
 
@@ -107,6 +107,7 @@ Content-Type: application/json
   "driverStaffId": "2077001000000000001",
   "driverName": "测试司机",
   "driverPhone": "13800000000",
+  "topologyFingerprint": "<64位 SHA-256 摘要>",
   "remark": "需求级最终派单快照"
 }
 ```
@@ -122,7 +123,11 @@ Content-Type: application/json
 }
 ```
 
-必填字段：`orderId`、`requirementId`、`vehicleId`、`vehicleType`、`vehicleCount`。其余快照字段允许为空，后端不得伪造车牌、品牌、座位、价格或司机信息。
+新版 Fleet 必填字段：`orderId`、`requirementId`、`vehicleId`、`vehicleType`、`vehicleCount`、`topologyFingerprint`。其中 `topologyFingerprint` 是 Fleet 根据该需求全部有效逐日派单生成的 64 位 SHA-256 摘要；其余快照字段允许为空，后端不得伪造车牌、品牌、座位、价格或司机信息。
+
+`vehicleId`、车牌和司机字段是稳定排序后的代表派单，`vehicleCount` 是该需求实际车辆组总数。完整逐日、多车辆和多司机拓扑仍以 Fleet 派单明细为准，不能从该轻量快照反推完整派车表。
+
+滚动发布期间，旧版 Fleet 不传 `topologyFingerprint` 时，Order-v3 会根据完整回调快照生成 `legacy:` 前缀摘要并持久化。该兼容仅用于先升级 Order-v3、后升级 Fleet 的过渡期；新版 Fleet 仍必须发送摘要。
 
 ### 4.2 轻量进度回写
 
@@ -156,13 +161,17 @@ Content-Type: application/json
 | 场景 | 结果 | 副作用 |
 |---|---|---|
 | `PENDING/PROCESSING` 且无快照 | 原子写快照并完成需求 | 同事务写需求 `DONE`、订单车辆状态 `DONE`、待办/日志并尝试推进订单 |
-| `DONE` 且已有快照 | 幂等成功 | 不重复插入快照，不重复推进 |
+| `DONE` 且摘要相同 | 幂等成功 | 不加需求写锁、不更新 `update_time`，不重复同步司机、待办、日志或推进订单 |
+| `DONE` 且摘要变化 | 刷新轻量快照 | 只更新同一需求快照和司机信息，不重复推进订单、待办或时间线 |
+| 旧版回调未传摘要 | 兼容成功 | Order-v3 生成稳定 `legacy:` 摘要；相同旧请求重放仍为零写入 |
 | `DONE` 但无快照 | 返回 `582081` | 禁止补造快照，禁止继续副作用 |
 | active 状态已有快照 | 返回 `582082` | 禁止重复回写 |
 | 需求不存在或失效 | 返回 `582080` | 无写入 |
 | 非法状态流转 | 返回 `582083` | 无写入 |
 | 订单/需求已取消 | 跳过 | 不写完成快照，不推进订单 |
 
+并发与重放需区分：同一摘要在 5 秒互斥窗口外再次提交时返回成功且数据库零写入；互斥窗口内的并发重复请求返回可识别冲突 `100502`，同样不得重复写快照、待办、流水或推进订单。前端遇到该冲突应刷新当前需求状态，不得自行补写完成状态。
+
 错误响应示例：
 
 ```json
@@ -199,17 +208,62 @@ Content-Type: application/json
 
 ## 九、验证状态
 
-合并前代码验证：
+### 9.1 合并前代码验证
 
 ```text
-hl-order-service-v3 verify: 5574 tests，0 failures，0 errors，15 skipped
+hl-order-service-v3 targeted: 198 tests，0 failures，0 errors，0 skipped
-hl-fleet-service clean verify: 1693 tests，0 failures，0 errors，0 skipped
+hl-order-service-v3 full verify: 5582 tests，0 failures，0 errors，15 skipped
-Feign 集成测试隔离定向回归: 63 tests，全部通过
+hl-fleet-service targeted: 226 tests，0 failures，0 errors，0 skipped
-Fleet Spotless: 472 files clean
+hl-fleet-service full verify: 1721 tests，0 failures，0 errors，0 skipped
-gate_check.py --dataflow --assert-base dev-v3: PASS
+独立终审: P0=0，P1=0，P2=0
 ```
 
-部署任务、测试环境网关/API、MySQL/Flyway 和服务日志证据将在 PR 合并后回填；在这些证据完成前，Issue #4935 保持 OPEN。
+### 9.2 测试环境部署
+
+- `hl-order-service-v3` Deploy Panel 任务 `29b541d6` 成功；`8086/8186` 双实例均启动并监听。
+- `hl-fleet-service` Deploy Panel 任务 `aaee8d01` 成功；`8087/8187` 双实例均启动并监听。
+- Nacos 已启用 `fleet.assign.requirement-lifecycle-enabled=true` 与 `fleet.feign.writeback.enabled=true`。
+- 发布顺序按“Order-v3 全实例 -> Fleet 全实例 -> 开启需求级生命周期开关”执行，未跨过滚动发布护栏。
+
+### 9.3 真实 API 与数据验收
+
+使用独立车务账号和真实测试订单完成 DIRECT、HOLD、取消后迟到回调、同摘要重放、摘要变化刷新、非法参数及失效需求分支验收；未使用 `admin`、`wx` 或 Mock 数据。
+
+公网网关 `https://api.test.1814.love:9443` 最终验证：
+
+| 请求 | 结果 |
+|---|---|
+| 车务账号登录 | HTTP 200 |
+| `GET /admin/fleet/board/summary` | HTTP 200，状态码/文案/数量由后端返回 |
+| `GET /admin/fleet/board/orders?status=assigned&orderNo=...` | HTTP 200，精准返回 1 条 |
+| `GET /admin/fleet/board/orders/{orderId}` | HTTP 200，返回逐日行程、车型诉求、司机确认凭证及当前派单 |
+| `GET /admin/fleet/board/orders/{orderId}/timeline` | HTTP 200，返回完整操作时间线 |
+
+HOLD 模式真实终态校验：
+
+```json
+{
+  "requirementStatus": "DONE",
+  "vehicleControlStatus": "DONE",
+  "hasFleetAssigned": true,
+  "snapshotCount": 1,
+  "activeDailySlices": 6,
+  "activeDailySliceStatus": "assigned",
+  "driverConfirmationEvidenceCount": 1,
+  "completionOutboxStatus": "SUCCESS"
+}
+```
+
+取消订单迟到回调保持 `hasFleetAssigned=false`、快照数为 0、有效逐日派单数为 0；相同拓扑摘要在互斥窗口外重放返回 HTTP 200 且不重复推进待办、流水或订单状态，窗口内并发重复返回 `100502` 且无重复副作用。
+
+### 9.4 OpenAPI 与日志
+
+- Order-v3 OpenAPI 已公开内部最终回调及 `VehicleAssignmentCallbackReqVO` 的 6 个必填字段。
+- Fleet OpenAPI 已公开创建、预检、取消、改派、最终确认、司机确认/拒绝、提前结束、需求驳回与撤销取消等 10 个生命周期接口。
+- 2026-07-16 22:22 后四个目标实例均无 `ERROR` 级日志；目标订单与需求在四实例中均为 0 条 WARN/ERROR，日志可见司机确认、最终回调成功和 Order-v3 快照刷新。
+- 测试环境另有保险 PDF 缺失与历史脏订单降级 WARN，未关联本次目标订单，不作为本契约成功响应的一部分。
+
+Issue #4935 的代码、部署、网关 API、MySQL 终态和服务日志证据均已补齐，可按后端验收清单关单。
 
 ## 十、相关文档