RAG/frontend/ui-ux.md

title	created	tags	summary	cover	updated
项目技术栈与开发规范	2026-06-03	[guide config work standard]	本文定义项目技术栈选型、z-index层级规范及响应式布局要求	/assets/default-cover.jpg	2026-08-15

技术栈规范

类别	技术选型	说明
前端框架	Vue 3 + JavaScript	不使用 TypeScript
构建工具	Vite + pnpm	包管理统一使用 pnpm
UI 框架	tdesign-vue-next	严格使用 TDesign 组件，尽可能少使用原始 HTML 标签
图标库	tdesign-icons-vue-next	所有 icon 统一使用 tdesign-icons-vue-next
状态管理	Pinia	全局状态集中管理
代码规范	eslint + @antfu/eslint-config	统一代码风格
工具库	xe-utils	对象、函数、数组、数字、字符串、URL、Web、计算、判空、数据处理统一使用
日期处理	dayjs	所有日期相关操作统一使用
Hooks 工具	vue-hooks-plus	复用 Vue 组合式交互逻辑、异步状态、DOM 事件、虚拟列表等 hooks

层级规范

层级	语义	使用场景
0	base	普通页面内容
10	raised	卡片 hover、轻微浮起元素
100	sticky	sticky 表头、吸顶筛选栏
200	local-floating	页面局部浮动按钮、局部工具栏
300	fixed-nav	顶部导航、移动端底部导航
400	dropdown	Dropdown、Select、DatePicker、AutoComplete
500	popover	Popup、Tooltip、Popconfirm
800	overlay-local	页面局部遮罩、局部 loading
1000	overlay	全局遮罩
1100	drawer	Drawer、侧边抽屉
1200	modal	Dialog
1300	modal-floating	Dialog 内部 Dropdown、Popup、Tooltip
1400	toast	Message、Notification
1500	global-loading	全屏 Loading、页面阻断加载
2000	onboarding	新手引导、产品引导遮罩
3000	system	系统级弹窗、强制升级、维护提示
9000	emergency	特殊兜底层，必须注释说明
9999	max	最高优先级，仅限极特殊场景

• 层级统一通过项目维护的 CSS 变量管理，如 --z-dropdown: 400、--z-drawer: 1100、--z-dialog: 1200、--z-message: 1400、--z-loading: 1500。
• TDesign 弹层组件（Dropdown、Popup、Dialog、Drawer、Message、Notification、Loading）通过主题变量或包裹层对齐上述层级，避免与项目 z-index 体系冲突。
• 0 ~ 500 为常规内容层级，1000 以上为弹层体系；不随意使用最高档位 --z-max。

Scroll 滚动规范

类别	规范	说明
滚动容器	单一主滚动区域	应用层只允许一个主滚动容器，禁止 body、main、组件多层嵌套滚动
页面滚动	Router 统一管理	禁止组件内部直接调用 window.scrollTo，统一通过路由滚动策略处理
滚动恢复	支持页面级 scroll restoration	列表页返回时恢复原滚动位置，普通页面进入默认滚动到顶部
滚动区域	明确 scroll-root	Layout 层定义主滚动容器，业务组件不得随意创建页面滚动区域
局部滚动	scroll-section	大列表、日志、代码区域等允许局部滚动，但必须明确高度和边界
弹窗滚动	Dialog / Drawer 独立滚动	弹窗内部内容滚动，不影响 body 滚动状态
Body 锁定	Overlay 打开时禁止背景滚动	Dialog、Drawer、全屏遮罩打开时锁定 body，关闭后恢复
Sticky	必须绑定正确滚动容器	sticky 元素必须位于对应 scroll container 内，避免定位失效
表格滚动	TDesign Table 统一处理	表格内部横向滚动，禁止页面整体横向滚动
表格固定	使用组件能力	TDesign Table 固定表头、固定列必须使用组件配置，不手写定位实现
大数据列表	必须虚拟滚动	超过指定数据量的大列表必须使用虚拟列表优化性能
滚动事件	Hook 统一封装	禁止页面散落 addEventListener，统一通过 useScroll 等 hooks 管理
滚动监听	必须节流优化	scroll 事件必须使用 throttle / requestAnimationFrame 降低性能消耗
滚动动画	局部启用 smooth	仅允许锚点跳转、返回顶部使用 smooth，禁止全局开启
减少动画	支持 prefers-reduced-motion	用户开启减少动画模式时关闭滚动动画效果
锚点定位	统一 scrollToAnchor	禁止业务组件直接调用 scrollIntoView，统一封装滚动方法
Sticky 偏移	使用 scroll-margin-top	页面存在固定导航时，锚点定位必须考虑顶部遮挡问题
返回顶部	local-floating 层级	返回顶部按钮使用 local-floating 层级（200），超过滚动阈值后显示，优先使用 TDesign BackTop 组件
横向滚动	禁止页面级横向滚动	页面禁止 overflow-x 滚动，特殊区域必须局部控制
移动端滚动	适配 Touch 滚动	支持 iOS / Android 惯性滚动，避免滚动卡顿
滚动高度稳定	避免 CLS	Skeleton、图片、异步内容必须保持高度稳定，避免滚动位置跳动
数据刷新	保留滚动上下文	刷新数据时保持当前滚动位置，不因重新渲染导致页面跳顶部
请求失败	保持用户上下文	请求失败进入错误态时保持当前滚动位置和已有数据
图片加载	预留尺寸	图片必须设置宽高或 aspect-ratio，避免加载造成页面跳动
虚拟列表	统一封装	虚拟滚动能力通过 hooks / 组件提供，禁止业务重复实现
滚动状态	禁止随意持久化	不允许直接 localStorage 保存 scrollTop，统一由滚动管理器维护
滚动性能	监控长任务	大量滚动计算必须避免阻塞主线程，必要时接入 Performance 监控
无障碍	支持键盘滚动	页面滚动区域必须保持键盘访问能力和 focus 可见性
滚动恢复清理	路由离开自动处理	页面卸载时清理滚动监听、缓存状态、事件绑定

布局

固定视口应用壳 + 圣杯布局 + 局部滚动 ┌──────────────── 固定顶部导航 ────────────────┐

│ 平台切换、全局操作、应用状态 │ ├──────────────┬──────────────────┬────────────┤ │ 左侧栏 │ 主内容区 │ 右侧栏 │ │ │ │ │ │ 配置列表 │ 配置编辑区 │ 环境检测 │ │ 平台导航 │ 独立局部滚动 │ 生成结果 │ │ 快捷操作 │ │ 状态信息 │ │ │ │ │ ├──────────────┴──────────────────┴────────────┤ │ 固定状态栏 │ └─────────────────────────────────────────────┘

响应式要求

• 支持移动端。
• 支持平板端。
• 页面必须使用响应式布局。

API 层标准化

类别	规范	说明
请求封装	Axios 二次封装	统一 baseURL、timeout、headers、错误处理
API 结构	按模块拆分	api/modules/*.api.js，禁止写在组件内
请求拦截	Token + Error 统一处理	自动注入 token、统一处理 401/500
响应结构	标准化返回	{ code, data, message } 统一格式
错误处理	全局错误中心	Message + 日志 + 可选上报
取消请求	AbortController	页面切换自动取消未完成请求
并发控制	防重复请求	相同 key 请求去重
Loading 管理	请求级 + 页面级	避免手动控制 loading 状态

---

Skeleton / Loading 规范

场景	优先方案	说明
首屏加载	页面骨架屏	模拟真实页面结构，避免白屏和布局跳动
模块加载	局部骨架屏	卡片、列表、表格、详情区按实际内容占位
数据刷新	保留旧数据 + 局部 Loading	不清空页面，避免用户失去上下文
表单提交	按钮 Loading + 禁用提交按钮	防重复提交，提交中保留表单内容
表格加载	TDesign Table loading / 表格骨架	表头固定，行高稳定，禁止整页遮罩替代表格加载
路由切换	页面级 Loading	只在跨页面等待明显时使用，优先展示目标页骨架
阻断型任务	全局 Loading	仅限鉴权初始化、应用启动、强制等待等不可交互场景

• 骨架屏必须贴近真实布局：标题、头像、卡片、表格行、按钮区域要按最终尺寸占位，禁止使用一整块灰色矩形糊弄。
• 骨架屏风格必须匹配 TDesign 设计语言：圆角、柔和底色、轻微点状或软边框质感；禁止使用生硬的默认灰阶风格。
• 骨架元素必须有稳定宽高、min-height 或固定行高，加载完成前后不能造成明显 CLS。
• 首次进入页面优先使用骨架屏；只有小面积异步操作、按钮提交、短时请求才使用 spinner / loading icon。
• 局部 Loading 使用层级 --z-overlay-local: 800；全屏 Loading 使用 --z-global-loading: 1500，不得随意使用最高档位。
• 加载超过 3 秒必须展示明确状态文案；超过 8 秒必须提供重试、取消或返回入口。
• 请求失败后必须进入错误态，数据为空必须进入空态，不能让 loading 无限停留。
• 页面级异步状态应由 composable、Pinia 或 API SDK 统一管理；禁止在多个组件里散落重复的 isLoading 和手写请求状态。
• 对刷新类请求，应优先保留已有数据并展示局部刷新状态；只有首次无数据时才用完整骨架屏。
• 动效必须克制，遵守 prefers-reduced-motion；骨架 shimmer 不得过亮、过快或大面积闪烁。
• Loading 文案使用业务语义，如“正在生成配置”“正在同步状态”；禁止只有“Loading...”且无上下文。

测试体系规范

类别	工具	说明
单元测试	Vitest	逻辑函数、工具库必须覆盖
组件测试	Vue Test Utils	关键 UI 组件行为测试
E2E 测试	Playwright	核心业务流程（登录/下单/操作链路）
Mock 数据	MSW / Vitest mock	API 层隔离测试
覆盖率	Vitest coverage	核心模块 ≥ 80%
测试范围	分级测试	utils > service > component > flow
CI 集成	GitHub Actions / GitLab CI	每次 PR 必跑测试
回归策略	关键路径回归	核心业务必须 e2e 覆盖

---

规范约束体系

类别	规范	说明
代码风格	eslint + @antfu/eslint-config	全项目统一风格
组件规范	三层结构	Base / Layout / Business
命名规范	语义化命名	禁止 a/b/c、data1 这种变量
引用规范	禁止跨 feature 引用	feature 之间不能直接依赖
import 顺序	规范化排序	外部库 → 内部模块 → 相对路径
目录约束	feature-first	按业务模块组织代码
JSDoc	JS 类型补强	无 TS 场景必须写 JSDoc

---

性能 & 监控兜底

类别	方案	说明
路由优化	Vue Router lazy load	页面级懒加载
代码拆分	Vite manualChunks	vendor / core / feature 分包
静态资源	图片懒加载	IntersectionObserver
列表优化	虚拟列表	大数据列表必须使用
缓存策略	HTTP + localStorage	关键数据缓存
错误监控	Sentry / 自建日志	JS 错误 + API 错误上报
性能监控	Web Vitals	LCP / FID / CLS 监控
请求监控	API 耗时统计	slow request 记录
白屏兜底	loading + fallback	首屏异常兜底页面
全局异常	errorHandler	Vue + Promise 统一捕获
资源压缩	gzip / brotli	Vite compression 插件
降级策略	feature flag	异常时关闭非核心功能

---

目录结构规范（Feature First）

层级	目录	说明
核心层	src/core	项目级能力（request、router、store 初始化）
通用层	src/shared	纯工具 / 通用组件 / hooks
业务层	src/features	按业务模块拆分（核心规范）
UI层	src/components	全局通用组件
布局层	src/layouts	页面布局结构
页面层	src/pages	路由入口页面
API层	src/api	API SDK（模块化）
状态层	src/stores	Pinia store
资源层	src/assets	图片 / 样式 / 字体
配置层	src/config	环境配置、常量

---

ENV 文件规范

类别	规范	说明
环境文件	.env 分层管理	.env / .env.development / .env.staging / .env.production
变量前缀	VITE_ 必须前缀	Vite 仅暴露 VITE_ 开头变量
命名规范	大写 + 下划线	如 VITE_API_BASE_URL
使用方式	统一 env 封装访问	禁止直接使用 import.meta.env
环境区分	mode 控制	vite --mode staging
mock控制	env 控制 mock 开关	VITE_MOCK=true/false
API绑定	baseURL 由 env 控制	不允许写死 API 地址

类别	规范	说明
API层	request 统一读取 env	baseURL 从 env 注入
配置层	src/config/env.js	统一封装 env 读取
业务层	禁止直接读取 env	必须通过 config 层