WuKongIM 管理端运维页面视觉重构实战:Slots / Tasks / Controller 三页面的「编辑控制台」化改造

原创2026-10-15 18:27:531,656 阅读
文章标签:即时通讯后端

WuKongIM 管理端运维页面视觉重构实战:Slots / Tasks / Controller 三页面的「编辑控制台」化改造

导读

本文以 WuKongIM 仓库内的一份完整实现计划(docs/superpowers/plans/2026-07-07-web-operations-pages-redesign.md)为主线,系统讲解如何在不改动后端行为的前提下,将管理端(web/)中 slots、tasks、controller 三个活跃运维页面收敛到已获批的「编辑控制台(editorial console)」视觉语言。读完本文,你将掌握一套可复用的前端视觉重构方法论:窄视觉契约测试先行(RED-GREEN)、页面局部表面改造、可访问性命名表格、以及 TypeScript / 生产构建的收尾验证流程,并能直接对照仓库源码理解每一处改造的落点与原理。


一、改造背景:为什么要做「编辑控制台」化

WuKongIM 管理端基于 Vite + React 19 + TypeScript + Tailwind CSS v4 构建(见 web/package.json),并配套 Vitest、Testing Library 与 Bun 作为测试工具链。随着运维页面增多,页面间出现了视觉风格漂移:部分旧页面还在使用较大圆角(rounded-xl)、独立摘要卡片等较"重"的容器,与整体偏"编辑/发布系统"的克制视觉(细边框、紧凑表面、规则分隔、等宽字体标签)不一致。

这份计划的核心目标非常明确:

将活跃的 slots、tasks、controller 三个 manager 页面,带入已获批的编辑控制台视觉语言,且不改变任何后端行为。

从仓库中的 web/DESIGN.md 可以看到该视觉语言的要点:白色画布为主、薄边框(border-border)替代阴影、紧凑圆角(rounded-lg/rounded-md)、等宽字体(font-mono)+ 大写字母间距标签(uppercase tracking-[0.14em])用于系统级标记、规则分隔列表而非堆叠卡片。本次改造正是把这些原则落到三个具体页面上。

改造遵循两条铁律:

  1. 行为不动:每个页面现有的数据加载、操作按钮、对话框、Tab、URL 行为全部保持原样;
  2. 局部优先:优先在页面内使用局部 wrapper 表达布局,避免改动共享组件——除非某个页面无法用局部方式表达已获批布局(Avoid shared component changes unless a page cannot express the approved layout locally)。

二、改造范围与边界

计划圈定了精确的文件清单,全部位于 web/src/pages 下:

文件 改造内容
web/src/pages/slots/page.test.tsx 新增 1 个视觉契约测试:槽位清单与操作结果 workbench 表面
web/src/pages/slots/page.tsx 命名槽位表格、将页面局部 rounded-xl 外壳收敛为紧凑 rounded-lg/rounded-md 编辑表面、为测试添加稳定的 data-slot-surface 属性
web/src/pages/tasks/page.test.tsx 新增 1 个只读任务中心的摘要条(summary strip)与筛选工具栏视觉契约测试
web/src/pages/tasks/page.tsx 将摘要卡片合并为规则分隔的摘要条、标记筛选工具栏、扁平化时间线事件卡片
web/src/pages/controller/page.test.tsx 新增 controller 工具栏、状态条、日志表的视觉契约测试
web/src/pages/controller/page.tsx 标记操作工具栏、将 Raft 状态格收敛为紧凑状态条、命名日志表

计划还明确了两条边界:

  • 不需要任何 i18n 改动,因为方案直接复用现有文案:slots.inventoryTitle、controller.logs.title 以及 tasks 页既有标签与标题。在仓库的 web/src/i18n/messages/zh-CN.ts 中可确认这些 key 已存在(如第 1146 行 "slots.inventoryTitle": "槽位清单"、第 722 行 "controller.logs.title": "Controller Raft 条目")。
  • 禁止触碰 web/src/pages/cluster-dashboard/* 与 web/src/pages/business-dashboard/*,保证本次批次聚焦。

三、方法论核心:先写「窄视觉契约测试」,再改代码

整个计划采用 TDD(测试驱动)节奏:每个任务先写一条会失败的测试(RED),再改页面代码让它通过(GREEN),最后独立提交。这保证了视觉改造可被自动化回归,而不是靠人工肉眼核对。

视觉契约测试的几个关键模式值得细看:

  1. 用可访问角色定位表格:screen.findByRole("table", { name: "Slot Inventory" }) —— 这要求页面给表格加上 aria-label,一举两得(可访问性 + 测试锚点)。
  2. 用 closest 沿 DOM 向上找表面容器:inventoryTable.closest("[data-slot-surface='inventory']"),避免测试与具体 DOM 层级强耦合。
  3. 用类名断言视觉契约:toHaveClass("rounded-lg", "border", "border-border", "bg-card", "p-3") 以及反向断言 not.toHaveClass("rounded-xl"),把"必须是什么、绝不能是什么"都写进测试。
  4. 通过真实交互触发操作结果:user.click(screen.getByRole("button", { name: "Rebalance slots" })) 后断言结果表面,保证测试覆盖的是真实用户路径。

仓库中 web/src/pages/slots/page.test.tsx 与 web/src/pages/tasks/page.test.tsx、web/src/pages/controller/page.test.tsx 中已经能看到这批契约测试的最终形态。


四、Task 1:Slots 页的编辑工作台表面

4.1 先写失败的 workbench 测试

计划要求在 web/src/pages/slots/page.test.tsx 中、uses compact slot page chrome without summary cards 之后追加如下测试:

test("marks slot inventory and operation results as editorial workbench surfaces", async () => {
  getSlotsMock.mockResolvedValue({ total: 1, items: [slotRow] })
  rebalanceSlotsMock.mockResolvedValue({
    total: 1,
    items: [{ hash_slot: 3, from_slot_id: 9, to_slot_id: 11 }],
  })

  const user = userEvent.setup()
  renderSlotsPage()

  const inventoryTable = await screen.findByRole("table", { name: "Slot Inventory" })
  const inventorySurface = inventoryTable.closest("[data-slot-surface='inventory']")
  expect(inventorySurface).toHaveClass("rounded-lg", "border", "border-border", "bg-card", "p-3")
  expect(inventorySurface).not.toHaveClass("rounded-xl")

  await user.click(screen.getByRole("button", { name: "Rebalance slots" }))
  await user.click(screen.getByRole("button", { name: "Confirm" }))

  const rebalanceSurface = (await screen.findByText("From slot 9 to slot 11")).closest(
    "[data-slot-surface='rebalance-result']",
  )
  expect(rebalanceSurface).toHaveClass("rounded-lg", "border", "border-border", "bg-card", "p-3")
  expect(rebalanceSurface).not.toHaveClass("rounded-xl")
})

此时运行测试(在 web 目录下):

cd web && /Users/tt/.bun/bin/bun run test -- src/pages/slots/page.test.tsx

预期 FAIL(RED):因为槽位清单表格还没有可访问名称 Slot Inventory,清单/结果 wrapper 也没有暴露 data-slot-surface。

4.2 改造槽位清单 wrapper

在 web/src/pages/slots/page.tsx 中,把槽位列表 wrapper 替换为如下结构,保留既有表头、行、按钮 handler 与空态内容不动:

<div data-slot-surface="inventory" className="rounded-lg border border-border bg-card p-3">
  {state.slots.items.length > 0 ? (
    <div className="overflow-x-auto rounded-md border border-border">
      <table
        aria-label={intl.formatMessage({ id: "slots.inventoryTitle" })}
        className="w-full border-collapse text-sm"
      >
        <thead className="bg-muted/40 text-left text-xs uppercase tracking-[0.14em] text-muted-foreground">
          {/* keep existing slot table header cells */}
        </thead>
        <tbody>
          {/* keep existing slot table rows */}
        </tbody>
      </table>
    </div>
  ) : (
    <ResourceState kind="empty" title={intl.formatMessage({ id: "nav.slots.title" })} />
  )}
</div>

源码落点验证:当前仓库 web/src/pages/slots/page.tsx 已是最终形态——外层 data-slot-surface="inventory" 采用 rounded-lg border border-border bg-card p-3,内部表格 aria-label 直接来自 slots.inventoryTitle,且保留了移动端横向滚动提示(slots.table.scrollHint)与 sticky left-0 / right-0 的首尾列固定(min-w-<a href="https://link.gitcode.com/i/bff4b520dcaf0e3c234c07f640f5aafe" target="_blank">78rem])。对应测试 [web/src/pages/slots/page.test.tsx 额外断言了首尾列 sticky 与滚动提示文案,可见"可访问性 + 操作可用性"是契约的一部分。

4.3 改造操作结果 wrapper

同文件继续把 rebalance 与批量转移结果外壳收敛为紧凑编辑表面:

<div data-slot-surface="rebalance-result" className="rounded-lg border border-border bg-card p-3">
  {/* keep existing rebalance result content */}
</div>
<div data-slot-surface="batch-transfer-result" className="rounded-lg border border-border bg-card p-3">
  {/* keep existing batch transfer result content */}
</div>

同时让 SlotClusterUnhealthyPanel 附近的异常槽位表格外壳使用同款紧凑页面局部形状:

<div data-slot-surface="unhealthy" className="rounded-lg border border-border bg-card p-3">
  {/* keep existing unhealthy slot table or empty state */}
</div>

实现演进说明(以仓库现状为准):计划原稿包含 rebalance-result 表面,但当前源码中 web/src/pages/slots/page.tsx 仅保留 batch-transfer-result(rounded-md border border-border bg-card p-3),且 web/src/pages/slots/page.test.tsx 明确断言它"必须是 rounded-md,不能是 rounded-lg 也不能是 rounded-xl";同时旧测试已移除 Rebalance slots 按钮(见 web/src/pages/slots/page.test.tsx)。这说明计划在执行中被收敛:槽位操作只保留"批量 Leader 转移"路径,表面圆角规格也在契约中进一步收紧。异常槽位面板当前实现为 rounded-md border border-border bg-card p-3(web/src/pages/slots/page.tsx),并配套独立契约测试(web/src/pages/slots/page.test.tsx)。

4.4 验证 GREEN 并提交

cd web && /Users/tt/.bun/bin/bun run test -- src/pages/slots/page.test.tsx

预期 PASS。随后提交:

git add web/src/pages/slots/page.tsx web/src/pages/slots/page.test.tsx
git commit -m "style(web): tighten slots workbench surfaces"

五、Task 2:Tasks 页的摘要条与筛选工具栏

Tasks 页是一个只读的任务中心:展示 Controller 运行中的任务(bootstrap、leader_transfer、slot_replica_move)与保留的审计历史,页头带有只读徽标(tasks.readOnly)。本次改造把原来 5 张独立摘要卡片压成一条规则分隔的摘要条,并让筛选工具栏获得稳定的测试标记。

5.1 先写失败的视觉测试

在 web/src/pages/tasks/page.test.tsx 中、renders active Controller tasks and retained audit history 之后追加:

test("uses a compact task-center summary strip and filter toolbar", async () => {
  renderTasksPage()

  expect(await screen.findByRole("heading", { name: "Controller Tasks" })).toBeInTheDocument()

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

  const filterToolbar = screen.getByTestId("tasks-filter-toolbar")
  expect(filterToolbar).toHaveClass("grid", "gap-3", "border-b", "border-border", "pb-4")
})

预期 FAIL:tasks-summary-strip、data-task-summary-cell、tasks-filter-toolbar 尚不存在。

5.2 把摘要卡片替换为摘要条

在 web/src/pages/tasks/page.tsx 中,把当前摘要 grid:

<div className="grid gap-3 md:grid-cols-5">
  {summaryCards.map((card) => (
    <div className="rounded-lg border border-border bg-card px-4 py-3" key={card.label}>
      <div className="text-xs font-medium text-muted-foreground">{card.label}</div>
      <div className="mt-2 text-2xl font-semibold text-foreground">{formatCount(card.value)}</div>
    </div>
  ))}
</div>

替换为:

<div
  className="grid overflow-hidden rounded-lg border border-border bg-card md:grid-cols-5"
  data-testid="tasks-summary-strip"
>
  {summaryCards.map((card, index) => (
    <div
      className="border-b border-border px-4 py-3 last:border-b-0 md:border-r md:border-b-0 md:last:border-r-0"
      data-task-summary-cell=""
      key={card.label}
    >
      <div className="font-mono text-[11px] font-semibold uppercase tracking-[0.14em] text-muted-foreground">
        {card.label}
      </div>
      <div className="mt-2 font-mono text-2xl font-semibold text-foreground">{formatCount(card.value)}</div>
      <span className="sr-only">{index + 1}</span>
    </div>
  ))}
</div>

这里体现了编辑控制台语言的两个典型手法:

  • 卡片 → 条(strip):去掉每个单元格各自的圆角与边框,改由外层统一 rounded-lg border 收边,单元格之间用 border-b / md:border-r 做规则分隔,正是 web/DESIGN.md 中 research-table"rule-separated" 的复刻;
  • 等宽 + 大写标签:标签改为 font-mono text-[11px] font-semibold uppercase tracking-[0.14em],数字也使用 font-mono,形成系统级读数质感;sr-only 序号为读屏用户保留位置信息。

数据来源(源码佐证):摘要的 5 个指标由 summaryCards 计算(web/src/pages/tasks/page.tsx):总数(tasks.summary.total)、运行中(running)、失败(failed)、审计历史总数(tasks.summary.history)与已完成数(completed),分别来自 getControllerTasks 与 getControllerTaskAudits 两个 API 的响应。

5.3 标记并扁平化筛选工具栏

在任务列表 SectionCard 中,把筛选 wrapper:

<div className="mb-4 grid gap-3 md:grid-cols-5">

替换为:

<div className="mb-4 grid gap-3 border-b border-border pb-4 md:grid-cols-5" data-testid="tasks-filter-toolbar">

保留所有现有标签、输入框、select 值与状态更新逻辑不变。当前源码 web/src/pages/tasks/page.tsx 中可见该工具栏包含 5 个筛选维度:kind、status、slot ID、node ID、keyword,交互时分别更新 kind/status/slotIdText/nodeIdText/keyword 状态,并触发 buildQueries 重新请求。

5.4 扁平化警告与时间线事件表面

审计截断提示从"带圆角的次级卡片"降级为更克制的提示条:

className="rounded-lg border border-border bg-secondary/40 px-4 py-3 text-sm text-foreground"

改为:

className="rounded-md border border-border bg-muted/30 px-4 py-3 text-sm text-foreground"

时间线事件外壳从"灰底圆角卡片"改为更平的背景表面:

<div className="rounded-lg border border-border bg-muted/30 p-3" key={event.event_id}>

改为:

<div className="rounded-md border border-border bg-background p-3" data-task-timeline-event="" key={event.event_id}>

源码落点验证:当前仓库 web/src/pages/tasks/page.tsx(截断提示 rounded-md ... bg-muted/30)与 web/src/pages/tasks/page.tsx(时间线事件 rounded-md ... bg-background + data-task-timeline-event)均已落地。同时该文件还展示了同类表面在活跃任务表与审计表上的延续:data-tasks-surface="active" / data-tasks-surface="audit"(web/src/pages/tasks/page.tsx),并配合 responsiveTaskCellClass 实现移动端"块状行 + data-label 标签"的响应式表格(web/src/pages/tasks/page.tsx)。

5.5 验证 GREEN 并提交

cd web && /Users/tt/.bun/bin/bun run test -- src/pages/tasks/page.test.tsx

预期 PASS。提交:

git add web/src/pages/tasks/page.tsx web/src/pages/tasks/page.test.tsx
git commit -m "style(web): compact controller task center"

六、Task 3:Controller 页的编辑工作台表面

Controller 页是全局控制器(Controller Raft)的运维入口:支持按节点查看 Raft 状态、Controller 日志,并触发 Raft 日志压缩(compaction)。本任务标记操作工具栏、把 5 个 Raft 状态格收敛为状态条、并给日志表命名。

6.1 先写失败的 workbench 测试

在 web/src/pages/controller/page.test.tsx 中、renders controller log entry creation time 之后追加:

test("uses compact controller workbench surfaces", async () => {
  getNodesMock.mockResolvedValueOnce({
    generated_at: "2026-05-06T08:00:00Z",
    controller_leader_id: 2,
    total: 1,
    items: [{
      node_id: 2,
      name: "node-2",
      addr: "127.0.0.1:7002",
      status: "alive",
      last_heartbeat_at: "2026-05-06T07:59:58Z",
      is_local: true,
      capacity_weight: 1,
      controller: { role: "leader", voter: true, leader_id: 2 },
      slot_stats: { count: 0, leader_count: 0 },
    }],
  })
  getControllerLogsMock.mockResolvedValueOnce({
    node_id: 2,
    first_index: 1,
    last_index: 4,
    commit_index: 4,
    applied_index: 3,
    items: [{
      index: 4,
      term: 2,
      type: "normal",
      data_size: 12,
      decode_status: "ok",
      decoded_type: "add_slot",
      decoded: { command: "add_slot", new_slot_id: 9 },
      created_at_ms: Date.UTC(2026, 5, 18, 1, 10, 11, 123),
    }],
  })
  getControllerRaftStatusMock.mockResolvedValueOnce(controllerRaftStatus(2))

  renderControllerPage("/controller?node_id=2")

  const toolbar = await screen.findByTestId("controller-workbench-toolbar")
  expect(toolbar).toHaveClass("border-b", "border-border", "pb-4")

  const statusStrip = await screen.findByTestId("controller-status-strip")
  expect(statusStrip).toHaveClass("grid", "gap-3")
  expect(statusStrip.querySelectorAll("[data-controller-status-cell]")).toHaveLength(5)

  const logsTable = await screen.findByRole("table", { name: "Controller Raft Entries" })
  const logsSurface = logsTable.closest("[data-controller-surface='logs']")
  expect(logsSurface).toHaveClass("rounded-lg", "border", "border-border", "bg-card")
})

注意测试首行 renderControllerPage("/controller?node_id=2")——URL 查询参数驱动节点选择是本页的既有行为,改造后必须保持(当前源码中 requestedNodeId 解析逻辑在 web/src/pages/controller/page.tsx)。

6.2 标记操作工具栏

在 ControllerLogsPanel 中,把顶部 wrapper:

<div className="flex flex-col gap-3 lg:flex-row lg:items-start lg:justify-between">

替换为:

<div
  className="flex flex-col gap-3 border-b border-border pb-4 lg:flex-row lg:items-start lg:justify-between"
  data-testid="controller-workbench-toolbar"
>

保持节点过滤器、压缩按钮、刷新按钮及其所有 handler 不变。当前源码 web/src/pages/controller/page.tsx 已落地:工具栏内含 NodeFilter、压缩触发按钮(controller.compaction.trigger)与刷新按钮。

6.3 把 Raft 状态格转换为命名状态条

在 ControllerRaftStatusPanel 中,把状态 grid 开头:

<div className="grid gap-3 md:grid-cols-2 xl:grid-cols-5">

替换为:

<div className="grid gap-3 md:grid-cols-2 xl:grid-cols-5" data-testid="controller-status-strip">

对 5 个状态格 wrapper 分别添加 data-controller-status-cell="" 并使用统一的紧凑背景:

<div className="rounded-md border border-border bg-background px-3 py-3" data-controller-status-cell="">
  {/* keep existing health cell content */}
</div>

该统一外壳应用到 health、role、watermark、snapshot、compaction 五个格子上。当前源码 web/src/pages/controller/page.tsx 中五个格子均已落地,且内容含义清晰:

  • health:健康态 StatusBadge;
  • role:formatRoleTerm(角色 + term)与当前 leader;
  • watermark:formatCommitApplied(commit/applied)与日志区间 first/last;
  • snapshot:快照 index/term 与恢复状态(controller.status.restoreOk/restoreFailed);
  • compaction:压缩是否 compaction_degraded 及触发阈值(compaction.trigger_entries)。

状态条下方还保留了 Followers 进度表(controller.status.followers),展示每个 peer 的 match/next、快照需求与活跃度(web/src/pages/controller/page.tsx)。

6.4 命名并标记日志表

在日志表 section 处替换:

<section className="overflow-hidden rounded-lg border border-border bg-card">

为:

<section className="overflow-hidden rounded-lg border border-border bg-card" data-controller-surface="logs">

再替换表格:

<table className="min-w-full divide-y divide-border text-sm">

为:

<table
  aria-label={intl.formatMessage({ id: "controller.logs.title" })}
  className="min-w-full divide-y divide-border text-sm"
>

保留所有日志行、decoded 展开、分页与 load-more 行为不变。当前源码 web/src/pages/controller/page.tsx 已完整落地,日志行支持点击"show decoded"展开 JSON 详情(formatControllerLogDecoded),并在 next_cursor 存在时渲染 load-more 按钮(web/src/pages/controller/page.tsx)。

6.5 验证 GREEN 并提交

cd web && /Users/tt/.bun/bin/bun run test -- src/pages/controller/page.test.tsx

预期 PASS。提交:

git add web/src/pages/controller/page.tsx web/src/pages/controller/page.test.tsx
git commit -m "style(web): refine controller workbench surfaces"

七、Task 4:聚焦验证与源码收尾

三个任务完成、三个独立提交就绪后,进入全量验证阶段。

7.1 聚焦页面测试

一次跑完三个页面的测试文件:

cd web && /Users/tt/.bun/bin/bun run test -- src/pages/slots/page.test.tsx src/pages/tasks/page.test.tsx src/pages/controller/page.test.tsx

预期三个文件全部 PASS。

7.2 TypeScript 验证

cd web && /Users/tt/.bun/bin/bunx tsc -b

预期退出码 0、无 TypeScript 错误。注意 web/package.json 中 build 脚本本身就是 tsc -b && vite build && bun run build:check,类型检查是构建流水线的一环。

7.3 生产构建

cd web && /Users/tt/.bun/bin/bun run build

预期退出码 0。Vite 的 large chunk 警告是可接受的——该应用本来就存在。

7.4 还原生成的 dist hash 抖动

git status --short
git diff -- web/dist/index.html

如果 web/dist/index.html 的唯一变化是生成的资源 hash,则还原它:

git restore web/dist/index.html

注意:只还原生成产物,绝不还原源码文件。

7.5 空白检查与状态汇报

git diff --check

预期无输出。最后在实现汇报中总结:

  • 创建的 commits;
  • 通过的聚焦测试;
  • TypeScript / 构建状态;
  • web/dist/index.html 是否已还原;
  • 剩余无关的未跟踪文件——计划特别点名了两个:web/DESIGN.md 与 docs/superpowers/plans/2026-07-05-legacy-app-slot-store-adapter.md,它们与本批次无关,不应被误提交。

八、本次改造的工程经验与可复用要点

  1. 视觉契约要窄而稳:每个页面只加 1 条契约测试,锚点用 aria-label + data-* 属性 + closest() 组合,既服务可访问性,又避免断言过于依赖 DOM 层级,未来样式微调时不易碎。
  2. 表面收边是编辑语言的核心:rounded-xl → rounded-lg/rounded-md、卡片堆叠 → 规则分隔条(strip)、bg-muted/30 → bg-background,这三组替换几乎覆盖了本次全部视觉差异。
  3. 共享组件零改动是硬约束:三个页面全部通过页面局部 wrapper 表达布局,SectionCard 等共享组件(见 web/src/components/shell/section-card.tsx)保持原样,把改造风险限制在页面文件内。
  4. 行为与视觉解耦:数据加载、URL 参数(如 /controller?node_id=2)、分页/load-more、压缩对话框等行为逻辑原封不动,重构只发生在"外壳"层——这也是 TDD 能让视觉改造安全落地的前提。
  5. 计划会随实现收敛:对比计划原稿与当前仓库可见,Rebalance slots 操作最终被移除、部分表面规格从 rounded-lg 收紧为 rounded-md,契约测试同步更新。以仓库现状为准理解这些演进,比照搬计划更能还原真实工程过程。

如果你正在为 WuKongIM 管理端新增运维页面,可以直接复用这套模式:先为页面写好"窄视觉契约"测试,再用 data-slot-surface / data-testid 标记表面、以紧凑圆角 + 细边框 + 等宽标签落地编辑控制台语言,最后跑通 tsc -b 与生产构建并独立提交——每一步都能在本文对应的源码文件中找到现成的参照实现。

登录后查看全文
WuKongIM