# Vue3 后台管理项目开发规范

## 项目概述

本项目是一个基于 Vue3 的后台管理系统，采用现代化技术栈构建，提供高效、美观的管理界面。

## 技术栈

- **Vue 3**: 渐进式 JavaScript 框架
- **Vite**: 下一代前端构建工具
- **Ant Design Vue**: 基于 Vue 3 的 UI 组件库
- **Vue Router**: Vue.js 官方路由管理器
- **Pinia**: Vue 3 官方状态管理库
- **Axios**: HTTP 客户端
- **JavaScript**: 主要开发语言（非 TypeScript）
- **Composition API**: 组合式 API 开发模式

## 图标系统

项目采用 Ant Design Vue 图标库，已全局引入：

- **Ant Design Vue Icons**: Ant Design Vue 官方图标库

**重要提示**: 图标已全局默认引入，开发时请勿重复引入或按需引入，直接使用即可。

## 开发规范

### 1. 项目结构

```
resources/admin/
├── src/
│   ├── api/                    # API 接口层
│   │   ├── auth.js            # 认证相关接口
│   │   ├── menu.js            # 菜单接口
│   │   └── system.js          # 系统相关接口
│   ├── assets/                 # 静态资源
│   │   ├── images/            # 图片资源
│   │   └── style/             # 全局样式
│   ├── components/             # 公共组件
│   │   ├── scEditor/          # 富文本编辑器
│   │   ├── scForm/            # 表单组件
│   │   ├── scIconPicker/      # 图标选择器
│   │   ├── scTable/           # 表格组件
│   │   └── scUpload/          # 上传组件
│   ├── config/                 # 配置文件
│   │   ├── index.js           # 主配置
│   │   ├── routes.js          # 路由配置
│   │   └── upload.js          # 上传配置
│   ├── hooks/                  # 组合式 API Hooks
│   │   ├── useI18n.js         # 国际化 Hook
│   │   └── useTable.js        # 表格 Hook
│   ├── i18n/                   # 国际化配置
│   │   ├── index.js           # i18n 配置
│   │   └── locales/           # 语言包
│   ├── layouts/                # 布局组件
│   │   ├── components/        # 布局子组件
│   │   ├── other/             # 其他布局
│   │   └── index.vue          # 主布局
│   ├── pages/                  # 页面组件
│   │   ├── auth/              # 认证页面
│   │   │   ├── users/         # 用户管理
│   │   │   │   ├── index.vue  # 主页面
│   │   │   │   └── components/ # 页面私有组件
│   │   │   │       ├── SaveDialog.vue      # 新增/编辑弹窗
│   │   │   │       ├── RoleDialog.vue      # 角色设置弹窗
│   │   │   │       └── DetailDialog.vue    # 详情弹窗
│   │   │   ├── roles/         # 角色管理
│   │   │   │   ├── index.vue
│   │   │   │   └── components/
│   │   │   │       ├── SaveDialog.vue
│   │   │   │       └── PermissionDialog.vue
│   │   │   └── ...
│   │   ├── home/              # 首页
│   │   ├── login/             # 登录页
│   │   ├── system/            # 系统管理
│   │   └── ucenter/           # 个人中心
│   ├── router/                 # 路由配置
│   │   ├── index.js           # 主路由
│   │   └── systemRoutes.js    # 系统路由
│   ├── stores/                 # 状态管理
│   │   ├── index.js           # Store 入口
│   │   ├── persist.js         # 持久化配置
│   │   └── modules/           # Store 模块
│   ├── utils/                  # 工具函数
│   │   ├── request.js         # Axios 封装
│   │   └── tool.js            # 工具函数
│   ├── App.vue                 # 根组件
│   ├── boot.js                 # 引导文件
│   ├── main.js                 # 入口文件
│   └── style.css               # 全局样式
├── public/                     # 公共资源
├── index.html                  # HTML 模板
├── package.json                # 依赖配置
├── vite.config.js             # Vite 配置
└── README.md                   # 项目说明
```

### 2. 页面组件开发规范

#### 页面组件目录结构

每个页面模块应遵循以下目录结构：

```
pages/
└── {module}/                # 模块目录（如 auth, system 等）
    └── {resource}/         # 资源目录（如 users, roles 等）
        ├── index.vue       # 主页面（列表页）
        └── components/      # 页面私有组件目录
            ├── SaveDialog.vue       # 新增/编辑弹窗（字段较少时使用）
            ├── SaveDrawer.vue       # 新增/编辑抽屉（字段较多时使用）
            ├── DetailDialog.vue     # 详情弹窗
            ├── RoleDialog.vue       # 角色设置弹窗
            ├── SearchDrawer.vue    # 高级搜索抽屉
            └── ...                  # 其他页面专用组件
```

**目录结构说明**:
- `index.vue`: 页面的主入口组件，通常是列表展示页面
- `components/`: 存放该页面专用的私有组件
  - 弹窗/抽屉组件：根据表单字段数量选择使用弹窗或抽屉
    - 字段较少（3-5个）：使用 `*Dialog.vue` 弹窗组件
    - 字段较多（5个以上）：使用 `*Drawer.vue` 抽屉组件
  - `SaveDialog.vue` / `SaveDrawer.vue`: 用于新增和编辑数据的表单组件
  - `DetailDialog.vue`: 用于查看数据详情的弹窗
  - `SearchDrawer.vue`: 用于高级搜索条件的抽屉组件
  - 其他与该页面紧密关联的组件

**组件命名规范**:
- 页面私有组件使用 PascalCase 命名
- 建议以功能命名：
  - 表单类：`SaveDialog.vue`, `SaveDrawer.vue`, `EditDialog.vue` 等
  - 功能类：`RoleDialog.vue`, `PermissionDialog.vue` 等
  - 搜索类：`SearchDrawer.vue`
- 避免 `Dialog.vue` 或 `Drawer.vue` 这样过于通用的命名

#### 页面布局规范

**基本布局要求**:

1. **使用 Flex 布局**: 页面容器必须使用 Flex 布局，确保占满全部内容区域
2. **表格高度自适应**: 表格使用封装的 `scTable` 组件，高度占满剩余内容空间

**标准页面布局模板**:

```vue
<template>
  <div class="pages {module}-{resource}-page">
    <!-- 工具栏区域 -->
    <div class="tool-bar">
      <div class="left-panel">
        <!-- 搜索表单 -->
      </div>
      <div class="right-panel">
        <!-- 操作按钮 -->
      </div>
    </div>
    
    <!-- 表格内容区域 -->
    <div class="table-content">
      <scTable
        :columns="columns"
        :data-source="tableData"
        :loading="loading"
        :pagination="pagination"
        :row-key="rowKey"
        @refresh="refreshTable"
        @paginationChange="handlePaginationChange"
      />
    </div>
  </div>
</template>

<style scoped lang="scss">
.{module}-{resource}-page {
  display: flex;
  flex-direction: column;
  height: 100%;
  padding: 0;

  .tool-bar {
    // 工具栏样式
  }

  .table-content {
    flex: 1;
    overflow: hidden;
  }
}
</style>
```

**布局样式说明**:
- 页面根元素使用 `display: flex` 和 `flex-direction: column` 实现垂直布局
- `height: 100%` 确保页面占满父容器高度
- `padding: 0` 去除内边距（由布局组件控制外边距）
- `table-content` 使用 `flex: 1` 占据剩余空间
- `overflow: hidden` 防止出现滚动条（表格内部自己处理滚动）

**侧边栏布局示例** (如用户管理页面):

```vue
<template>
  <div class="pages user-page">
    <!-- 左侧部门树 -->
    <div class="left-box">
      <div class="header">
        <!-- 搜索框 -->
      </div>
      <div class="body">
        <!-- 树形组件 -->
      </div>
    </div>
    
    <!-- 右侧内容区 -->
    <div class="right-box">
      <!-- 工具栏 -->
      <div class="tool-bar">...</div>
      
      <!-- 表格 -->
      <div class="table-content">...</div>
    </div>
  </div>
</template>

<style scoped lang="scss">
.user-page {
  display: flex;
  flex-direction: row;
  height: 100%;
  padding: 0;

  .left-box {
    width: 260px;
    border-right: 1px solid #f0f0f0;
    display: flex;
    flex-direction: column;
    background: #fff;

    .header {
      padding: 12px 16px;
      border-bottom: 1px solid #f0f0f0;
      background: #fafafa;
    }

    .body {
      flex: 1;
      overflow-y: auto;
      padding: 16px;
    }
  }

  .right-box {
    flex: 1;
    display: flex;
    flex-direction: column;
    overflow: hidden;

    .table-content {
      flex: 1;
      overflow: hidden;
      background: #f5f5f5;
    }
  }
}
</style>
```

#### 列表搜索区域规范

**搜索区域设计原则**:

1. **精简显示**: 搜索条件不全部显示，只显示最常用的 1-2 项
2. **去除 label 属性**: 搜索输入框不使用 label 属性，通过 placeholder 直接说明用途，保持界面简洁
3. **优先使用表格筛选**: 对于状态等枚举类型的筛选，优先使用 Ant Design Vue Table 的自定义过滤器功能
4. **高级搜索抽屉**: 其他复杂搜索条件使用抽屉弹出（需要在页面 components 目录下创建 SearchDrawer.vue 组件）
5. **保持界面整洁**: 避免搜索区域占用过多空间

**实现方式**:

**方式一: 使用表格自定义筛选（推荐）**

```vue
<template>
  <div class="pages-base-layout role-page">
    <div class="tool-bar">
      <div class="left-panel">
        <a-space>
          <a-input v-model:value="searchForm.keyword" placeholder="角色名称" allow-clear style="width: 180px" />
          <a-button type="primary" @click="handleSearch">
            <template #icon><search-outlined /></template>
            搜索
          </a-button>
          <a-button @click="handleReset">
            <template #icon><redo-outlined /></template>
            重置
          </a-button>
        </a-space>
      </div>
      <div class="right-panel">
        <a-button type="primary" @click="handleAdd">
          <template #icon><plus-outlined /></template>
          新增
        </a-button>
      </div>
    </div>
    <div class="table-content">
      <scTable
        :columns="columns"
        :data-source="tableData"
        :loading="loading"
        :pagination="pagination"
        @refresh="refreshTable"
        @paginationChange="handlePaginationChange"
      />
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { useTable } from '@/hooks/useTable'

// 使用 useTable Hook
const {
  tableRef,
  searchForm,
  tableData,
  loading,
  pagination,
  handleSearch,
  handleReset,
  handlePaginationChange,
  refreshTable
} = useTable({
  api: api.roles.list.get,
  searchForm: {
    keyword: '',
    status: null
  },
  columns: [],
  needPagination: true
})

// 表格列配置（包含筛选器）
const columns = [
  { 
    title: '角色名称', 
    dataIndex: 'name', 
    key: 'name', 
    width: 200 
  },
  { 
    title: '描述', 
    dataIndex: 'description', 
    key: 'description', 
    ellipsis: true 
  },
  { 
    title: '状态', 
    dataIndex: 'status', 
    key: 'status', 
    width: 100, 
    align: 'center',
    filters: [
      { text: '正常', value: 1 },
      { text: '禁用', value: 0 }
    ],
    filterMultiple: false,
    slot: 'status'
  },
  // ...其他列
]
</script>
```

**方式二: 使用高级搜索抽屉（复杂搜索条件）**

```vue
<template>
  <div class="pages-base-layout user-page">
    <div class="tool-bar">
      <div class="left-panel">
        <a-space>
          <a-input v-model:value="searchForm.username" placeholder="用户名" allow-clear style="width: 140px" />
          <a-button type="primary" @click="handleSearch">搜索</a-button>
          <a-button @click="handleReset">重置</a-button>
          <a-button @click="showAdvancedSearch = true">高级搜索</a-button>
        </a-space>
      </div>
    </div>
    
    <div class="table-content">
      <scTable
        :columns="columns"
        :data-source="tableData"
        :loading="loading"
        :pagination="pagination"
        @refresh="refreshTable"
        @paginationChange="handlePaginationChange"
      />
    </div>
  </div>

  <!-- 高级搜索抽屉 -->
  <SearchDrawer
    v-model:visible="showAdvancedSearch"
    :form-data="searchForm"
    @confirm="handleAdvancedSearch"
  />
</template>

<script setup>
import { ref } from 'vue'
import { useTable } from '@/hooks/useTable'
import SearchDrawer from './components/SearchDrawer.vue'

const showAdvancedSearch = ref(false)

const handleAdvancedSearch = (formData) => {
  // 更新搜索表单数据
  Object.assign(searchForm, formData)
  showAdvancedSearch.value = false
  handleSearch()
}
</script>
```

**SearchDrawer.vue 组件示例**:

```vue
<template>
  <a-drawer v-model:open="visible" title="高级搜索" placement="right" width="400">
    <a-form :model="formData" :label-col="{ span: 6 }" :wrapper-col="{ span: 18 }">
      <a-form-item label="姓名">
        <a-input v-model:value="formData.real_name" placeholder="请输入姓名" allow-clear />
      </a-form-item>
      <a-form-item label="邮箱">
        <a-input v-model:value="formData.email" placeholder="请输入邮箱" allow-clear />
      </a-form-item>
      <a-form-item label="手机号">
        <a-input v-model:value="formData.phone" placeholder="请输入手机号" allow-clear />
      </a-form-item>
      <a-form-item label="状态">
        <a-select v-model:value="formData.status" placeholder="请选择状态" allow-clear>
          <a-select-option :value="1">正常</a-select-option>
          <a-select-option :value="0">禁用</a-select-option>
        </a-select>
      </a-form-item>
    </a-form>
    <template #footer>
      <a-space>
        <a-button @click="handleCancel">取消</a-button>
        <a-button type="primary" @click="handleConfirm">确定</a-button>
      </a-space>
    </template>
  </a-drawer>
</template>

<script setup>
defineProps({
  visible: Boolean,
  formData: {
    type: Object,
    default: () => ({})
  }
})

const emit = defineEmits(['update:visible', 'confirm'])

const handleCancel = () => {
  emit('update:visible', false)
}

const handleConfirm = () => {
  emit('confirm', { ...formData })
}
</script>
```

**搜索条件选择建议**:

常用搜索条件（显示在工具栏）:
- 主要关键字搜索（如用户名、角色名称）
- 无需筛选的简单字段

表格筛选（推荐用于）:
- 状态、类型等枚举值字段
- 不需要组合条件的单一筛选

高级搜索抽屉（用于）:
- 次要字段（如邮箱、手机号）
- 日期范围筛选
- 多条件组合筛选
- 复杂的搜索逻辑

**scTable 组件筛选器优化说明**:

scTable 组件已支持 Ant Design Vue Table 的筛选功能，使用方式：

1. 在 `columns` 配置中添加 `filters` 属性
2. 通过 `@filterChange` 事件处理筛选变化
3. 将筛选条件合并到搜索表单中提交

```javascript
// 在 useTable Hook 中处理筛选变化
const handleFilterChange = (pagination, filters) => {
  // 将筛选条件添加到搜索表单
  if (filters.status) {
    searchForm.status = filters.status[0] // filterMultiple: false 时取第一个值
  }
  handleSearch()
}
```

### 3. 组件开发规范

#### 组件命名

- **单文件组件**: 使用 PascalCase 命名，如 `UserList.vue`
- **公共组件**: 以 `sc` 开头，如 `scTable.vue`
- **页面私有组件**: 使用语义化命名，如 `SaveDialog.vue`, `RoleDialog.vue`

#### 组件结构

```vue
<template>
  <!-- 模板内容 -->
</template>

<script setup>
// 导入
import { ref, computed, onMounted } from 'vue'

// 响应式数据
const state = ref({})

// 计算属性
const computedValue = computed(() => {})

// 方法
const handleAction = () => {}

// 生命周期
onMounted(() => {})
</script>

<style scoped>
/* 样式 */
</style>
```

### 4. API 接口开发规范

#### API 文件组织

每个业务模块对应一个 API 文件，统一放在 `src/api/` 目录下。

```javascript
// src/api/auth.js
import request from '@/utils/request'

export default {
  // 认证相关
  login: {
    post: async function (params) {
      return await request.post('auth/login', params)
    },
  },
  logout: {
    post: async function () {
      return await request.post('auth/logout')
    },
  },
  me: {
    get: async function () {
      return await request.get('auth/me')
    },
  },

  // 权限和菜单
  permissions: {
    menu: {
      get: async function () {
        return await request.get('permissions/menu')
      },
    },
    tree: {
      get: async function () {
        return await request.get('permissions/tree')
      },
    },
  },
}
```

#### 使用示例

```javascript
import authApi from '@/api/auth'

const login = async () => {
  try {
    const res = await authApi.login.post({
      username: 'admin',
      password: '123456'
    })
    // 处理响应
  } catch (error) {
    // 处理错误
  }
}

// 获取用户菜单
const getMenu = async () => {
  const res = await authApi.permissions.menu.get()
  return res.data
}
```

### 5. 路由开发规范

#### 路由类型

项目包含两类路由：

1. **静态路由**: 定义在 `src/router/systemRoutes.js` 中的基础路由，如登录页、404 页面等
2. **动态路由**: 用户登录后，通过 API 获取菜单数据，动态添加到路由中

#### 静态路由定义

```javascript
// src/router/systemRoutes.js
export default [
  {
    path: '/login',
    name: 'Login',
    component: () => import('@/pages/login/index.vue'),
    meta: {
      title: '登录',
      hidden: true
    }
  },
  {
    path: '/',
    name: 'Layout',
    component: () => import('@/layouts/index.vue'),
    redirect: '/dashboard',
    children: [
      // 动态路由将被添加到这里
    ]
  }
]
```

#### 动态路由加载

用户登录后，系统会自动执行以下流程：

1. 调用后端 API 获取用户菜单和权限信息
2. 将菜单数据转换为路由格式
3. 将动态路由添加到路由器中
4. 生成菜单树用于侧边栏展示

**路由元信息 (meta)**:
- `title`: 页面标题
- `icon`: 菜单图标（使用 Ant Design Vue 图标名称）
- `hidden`: 是否隐藏菜单
- `noAuth`: 是否不需要认证
- `keepAlive`: 是否缓存页面
- `affix`: 是否固定标签页

**后端菜单数据格式**:

菜单权限节点数据结构如下：

| 字段 | 类型 | 说明 |
|------|------|------|
| id | number | 权限ID |
| title | string | 权限标题（用于菜单显示） |
| name | string | 权限编码（唯一标识） |
| type | string | 权限类型：menu（菜单）、api（接口）、button（按钮）、url（链接） |
| parent_id | number | 父级ID，顶级菜单为 0 |
| path | string | 路由路径（如 `/system/users`） |
| component | string | 前端组件路径（如 `system/users/index`） |
| meta | object | 元数据（包含 icon、hidden、keepAlive 等） |
| sort | number | 排序 |
| status | number | 状态：1启用 0禁用 |
| children | array | 子权限列表（树形结构） |

**菜单节点规范**:

1. **顶级菜单**（parent_id=0）不需要 component 值
   - 顶级菜单作为分组容器，不需要指定组件路径
   - 示例：系统管理菜单

2. **只有最后一级的菜单**才需要 component 值
   - 如果菜单没有子菜单，则需要指定 component
   - 如果菜单有子菜单，则不需要指定 component

3. **非菜单类型**（如 button）不需要 component 值
   - 按钮权限只用于权限控制，不涉及页面路由

4. **所有页面组件的菜单**在前端处理时都拉平挂载在 Layouts 框架组件下
   - 前端会将菜单数据转换为路由，所有页面路由都会挂载到 Layout 布局下
   - 不需要在前端维护嵌套的路由结构

**数据示例**:

```javascript
// 示例：顶级菜单（无 component）
{
  id: 1,
  title: '系统管理',
  name: 'system',
  type: 'menu',
  parent_id: 0,
  path: '/system',
  component: null,  // 顶级菜单不需要 component
  meta: {
    icon: 'Setting',
    hidden: false,
    hiddenBreadcrumb: false,
    keepAlive: false
  },
  sort: 1,
  status: 1,
  children: []
}

// 示例：最后一级菜单（有 component）
{
  id: 2,
  title: '用户管理',
  name: 'system.users',
  type: 'menu',
  parent_id: 0,
  path: '/system/users',
  component: 'system/users/index',  // 最后一级菜单需要 component
  meta: {
    icon: 'User',
    hidden: false,
    hiddenBreadcrumb: false,
    keepAlive: true
  },
  sort: 1,
  status: 1,
  children: []
}

// 示例：按钮权限（无 component）
{
  id: 3,
  title: '查看用户',
  name: 'system.users.view',
  type: 'button',
  parent_id: 2,
  path: null,
  component: null,  // 非菜单类型不需要 component
  meta: null,
  sort: 1,
  status: 1,
  children: []
}

// 示例：API 权限
{
  id: 4,
  title: '获取用户列表',
  name: 'system.users.list',
  type: 'api',
  parent_id: 0,
  path: 'admin.users.index',
  component: null,
  meta: null,
  sort: 1,
  status: 1,
  children: []
}
```

**路由转换逻辑**:

前端会将后端返回的菜单数据转换为 Vue Router 路由格式，所有页面路由都会拉平挂载在 Layout 布局组件下：

```javascript
// 将后端菜单转换为路由格式
function transformMenusToRoutes(menus) {
  return menus.map(menu => {
    const route = {
      path: menu.path,
      name: menu.name,
      meta: {
        title: menu.title,
        icon: menu.meta?.icon,
        hidden: menu.meta?.hidden || false,
        keepAlive: menu.meta?.keepAlive || false
      }
    }
    
    // 只有菜单类型且有 component 值的才加载组件
    if (menu.type === 'menu' && menu.component) {
      route.component = loadComponent(menu.component)
    }
    
    // 不处理 children，所有菜单都会拉平到 Layout 下
    // if (menu.children) {
    //   route.children = transformMenusToRoutes(menu.children)
    // }
    
    return route
  })
}

// 加载组件函数
function loadComponent(componentPath) {
  return () => import(`@/pages/${componentPath}.vue`)
}
```

**菜单拉平处理说明**:

由于前端将所有页面菜单拉平挂载在 Layout 下，因此：
- 后端菜单的 `parent_id` 主要用于构建菜单树的层级关系（侧边栏显示）
- 路由层面不需要维护嵌套结构，所有页面路由都在同一层级
- `component` 值只需要在最后一级菜单（叶子节点）中设置
- 路由 `path` 使用后端返回的 `path` 字段
- 路由 `name` 使用后端返回的 `name` 字段（权限编码）
- 路由 `meta.title` 使用后端返回的 `title` 字段（权限标题）

#### 路由守卫

系统通过路由守卫实现权限控制和动态路由加载：

```javascript
router.beforeEach(async (to, from, next) => {
  const userStore = useUserStore()
  const isLoggedIn = userStore.isLoggedIn()
  
  // 白名单直接放行
  if (whiteList.includes(to.path)) {
    return next()
  }
  
  // 未登录跳转登录页
  if (!isLoggedIn) {
    return next({ path: '/login', query: { redirect: to.fullPath } })
  }
  
  // 动态路由加载
  if (!isDynamicRouteLoaded) {
    const menus = userStore.getMenu()
    const dynamicRoutes = transformMenusToRoutes(menus)
    
    // 添加动态路由
    dynamicRoutes.forEach(route => {
      router.addRoute('Layout', route)
    })
    
    isDynamicRouteLoaded = true
    next({ ...to, replace: true })
  } else {
    next()
  }
})
```

### 6. 状态管理规范

#### Pinia Store 定义

使用组合式 API 定义 Store。

#### User Store（用户认证与权限）

`src/stores/modules/user.js` 负责管理用户认证信息和权限数据：

```javascript
// src/stores/modules/user.js
import { ref } from 'vue'
import { defineStore } from 'pinia'
import { resetRouter } from '../../router'

export const useUserStore = defineStore('user', () => {
  // State
  const token = ref('')              // 访问令牌
  const refreshToken = ref('')       // 刷新令牌
  const userInfo = ref(null)         // 用户信息
  const menu = ref([])               // 用户菜单
  const permissions = ref([])        // 用户权限节点

  // Getters
  const isLoggedIn = () => !!token.value

  // Actions
  function setToken(newToken) {
    token.value = newToken
  }

  function setUserInfo(info) {
    userInfo.value = info
  }

  // 设置菜单（合并静态菜单和后端菜单）
  function setMenu(newMenu) {
    const staticMenus = userRoutes || []
    let mergedMenus = [...staticMenus]

    if (newMenu && newMenu.length > 0) {
      const menuMap = new Map()
      
      // 添加静态菜单
      staticMenus.forEach(m => {
        if (m.path) menuMap.set(m.path, m)
      })
      
      // 添加后端菜单（覆盖重复路径）
      newMenu.forEach(m => {
        if (m.path) menuMap.set(m.path, m)
      })
      
      mergedMenus = Array.from(menuMap.values())
    }
    menu.value = mergedMenus
  }

  function getMenu() {
    return menu.value
  }

  function setPermissions(data) {
    permissions.value = data
  }

  function hasPermission(permission) {
    if (!permissions.value || permissions.value.length === 0) {
      return false
    }
    return permissions.value.includes(permission)
  }

  function logout() {
    token.value = ''
    refreshToken.value = ''
    userInfo.value = null
    menu.value = []
    resetRouter()
  }

  return {
    token,
    refreshToken,
    userInfo,
    menu,
    permissions,
    setToken,
    setUserInfo,
    setMenu,
    getMenu,
    setPermissions,
    hasPermission,
    logout,
    isLoggedIn
  }
})
```

#### Store 使用

```javascript
import { useUserStore } from '@/stores/modules/user'

const userStore = useUserStore()

// 使用 state
console.log(userStore.token)
console.log(userStore.menu)
console.log(userStore.permissions)

// 调用 action
userStore.setToken('xxx')
userStore.setMenu(menus)
userStore.setPermissions(permissions)

// 检查权限
if (userStore.hasPermission('user.create')) {
  // 有权限，执行操作
}

// 登出
userStore.logout()
```

#### Store 持久化

使用 `pinia-plugin-persistedstate` 实现数据持久化：

```javascript
{
  persist: {
    key: 'user-store',
    storage: customStorage,
    pick: ['token', 'refreshToken', 'userInfo', 'menu']
  }
}
```

#### 权限指令

项目提供权限指令，用于在模板中控制元素显示：

```vue
<template>
  <!-- 只有拥有 user.create 权限时显示 -->
  <a-button v-permission="'user.create'">新增</a-button>
  
  <!-- 拥有多个权限之一时显示 -->
  <a-button v-permission="['user.create', 'user.update']">编辑</a-button>
</template>

<script setup>
import { useUserStore } from '@/stores/modules/user'

const userStore = useUserStore()
</script>
```

### 7. 表格开发规范

#### 使用 useTable Hook

项目提供了 `useTable` Hook 简化表格开发：

```javascript
import { useTable } from '@/hooks/useTable'
import { ref } from 'vue'

const {
  loading,
  dataSource,
  pagination,
  handleSearch,
  handleReset,
  handlePageChange
} = useTable({
  api: userApi.getList, // API 方法
  immediate: true // 是否立即加载
})

// 搜索参数
const searchParams = ref({
  keyword: '',
  status: ''
})
```

#### scTable 组件使用

```vue
<template>
  <sc-table
    :columns="columns"
    :data-source="dataSource"
    :loading="loading"
    :pagination="pagination"
    @page-change="handlePageChange"
  >
    <template #action="{ record }">
      <a-button @click="handleEdit(record)">编辑</a-button>
    </template>
  </sc-table>
</template>
```

### 8. 表单开发规范

#### scForm 组件使用

```vue
<template>
  <sc-form
    ref="formRef"
    :model="formData"
    :rules="formRules"
    :items="formItems"
    @submit="handleSubmit"
  />
</template>

<script setup>
import { ref } from 'vue'

const formRef = ref(null)
const formData = ref({
  username: '',
  email: ''
})

const formRules = {
  username: [
    { required: true, message: '请输入用户名', trigger: 'blur' }
  ],
  email: [
    { required: true, message: '请输入邮箱', trigger: 'blur' },
    { type: 'email', message: '请输入正确的邮箱', trigger: 'blur' }
  ]
}

const formItems = [
  {
    type: 'input',
    prop: 'username',
    label: '用户名',
    placeholder: '请输入用户名'
  },
  {
    type: 'input',
    prop: 'email',
    label: '邮箱',
    placeholder: '请输入邮箱'
  }
]

const handleSubmit = async () => {
  await formRef.value.validate()
  // 提交逻辑
}
</script>
```

### 9. 图标使用规范

#### Ant Design Vue Icons

```vue
<!-- 直接使用，无需导入 -->
<template>
  <a-icon type="user" />
  <a-icon type="setting" />
</template>
```

#### 常用图标

- `user`: 用户
- `setting`: 设置
- `delete`: 删除
- `edit`: 编辑
- `plus`: 添加
- `search`: 搜索
- `reload`: 刷新
- `download`: 下载
- `upload`: 上传
- `eye`: 查看
- `eye-invisible`: 隐藏
- `check-circle`: 成功
- `close-circle`: 失败
- `info-circle`: 信息
- `warning`: 警告

### 10. 国际化 (i18n) 规范

#### 使用 i18n

```javascript
import { useI18n } from '@/hooks/useI18n'

const { t } = useI18n()

// 使用
console.log(t('common.save'))
console.log(t('user.deleteConfirm'))
```

#### 语言文件组织

```javascript
// src/i18n/locales/zh.js
export default {
  common: {
    save: '保存',
    cancel: '取消',
    confirm: '确认',
    delete: '删除'
  },
  user: {
    deleteConfirm: '确定要删除该用户吗？'
  }
}
```

### 11. 文件上传规范

#### scUpload 组件使用

```vue
<template>
  <sc-upload
    v-model="imageUrl"
    :limit="1"
    accept="image/*"
    list-type="picture-card"
  />
</template>

<script setup>
import { ref } from 'vue'

const imageUrl = ref('')
</script>
```

### 12. 富文本编辑器规范

#### scEditor 组件使用

```vue
<template>
  <sc-editor
    v-model="content"
    :height="400"
    :toolbar="toolbarConfig"
  />
</template>

<script setup>
import { ref } from 'vue'

const content = ref('')
const toolbarConfig = [
  'bold', 'italic', 'underline', 'strike',
  'list', 'orderedList', 'quote', 'codeBlock',
  'image', 'link'
]
</script>
```

### 13. 样式规范

#### 全局样式

在 `src/style.css` 中定义全局样式。

#### 页面公共样式

页面布局的公共样式已提取到全局样式文件中，各页面可直接使用：

**在 `src/assets/style/pages.scss` 中定义的公共类：**

```scss
// 标准页面布局（垂直布局）
.pages-base-layout {
  display: flex;
  flex-direction: column;
  height: 100%;
  padding: 0;

  .tool-bar {
    padding: 12px 16px;
    background: #fff;
    border-bottom: 1px solid #f0f0f0;

    .left-panel {
      display: flex;
      align-items: center;
      flex: 1;
    }

    .right-panel {
      display: flex;
      gap: 8px;
    }
  }

  .table-content {
    flex: 1;
    overflow: hidden;
    padding: 16px;
    background: #f5f5f5;
  }
}

// 侧边栏布局（左右分栏）
.pages-sidebar-layout {
  display: flex;
  flex-direction: row;
  height: 100%;
  padding: 0;

  .left-box {
    width: 260px;
    border-right: 1px solid #f0f0f0;
    display: flex;
    flex-direction: column;
    background: #fff;

    .header {
      padding: 12px 16px;
      border-bottom: 1px solid #f0f0f0;
      background: #fafafa;
    }

    .body {
      flex: 1;
      overflow-y: auto;
      padding: 16px;
    }
  }

  .right-box {
    flex: 1;
    display: flex;
    flex-direction: column;
    overflow: hidden;

    .tool-bar {
      padding: 12px 16px;
      background: #fff;
      border-bottom: 1px solid #f0f0f0;

      .left-panel {
        display: flex;
        align-items: center;
        flex: 1;
      }

      .right-panel {
        display: flex;
        gap: 8px;
      }
    }

    .table-content {
      flex: 1;
      overflow: hidden;
      padding: 16px;
      background: #f5f5f5;
    }
  }
}
```

**使用示例：**

```vue
<!-- 标准页面布局 -->
<style scoped lang="scss">
.user-page {
  @extend .pages-base-layout;
}
</style>

<!-- 侧边栏布局 -->
<style scoped lang="scss">
.user-page {
  @extend .pages-sidebar-layout;
}
</style>
```

#### 组件样式

使用 `scoped` 避免样式污染：

```vue
<style scoped>
.user-list {
  padding: 20px;
}

.user-list .table {
  margin-top: 20px;
}
</style>
```

#### 命名规范

- 使用 BEM 命名法
- 类名使用 kebab-case

### 14. 工具函数使用

#### request.js (HTTP 请求)

```javascript
import request from '@/utils/request'

// GET 请求
request.get('/api/users', { params: { page: 1 } })

// POST 请求
request.post('/api/users', { name: 'test' })

// PUT 请求
request.put('/api/users/1', { name: 'updated' })

// DELETE 请求
request.delete('/api/users/1')
```

#### tool.js (工具函数)

```javascript
import { formatDate, deepClone } from '@/utils/tool'

// 格式化日期
formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')

// 深拷贝
deepClone(originalObject)
```

### 15. 开发流程

#### 登录流程

1. 用户输入用户名和密码
2. 调用 `authApi.login.post()` 发送登录请求
3. 后端返回 `token`、`refreshToken`、`userInfo`、`menu`、`permissions`
4. 前端保存数据到 Store（持久化）
5. 路由守卫检测到登录状态，加载动态路由
6. 跳转到首页或重定向页

```javascript
import { useUserStore } from '@/stores/modules/user'
import authApi from '@/api/auth'

const userStore = useUserStore()

const handleLogin = async () => {
  try {
    const res = await authApi.login.post({
      username: 'admin',
      password: '123456'
    })
    
    // 保存 token
    userStore.setToken(res.data.token)
    userStore.setRefreshToken(res.data.refreshToken)
    
    // 保存用户信息
    userStore.setUserInfo(res.data.user)
    
    // 保存菜单（合并静态菜单）
    userStore.setMenu(res.data.menu)
    
    // 保存权限节点
    userStore.setPermissions(res.data.permissions)
    
    // 跳转首页
    router.push('/dashboard')
  } catch (error) {
    message.error('登录失败')
  }
}
```

#### 添加新页面

1. 在 `src/pages/` 对应模块下创建页面组件
2. 在 `src/api/` 中创建对应的 API 文件
3. 在后端添加对应的菜单和权限配置
4. 前端会自动加载动态路由（无需手动配置路由）

#### 添加新组件

1. 在 `src/components/` 或对应子目录下创建组件
2. 遵循组件结构规范
3. 添加必要的 Props 和 Emits
4. 编写组件文档

### 16. 常用命令

```bash
# 安装依赖
npm install

# 开发环境启动
npm run dev

# 生产环境构建
npm run build

# 预览生产构建
npm run preview

# 代码格式化
npm run format

# 代码检查
npm run lint
```

### 17. 注意事项

1. **禁止重复引入图标**: Ant Design Vue 图标已全局引入，直接使用即可
2. **使用组合式 API**: 新代码统一使用 `<script setup>` 语法
3. **组件复用**: 优先使用项目提供的公共组件（scTable、scForm 等）
4. **API 统一管理**: 所有接口统一在 `src/api/` 目录下管理
5. **路由懒加载**: 路由组件必须使用动态导入
6. **环境变量**: 通过 `import.meta.env` 访问环境变量
7. **不要编写 demo**: 开发过程中不编写示例代码
8. **测试提示**: 如需测试，提示用户是否运行测试，不主动运行

### 18. 代码质量

- 遵循 Vue 3 官方风格指南
- 保持代码简洁、可读
- 适当添加注释说明复杂逻辑
- 使用语义化的变量和函数命名
- 避免过多的嵌套层级

### 19. 性能优化

- 合理使用 `v-if` 和 `v-show`
- 列表渲染必须设置 `key`
- 大列表使用虚拟滚动
- 图片懒加载
- 路由懒加载
- 组件按需引入（除图标外）