WuKongIM Web 管理台集群轻量页面改版实战:以 topology、channels、diagnostics 三页面为例

原创2026-10-15 18:37:461,611 阅读
文章标签:即时通讯后端

WuKongIM Web 管理台集群轻量页面改版实战:以 topology、channels、diagnostics 三页面为例

本文基于仓库内实施计划文档 docs/superpowers/plans/2026-07-08-web-cluster-light-pages-redesign.md 展开,系统讲解 WuKongIM Web 管理台如何在不改动后端 API、路由定义、鉴权规则与 i18n 语义的前提下,将 /cluster/topology、/cluster/channels、/cluster/diagnostics 三个页面收敛到统一的编辑器控制台视觉语言。读者将掌握一套「先写失败测试、再页面局部重构、最后构建卫生收尾」的 TDD 页面改版流程,并能在当前仓库中直接对照源码与测试验证每一条断言。

WuKongIM 的 Web 管理台(web/ 目录)基于 Vite + React 19 + TypeScript + Tailwind CSS v4 + Vitest + Testing Library + Bun 构建,其集群运维页面经历了多轮视觉语言收敛。本文对应的计划文档记录了一次「轻量页面改版」(light pages redesign)的完整实施步骤:让三个集群子页面在保持数据流与路由行为完全不变的前提下,复用现有 PageHeader、SectionCard、PageTabs、ResourceState 等设计基元,以最小改动贴近新视觉语言。当前仓库中 channels 与 diagnostics 两个页面的改版已经落地,topology 页面则因后续演进被移除并由相邻页面承接信息——这些演进结果都能在源码与测试中找到明确证据。

一、改版目标与硬性约束

计划文档开头即明确了本次改版的边界,这是理解后续每个改动步骤的前提:

  • 目标:把 /cluster/topology、/cluster/channels、/cluster/diagnostics 三个页面带入已批准的编辑器控制台视觉语言,不改变数据流,也不改变已退役路由(retired-route)的行为。
  • 架构原则:所有改动页面局部化(page-local),复用既有 PageHeader、SectionCard、PageTabs、ResourceState、表格与 i18n 基元;仅在支撑视觉契约测试(visual contract tests)的地方增加稳定的 DOM 标记与可访问的表格标签;拓扑加载/过滤、集群频道仅列表行为、诊断仅追踪归一化行为均保持不变。
  • 明确禁止修改:后端 manager API 代码、路由定义、鉴权规则、i18n 消息文件、dashboard 页面,以及 /cluster/nodes、/cluster/slots、/cluster/monitor 三个相邻页面。

这些约束的落地情况可以直接在仓库中验证:i18n 词条中 channelCluster.title("Channel Cluster" / "频道集群")与 diagnostics.tabs.trace("Tracing" / "追踪")等语义均未被改版破坏(见 web/src/i18n/messages/en.ts 与 web/src/i18n/messages/zh-CN.ts),后端 API 契约保持原样。

二、改版所依赖的通用设计基元

计划文档要求"复用现有基元",这些基元在当前仓库中均有独立实现,改版只在其上层做组合:

  • PageHeader:页面级标题区,负责 eyebrow、标题与描述,cluster/channels 与 cluster/diagnostics 两个页面都通过它渲染 CLUSTER / CHANNELS、CLUSTER / DIAGNOSTICS 面包屑标签。
  • PageTabs:role="tablist" 的标签条组件,通过 aria-selected 标记当前激活项,激活态使用 --status-healthy 主题色。诊断页的 Tracing 标签即由它渲染。
  • SectionCard:border border-border bg-card shadow-none 的通用区块卡片,内部自带 CardHeader(等宽字体、大写标题)与 CardContent。
  • ResourceState:加载中/错误/空态的统一呈现组件,频道列表面板与诊断追踪面板都依赖它处理加载与异常。
  • PageContainer(web/src/components/shell/page-container.tsx):页面最外层容器。

理解这些基元后,本次改版的三个任务本质上都是用一层"具名表面(named surface)"包装既有内容,并微调圆角与边框层级,因此风险极低、可测试性极强。

三、Task 1:Topology 操作面(compact strip + 具名表面)

计划文档的 Task 1 针对 /cluster/topology 页面,目标是三件事:把摘要卡片改成紧凑条带(compact strip)、给节点网格与槽位表格加上具名表面、收紧节点卡片圆角。

3.1 先写失败测试

第一步是在 web/src/pages/topology/page.test.tsx 中扩展既有测试 renders topology summary, nodes, and slot matrix。测试用 screen.getByTestId("topology-summary-strip") 定位摘要条带,用 closest("[data-topology-surface='nodes']") 与 closest("[data-topology-surface='slot-placement']") 定位两个具名表面,并通过 getByRole("table", { name: "Slot Placement" }) 校验表格的可访问名称:

const summaryStrip = screen.getByTestId("topology-summary-strip")
expect(summaryStrip).toHaveClass("grid", "overflow-hidden", "rounded-md", "border", "border-border", "bg-card")
expect(summaryStrip.querySelectorAll("[data-topology-summary-cell]")).toHaveLength(4)
expect(summaryStrip.querySelector("[data-topology-summary-cell]")).not.toHaveClass("rounded-lg")

const nodeSurface = screen.getByText("wk-node-1").closest("[data-topology-surface='nodes']")
expect(nodeSurface).toHaveClass("grid", "gap-3", "md:grid-cols-2", "xl:grid-cols-3")

const nodeCard = screen.getByText("wk-node-1").closest("article")
expect(nodeCard).toHaveClass("rounded-md", "border", "border-border", "bg-background")

const slotTable = screen.getByRole("table", { name: "Slot Placement" })
const slotSurface = slotTable.closest("[data-topology-surface='slot-placement']")
expect(slotSurface).toHaveClass("overflow-x-auto", "rounded-md", "border", "border-border")
expect(slotTable).toHaveClass("w-full", "border-collapse", "text-sm")
expect(within(slotTable).getByText("Slot 1")).toBeInTheDocument()

同时保留全部行为断言——Controller leader: 1、Nodes: 2、Slots: 3、Slot anomalies: 2、wk-node-1、wk-node-2、Preferred leader 1、quorum lost 都必须仍然出现。行为断言与视觉断言并存,正是这类改版测试的精髓:视觉变了,语义与数据不变。随后运行聚焦测试,预期因新标记不存在而 FAIL。

3.2 摘要卡片 → 紧凑条带

原实现是四个独立圆角卡片(grid gap-3 md:grid-cols-4 + 每项 rounded-lg border bg-muted/30 p-3)。计划文档将其替换为单一条带容器:

<div
  className="grid overflow-hidden rounded-md border border-border bg-card md:grid-cols-4"
  data-testid="topology-summary-strip"
>
  <div className="border-b border-border px-3 py-3 text-sm font-semibold text-foreground last:border-b-0 md:border-r md:border-b-0 md:last:border-r-0" data-topology-summary-cell="">
    {controllerLeaderID > 0
      ? intl.formatMessage({ id: "topology.controllerLeader" }, { id: controllerLeaderID })
      : intl.formatMessage({ id: "topology.controllerLeader.empty" })}
  </div>
  {/* nodesValue / slotsValue / anomaliesValue 三个单元格结构相同 */}
</div>

注意两个细节:overflow-hidden 让条带内部单元格的圆角被裁剪为整体圆角;md:border-r + md:last:border-r-0 负责桌面端四列分隔线,border-b + last:border-b-0 负责移动端堆叠时的分隔线。展示值本身(topology.controllerLeader、topology.nodesValue、topology.slotsValue、topology.anomaliesValue)完全不变。

3.3 具名节点表面与圆角收紧

节点网格容器从 grid gap-3 md:grid-cols-2 xl:grid-cols-3 升级为带 data-topology-surface="nodes" 的具名表面,节点卡片 article 的圆角从 rounded-lg 收紧为 rounded-md,以匹配条带与表格的视觉层级:

<div className="grid gap-3 md:grid-cols-2 xl:grid-cols-3" data-topology-surface="nodes">
  <article className="rounded-md border border-border bg-background p-4" key={node.node_id}>

计划文档明确要求:不改节点过滤器、节点列表映射、状态徽章、local/controller 徽章、槽位摘要与运行时摘要。

3.4 具名槽位表格表面与可访问名称

表格外层从 overflow-x-auto rounded-lg border 变为带 data-topology-surface="slot-placement" 的表面,同时给 <table> 加上 aria-label(取自 i18n 词条 topology.slotPlacement.title)与 text-sm:

<div
  className="overflow-x-auto rounded-md border border-border"
  data-topology-surface="slot-placement"
>
  <table
    aria-label={intl.formatMessage({ id: "topology.slotPlacement.title" })}
    className="w-full border-collapse text-sm"
  >

filteredSlots、过滤计数文本、表头、行值与空槽位渲染一律不动。

3.5 现状核对:topology 页面在主线上的去处

需要如实说明的是:在当前仓库主线中,topology 页面已被移除——web/src/pages 下已不存在 topology/ 目录,且路由测试明确锁定了这一行为(web/src/app/router.test.tsx):

test("does not register the removed topology page or legacy alias", () => {
  const registeredPaths = appRoute?.children?.map((route) => route.path)
  expect(registeredPaths).not.toContain("cluster/topology")
  expect(registeredPaths).not.toContain("topology")
})

同时,集群操作路由只保留 /cluster/nodes、/cluster/slots、/cluster/monitor、/cluster/channels、/cluster/diagnostics 等页面(见 web/src/app/router.tsx)。也就是说,计划文档中的 Task 1 记录的是该页面在改版方案中的设计意图与具体改法;在后续演进中,拓扑信息由节点页与槽位页承接,路由层与测试层则彻底封存了 topology 入口。这也从侧面说明:本文档所体现的"具名表面 + 视觉契约测试"方法论,最终以 channels 与 diagnostics 两个页面完整落地。

四、Task 2:Cluster Channels 入口面(已落地)

/cluster/channels 页面的改版是三个任务中最"轻"的一个:只给既有列表面板包一层中性具名表面。当前仓库 web/src/pages/cluster/channels/page.tsx 已包含最终实现:

<PageContainer>
  <PageHeader
    eyebrow={intl.formatMessage({ id: "nav.path.cluster.channels" })}
    title={intl.formatMessage({ id: "channelCluster.title" })}
    description={intl.formatMessage({ id: "channelCluster.description" })}
  />
  <div className="space-y-4" data-cluster-channels-surface="list">
    <ChannelClusterListPanel messagesHref="/business/messages" />
  </div>
</PageContainer>

4.1 测试如何锁定这次改版

测试 web/src/pages/cluster/channels/page.test.tsx 中的 defaults to the channel cluster list without overview or unhealthy tabs 既校验了新表面,又完整保留了行为断言:

expect(screen.queryByRole("tab", { name: "Overview" })).not.toBeInTheDocument()
expect(screen.queryByRole("tab", { name: "Unhealthy" })).not.toBeInTheDocument()
expect(screen.queryByRole("tab", { name: "List" })).not.toBeInTheDocument()
expect(await screen.findByText("alpha")).toBeInTheDocument()
const listSurface = screen.getByText("alpha").closest("[data-cluster-channels-surface='list']")
expect(listSurface).toHaveClass("space-y-4")
expect(within(listSurface as HTMLElement).getByText("Channel ID")).toBeInTheDocument()
expect(getChannelRuntimeMetaMock).toHaveBeenCalledWith({ nodeId: 1, limit: 50, includeMaxMessageSeq: true })
expect(getBusinessChannelsMock).not.toHaveBeenCalled()
expect(getChannelClusterSummaryMock).not.toHaveBeenCalled()
expect(getChannelClusterUnhealthyMock).not.toHaveBeenCalled()

这段断言值得拆解三层含义:

  1. 视觉契约:列表内容被包进 space-y-4 的具名表面;
  2. 退役行为:Overview / Unhealthy / List 三个旧标签必须不存在——频道页退化为纯列表页;
  3. 数据流契约:只调用 getChannelRuntimeMeta(nodeId: 1, limit: 50, includeMaxMessageSeq: true),业务频道、集群摘要、不健康频道三个 API 一律不调用。

另有 keeps legacy list tab URLs on the list page 测试覆盖 ?tab=list 历史 URL 兼容,确保旧入口进入后仍是纯列表视图。

4.2 面板自身即容器,外层不重复加边框

计划文档特别提醒:不要在这层包装上新增边框——ChannelClusterListPanel 已经自带内部圆角卡片与表格外壳。从源码看(web/src/pages/channels/page.tsx),该面板负责节点加载(getNodes)、按节点拉取运行时元数据(getChannelRuntimeMeta,单页 50 条、含 includeMaxMessageSeq)、关键字过滤、分页追加与错误映射(403→forbidden、503→unavailable),并渲染 rounded-xl border border-border bg-card 的表格外壳。改版只是在外层加 space-y-4 统一页面间距节奏,不干预面板内部逻辑。

五、Task 3:Cluster Diagnostics 追踪面(已落地)

/cluster/diagnostics 页面的改版将"追踪"作为唯一合法标签,把标签条与 DiagnosticsTracePanel 一起包进具名追踪表面。当前仓库 web/src/pages/cluster/diagnostics/page.tsx 已包含最终实现:

const tabs = [{ id: "trace", labelMessageId: "diagnostics.tabs.trace" }] as const

function normalizeTab(value: string | null): DiagnosticsTab {
  return tabs.some((tab) => tab.id === value) ? (value as DiagnosticsTab) : "trace"
}

// ...
<div className="space-y-4" data-cluster-diagnostics-surface="trace">
  <PageTabs
    activeTab={activeTab}
    className="px-0 pt-0"
    tabs={tabs.map((tab) => ({ id: tab.id, label: intl.formatMessage({ id: tab.labelMessageId }) }))}
    onTabChange={setTab}
  />
  {activeTab === "trace" ? <DiagnosticsTracePanel /> : null}
</div>

5.1 测试如何锁定"仅追踪"

测试 web/src/pages/cluster/diagnostics/page.test.tsx 中的 defaults to the diagnostics trace tab 先断言 Tracing 标签激活,再断言四个退役标签全部不存在,最后校验追踪面板位于具名表面内:

const tracingTab = screen.getByRole("tab", { name: "Tracing" })
expect(tracingTab).toHaveAttribute("aria-selected", "true")
expect(screen.queryByRole("tab", { name: "Network" })).not.toBeInTheDocument()
expect(screen.queryByRole("tab", { name: "Control Plane Logs" })).not.toBeInTheDocument()
expect(screen.queryByRole("tab", { name: "Slot Logs" })).not.toBeInTheDocument()
expect(screen.queryByRole("tab", { name: "App Logs" })).not.toBeInTheDocument()
expect(await screen.findByText("Message Diagnostics")).toBeInTheDocument()
const traceSurface = screen.getByText("Message Diagnostics").closest("[data-cluster-diagnostics-surface='trace']")
expect(traceSurface).toHaveClass("space-y-4")
expect(within(traceSurface as HTMLElement).getByRole("tab", { name: "Tracing" })).toHaveAttribute("aria-selected", "true")
expect(within(traceSurface as HTMLElement).queryByRole("tab", { name: "Network" })).not.toBeInTheDocument()

5.2 退役标签的归一化由路由与页面双重完成

  • 页面层:normalizeTab 把任何非 trace 的 ?tab= 值(如 network、controller-logs、slot-logs、app-logs)一律归一为 "trace"。测试 normalizes retired diagnostics tabs to tracing 用 ?tab=network 进入页面,断言 Tracing 激活、Node Health Status 与 Node Process Logs 均不渲染,且 getNetworkSummaryMock、getApplicationLogSourcesMock 从未被调用——退役 API 被彻底隔离。
  • 路由层:旧入口统一重定向到追踪页,web/src/app/router.tsx 中可见 network → /cluster/diagnostics?tab=trace、controller → 带 tab=trace 的 RedirectWithSearch、slot-logs → 同样归一化到追踪页;路由测试 normalizes retired controller diagnostics route to tracing 验证 /controller?node_id=1&tab=controller-logs 最终落在 /cluster/diagnostics?node_id=1&tab=trace(web/src/app/router.test.tsx)。

计划文档要求:不得新增 network、controller-log、slot-log、app-log 面板,不得改动 tabs、normalizeTab、setTab——页面层与路由层的双重归一化保证了"诊断入口永远落在追踪视图"。

六、Task 4:聚焦验证与构建卫生

改版合入前,计划文档设计了完整的验证门禁,这套流程对任何前端页面改动都通用:

6.1 组合页面测试门

cd web && /Users/tt/.bun/bin/bun run test -- \
  src/pages/topology/page.test.tsx \
  src/pages/cluster/channels/page.test.tsx \
  src/pages/cluster/diagnostics/page.test.tsx \
  src/pages/page-shells.test.tsx

说明:/Users/tt/.bun/bin/bun 是计划文档撰写环境中的本地 Bun 路径,实际执行时请替换为当前机器的 Bun 可执行路径。

page-shells.test.tsx(web/src/pages/page-shells.test.tsx)作为路由烟测文件,不改源码,但覆盖了本次相关路由的标题、面包屑标签与中文(zh-CN)渲染:/cluster/channels 渲染 "Channel Cluster" 与 "CLUSTER / CHANNELS"、/cluster/diagnostics 渲染 "Message Diagnostics" 与 "CLUSTER / DIAGNOSTICS",并断言工作区(workspace)字样不出现。计划文档同时确认:本任务在三个阶段各只提交页面与对应测试两个文件。

6.2 类型检查与生产构建

cd web && /Users/tt/.bun/bin/bunx tsc -b   # 预期零 TypeScript 错误
cd web && /Users/tt/.bun/bin/bun run build # 预期成功;Vite chunk 体积警告在退出码 0 时可接受

对照 web/package.json,build 脚本为 tsc -b && vite build && bun run build:check,即类型检查、打包、产物校验三者串联,与计划文档的验证顺序一致。

6.3 构建产物卫生

计划文档特别处理了 web/dist/index.html 的哈希抖动(hash churn):

git diff -- web/dist/index.html

若 diff 只涉及 /assets/index-*.js、/assets/index-*.css 的哈希引用变化,则 git restore web/dist/index.html 还原该文件;仅当构建产生了真实需要评审的已入库产物变更时才保留。随后执行 git diff --check(预期无空白错误与冲突标记)与 git status --short(预期无本计划产生的未提交源码改动),并输出完成报告:

Implemented the approved cluster light pages redesign for /cluster/topology,
/cluster/channels, and /cluster/diagnostics. Focused page tests, route shell
coverage, TypeScript build, production build, and git diff check passed.
No backend API, route, auth, i18n semantic, dashboard, nodes, slots, monitor,
retired-tab, or unrelated page changes were made.

七、方法论小结:视觉契约测试的正确姿势

回顾整个改版,最值得沉淀的工程经验有三条:

  1. 具名 DOM 表面是视觉契约的锚点。data-topology-surface、data-cluster-channels-surface、data-cluster-diagnostics-surface 这类标记让测试无需依赖具体文案或嵌套层级即可定位"表面",配合 closest() 与 within() 精确限定断言范围,视觉改版因此可以被自动化测试稳定护航。
  2. 行为断言与视觉断言必须并存。每个任务的测试都同时保留"数据值仍然渲染"(如 Controller leader: 1、alpha、Message Diagnostics)、"退役 API 不被调用"(not.toHaveBeenCalled())与"退役标签/路由不存在"(queryByRole(...).not.toBeInTheDocument())三类断言,确保视觉收敛不以功能回归为代价。
  3. 页面局部化 + 构建卫生 = 低风险合入。改动全部局限在页面文件与其测试内,配合 git diff --check 与 dist 哈希抖动还原,最终合入只涉及目标页面,后端与路由零变更。

对于 WuKongIM 管理台后续的任何视觉语言迭代,channels 与 diagnostics 两个页面的落地实现(web/src/pages/cluster/channels/page.tsx、web/src/pages/cluster/diagnostics/page.tsx)及其测试,都是可直接参照的样板;topology 计划(本计划文档 Task 1)则完整保留了"先测后改、逐层收敛"的设计过程记录,供理解该页面在移除前的改版意图与演进脉络。

登录后查看全文
WuKongIM