---
schema: "hl-changelog/v2"
ticket: "5931"
title: "看板/矩阵 Map 跨层清理 + 契约强类型化（fleetCount 下线）"
consumer: "admin"
author: "wx"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: "mmg"
frontend_ref: ""
target_release: ""
verified_at: "2026-08-16"
status_note: "后端完成：PR #5984 已合并 dev-v3（617a83dcf）并部署 TEST（user-service + order-v3 + fleet 三服务按顺序发布 UP）。fleetCount 下线/强类型化零 wire 变化由 wire 级单测覆盖；跨服务 Feign unreads[] 字段逐字段一致，容错双向安全。"
updated_at: "2026-08-16"
base: "dev-v3"
generated: "2026-08-16T00:20:00+08:00"
---

# 看板/矩阵 Map 跨层清理 + 契约强类型化（#5931）

## 背景

矩阵/看板若干出参用 `Map` 跨层（违 CODE_RULES §3 VO 强制），且部分契约字段随枚举文案漂移。本次把 Map 全部强类型化，并明确若干统计口径。**矩阵 `fleetCount` 字段删除**（前端已迁 `fleetTeamCounts`）。

## 变更接口与行为变化

| 接口 | 变更 |
| --- | --- |
| `GET /admin/fleet/matrix/grid` | 删除 `fleetCount`（旧 Map）；补录 `fleetTeamCounts[]`；`statusCounts.effectiveStatusCounts` 改强类型五字段（`unassigned`/`unassigned_urgent`/`holding`/`holding_urgent`/`assigned`），**JSON 键名与历史 Map 完全一致，前端零感知** |
| `GET /admin/fleet/board/orders` | records[] 新增 `baseAssignmentStatus`（槽位落库基础态，不派生不覆写） |
| `GET /admin/fleet/board/summary` | `todayDepartCount` 口径明确为「start_date==TODAY 且代表槽位**落库** status=assigned」（陈旧定稿覆写后已派车出团不再漏计） |
| `GET /admin/fleet/dashboard/summary` | `pendingStatusCards` 固定顺序+固定中文标签（待派车/待确认），不随枚举文案漂移 |
| 看板候选游标 | 畸形游标由 500 系统异常改业务码 **605310**（请刷新后重试） |

## 前端动作

- **矩阵 `fleetCount` 已下线，勿再使用**——改用 `fleetTeamCounts`（若仍读 fleetCount 会 undefined）。
- `effectiveStatusCounts` 键名不变，零改动。
- 看板/矩阵候选操作遇 605310 提示「刷新后重试」即可。
- 其余为后端口径/健壮性修正，无前端改动。

## 内部 Feign 契约（后端三服务，前端不直连）

- `/internal/message/chat/biz-unread-batch` 出参 `unreadMap`(Map) → `unreads[]`（`{bizId, unreadCount}` 列表）。**部署顺序**：user-service 先于或同批 order-v3/fleet 发布（已按此执行）。

## 验证证据

- fleet 258 目标测试（Matrix/Board/EffectiveStatus/Dashboard 六服务）+ FleetRedLineArchTest 13 + spotless 全绿；order-v3 354 + user-service 4 全绿。
- `effectiveStatusCounts` 键名与旧 Map 一致性经 MockMvc wire 级断言；四处 ChatBizUnreadItemVO 字段逐字段比对一致。