WuKongIM 管理端运维页面视觉重构实战:Slots / Tasks / Controller 三页面的「编辑控制台」化改造
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])用于系统级标记、规则分隔列表而非堆叠卡片。本次改造正是把这些原则落到三个具体页面上。
改造遵循两条铁律:
- 行为不动:每个页面现有的数据加载、操作按钮、对话框、Tab、URL 行为全部保持原样;
- 局部优先:优先在页面内使用局部 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),最后独立提交。这保证了视觉改造可被自动化回归,而不是靠人工肉眼核对。
视觉契约测试的几个关键模式值得细看:
- 用可访问角色定位表格:
screen.findByRole("table", { name: "Slot Inventory" })—— 这要求页面给表格加上aria-label,一举两得(可访问性 + 测试锚点)。 - 用
closest沿 DOM 向上找表面容器:inventoryTable.closest("[data-slot-surface='inventory']"),避免测试与具体 DOM 层级强耦合。 - 用类名断言视觉契约:
toHaveClass("rounded-lg", "border", "border-border", "bg-card", "p-3")以及反向断言not.toHaveClass("rounded-xl"),把"必须是什么、绝不能是什么"都写进测试。 - 通过真实交互触发操作结果:
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 条契约测试,锚点用
aria-label+data-*属性 +closest()组合,既服务可访问性,又避免断言过于依赖 DOM 层级,未来样式微调时不易碎。 - 表面收边是编辑语言的核心:
rounded-xl→rounded-lg/rounded-md、卡片堆叠 → 规则分隔条(strip)、bg-muted/30→bg-background,这三组替换几乎覆盖了本次全部视觉差异。 - 共享组件零改动是硬约束:三个页面全部通过页面局部 wrapper 表达布局,
SectionCard等共享组件(见 web/src/components/shell/section-card.tsx)保持原样,把改造风险限制在页面文件内。 - 行为与视觉解耦:数据加载、URL 参数(如
/controller?node_id=2)、分页/load-more、压缩对话框等行为逻辑原封不动,重构只发生在"外壳"层——这也是 TDD 能让视觉改造安全落地的前提。 - 计划会随实现收敛:对比计划原稿与当前仓库可见,
Rebalance slots操作最终被移除、部分表面规格从rounded-lg收紧为rounded-md,契约测试同步更新。以仓库现状为准理解这些演进,比照搬计划更能还原真实工程过程。
如果你正在为 WuKongIM 管理端新增运维页面,可以直接复用这套模式:先为页面写好"窄视觉契约"测试,再用 data-slot-surface / data-testid 标记表面、以紧凑圆角 + 细边框 + 等宽标签落地编辑控制台语言,最后跑通 tsc -b 与生产构建并独立提交——每一步都能在本文对应的源码文件中找到现成的参照实现。