124 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`
- **现象描述**:全站所有空状态千篇一律地渲染灰色小盒子,文案空洞(如「尚未加载数据」),缺少符合业务语境的下一步引导按钮(例如「新建第一个愿望」、「去连接执行器」)。
- **观感危害**:新接入项目的客户面对空白界面不知所措,流失率高。