docs(fleet): notify view detail processing contract

2026-07-06 18:10:43 +08:00 · 2026-07-06 18:10:43 +08:00 · 93b4742dd7
--- a/changelogs-v2/2026-07/31_4787_车务查看订单详情即进入配车中-管理后台.md
+++ b/changelogs-v2/2026-07/31_4787_车务查看订单详情即进入配车中-管理后台.md
@ -0,0 +1,166 @@
+# 【前端对接·管理后台】车务查看订单详情即进入配车中
+
+> **Issue**: [wx/HL#4787](https://git.1814.love:8443/wx/HL/issues/4787)  
+> **服务**: hl-fleet-service + hl-order-service-v3  
+> **日期**: 2026-07-06  
+> **影响范围**: 车务派单看板 / 矩阵派单 / 订单详情状态联动  
+> **前端代码**: 不需要直接修改，本通知用于纠正状态口径和测试断言
+
+---
+
+## 1. 结论
+
+车务没有房务式“抢单池”。车务用户只要打开订单详情，就代表车务已经接手该订单的当前 active 用车需求，后端会把用车需求推进到 `PROCESSING`（配车中）。
+
+触发接口只有现有详情接口：
+
+```http
+GET /admin/fleet/board/orders/{orderId}
+```
+
+前端不需要新增调用，不要调用旧 order-v3 抢单接口，也不要等“展开建单”后再认为订单进入配车中。
+
+---
+
+## 2. 行为变化
+
+| 场景 | 后端行为 | 前端处理 |
+|------|----------|----------|
+| 当前 active 用车需求是 `PENDING` | 打开详情后同步改为 `PROCESSING`，并同步 `order_main.vehicle_control_status=PROCESSING` | 继续打开详情即可；后续订单状态从后端刷新 |
+| 当前 active 用车需求已是 `PROCESSING` | 幂等成功，不重复制造副作用 | 不需要特殊处理 |
+| 当前 active 用车需求已是 `DONE` | 不回退到 `PROCESSING` | 不要把已派完订单展示回配车中 |
+| 当前 active 用车需求是 `REJECTED_TO_CONSULTANT` / `REJECTED_TO_ADMIN` / `PENDING_REVIEW` | 不允许被详情查看拉回 `PROCESSING` | 展示后端返回状态，不要本地覆盖 |
+| order-v3 详情降级或无当前需求 | 详情接口尽量返回可展示数据，状态回写失败只告警，不阻断详情 | 前端仍按 `relatedDetailReady` 和空字段兜底展示 |
+
+---
+
+## 3. 请求示例
+
+```http
+GET /admin/fleet/board/orders/2070756230887890945
+Authorization: Bearer <admin-token>
+```
+
+路径参数：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `orderId` | string/long | 是 | 订单 ID。前端按字符串保存，避免 JS 长整型精度问题 |
+
+无 query 参数，无 request body。
+
+---
+
+## 4. 响应示例
+
+响应结构不新增字段，本次变化是状态副作用。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "id": "2070756230887890945",
+    "orderNo": "HL20260702092466935",
+    "customerName": "张伟",
+    "productName": "测试核心产品-单档-固定订金",
+    "headcount": 2,
+    "startDate": "2026-05-09",
+    "endDate": "2026-05-11",
+    "vehicleTypeSummary": "SUV×1",
+    "plannerNote": "[单1:流程-全流程-目标态:已完成-验:全链路E2E,mock合同保险,BUG1配车null司机] 需求床房，方便带孩子入住",
+    "transport": {
+      "arrive": null,
+      "depart": null,
+      "batches": []
+    },
+    "currentAssignment": null,
+    "relatedDetailReady": true
+  }
+}
+```
+
+字段说明：
+
+| 字段 | 说明 |
+|------|------|
+| `currentAssignment=null` | 当前没有已派/占位派单，不代表不能进入配车中。查看详情本身已经触发车务接手 |
+| `transport.arrive/depart=null` | 大交通缺失时真实返回空槽，不要 mock 时间 |
+| `transport.batches=[]` | 源订单没有大交通批次，前端按空列表展示 |
+| `relatedDetailReady=false` | order-v3 上下文拉取降级，前端可展示本地快照和空字段 |
+
+---
+
+## 5. 状态副作用示例
+
+调用详情前：
+
+```json
+{
+  "orderId": "2070756230887890945",
+  "requirementId": "2070756234515968001",
+  "order_vehicle_requirement.status": "PENDING",
+  "order_main.vehicle_control_status": "PENDING"
+}
+```
+
+调用详情后：
+
+```json
+{
+  "orderId": "2070756230887890945",
+  "requirementId": "2070756234515968001",
+  "order_vehicle_requirement.status": "PROCESSING",
+  "order_main.vehicle_control_status": "PROCESSING"
+}
+```
+
+已完成/驳回态不会回退：
+
+```json
+{
+  "before": "DONE",
+  "after": "DONE",
+  "reason": "已完成派单不能被迟到的详情查看拉回配车中"
+}
+```
+
+```json
+{
+  "before": "REJECTED_TO_CONSULTANT",
+  "after": "REJECTED_TO_CONSULTANT",
+  "reason": "车务已驳回给定制师，详情查看不能覆盖驳回态"
+}
+```
+
+---
+
+## 6. 前端验收点
+
+1. 从派单看板或矩阵打开订单详情后，订单侧车务状态应刷新为配车中。
+2. 不要在前端模拟 `PROCESSING`；刷新后以接口返回/订单详情真实状态为准。
+3. 不要调用房务抢单接口或旧 order-v3 车控抢单接口。
+4. 已派完订单再次打开详情，不能在 UI 上被改回“配车中”。
+5. 驳回给定制师/驳回给车务管理员/待审核的用车需求，不能因为打开详情被前端本地覆盖为“配车中”。
+6. 大交通缺失仍然是合法数据：`arrive=null`、`depart=null`、`batches=[]` 时按缺失展示，不要 mock。
+
+---
+
+## 7. 后端验证口径
+
+本地已覆盖：
+
+```bash
+mvn -pl hl-fleet-service -am "-Dtest=BoardOrderServiceTest,AssignmentServiceTest,AssignmentOccupancyListenerTest" -DfailIfNoTests=false -DfailIfNoSpecifiedTests=false test
+mvn -pl hl-order-service-v3 -am "-Dtest=RequirementServiceVehicleStatusTest" -DfailIfNoTests=false -DfailIfNoSpecifiedTests=false test
+mvn -pl hl-fleet-service spotless:check
+git diff --check
+```
+
+待 PR 合并并部署测试服后，会继续用真实车务账号验证：
+
+- `GET /admin/fleet/board/orders/{orderId}`：`PENDING -> PROCESSING`
+- 重复打开详情：`PROCESSING -> PROCESSING`
+- DONE/驳回态订单：不回退
+- 订单主表 `vehicle_control_status` 与当前 active 用车需求状态同步