nex_design_system/docs/01-project-audit.md

181 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

> **范围声明(NEX 0.1.2):** 本文是 NexDocus 单一参考项目的历史代码审计,不是 NEX Core 规范,也不是其他项目的技术栈、Token、尺寸或页面模式基线。本文中出现的 React/Ant Design、颜色值、64px Header、260/80px 导航等,只描述该参考项目当时的实现事实。新项目必须先按 `docs/00-governance-and-adaptation.md` 完成自己的项目审计与映射。
# 01. NexDocus 前端设计审计
## 1. 审计范围与方法
本次检查了压缩包中的 `frontend/`,重点覆盖 `package.json`、全局样式、设计令牌、Ant Design 主题、主题 Store、应用路由、主布局、导航、公共组件以及 Dashboard、项目列表、聊天、文档阅读/编辑、登录和系统管理页面。
本次是**静态源代码审计**,不是在浏览器中逐页运行后的视觉验收。压缩包没有附带运行截图、设计稿或交互录屏,因此本报告对视觉效果的判断基于 CSS/JSX 的设计实现;响应式和真实像素观感还需在运行后确认。
## 2. 当前实际前端技术栈
| 项目 | 当前实现 |
|---|---|
| UI 框架 | React 18.2 |
| 构建工具 | Vite 5 |
| UI 组件库 | Ant Design 5 |
| 路由 | React Router 6 |
| 状态管理 | Zustand 4 |
| HTTP | Axios |
| 样式 | 普通 CSS + CSS Variables;不是 CSS Modules |
| Markdown | ByteMD、React Markdown 等 |
| PDF | react-pdf / pdfjs-dist |
| 语言 | JavaScript / JSX |
**参考项目事实:** NexDocus 当时采用 React + Ant Design 5 + 普通 CSS;TypeScript、Tailwind 和 CSS Modules 并非该项目当时的实际技术。该事实不构成其他项目的技术栈要求。
## 3. 值得保留的设计资产
### 3.1 已经存在基础设计令牌
`src/styles/design-tokens.css` 已经包含品牌色、状态色、文本、背景、边框、Markdown、间距、圆角、阴影、层级、过渡和布局尺寸,并提供 `body.dark` 覆盖。这是 NEX 可以直接继承的基础。
### 3.2 已经存在 Ant Design 主题集中配置
`src/theme/antdTheme.js` 对字体、主色、边框、按钮、输入框、卡片、Modal、Drawer、Table、Menu、Tag、Tooltip 和 Segmented 做了主题设置。说明项目已经有统一主题的意识。
### 3.3 公共页面模式已经初步形成
以下组件值得纳入 NEX 的第一批参考组件:
- `PageHeader`:标题、说明、返回和操作区。
- `StatCard`:指标卡片与趋势。
- `ListActionBar`:操作、批量操作、搜索和筛选。
- `ListTable`:表格选择、分页与选中信息。
- `ModernSidebar`:可折叠导航、分组和用户区域。
- `LargeMarkdownViewer`、`VirtualPDFViewer`、`ProjectFileTree`:专业工作区组件。
### 3.4 专业工作区有经过修正的布局经验
文档阅读、编辑和聊天页面都采用专用工作区,而不是普通滚动页面。代码中已经出现针对 Ant Design Sider/Flex 子项、内容区滚动和编辑器宽度的修复说明。NEX 必须保留这些经验:
- 嵌套 Flex/Grid 子项在需要收缩时设置 `min-width: 0` / `min-height: 0`。
- 一个工作区只指定明确的主滚动容器,避免多个父子容器争抢滚动。
- 工具栏、侧栏、编辑区和内容区的高度关系要明确。
- 文档阅读与编辑共享同一阅读宽度规则,避免两种模式内容行长不一致。
### 3.5 全局可访问性基础
`index.css` 已提供 `:focus-visible` 和 `prefers-reduced-motion` 处理。这两项应保留并扩展,而不是在重构时删除。
## 4. 主要问题与规范漂移
### A. 设计 token 与真实布局尺寸不一致(高优先级)
`design-tokens.css` 定义:
- `--header-height: 56px`
- `--sider-width: 232px`
- `--sider-collapsed-width: 64px`
但当前运行组件的实际默认值是:
- `MainLayout/AppHeader.css`:Header 高度 64px。
- `ModernSidebar.jsx`:Sider 宽度 260px,折叠宽度 80px。
`AppSider` 没有覆盖这两个默认值,因此 token 与页面真实值存在漂移。AI 可能读到 token 后按 56/232/64 开发,但现有 UI 实际按 64/260/80 工作。
**NexDocus 参考项目当时的处理建议(非通用规则):** 0.1 版先以当前组件真实使用的 64px / 260px / 80px 作为基线,待结合运行截图确认后再调整;不得同时保留两套互相冲突的数字。
### B. CSS 与 Ant Design 主题重复维护(高优先级)
品牌色、状态色、边框色和表格颜色同时存在于 CSS Variables 与 `antdTheme.js`。两处由人工分别维护,长期容易出现亮色/暗色、按钮/表格和自定义样式不一致。
**NexDocus 参考项目当时的处理建议(非通用规则):** 设计 token 必须有单一事实来源。CSS Variables 与 Ant Design Theme 应由同一份 token 数据生成,或至少由自动化一致性检查保证一致;禁止在两处独立调整同一个语义 token。
### C. 页面级硬编码颜色较多(高优先级)
静态扫描 CSS(排除中央 `design-tokens.css`)发现约 204 处颜色字面量、约 143 种不同值,分布在 19 个样式文件中。颜色字面量并非全部错误,例如语法高亮或第三方品牌色可以保留;但品牌蓝、边框、背景、状态色和阴影不应在业务页面各自定义。
颜色字面量较多的文件包括:
- `pages/Chat/Chat.css`
- `pages/ProjectList/ProjectList.css`
- `components/ModeSwitch/ModeSwitch.css`
- `pages/Profile/ProfilePage.css`
- `pages/Login/Login.css`
**NexDocus 参考项目当时的处理建议(非通用规则):** 新代码不允许新增普通 UI 颜色硬编码;旧代码分批迁移,不做一次性机械替换。语法高亮、文档内容、第三方品牌等例外必须局部隔离。
### D. 组件与页面使用方式不够统一(高优先级)
项目已经有 `PageHeader`、`StatCard`、`ListActionBar`、`ListTable` 等共享组件,但业务页面仍大量直接组合 Ant Design 原生组件与页面私有 CSS。不同页面对搜索栏、标题区、统计卡片、表格容器和操作反馈的结构并不完全一致。
**NexDocus 参考项目当时的处理建议(非通用规则):** 建立有明确合同的页面级复合组件(例如 `NexPageHeader`、`NexSearchToolbar`、`NexDataTable`、`NexStatCard`),让常见业务页面调用标准组合。低频、无特殊主题的 Ant Design 基础组件不必全部二次封装。
### E. 页面标题的视觉强调不分场景(中高优先级)
`PageHeader.css` 使用大面积蓝色渐变背景、装饰圆形和白色标题。它有鲜明识别度,适合欢迎页、概览页或需要强调的主页面;但若每个管理页面都使用,会让操作型页面过度强调标题、压缩有效内容空间,也容易形成“每页一个大横幅”的视觉疲劳。
**NexDocus 参考项目当时的处理建议(非通用规则):** 定义两种明确变体:
- `standard`:中性背景、清晰标题/说明/操作区,是 CRUD、设置和系统管理页的默认方式。
- `hero`:保留品牌渐变,只用于概览、欢迎或少量需要强调的页面。
### F. 主题与字体系统存在重复定义(中高优先级)
`App.css` 与 `antdTheme.js` 使用的字体栈并不完全相同。部分页面还直接设置固定灰色、白色背景和固定状态色。随着暗色主题扩展,容易出现某些页面切换主题后仍保留浅色硬编码。
**NexDocus 参考项目当时的处理建议(非通用规则):** 统一一份全局字体令牌;颜色一律使用语义 token。暗色主题的覆盖必须在基础 token 层完成,而不是散落在业务 CSS 的 `body.dark` 选择器里。
### G. 部分 CSS 选择器疑似无效(需要修正)
`components/ListActionBar/ListActionBar.css` 使用了 `:global(...)` 选择器,但文件是普通 `.css`,不是 CSS Module(项目也没有将该文件配置成 CSS Modules)。`:global` 是 CSS Modules 的作用域语法,不是普通浏览器 CSS 的标准伪类;相关选择器很可能不会按预期生效。
**NexDocus 参考项目当时的处理建议(非通用规则):** 普通 CSS 文件直接使用 `.list-action-bar-right .ant-space-compact ...` 等普通选择器;只有 `.module.css` 才允许使用 CSS Modules 语法。
### H. 交互元素的语义和键盘操作不足(中高优先级)
导航菜单项、Header 图标操作等位置存在使用 `div` 承载点击事件的实现。鼠标操作可用不代表键盘可访问,也不具备原生按钮/链接语义。
**NexDocus 参考项目当时的处理建议(非通用规则):** 导航用 `button` 或 `a`;动作使用 `button`;跳转使用 `Link`;需要自定义外观时用 CSS 重置原生控件,而不是把可点击 `div` 当按钮。
### I. 固定高度可能限制视口适配(中优先级)
`ListTable.css` 中表格容器使用固定 `height: 626px`。项目卡片使用固定高度 236px。卡片统一高度可以是有意的视觉决策,但表格容器高度应基于视口和布局弹性计算,而不是对所有显示器固定 626px。
**NexDocus 参考项目当时的处理建议(非通用规则):** 列表区域采用可伸缩高度、最大高度或父容器约束;表格滚动归属必须清楚。固定高度只有在明确的内容卡片模式中才可使用。
### J. 文档说明和当前实际依赖不一致(中优先级)
`frontend/README.md` 描述 Tailwind CSS + CSS Modules,并提到 `@uiw/react-md-editor`;但当前 `package.json` 未包含 Tailwind 或该 Markdown Editor 依赖,项目样式以普通 CSS 为主,Markdown 相关实现使用 ByteMD 等依赖。
**NexDocus 参考项目当时的处理建议(非通用规则):** README、项目配置和真实依赖必须同步。Agent 不得把 README 中过期描述当作新增依赖的依据。
### K. 质量检查脚本尚未覆盖 UI 回归(中优先级)
当前 package scripts 包含 dev/build/lint/lint:strict,但没有独立的前端测试、视觉回归或主题截图检查脚本。
**NexDocus 参考项目当时的处理建议(非通用规则):** 第一阶段保留现有脚本;后续为核心共享组件加入组件测试和 Playwright 视觉基线。不得在没有安装/配置时声称这些测试已经执行。
## 5. 推荐处理优先级
| 优先级 | 问题 | 处理方式 |
|---|---|---|
| P0 | token 与真实布局尺寸冲突 | 统一 Header/Sider 尺寸事实来源 |
| P0 | CSS 与 AntD 主题重复维护 | 建立单一 token 来源 |
| P0 | 普通 CSS 中的 `:global` | 改成有效的普通 CSS 选择器 |
| P1 | 业务页颜色硬编码 | 建立语义 token,分批迁移 |
| P1 | 共享页面模式未全面采用 | 先统一列表/表单/详情复合组件 |
| P1 | 点击 div 的键盘可达性 | 更换为语义化 button/link |
| P1 | 标题 Banner 使用范围不清 | 标准页头与 Hero 页头分离 |
| P2 | 固定表格高度与响应式细节 | 结合视口和真实页面调整 |
| P2 | README 与依赖漂移 | 修订项目文档和 Agent 入口 |
| P2 | 缺少视觉回归 | 建立核心页面截图基线 |
## 6. 本次不建议做的事情
- 不建议把所有页面统一改成相同的卡片堆叠样式。
- 不建议把文档编辑器、聊天工作区强制改造成普通后台表格页面。
- 不建议仅凭源代码就擅自换掉目前的品牌蓝和整体视觉路线。
- 不建议为了“统一”而给每个 Ant Design 原生组件都创建一层无差异的包装。
- 不建议一次性替换所有 CSS 颜色;应先确定 token 语义再迁移。
- 不建议在 NEX 规范确立前直接重写整个前端。
## 7. 总体判断
NexDocus 已经有可复用的视觉基础和一批成熟的专业工作区组件,问题不是“没有设计”,而是**设计决策分散在 token、Ant Design 主题、共享组件和页面私有 CSS 中,且历史修正尚未沉淀为可验证的统一规则**。
该参考项目当时更适合先提炼、校准并建立约束,再落实到组件与质量门禁,而不是先做大规模视觉翻新。该建议仅用于理解本次参考项目的审计背景。