# Vue 3 + Vben Admin 5.0 约束

> 本文件为公司统一配置（L1）的语言约束部分，涵盖 Vue 3 + Vben Admin 5.0 的**专属**约定和模板。
> 按需动态加载：当任务涉及 Vben Admin / Vue 3 + Composition API / TypeScript 前端代码编写时加载本文件。
>
> **公共规范**（格式、组件命名、API命名、API层组织、权限模式、CRUD架构、Lint流程）已在公司统一配置 §六 中定义，本文件不再重复。

---

## 一、技术栈约束

- 使用 Vue 3 + Composition API + `<script setup>` + TypeScript
- 使用 Vben Admin 5.0 框架（Monorepo 架构）
- UI 库按应用选择：Ant Design Vue / Element Plus / Naive UI
- 状态管理使用 Pinia
- 构建工具使用 Vite
- 包管理使用 pnpm
- **禁止引入** Vue 2 / Options API / Vuex / Element UI（Vue 2 版）

---

## 二、项目结构

采用 Monorepo 架构，核心目录：

```
├── apps/                    # 应用目录
│   ├── web-antd/           # Ant Design Vue 应用
│   ├── web-ele/            # Element Plus 应用
│   ├── web-naive/          # Naive UI 应用
│   └── backend-mock/       # Mock 后端服务
├── packages/               # 共享包
│   ├── @core/              # 核心包（UI组件、布局等）
│   ├── effects/            # 副作用包（权限、请求、hooks等）
│   ├── stores/             # 状态管理
│   ├── locales/            # 国际化
│   └── utils/              # 工具函数
└── internal/               # 内部工具配置
```

---

## 三、Vben 5.0 专属规范

- 路径别名：使用 `#/` 代表 `src`（通过 package.json imports 配置）
- 路由配置：`src/router/routes/modules/`
- API 文件：`src/api/` 目录，按功能模块组织
- 组件命名：PascalCase（见公司统一配置 §6.2）
- 组合式函数：use 前缀 camelCase
- Pinia Store：use 前缀 camelCase
- API 方法：动词 + 名词（见公司统一配置 §6.3）

### 路径别名

```ts
// package.json
{
  "imports": {
    "#/*": "./src/*"
  }
}

// 使用
import { useAuthStore } from '#/store'
```

---

## 四、常用命令

```bash
pnpm dev:antd          # 启动 Ant Design 应用
pnpm dev:ele           # 启动 Element Plus 应用
pnpm dev:naive         # 启动 Naive UI 应用
pnpm build             # 构建所有应用
pnpm build:antd        # 构建指定应用
pnpm lint              # 代码检查
pnpm check:type        # 类型检查
pnpm reinstall         # 重新安装依赖
```

---

## 五、路由与菜单

路由配置位于 `src/router/routes/modules/` 目录：

```ts
import type { RouteRecordRaw } from "vue-router";

const routes: RouteRecordRaw[] = [
  {
    meta: {
      icon: "mdi:home",
      title: $t("page.home.title"),
      authority: ["admin"], // 权限控制
      order: 1000, // 菜单排序
      keepAlive: true, // 开启缓存
      hideInMenu: false, // 菜单中隐藏
      hideInTab: false, // 标签页中隐藏
    },
    name: "Home",
    path: "/home",
    component: () => import("#/views/home/index.vue"),
  },
];

export default routes;
```

---

## 六、权限控制

> 公共权限模式见公司统一配置 §6.5。以下为 Vben 5.0 专属实现。

三种模式在 `preferences.ts` 中配置：

```ts
import { defineOverridesPreferences } from "@vben/preferences";

export const overridesPreferences = defineOverridesPreferences({
  app: {
    accessMode: "frontend", // 'frontend' | 'backend' | 'mixed'
  },
});
```

按钮级权限：

```vue
<script setup>
import { AccessControl, useAccess } from "@vben/access";
const { hasAccessByCodes, hasAccessByRoles } = useAccess();
</script>

<template>
  <!-- 权限码方式 -->
  <AccessControl :codes="['AC_100100']" type="code">
    <Button>有权限可见</Button>
  </AccessControl>

  <!-- 角色方式 -->
  <Button v-if="hasAccessByRoles(['admin'])">管理员可见</Button>

  <!-- 指令方式 -->
  <Button v-access:code="'AC_100100'">有权限可见</Button>
</template>
```

---

## 七、偏好设置配置

在应用目录的 `preferences.ts` 中配置：

```ts
import { defineOverridesPreferences } from "@vben/preferences";

export const overridesPreferences = defineOverridesPreferences({
  app: {
    layout: "sidebar-nav", // 布局方式
    locale: "zh-CN", // 语言
    dynamicTitle: true, // 动态标题
    watermark: false, // 水印
    loginExpiredMode: "page", // 登录过期模式
  },
  theme: {
    mode: "dark", // 主题模式
    builtinType: "default", // 内置主题
    colorPrimary: "hsl(212 100% 45%)", // 主题色
  },
  sidebar: {
    collapsed: false, // 侧边栏折叠
    width: 224, // 侧边栏宽度
  },
  tabbar: {
    enable: true, // 标签页
    keepAlive: true, // 缓存
  },
});
```

---

## 八、API 请求

> 公共API层组织原则见公司统一配置 §6.4。以下为 Vben 5.0 专属实现。

请求配置在 `src/api/request.ts`：

```ts
import { requestClient } from "#/api/request";

// GET 请求
export async function getUserInfoApi() {
  return requestClient.get<UserInfo>("/user/info");
}

// POST 请求
export async function saveUserApi(user: UserInfo) {
  return requestClient.post<UserInfo>("/user", user);
}
```

代理配置在 `vite.config.mts`：

```ts
export default defineConfig(async () => {
  return {
    vite: {
      server: {
        proxy: {
          "/api": {
            target: "http://localhost:5320/api",
            changeOrigin: true,
            rewrite: (path) => path.replace(/^\/api/, ""),
          },
        },
      },
    },
  };
});
```

---

## 九、登录接口对接

```ts
// src/api/core/auth.ts
export async function loginApi(data: LoginParams) {
  return requestClient.post<LoginResult>("/auth/login", data);
}

// src/api/core/user.ts
export async function getUserInfoApi() {
  return requestClient.get<UserInfo>("/user/info");
}

// src/api/core/auth.ts (可选)
export async function getAccessCodesApi() {
  return requestClient.get<string[]>("/auth/codes");
}
```

---

## 十、国际化

使用 `$t()` 函数：

```ts
import { $t } from '#/locales';

meta: {
  title: $t('page.home.title'),
}
```

语言文件在 `packages/locales/` 目录。

---

## 十一、主题定制

CSS 变量覆盖：

```css
:root {
  --primary: 212 100% 45%;
  --sidebar: 0 0% 100%;
  --header: 0 0% 100%;
}

.dark {
  --background: 222.34deg 10.43% 12.27%;
  --sidebar: 222.34deg 10.43% 12.27%;
}
```

---

## 十二、环境变量

```bash
# .env.development
VITE_PORT=5555
VITE_GLOB_API_URL=/api
VITE_NITRO_MOCK=true

# .env.production
VITE_GLOB_API_URL=https://api.example.com
VITE_COMPRESS=gzip
VITE_ROUTER_HISTORY=hash
```

---

## 十三、格式规范

> 通用格式规范见公司统一配置 §6.1。以下为 Vben 5.0 专属补充。

- Vue SFC 顺序：`template` → `script setup` → `style scoped`
- 组件文件使用 PascalCase 命名
- CSS 使用 `scoped` + CSS 变量，避免全局污染

---

## 十四、编辑前 Lint 流程

> 通用步骤见公司统一配置 §6.7。以下为 Vben 5.0 专属命令。

1. 对变更区域运行 `pnpm lint`
2. 运行 `pnpm check:type` 确认类型正确
3. 修复新引入的 lint / 类型错误
4. 保持变更范围；不重新格式化无关文件

---

## 十五、代码模板

- 代码生成模板按照[template/vue3_templates.md](./template/vue3_templates.md)模板生成代码

## 十六、外部参考文档

> 以下为 Vben Admin 5.0 官方 skill 包中的详细参考文件，需配合 Vben Admin skill 使用。
> 路径相对于 Vben Admin skill 的 `references/` 目录，不在本记忆系统内。

### 核心功能 (references/core/)

- **路由菜单**: `route.md` - 路由配置、Meta属性、多级菜单
- **权限控制**: `access.md` - 三种权限模式、按钮级权限
- **偏好设置**: `preferences.md` - 完整配置项说明
- **主题定制**: `theme.md` - CSS变量、内置主题、自定义主题
- **API请求**: `api.md` - 请求配置、拦截器、多接口地址
- **国际化**: `locale.md` - 语言配置、新增语言包
- **登录对接**: `login.md` - 登录接口、Token刷新
- **图标使用**: `icons.md` - Iconify图标、SVG图标

### 业务组件 (references/components/business/)

- **Page页面**: `page.md` - 页面布局容器、标题区、内容区
- **表单组件**: `form.md` - Vben Form表单配置、校验、联动
- **表格组件**: `table.md` - Vben Vxe Table表格配置、搜索、远程加载
- **模态框**: `modal.md` - Vben Modal配置、拖拽、全屏
- **抽屉**: `drawer.md` - Vben Drawer配置、组件抽离
- **轻量提示框**: `alert.md` - alert、confirm、prompt调用
- **API组件包装器**: `api-component.md` - 远程数据自动加载

### 通用组件 (references/components/common/)

- **数字动画**: `count-to.md` - CountToAnimator数字滚动动画
- **省略文本**: `ellipsis-text.md` - EllipsisText文本省略展开

### 功能配置 (references/features/)

- **常用功能**: `features.md` - 水印、缓存、动态标题等

### 构建部署 (references/deployment/)

- **构建部署**: `deploy.md` - 构建配置、Nginx、Docker
- **常见问题**: `faq.md` - 依赖安装、打包部署、错误排查

---

_最后更新：2026-04-22_
_版本：5.0.0（公共规范已提取至公司统一配置 §六）_