---
schema: "hl-changelog/v2"
ticket: "5226"
title: "用车需求提交后实时刷新派单看板"
consumer: "admin"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "hl-ui-codex"
frontend_ref: "mmg/hl-ui@716d5e81311628f42d2ac1945089755b4264d47e"
target_release: "hl-ui/v2.1"
verified_at: ""
status_note: "2026-07-24T17:12:49+08:00 后端已部署且网关 SSE 契约已验证；管理台仍待消费 fleet-board-changed，前端状态保持 pending。"
updated_at: "2026-07-24T09:29:05.220Z"
base: "origin/dev-v3"
generated: "2026-07-24T16:41:16+08:00"
---

# 用车需求提交后实时刷新派单看板

> 自动草稿不会代表已验证；完成实际测试后再更新 frontmatter。

## 关联

- Issue: [wx/HL#5226](https://git.1814.love:8443/wx/HL/issues/5226)
- PR: [wx/HL#5232](https://git.1814.love:8443/wx/HL/pulls/5232)

## 变更接口

| 方法 | 路径 | 来源 |
|---|---|---|
| `POST` | `/internal/notification/fleet-board/broadcast` | Fleet 事务提交后调用 user-service 的内部广播端点 |
| `GET` | `/ws/admin-msg/stream` | 既有 SSE 流新增命名事件 `fleet-board-changed` |

## 契约影响文件

- `hl-fleet-service/src/main/java/com/hulalv/fleet/board/port/vo/FleetBoardChangedFeignReqVO.java`
- `hl-user-service/src/main/java/com/hulalv/user/notification/sse/vo/FleetBoardChangedReqVO.java`

## 前端/调用方动作

管理台继续复用现有 `/ws/admin-msg/stream` 连接，不新建第二条 EventSource。全局 SSE
组合式函数新增命名事件监听：

```js
eventSource.addEventListener('fleet-board-changed', onFleetBoardChanged)
```

事件数据示例：

```json
{
  "type": "FLEET_BOARD",
  "targetRoleKey": "VEHICLE_MANAGER",
  "orderId": "2079000000000000001",
  "requirementId": "2079000000000000101"
}
```

- 该事件是“看板数据已失效”信令，不承载订单行数据；收到后重新查询当前看板。
- 只刷新 `getBoardSummary` 和当前页 `getBoardOrders`，保留状态、日期、车型、关键词、页码和展开状态。
- 事件可能短时间连续到达，必须合并刷新并避免并发请求覆盖；不得每个事件各发一组请求。
- `orderId/requirementId` 只用于定位和诊断，按 String 保存，不能转为 Number。
- 页面不可见时先标记 dirty，恢复可见或 SSE 重连成功后刷新一次。
- 刷新失败保留现有列表，不清空页面；沿用现有错误提示与下一次事件重试。

### 展示矩阵

| 场景 | 汇总卡 | 看板列表 | 筛选/页码 | 请求策略 |
| --- | --- | --- | --- | --- |
| 页面可见，收到一次事件 | 重新查询 | 重新查询当前页 | 完整保留 | 合并为一轮刷新 |
| 短时间收到多次事件 | 最终值更新一次 | 最终值更新一次 | 完整保留 | debounce/coalesce，禁止并发覆盖 |
| 刷新进行中又收到事件 | 当前请求完成后再补一次 | 同左 | 完整保留 | 最多保留一个 pending refresh |
| 页面隐藏时收到事件 | 暂不请求 | 暂不请求 | 完整保留 | 标记 dirty，恢复可见后刷新一次 |
| SSE 重连成功 | 重新查询 | 重新查询当前页 | 完整保留 | 主动补偿一次，覆盖断线窗口 |
| 查询失败 | 保留旧值 | 保留旧列表 | 完整保留 | 展示既有错误提示，等待重试 |
| 非车务当前角色 | 不收到事件 | 不刷新 | 不变 | 后端仅投递 `VEHICLE_MANAGER` |

## 验证证据

- Fleet 定向测试：254 项通过，0 failure / 0 error。
- User 定向测试：40 项通过，0 failure / 0 error。
- `mvn -f hl-fleet-service/pom.xml spotless:check` 通过。
- `mvn -pl hl-fleet-service -am verify` 通过。
- `mvn -pl hl-user-service -am verify` 通过。
- 事务语义：只有用车需求展开事务 `AFTER_COMMIT` 才广播；回滚不发事件，广播失败不阻断主流程。
- 路由语义：事件名固定为 `fleet-board-changed`，仅投递当前角色为 `VEHICLE_MANAGER` 的连接。
- 测试环境部署：`hl-user-service` 任务 `6d567b7f`、`hl-fleet-service` 任务 `561b1051`
  均成功，两个滚动实例分别恢复健康。
- 网关/SSE：`GET /ws/admin-msg/stream` 返回 HTTP 200 和 `text/event-stream`；
  `8081/8181` 两实例内部广播均返回业务码 200，未带内部令牌返回 403。
- 实际事件：当前角色为 `VEHICLE_MANAGER` 的连接收到 `fleet-board-changed`，
  `type=FLEET_BOARD`，`targetRoleKey=VEHICLE_MANAGER`，订单与需求 ID 按 String 到达。
- 脱敏证据：`5226-gateway-sse.json`，SHA-256
  `00f3a2d441e9993ea7df706924fa792497170f1d4efee7ca190f741ca5844936`。
- 兼容性结论：既有 SSE 事件和看板查询接口不变；未消费新命名事件的前端保持原行为。