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: '2026-06-03'tags: - guide - config - work - standardsummary: 本文定义项目技术栈选型、z-index层级规范及响应式布局要求cover: /assets/default-cover.jpgupdated: '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 层 |
|
