12 KiB
Raw Permalink Blame History

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-0107)、操作规范(OPR-0102)、算子手册与结构化索引
全局侧栏 / 浮层 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)

  1. Button / ButtonLink:支持 primary、secondary、ghost、danger,支持 busy(加载转圈)。
  2. PageHeader:页面主标题 + 一句话说明 + 右侧主操作 + 面包屑后退链接。
  3. Panel:卡片容器,支持 title、aside 及通用内嵌 children。
  4. EmptyState:居中空状态图标(默认 Inbox,字重 1.35)+ 标题 + 简述 + 恢复操作。
  5. ErrorNotice / Notice:基于 HTTP 状态码的标准化错误报警与信息栏。
  6. Loading:居中 spinner + 固定文案「正在读取控制面数据…」。
  7. Status:24 种状态字典映射的徽章,带有内嵌圆点指示灯。
  8. Field / FormError / Success:表单输入框包装、错误与成功提示。
  9. Modal:原生 <dialog> 封装,支持普通与 wide 视图。
  10. RunTable:多列运行记录表格(ID、目标、执行器、状态、时间)。
  11. 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,缺少 droboticflow docs/ui/copy-guidelines.md 规范要求的「最简业务语言 + 明确恢复按钮」。
  • 观感危害:客户看不懂报错,恐慌感加剧,频繁打扰平台技术支持。

TOP 10: 空状态 (EmptyState) 缺乏场景化与直接引导动作

  • 涉及文件:apps/web/src/components/ui.tsx:96-117
  • 现象描述:全站所有空状态千篇一律地渲染灰色小盒子,文案空洞(如「尚未加载数据」),缺少符合业务语境的下一步引导按钮(例如「新建第一个愿望」、「去连接执行器」)。
  • 观感危害:新接入项目的客户面对空白界面不知所措,流失率高。