Web_Template_Vue3_Dev/README.md

Admin Plus（Vue3 企业级开发模板）

面向公司项目的前端模板与基础库：内置 Vue 3 + Vue CLI 5 + TypeScript + Pinia + Vue Router + Element Plus，并集成 Mock、代码生成（Plop）、多套布局组件与常用工具链，支持在此基础上快速裁剪与复用。

本仓库同时提供面向 AI 的结构说明与模块索引：见 AI-Coding/README.md。

---

亮点

• 开箱即用：工程化配置齐全（TS/ESLint/Prettier/Stylelint/Unit Test）。
• 可扩展的 UI/布局体系：library/layouts/、library/components/ 内置多布局与业务型基础组件。
• Mock 一体化：开发环境通过 devServer.setupMiddlewares 自动挂载 mock/ 路由。
• 现代依赖栈：Element Plus + @element-plus/icons-vue，并内置图标组件 vab-icons。
• 可生成代码：通过 plop 快速生成页面/CRUD/组件/mock&api。

---

环境要求

• Node.js：建议 16/18/20 LTS（与 Vue CLI 5 兼容）
• 包管理器：推荐 pnpm（项目脚本也提供 npm 用法）

---

快速开始

1）安装依赖

cd d:\project\Web_Template_Vue3_Dev
pnpm i

如你使用 npm：

cd d:\project\Web_Template_Vue3_Dev
npm i

2）启动开发环境

pnpm run serve

3）构建

pnpm run build

4）单元测试 / 代码质量

pnpm run test:unit
pnpm run lint
pnpm run lint:eslint
pnpm run lint:prettier
pnpm run lint:stylelint

---

常用脚本（scripts）

来自 package.json：

• serve：启动开发服务器（本地 Mock 会自动挂载）。
• build：生产构建。
• build:compress / compress：构建后压缩产物（scripts/compress.js）。
• build:website：站点构建（使用 VAB_VARIABLE=website + 压缩）。
• test:unit：单元测试。
• lint：Vue CLI ESLint。
• lint:eslint / lint:prettier / lint:stylelint：更精细的格式化与风格修复。
• template：启动 plop 代码生成。

---

项目结构（速览）

更完整、可供 AI 检索复用的索引见 AI-Coding/README.md。

src/                 应用主代码（入口、路由、状态、国际化、业务页面）
library/             模板基础库（全局样式、插件集合、构建扩展等）
library/components/  可复用基础组件（Vab* 体系）
library/layouts/     多套布局（含主 Layout 入口）
mock/                本地 Mock 服务（devServer 中间件挂载）
types/               全局类型声明与业务类型
tests/unit/          单元测试
scripts/             构建后处理脚本（如压缩）
public/              静态资源与 HTML 模板

---

关键约定与入口

应用入口

• src/main.ts
  • 创建应用并挂载：createApp(App)
  • 初始化顺序：setupVab → setupI18n → setupStore → setupRouter
  • 生产环境可自动启用 Mock：当 baseURL 不是外链地址时（见 src/main.ts 的判断）

路由

• src/router/index.ts
  • constantRoutes：如登录/注册/404 等基础路由
  • asyncRoutes：业务路由（包含 Layout 作为壳）

状态管理

• src/store/index.ts：Pinia 初始化与注入。

国际化

• src/i18n/index.ts
  • createI18n({ legacy:false })
  • 当前语言读取自 useSettingsStore(pinia)

Mock

• mock/index.js
  • 挂载到开发服务器中间件（在 vue.config.js 的 devServer.setupMiddlewares）
  • 基于 mockjs 返回数据，并支持文件变更热更新

---

别名（Alias）

来自 vue.config.js / tsconfig.json：

• @ → src
• ~ → 项目根目录
• /# → types
• @vab → library
• @gp → library/plugins/vab

---

代码生成（Plop）

项目提供 plop 生成器（见 plopfile.js）：

• view：页面
• curd：CRUD
• component：组件
• mock&api：Mock 与 API 片段

运行：

pnpm run template

---

贡献与团队协作建议

• 建议以“业务模块”为单位在 src/views/ 组织页面。
• API 按域拆分在 src/api/，与 mock/controller/ 保持同名与路径一致，方便对照。
• 公共能力优先沉淀在 library/（全局插件/样式/构建扩展）与 library/components/（可视组件）。