619 lines
18 KiB
Markdown
619 lines
18 KiB
Markdown
# 011-vue.mdc (Deep Reference)
|
||
|
||
> 该文件为原始详细规范归档，供 Tier 3 按需读取。
|
||
|
||
---
|
||
|
||
|
||
# 🟢 Vue 3 / Vite Standards
|
||
|
||
> **⚠️ 双前端区分**：本文件中的 Element Plus 相关内容**仅适用于管理端** (`Case-Database-Frontend-admin/`)。
|
||
> 用户端 (`Case-Database-Frontend-user/`) 使用 Headless UI + Tailwind CSS，**禁止引入 Element Plus**。
|
||
|
||
## 组件规范
|
||
|
||
- **所有组件使用 `<script setup>`**（Composition API + 语法糖，不使用 `lang` 类型标注）
|
||
- 禁止 Options API（除非集成第三方库）
|
||
- 禁止 Class 组件
|
||
- 组件嵌套不超过 3 层，超过则拆分
|
||
- 使用 `defineProps` + `defineEmits` 声明接口（编译时宏，无需导入）
|
||
- Named exports for composables；组件文件本身使用 default export（Vue 惯例）
|
||
|
||
## 项目目录结构
|
||
|
||
```
|
||
src/
|
||
├── api/ # API 接口层（按业务模块分目录）
|
||
│ ├── production/ # 生产管理 API
|
||
│ ├── auth.ts # 认证 API
|
||
│ └── common.ts # 通用 API
|
||
├── assets/ # 静态资源
|
||
│ ├── styles/ # 全局样式 (SCSS)
|
||
│ ├── icons/ # 图标
|
||
│ └── images/ # 图片
|
||
├── components/ # 公共组件
|
||
│ ├── core/ # 核心通用组件
|
||
│ └── custom/ # 业务组件
|
||
├── config/ # 前端配置
|
||
├── directives/ # 自定义指令
|
||
├── hooks/ # 组合式函数
|
||
├── layouts/ # 布局组件
|
||
├── locales/ # 国际化
|
||
├── router/ # 路由配置
|
||
│ ├── guards/ # 路由守卫
|
||
│ └── routes/ # 路由定义
|
||
├── store/ # Pinia 状态管理
|
||
│ └── modules/ # Store 模块
|
||
├── types/ # JSDoc 类型定义（可选，.ts 文件）
|
||
├── utils/ # 工具函数
|
||
│ ├── request.ts # Axios 封装
|
||
│ ├── storage/ # 本地存储工具
|
||
│ └── websocket/ # WebSocket 工具
|
||
└── views/ # 页面视图（按业务模块）
|
||
├── auth/ # 认证页面
|
||
├── dashboard/ # 仪表盘
|
||
└── production/ # 生产管理
|
||
```
|
||
|
||
## 组件模板
|
||
|
||
```vue
|
||
<script setup>
|
||
const props = defineProps({
|
||
variant: {
|
||
type: String,
|
||
default: 'primary', // 'primary' | 'secondary' | 'ghost'
|
||
},
|
||
size: {
|
||
type: String,
|
||
default: 'default', // 'small' | 'default' | 'large'
|
||
},
|
||
disabled: {
|
||
type: Boolean,
|
||
default: false,
|
||
},
|
||
})
|
||
|
||
const emit = defineEmits(['click'])
|
||
</script>
|
||
|
||
<template>
|
||
<el-button
|
||
:type="props.variant === 'ghost' ? 'default' : props.variant"
|
||
:size="props.size"
|
||
:disabled="props.disabled"
|
||
@click="emit('click', $event)"
|
||
>
|
||
<slot />
|
||
</el-button>
|
||
</template>
|
||
```
|
||
|
||
## Element Plus 使用规范（仅管理端）
|
||
|
||
> 以下内容仅适用于 `Case-Database-Frontend-admin/`，用户端禁止使用 Element Plus。
|
||
|
||
- **按需导入**：使用 `unplugin-vue-components` + `unplugin-auto-import` 自动导入
|
||
- **表单验证**：使用 Element Plus 内置 `el-form` rules，复杂场景配合 `async-validator`
|
||
- **主题定制**：通过 SCSS 变量覆盖 Element Plus 默认主题
|
||
- **图标**：使用 `@element-plus/icons-vue`，按需导入
|
||
|
||
```typescript
|
||
// vite.config.ts 自动导入配置
|
||
import AutoImport from 'unplugin-auto-import/vite'
|
||
import Components from 'unplugin-vue-components/vite'
|
||
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
|
||
|
||
export default defineConfig({
|
||
plugins: [
|
||
AutoImport({ resolvers: [ElementPlusResolver()] }),
|
||
Components({ resolvers: [ElementPlusResolver()] }),
|
||
],
|
||
})
|
||
```
|
||
|
||
## 状态管理选择
|
||
|
||
| 场景 | 方案 |
|
||
|------|------|
|
||
| 组件内部 | `ref` / `reactive` |
|
||
| 计算属性 | `computed` |
|
||
| 跨组件共享 | **Pinia** (`defineStore`) |
|
||
| 服务端状态 | Axios + Pinia Action |
|
||
| 表单验证 | 管理端：Element Plus `el-form` rules；用户端：自定义验证 |
|
||
| URL 状态 | `useRoute` / `useRouter`（vue-router） |
|
||
|
||
## Axios 封装规范
|
||
|
||
```typescript
|
||
// src/utils/request.ts
|
||
import axios from 'axios'
|
||
|
||
const service = axios.create({
|
||
baseURL: import.meta.env.VITE_API_URL,
|
||
timeout: 60000,
|
||
headers: { 'Content-Type': 'application/json;charset=UTF-8' },
|
||
})
|
||
|
||
// Request interceptor: inject token
|
||
service.interceptors.request.use((config) => {
|
||
const token = localStorage.getItem('access_token')
|
||
if (token) {
|
||
config.headers.Authorization = `Bearer ${token}`
|
||
}
|
||
return config
|
||
})
|
||
|
||
// Response interceptor: unified error handling
|
||
service.interceptors.response.use(
|
||
(response) => {
|
||
const { code, data, message } = response.data
|
||
if (code === 200) return data
|
||
return Promise.reject(new Error(message || 'Request failed'))
|
||
},
|
||
(error) => {
|
||
if (error.response?.status === 401) {
|
||
// Token expired -> redirect to login
|
||
}
|
||
return Promise.reject(error)
|
||
},
|
||
)
|
||
```
|
||
|
||
## Vue Router 路由规范
|
||
|
||
```typescript
|
||
// src/router/guards/auth.ts
|
||
export function setupAuthGuard(router) {
|
||
router.beforeEach(async (to, _from, next) => {
|
||
const token = localStorage.getItem('access_token')
|
||
|
||
if (to.meta.requiresAuth && !token) {
|
||
return next({ name: 'login', query: { redirect: to.fullPath } })
|
||
}
|
||
|
||
// Dynamic route loading for RBAC
|
||
if (token && !hasLoadedDynamicRoutes()) {
|
||
await loadDynamicRoutes(router)
|
||
return next({ ...to, replace: true })
|
||
}
|
||
|
||
next()
|
||
})
|
||
}
|
||
```
|
||
|
||
## Composables 目录约定
|
||
|
||
所有 composable 位于 `src/hooks/`，以 `use` 前缀命名：
|
||
|
||
| Composable | 职责 | 返回值 |
|
||
|------------|------|--------|
|
||
| `useTable` | 表格数据加载、分页、搜索、排序 | `{ loading, dataList, pagination, loadData, handleSearch, handleReset }` |
|
||
| `useForm` | 表单状态、校验、提交 | `{ formRef, formData, rules, loading, handleSubmit, handleReset }` |
|
||
| `useAuth` | 权限判断、按钮/菜单可见性 | `{ hasAuth, hasRole, checkPermission }` |
|
||
| `useCommon` | 通用工具（字典、枚举转换） | `{ getDictLabel, formatEnum }` |
|
||
| `useFastEnter` | 快速导航、全局搜索 | `{ visible, keyword, results, navigate }` |
|
||
| `useHeaderBar` | 顶部栏状态（全屏、消息、用户） | `{ isFullscreen, toggleFullscreen, unreadCount }` |
|
||
| `useSmsCode` | 短信验证码倒计时 | `{ countdown, isSending, sendCode }` |
|
||
| `useTableColumns` | 表格列配置、列显隐持久化 | `{ columns, visibleColumns, toggleColumn }` |
|
||
| `useTheme` | 主题切换 + 系统跟随 | `{ isDark, toggleTheme, colorPrimary }` |
|
||
| `useChart` | ECharts 实例管理、自动 resize | `{ chartRef, setOption, resize }` |
|
||
| `useWebSocket` | WebSocket 连接管理 | `{ connect, disconnect, send, onMessage }` |
|
||
|
||
```typescript
|
||
// src/hooks/useTable.ts — 标准实现
|
||
export function useTable(fetchFn) {
|
||
const loading = ref(false)
|
||
const dataList = ref([])
|
||
const pagination = reactive({ current: 1, size: 10, total: 0 })
|
||
const searchForm = reactive({})
|
||
|
||
async function loadData() {
|
||
loading.value = true
|
||
try {
|
||
const result = await fetchFn({
|
||
page: pagination.current,
|
||
page_size: pagination.size,
|
||
...searchForm,
|
||
})
|
||
dataList.value = result.data
|
||
pagination.total = result.total
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
function handleSearch() {
|
||
pagination.current = 1
|
||
loadData()
|
||
}
|
||
|
||
function handleReset() {
|
||
Object.keys(searchForm).forEach((key) => { searchForm[key] = undefined })
|
||
handleSearch()
|
||
}
|
||
|
||
function handlePageChange(page) {
|
||
pagination.current = page
|
||
loadData()
|
||
}
|
||
|
||
return { loading, dataList, pagination, searchForm, loadData, handleSearch, handleReset, handlePageChange }
|
||
}
|
||
```
|
||
|
||
## 自定义指令
|
||
|
||
所有指令位于 `src/directives/`：
|
||
|
||
| 指令 | 用途 | 用法示例 |
|
||
|------|------|---------|
|
||
| `v-auth` | 按钮级权限控制（权限标识） | `v-auth="'system:user:add'"` |
|
||
| `v-roles` | 角色级权限控制 | `v-roles="['admin', 'manager']"` |
|
||
| `v-focus` | 自动聚焦输入框 | `v-focus` |
|
||
| `v-highlight` | 搜索关键词高亮 | `v-highlight="keyword"` |
|
||
| `v-index` | 序号自动生成 | `v-index="{ page, size }"` |
|
||
| `v-ripple` | 点击波纹效果 | `v-ripple` |
|
||
|
||
```typescript
|
||
// src/directives/auth.ts
|
||
import { useUserStore } from '@/store/modules/user'
|
||
|
||
export const vAuth = {
|
||
mounted(el, binding) {
|
||
const userStore = useUserStore()
|
||
if (!userStore.permissions.includes(binding.value)) {
|
||
el.parentNode?.removeChild(el)
|
||
}
|
||
},
|
||
}
|
||
|
||
// src/directives/roles.ts
|
||
export const vRoles = {
|
||
mounted(el, binding) {
|
||
const userStore = useUserStore()
|
||
const hasRole = binding.value.some((role) => userStore.roles.includes(role))
|
||
if (!hasRole) {
|
||
el.parentNode?.removeChild(el)
|
||
}
|
||
},
|
||
}
|
||
```
|
||
|
||
## 布局组件约定
|
||
|
||
布局组件位于 `src/layouts/`：
|
||
|
||
| 组件 | 职责 |
|
||
|------|------|
|
||
| `ArtSidebarMenu` | 侧边导航菜单（递归菜单树） |
|
||
| `ArtHeader` | 顶部栏（面包屑 + 用户 + 通知 + 全屏） |
|
||
| `ArtWorkTab` | 多标签页管理（右键菜单、拖拽排序） |
|
||
| `ArtNotification` | 通知面板（WebSocket 实时推送） |
|
||
| `ArtChatWindow` | 即时通讯窗口 |
|
||
| `ArtFastEnter` | 全局快速搜索导航（Ctrl+K） |
|
||
| `ArtGlobalSearch` | 全局搜索弹窗 |
|
||
|
||
## Pinia Store 模块映射
|
||
|
||
| Store | 职责 | 持久化 | 加密 |
|
||
|-------|------|--------|------|
|
||
| `user` | 用户信息、Token、权限、角色 | ✅ | ✅ Token 加密 |
|
||
| `menu` | 菜单树、动态路由 | ✅ | ❌ |
|
||
| `setting` | 主题、布局、语言设置 | ✅ | ❌ |
|
||
| `worktab` | 标签页状态 | ✅ | ❌ |
|
||
| `table` | 表格列配置、列显隐 | ✅ | ❌ |
|
||
| `notification` | 通知消息、未读计数 | ❌ | ❌ |
|
||
| `workflow` | 审批流程状态 | ❌ | ❌ |
|
||
| `product` | 产品/生产模块状态 | ❌ | ❌ |
|
||
| `outsideflow` | 外部审批流程 | ❌ | ❌ |
|
||
|
||
```typescript
|
||
// Pinia 加密持久化示例
|
||
import CryptoJS from 'crypto-js'
|
||
|
||
const ENCRYPT_KEY = import.meta.env.VITE_STORAGE_KEY || 'default-key'
|
||
|
||
function encrypt(data) {
|
||
return CryptoJS.AES.encrypt(data, ENCRYPT_KEY).toString()
|
||
}
|
||
|
||
function decrypt(data) {
|
||
return CryptoJS.AES.decrypt(data, ENCRYPT_KEY).toString(CryptoJS.enc.Utf8)
|
||
}
|
||
|
||
export const useUserStore = defineStore('user', () => {
|
||
// ... state and actions
|
||
}, {
|
||
persist: {
|
||
key: 'user-store',
|
||
storage: {
|
||
getItem: (key) => {
|
||
const raw = localStorage.getItem(key)
|
||
return raw ? decrypt(raw) : null
|
||
},
|
||
setItem: (key, value) => {
|
||
localStorage.setItem(key, encrypt(value))
|
||
},
|
||
},
|
||
pick: ['token', 'refreshToken'],
|
||
},
|
||
})
|
||
```
|
||
|
||
## 路由守卫完整流程
|
||
|
||
```typescript
|
||
// src/router/guards/index.ts
|
||
import NProgress from 'nprogress'
|
||
import { useUserStore } from '@/store/modules/user'
|
||
import { useMenuStore } from '@/store/modules/menu'
|
||
import { useWorktabStore } from '@/store/modules/worktab'
|
||
|
||
const WHITE_LIST = ['/login', '/register', '/404', '/403']
|
||
|
||
export function setupRouterGuards(router) {
|
||
router.beforeEach(async (to, _from, next) => {
|
||
NProgress.start()
|
||
document.title = `${to.meta.title || ''} - ${import.meta.env.VITE_APP_TITLE}`
|
||
|
||
const userStore = useUserStore()
|
||
const token = userStore.token
|
||
|
||
// Step 1: 白名单放行
|
||
if (WHITE_LIST.includes(to.path)) {
|
||
return next()
|
||
}
|
||
|
||
// Step 2: 无 Token -> 登录
|
||
if (!token) {
|
||
return next({ path: '/login', query: { redirect: to.fullPath } })
|
||
}
|
||
|
||
// Step 3: 已登录访问登录页 -> 首页
|
||
if (to.path === '/login') {
|
||
return next({ path: '/' })
|
||
}
|
||
|
||
// Step 4: 动态路由未加载 -> 加载
|
||
const menuStore = useMenuStore()
|
||
if (!menuStore.isRoutesLoaded) {
|
||
try {
|
||
await menuStore.loadDynamicRoutes(router)
|
||
return next({ ...to, replace: true })
|
||
} catch {
|
||
userStore.logout()
|
||
return next({ path: '/login' })
|
||
}
|
||
}
|
||
|
||
next()
|
||
})
|
||
|
||
router.afterEach((to) => {
|
||
NProgress.done()
|
||
|
||
// Step 5: 更新标签页
|
||
const worktabStore = useWorktabStore()
|
||
if (to.meta.title && !to.meta.hideTab) {
|
||
worktabStore.addTab({
|
||
path: to.path,
|
||
title: to.meta.title,
|
||
name: to.name,
|
||
})
|
||
}
|
||
})
|
||
}
|
||
```
|
||
|
||
## WebSocket 集成模式
|
||
|
||
```typescript
|
||
// src/utils/websocket/notification.ts
|
||
import { useUserStore } from '@/store/modules/user'
|
||
import { useNotificationStore } from '@/store/modules/notification'
|
||
|
||
class NotificationWebSocket {
|
||
ws = null
|
||
reconnectTimer = null
|
||
heartbeatTimer = null
|
||
reconnectAttempts = 0
|
||
maxReconnectAttempts = 5
|
||
|
||
connect() {
|
||
const userStore = useUserStore()
|
||
if (!userStore.token) return
|
||
|
||
const wsUrl = `${import.meta.env.VITE_WS_URL}?token=${userStore.token}`
|
||
this.ws = new WebSocket(wsUrl)
|
||
|
||
this.ws.onopen = () => {
|
||
this.reconnectAttempts = 0
|
||
this.startHeartbeat()
|
||
}
|
||
|
||
this.ws.onmessage = (event) => {
|
||
const message = JSON.parse(event.data)
|
||
this.handleMessage(message)
|
||
}
|
||
|
||
this.ws.onclose = () => {
|
||
this.stopHeartbeat()
|
||
this.tryReconnect()
|
||
}
|
||
}
|
||
|
||
handleMessage(message) {
|
||
const notificationStore = useNotificationStore()
|
||
switch (message.type) {
|
||
case 'notification':
|
||
notificationStore.addNotification(message.data)
|
||
break
|
||
case 'heartbeat':
|
||
// Pong
|
||
break
|
||
}
|
||
}
|
||
|
||
startHeartbeat() {
|
||
this.heartbeatTimer = setInterval(() => {
|
||
this.ws?.send(JSON.stringify({ type: 'heartbeat', data: 'ping' }))
|
||
}, 30000)
|
||
}
|
||
|
||
stopHeartbeat() {
|
||
if (this.heartbeatTimer) clearInterval(this.heartbeatTimer)
|
||
}
|
||
|
||
tryReconnect() {
|
||
if (this.reconnectAttempts >= this.maxReconnectAttempts) return
|
||
this.reconnectTimer = setTimeout(() => {
|
||
this.reconnectAttempts++
|
||
this.connect()
|
||
}, Math.min(1000 * 2 ** this.reconnectAttempts, 30000))
|
||
}
|
||
|
||
disconnect() {
|
||
this.stopHeartbeat()
|
||
if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
|
||
this.ws?.close()
|
||
this.ws = null
|
||
}
|
||
}
|
||
|
||
export const notificationWs = new NotificationWebSocket()
|
||
```
|
||
|
||
## 性能检查清单
|
||
|
||
- [ ] 路由使用 `() => import()` 懒加载
|
||
- [ ] 列表使用稳定 `:key`（非 index）
|
||
- [ ] 大列表使用虚拟化（`@tanstack/vue-virtual`）
|
||
- [ ] 使用 `defineAsyncComponent` 做组件懒加载
|
||
- [ ] 避免在 `<template>` 中写复杂表达式，提取为 `computed`
|
||
- [ ] 动态组件使用 `shallowRef` 存储组件引用
|
||
- [ ] 管理端：Element Plus 按需导入，避免全量引入（用户端不使用 Element Plus）
|
||
- [ ] Vite 构建配置 `manualChunks` 分离 vendor
|
||
- [ ] Pinia 敏感数据（Token）使用加密持久化
|
||
- [ ] WebSocket 连接登录后建立，登出后断开
|
||
|
||
## Props 反模式全集
|
||
|
||
> 以下案例来源于项目实际 ESLint 修复（`vue/no-mutating-props`），作为永久参考。
|
||
|
||
### 场景 A：表单子组件 v-model 直接修改对象 prop
|
||
|
||
父组件传递 `reactive` 对象作为 prop，子组件用 `v-model` 直接绑定其字段。
|
||
|
||
```vue
|
||
<!-- ❌ ForgotPanel.vue — 直接修改 prop.form 的字段 -->
|
||
<script setup>
|
||
defineProps<{
|
||
form: { username: string; phone: string; code: string }
|
||
}>()
|
||
</script>
|
||
<template>
|
||
<AppInput v-model="form.username" />
|
||
<AppInput v-model="form.phone" />
|
||
<AppInput v-model="form.code" />
|
||
</template>
|
||
```
|
||
|
||
```vue
|
||
<!-- ✅ 修复后 — 通过 emit 通知父组件更新 -->
|
||
<script setup>
|
||
type FormData = { username: string; phone: string; code: string }
|
||
|
||
const props = defineProps<{ form: FormData }>()
|
||
const emit = defineEmits<{ 'update:form': [value: FormData] }>()
|
||
|
||
function updateField(field: keyof FormData, value: string) {
|
||
emit('update:form', { ...props.form, [field]: value })
|
||
}
|
||
</script>
|
||
<template>
|
||
<AppInput :model-value="form.username" @update:model-value="updateField('username', $event)" />
|
||
<AppInput :model-value="form.phone" @update:model-value="updateField('phone', $event)" />
|
||
<AppInput :model-value="form.code" @update:model-value="updateField('code', $event)" />
|
||
</template>
|
||
```
|
||
|
||
**父组件响应**：`@update:form="Object.assign(formData, $event)"`
|
||
|
||
### 场景 B：筛选器子组件动态 key 修改 prop
|
||
|
||
子组件通过 `v-model` 绑定 `prop[dynamicKey]`，遍历配置项时逐个修改 prop 的属性。
|
||
|
||
```vue
|
||
<!-- ❌ FilterDrawerBody.vue — v-model 绑定动态 prop key -->
|
||
<RadioGroup v-model="radios[f.key]" :options="f.options" />
|
||
<CheckboxGroup v-model="checkboxes[f.key]" :options="f.options" />
|
||
<SelectField v-model="selects[f.key]" :options="f.options" />
|
||
```
|
||
|
||
```vue
|
||
<!-- ✅ 修复后 — 拆分为 :model-value + emit -->
|
||
<RadioGroup
|
||
:model-value="radios[f.key]"
|
||
:options="f.options"
|
||
@update:model-value="emit('update:radio', f.key, $event)"
|
||
/>
|
||
<CheckboxGroup
|
||
:model-value="checkboxes[f.key]"
|
||
:options="f.options"
|
||
@update:model-value="emit('update:checkbox', f.key, $event)"
|
||
/>
|
||
<SelectField
|
||
:model-value="selects[f.key]"
|
||
:options="f.options"
|
||
@update:model-value="emit('update:select', f.key, $event)"
|
||
/>
|
||
```
|
||
|
||
**父组件响应**：`@update:radio="(key, val) => radios[key] = val"`
|
||
|
||
### 场景 C：事件回调中赋值 prop 属性（隐蔽变体）
|
||
|
||
不通过 `v-model`，但在事件处理函数中直接赋值 prop 的属性。ESLint 同样检测为 prop mutation。
|
||
|
||
```vue
|
||
<!-- ❌ FilterDrawerBody.vue — 事件回调中直接赋值 prop -->
|
||
<LogicTable
|
||
:values="logics"
|
||
@update-logic="(k: string, v: string) => logics[k] = v"
|
||
/>
|
||
```
|
||
|
||
```vue
|
||
<!-- ✅ 修复后 — 转发为 emit，由父组件执行赋值 -->
|
||
<LogicTable
|
||
:values="logics"
|
||
@update-logic="(k: string, v: string) => emit('update:logic', k, v)"
|
||
/>
|
||
```
|
||
|
||
**父组件响应**：`@update:logic="(key, val) => logics[key] = val"`
|
||
|
||
### 附：事件命名规范
|
||
|
||
以上修复中同步修正了 `defineEmits` 的事件命名：
|
||
|
||
```typescript
|
||
// ❌ kebab-case（触发 vue/custom-event-name-casing）
|
||
defineEmits<{
|
||
'add-room-condition': []
|
||
'remove-room-condition': [id: number]
|
||
'update-room-condition': [id: number, field: string, value: string | number]
|
||
}>()
|
||
|
||
// ✅ camelCase
|
||
defineEmits<{
|
||
addRoomCondition: []
|
||
removeRoomCondition: [id: number]
|
||
updateRoomCondition: [id: number, field: string, value: string | number]
|
||
}>()
|
||
```
|
||
|
||
模板中 `@add-room-condition` 和 `@addRoomCondition` 均可，Vue 自动双向转换。
|