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](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）安装依赖

```powershell
cd d:\project\Web_Template_Vue3_Dev
pnpm i
```

如你使用 npm：

```powershell
cd d:\project\Web_Template_Vue3_Dev
npm i
```

### 2）启动开发环境

```powershell
pnpm run serve
```

### 3）构建

```powershell
pnpm run build
```

### 4）单元测试 / 代码质量

```powershell
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](AI-Coding/README.md)。

```text
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 片段

运行：

```powershell
pnpm run template
```

---

## 贡献与团队协作建议

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