You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
| 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 层 |
