12 KiB
12 KiB
WishForge 视觉与体验摸底报告 (Audit)
审计基准:WishForge 仓库(分支
review/overhaul,apps/web)
审计日期:2026-11-09
审计环境说明:当前终端执行环境无图形界面及无头浏览器渲染驱动,无法输出自动化像素级截屏。本摸底严格基于apps/web/src源码、组件树遍历、CSS 静态词法分析(AST/Regex)、DOM 结构以及 droboticflow(docs/ui/copy-guidelines.md)最简文案规范进行系统性走查。
1. 现有页面与组件资产盘点
1.1 路由与页面清单
| 页面 / 路由 | 对应 Feature 文件 | 页面核心职责与客户可见内容 |
|---|---|---|
/ (概览) |
features/dashboard.tsx |
工作概览、进行中运行数、待确认事项、执行器就绪状态、最近运行列表、交付路径(5 步) |
/runs (运行列表) |
features/runs.tsx |
许愿与执行记录列表、项目/状态筛选器、愿望检索、状态指示 |
/runs/[id] (运行详情) |
features/runs.tsx |
执行目标、阶段流转状态机、命令证据、Diff 审阅、交付报告、日志抽检与分支锁 |
/runs/new (新建愿望) |
features/runs.tsx |
目标输入框、验收标准编辑、执行模型/执行器选择、分支指派与前置检查 |
/releases (发布与审批) |
features/releases.tsx |
部署发布列表、审批状态核对、代码/镜像摘要验证、回滚入口、上线应用直达 |
/environments (环境管理) |
features/environments.tsx |
目标环境卡片(生产/测试)、运行时配置、分支关联、在线健康状态 |
/projects (项目列表) |
features/projects.tsx |
客户项目看板、代码仓库关联、验证配置文件绑定 |
/projects/[id]/wiki (Wiki 知识库) |
features/wiki-source.tsx |
业务规则(BR-01 |
| 全局侧栏 / 浮层 Copilot | features/copilot.tsx |
诊断对话、Wiki 依据链(文件:行号)、置信度判别、一键转成许愿 |
/usage (用量监控) |
features/usage.tsx |
Token/时间额度消耗、按提供商与任务划分的成本账单 |
/providers (执行器配置) |
features/providers.tsx |
Claude CLI、Codex 等模型执行器凭据、配额与连通性自检 |
/members (成员与权限) |
features/members.tsx |
租户成员列表、角色指派(客户负责人/开发者/观察员)、Token 审计 |
/settings (项目配置) |
features/project-settings.tsx |
验证基线配置、门禁敏感路径规则(CodeReviewPolicy)、沙箱策略 |
1.2 核心基础组件 (components/ui.tsx, console-shell.tsx, run-table.tsx, diff-view.tsx)
- Button / ButtonLink:支持
primary、secondary、ghost、danger,支持busy(加载转圈)。 - PageHeader:页面主标题 + 一句话说明 + 右侧主操作 + 面包屑后退链接。
- Panel:卡片容器,支持
title、aside及通用内嵌 children。 - EmptyState:居中空状态图标(默认
Inbox,字重 1.35)+ 标题 + 简述 + 恢复操作。 - ErrorNotice / Notice:基于 HTTP 状态码的标准化错误报警与信息栏。
- Loading:居中 spinner + 固定文案「正在读取控制面数据…」。
- Status:24 种状态字典映射的徽章,带有内嵌圆点指示灯。
- Field / FormError / Success:表单输入框包装、错误与成功提示。
- Modal:原生
<dialog>封装,支持普通与 wide 视图。 - RunTable:多列运行记录表格(ID、目标、执行器、状态、时间)。
- DiffView:Git 变更差异高亮对比组件。
2. 样式异味与重复分析 (CSS Smells)
2.1 globals.css 规模与膨胀成因
- 总行数:
3580行。 - 变量仅 14 个:其余 3500+ 行全为全局选择器与局部选择器混杂。
- 硬编码 Hex 颜色:静态统计共有 131 个 不同的 Hex 颜色代码。同一种灰色在不同选择器中存在
#d8e0ea、#b4c1d0、#edf1f5、#f6f8fb、#fbfcfe、#e1e7ef等 28 种极细微的变体,未形成层级梯队。 - 字号碎片化:存在 23 种 不同的字号定义(如
8px、10px、11px、12px、13px、14px、15px、16px、17px、18px、20px、22px、25px、28px、34px等),缺少比例阶梯系统。 - 圆角不规范:虽有
--radius: 7px,但在代码中同时存在4px、5px、8px、9px、10px、12px、20px、999px等 15 种 显式 border-radius。 - 间距无规则:
margin和padding使用任意像素值(7px、11px、13px、17px、23px、29px等奇数间距随处可见),组件间节奏感脱节。
3. 缺失的状态矩阵盘点 (States Audit)
依据 droboticflow 界面规范要求的四态闭环(正常、加载、空、错误)以及企业多租户必备的无权限态,走查各主要功能模块:
| 模块 / 页面 | 加载态 (Loading) | 空数据态 (Empty) | 错误态 (Error) | 权限限制态 (No Permission) | 诊断评价 |
|---|---|---|---|---|---|
| 工作概览 Dashboard | ✅ 有全局加载骨架 | ⚠️ 仅 Recent Runs 有空状态 | ⚠️ ErrorNotice 置顶,但 metric 变成假 0 或空白 | ❌ 403 仅简单置空数据,无申请/提升权限指引 | 需补全单模块骨架屏 |
| 运行列表 Runs | ⚠️ 无骨架,仅由 SWR 延迟刷新 | ❌ 搜索无结果时直接渲染空表格头部,无提示 | ✅ 有通用 ErrorNotice | ⚠️ 非租户只隐藏按钮,无说明 | 搜索空态缺失 |
| 运行详情 Run Detail | ⚠️ 加载中时页面大面积空白 | ❌ 门禁未运行时显示为「-」,缺少未就绪说明 | ⚠️ 任务失败与控制面接口错误混合 | ❌ 无敏感分支查看鉴权拦截兜底 | 门禁结果四态极不规范 |
| 发布审批 Releases | ✅ 有 <Loading /> |
⚠️ 空数据时渲染空面板,无首次发布引导 | ✅ 有 ErrorNotice 且可重试 | ⚠️ 非审批人(普通成员)按钮灰显无 hover 解释 | 需明确谁能审批(客户负责人/平台方) |
| Wiki 知识库 | ⚠️ 内容拉取时跳动 | ❌ 检索无结果时空白 | ⚠️ 文件读取失败报错暴露后端路径 | ❌ 无租户隔离提示 | 需结构化空态与报错遮罩 |
| Copilot 面板 | ❌ 仅发送按钮转圈,无会话流式骨架 | ❌ 首次进入无典型问题推荐 | ⚠️ 网络错误直接断开,无断线重连/重试 | ❌ 只读日志越权时仅报未知异常 | 缺失引导与优雅断网处理 |
| 集群资源 (新增) | 待实现 | 待实现 | 待实现 | 待实现 | 必须按标准四态完整设计交付 |
4. 最影响观感的前 10 个界面体验与视觉问题
TOP 1: 缺少系统级设计系统,CSS 严重缺乏语义化与复用
- 涉及文件:
apps/web/src/app/globals.css(3580 行) - 现象描述:样式全部平铺在单一巨大 css 文件中,类名如
.run-row-3、.copilot-inner-box-v2等临时拼凑样式泛滥,修改一处极易产生未知回归。 - 观感危害:布局不稳、视觉断层、样式维护难度指数级上升。
TOP 2: 品牌色与主动作饱和度/对比度不协调,视觉焦点发暗
- 涉及文件:
apps/web/src/app/globals.css:10-12(--teal: #168574,--navy: #102031) - 现象描述:现行 Teal 绿偏墨暗,作为主要操作按钮(CTA)背景时,在暗灰底与白底上的存在感偏重且沉闷;而警告色 Amber 与错误色 Red 同样偏暗红泥黄色,高危操作缺乏即时震撼力。
- 观感危害:整体界面显得陈旧、缺乏现代研发协同工具应有的科技感与清爽感。
TOP 3: 运行详情页(Run Detail)信息层级混乱,关键证据与风险被折叠埋没
- 涉及文件:
apps/web/src/features/runs.tsx:840-1120 - 现象描述:Run 详情页将近 1600 行代码,包含了执行目标、阶段时间线、沙箱命令证据、Diff 审阅、日志与交付报告。所有内容以简单的 vertical stack 罗列,页面极长,缺少核心看板(4 栏交付矩阵)。
- 观感危害:客户无法在 3 秒内看清「改了什么」、「风险高不高」、「验证过了没有」。
TOP 4: 风险等级与审批门禁缺乏醒目、统一的徽章规范
- 涉及文件:
apps/web/src/features/releases.tsx:80-140,apps/web/src/lib/risk.ts - 现象描述:低/中/高风险判定逻辑已存在于
risk.ts(例如涉数据迁移、超卖、权限扩大为高风险),但在 UI 上仅以朴素的小字体或普通标签呈现,未区分「客户负责人可批」与「必须平台方介入」的视觉权重。 - 观感危害:审批人极易误触高风险发布,带来重大生产事故隐患。
TOP 5: Copilot 对话面板缺乏结构化视觉卡片与可信度分级
- 涉及文件:
apps/web/src/features/copilot.tsx:17-43 - 现象描述:Copilot 输出时,代码引用与 Wiki 链接混合在正文下方,样式类似一段简陋的小字;当 LLM 判断「依据不足/不确定」时,仅有一行小字标注
unknown,没有半透明警示背景与清晰免责卡片。 - 观感危害:用户无法迅速建立对 Copilot 诊断答案的信任边界,不敢将诊断直接转为许愿。
TOP 6: 表格与卡片间距密度失控,屏幕利用率极低
- 涉及文件:
apps/web/src/components/run-table.tsx,apps/web/src/app/globals.css:1240-1420 - 现象描述:列表每一行高度高达 68px 以上,但有效文字仅占不到 30%;水平方向上有大量空白,垂直方向上信息却被挤出屏外。
- 观感危害:在标准 1440 笔记本屏幕下,一屏只能看到 5~6 条运行记录,排查问题体验繁重。
TOP 7: 移动端(390px 视口)适配粗糙,大量横向滚动与溢出
- 涉及文件:
apps/web/src/components/console-shell.tsx:40-90,apps/web/src/app/globals.css:2900-3100 - 现象描述:侧边栏在手机端遮挡主界面,表格未做移动端卡片化(Cardify)适配,直接出现横向滚动条;按钮组(Button Group)在移动端发生折行错位与挤压。
- 观感危害:现场运维或移动端紧急确认发布时几乎不可用。
TOP 8: 加载骨架屏缺失,内容加载时发生剧烈布局偏移 (CLS)
- 涉及文件:
apps/web/src/components/ui.tsx:168-175(<Loading />) - 现象描述:全站通用加载仅为一个居中的转圈小菊花
<LoaderCircle className="spin" />,一旦数据返回,页面元素瞬间撑开,视觉抖动极度严重。 - 观感危害:给人一种系统极不稳定、卡顿、开发未完成的粗糙毛坯感。
TOP 9: 报错与异常反馈文案充斥内部技术黑话,缺失下一步动作指引
- 涉及文件:
apps/web/src/components/ui.tsx:119-158,apps/web/src/features/copilot.tsx:98 - 现象描述:遇到失败时直接抛出如
API 500: MongoNetworkError或Command failed with code 124,缺少 droboticflowdocs/ui/copy-guidelines.md规范要求的「最简业务语言 + 明确恢复按钮」。 - 观感危害:客户看不懂报错,恐慌感加剧,频繁打扰平台技术支持。
TOP 10: 空状态 (EmptyState) 缺乏场景化与直接引导动作
- 涉及文件:
apps/web/src/components/ui.tsx:96-117 - 现象描述:全站所有空状态千篇一律地渲染灰色小盒子,文案空洞(如「尚未加载数据」),缺少符合业务语境的下一步引导按钮(例如「新建第一个愿望」、「去连接执行器」)。
- 观感危害:新接入项目的客户面对空白界面不知所措,流失率高。