124 lines
12 KiB
Markdown
124 lines
12 KiB
Markdown
# 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~07)、操作规范(OPR-01~02)、算子手册与结构化索引 |
|
||
| 全局侧栏 / 浮层 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`
|
||
- **现象描述**:全站所有空状态千篇一律地渲染灰色小盒子,文案空洞(如「尚未加载数据」),缺少符合业务语境的下一步引导按钮(例如「新建第一个愿望」、「去连接执行器」)。
|
||
- **观感危害**:新接入项目的客户面对空白界面不知所措,流失率高。
|