From 70b18d43f86661cf3e15c8b315cc6e862e5471de Mon Sep 17 00:00:00 2001 From: wx Date: Tue, 28 Jul 2026 21:49:17 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BA=A4=E6=8E=A5=20Fleet=20=E5=89=8D?= =?UTF-8?q?=E7=AB=AF=20D-01/D-02=20P2=20=E6=A0=B9=E5=9B=A0=20(#5337=20#533?= =?UTF-8?q?8)=20(#63)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit frontend-only changelog handoff；D-03 continues under #4760. --- ...t日期清单陈旧失败隔离-修改接口-管理后台.md | 73 ++++++++++++++++++ ...订单分窗状态集合守恒-修改接口-管理后台.md | 76 +++++++++++++++++++ 2 files changed, 149 insertions(+) create mode 100644 changelogs-v2/2026-07/28_5337_Fleet日期清单陈旧失败隔离-修改接口-管理后台.md create mode 100644 changelogs-v2/2026-07/28_5338_Fleet按订单分窗状态集合守恒-修改接口-管理后台.md diff --git a/changelogs-v2/2026-07/28_5337_Fleet日期清单陈旧失败隔离-修改接口-管理后台.md b/changelogs-v2/2026-07/28_5337_Fleet日期清单陈旧失败隔离-修改接口-管理后台.md new file mode 100644 index 0000000..3ad585b --- /dev/null +++ b/changelogs-v2/2026-07/28_5337_Fleet日期清单陈旧失败隔离-修改接口-管理后台.md @@ -0,0 +1,73 @@ +--- +schema: "hl-changelog/v2" +ticket: "5337" +title: "Fleet 日期清单隔离陈旧失败与当前弹窗状态" +consumer: "admin" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "frontend-only：复用 #4760 已部署 day-orders 契约，无新增后端发布；本次只交接前端异步 identity 修复，fresh gateway probe 不适用" +updated_at: "2026-07-28" +base: "dev-v3" +--- + +# Fleet：日期清单隔离陈旧失败与当前弹窗状态 + +> **Tracking Issue**：[wx/HL#5337](https://git.1814.love:8443/wx/HL/issues/5337) +> **责任端**：`mmg/hl-ui` Fleet Matrix 前端 +> **前端基线**：`v2.1@18daf2a03e9946c46d7bf31c7577adcb05d3c168` +> **性质**：frontend-only；不是后端缺陷，不新增后端接口、字段、错误码或部署 + +## 问题与根因 + +日期弹窗快速从 A 日期切到 B 日期时，`fetchDayOrders` 的 `dayRequestSeq` 只在 Promise 成功后检查。A 旧请求若在 B 新请求成功后才失败，会在 `await` 处直接 reject，随后 A 对应的 `openDayList` catch 无 `requestSeq + date` 身份校验并无条件清空共享 `dayOrders`。 + +结果是标题仍属于 B，但 rows 被旧 A 清空，页面显示 B 日期假空数据，统一 error 也可能属于旧 A。旧 success 已有序号保护；缺口仅在 failure/error/clear/loading/title 的共同身份约束。 + +## 变更接口 + +### `GET /admin/fleet/matrix/day-orders` + +接口契约保持不变，继续沿用 `#4760`： + +```http +GET /admin/fleet/matrix/day-orders?date=YYYY-MM-DD +``` + +- 请求参数、响应结构、空值和错误码均不变。 +- `backend_status=deployed` 仅表示 `#4760` 的既有接口契约已部署，不表示 #5337 有后端代码发布。 +- `gateway_status=not_required`：根因是前端 Promise 乱序与共享状态写入，接口 fresh probe 不能证明竞态修复。 + +## 前端必须调整 + +1. 为每次日期请求建立稳定的 `requestSeq + date` identity。 +2. 只有当前 identity 可以写 rows、清空 rows、更新 error/loading 或改变弹窗状态。 +3. 陈旧 success 与陈旧 failure 都必须 no-op，不能依赖只有成功路径执行的序号检查。 +4. title、rows、error、loading 必须绑定同一 identity；禁止新日期标题搭配旧错误或假空数据。 + +## 前端验收 + +- [ ] deferred 测试覆盖 A旧 success 晚于B新 success、A旧 failure 晚于B新 success、A旧 success 晚于B新 failure、当前请求 failure 四类交错。 +- [ ] A旧 failure 晚于B新 success 时，B rows、B title 与 B error state 保持不变，旧 A 完全 no-op。 +- [ ] 只有当前 `requestSeq + date` identity 可以写 rows、clear、error 与 loading。 +- [ ] 真实 Matrix 页面挂载测试快速点击两个日期列头并控制 Promise 顺序，断言最终标题、行数、空态和错误均属于最新日期。 +- [ ] 不改变 `/day-orders` API 字段、后端行为或公共契约。 + +## 验证证据 + +- 权威审计：`C:/Users/Administrator/AppData/Local/Temp/fleet-frontend-current-remote-audit-task_e6c54bb3a8b9.md` +- 审计 SHA-256：`ab3ceafdf3a433ea7d0a99d1f8962839ed49d2819d4eab1d6de13c85e891d882` +- 当前前端远端源码：`mmg/hl-ui v2.1@18daf2a03e9946c46d7bf31c7577adcb05d3c168` +- 源码证据：`useFleetMatrixData.js:553-559`、`matrix/index.vue:902-908`、`DayListModal.vue:10-16,120-124`。 +- 审计已确认当前测试没有 day-orders deferred race 页面挂载覆盖；本条目初始状态为 `pending`，不宣称前端已修复或测试已通过。 + +## 关联与去重 + +- `#4760` 是 day-orders 既有接口和 Fleet Matrix 真实数据源责任，本条目不修改其历史文件。 +- D-03 的 `todayDay` 未消费仍归 `#4760` existing-follow-up，不在 #5337 创建重复验收。 +- D-02 byOrder 分窗状态守恒由独立 `#5338` 跟踪。 diff --git a/changelogs-v2/2026-07/28_5338_Fleet按订单分窗状态集合守恒-修改接口-管理后台.md b/changelogs-v2/2026-07/28_5338_Fleet按订单分窗状态集合守恒-修改接口-管理后台.md new file mode 100644 index 0000000..8ba73b9 --- /dev/null +++ b/changelogs-v2/2026-07/28_5338_Fleet按订单分窗状态集合守恒-修改接口-管理后台.md @@ -0,0 +1,76 @@ +--- +schema: "hl-changelog/v2" +ticket: "5338" +title: "Fleet 按订单分窗保持路由状态集合守恒" +consumer: "admin" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "frontend-only：复用 #4760 grid/unassigned 与 #5301 coarse status 已部署契约，无新增后端发布；本次只交接前端最终集合过滤，fresh gateway probe 不适用" +updated_at: "2026-07-28" +base: "dev-v3" +--- + +# Fleet：按订单分窗保持路由状态集合守恒 + +> **Tracking Issue**：[wx/HL#5338](https://git.1814.love:8443/wx/HL/issues/5338) +> **责任端**：`mmg/hl-ui` Fleet Matrix 分窗前端 +> **前端基线**：`v2.1@18daf2a03e9946c46d7bf31c7577adcb05d3c168` +> **性质**：frontend-only；不是后端缺陷，不新增后端接口、字段、错误码或部署 + +## 问题与根因 + +`matrix-solo?solo=byOrder&status=assigned` 已把 route status 传给 grid，且 coarse assigned 正确映射为 `holding/holding_urgent/assigned`。但共享 composable 仍无条件请求并合并不带 status 的 `unassigned-orders`，`SoloByOrderView.visibleOrders` 只排除 canceled，未按 route status 最终收口。 + +因此 assigned 分窗会混入无车的 `unassigned/unassigned_urgent` rows。主矩阵已使用共享 `matchesMatrixStatusFilter` 做最终过滤，缺口只在 byOrder 分窗没有复用同一保护；不得归因于后端 grid 或 coarse status 契约。 + +## 变更接口 + +### `GET /admin/fleet/matrix/grid` + +### `GET /admin/fleet/matrix/unassigned-orders` + +接口契约保持不变，继续沿用 `#4760/#5301`： + +- coarse `assigned` = `holding + holding_urgent + assigned`。 +- coarse `unassigned` = `unassigned + unassigned_urgent`。 +- 只有 route `all` 的最终显示集合可以同时包含已派与未派两侧。 +- `backend_status=deployed` 仅表示上述既有接口契约已部署，不表示 #5338 有后端代码发布。 +- `gateway_status=not_required`：根因是前端将两个成功响应合并后缺少 view-level route filter，fresh API probe 不能证明页面集合守恒。 + +## 前端必须调整 + +1. `SoloByOrderView` 最终展示复用共享 `matchesMatrixStatusFilter`，不维护第二套状态映射。 +2. route query、grid/unassigned 请求、visibleOrders 与跨窗口 drag source 使用同一筛选 identity。 +3. `assigned` 只显示 `holding/holding_urgent/assigned`，并排除全部无车未派 rows。 +4. `unassigned` 只显示 `unassigned/unassigned_urgent`，并排除已绑车 rows；`all` 才合并两侧。 +5. 最终过滤后的集合同时用于渲染与拖拽，禁止拖拽源绕过 visibleOrders。 + +## 前端验收 + +- [ ] 组件挂载测试覆盖 route `all/unassigned/assigned`，显示集合与主矩阵同筛选口径守恒。 +- [ ] `assigned` 样本同时包含 `holding/holding_urgent/assigned`，并排除 `unassigned/unassigned_urgent` 无车 rows。 +- [ ] `unassigned` 只含未派 rows 并排除所有已绑车 rows；只有 `all` 合并两侧。 +- [ ] 最终展示与 drag source 都复用 `matchesMatrixStatusFilter` 的同一过滤结果。 +- [ ] year/month/fleetTeamIds/typeKeys/status 从 route、请求到 visible/drag 集合保持同一身份。 +- [ ] 不改变 grid、unassigned-orders、statuses[] 或 coarse status 后端契约。 + +## 验证证据 + +- 权威审计：`C:/Users/Administrator/AppData/Local/Temp/fleet-frontend-current-remote-audit-task_e6c54bb3a8b9.md` +- 审计 SHA-256：`ab3ceafdf3a433ea7d0a99d1f8962839ed49d2819d4eab1d6de13c85e891d882` +- 当前前端远端源码：`mmg/hl-ui v2.1@18daf2a03e9946c46d7bf31c7577adcb05d3c168` +- 源码证据：`matrix-status.js:27-36,49-66`、`useFleetMatrixData.js:350-364,505-525`、`SoloByOrderView.vue:52-82,101-105`。 +- 现有 composable 测试确认 `allOrders` 即使在 assigned exact 下仍包含 unassigned row，但当前远端没有 SoloByOrder route 挂载测试；本条目初始状态为 `pending`，不宣称前端已修复或测试已通过。 + +## 关联与去重 + +- `#4760` 规定 byOrder 使用 grid + unassigned-orders 并携带 route status；本条目补充最终显示集合守恒，不修改其历史文件。 +- `#5301` 规定 coarse assigned 与精确 statuses[]；本条目不改变该契约。 +- D-03 的 `todayDay` 未消费仍归 `#4760` existing-follow-up，不在 #5338 创建重复验收。 +- D-01 day-orders 陈旧失败隔离由独立 `#5337` 跟踪。