1b0bbad5b4
一些检查失败了
changelog-filename-gate / validate (push) Failing after 1s
修改原因：hl-ui changelog loop 需要把前端消费进度回写到契约源，避免领取、实现状态与实际交付脱节。 修改内容：将 frontend_status 与已有 legacy frontend 同步为 implemented，记录负责人 hl-ui-codex，并关联 mmg/hl-ui@716d5e81311628f42d2ac1945089755b4264d47e；发布和验收字段保持不变。 实际验证：回写器已校验目标文件、状态单调性、提交范围和 Front Matter 内容，提交只包含当前 changelog。 Frontend-Status: tools/mcp-api-sync/.changelog-repo/changelogs-v2/2026-07/24_5226_用车需求提交后实时刷新派单看板-修改接口-管理后台.md
98 行
4.7 KiB
Markdown
98 行
4.7 KiB
Markdown
---
|
||
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 事件和看板查询接口不变；未消费新命名事件的前端保持原行为。
|