---
description: 项目 overview —— portal-mini-front 后台管理系统的技术栈、目录结构与运行方式
globs: ["**/*"]
alwaysApply: true
---

# 项目概述

## 产品定位
`portal-mini-front` 是一个**后台管理系统前端**（Portal 管理后台），面向内部运营/管理员，核心场景是：登录鉴权 → 菜单/路由权限 → 数据列表（查询/分页/筛选）→ 增删改查表单 → 数据看板。

## 技术栈（固定选型，不得随意替换）

| 领域 | 选型 | 说明 |
| --- | --- | --- |
| 框架 | Vue 3.4+ | 仅使用 Composition API |
| 语言 | TypeScript 5.x | 严格模式，禁止 `any` |
| 构建 | Vite 5+ | |
| UI 库 | Element Plus | 主题色、组件尺寸统一在应用入口配置 |
| 脚手架基线 | `vue3-element-admin` | 目录结构、请求封装、权限方案以该模板为基准 |
| 状态管理 | Pinia | 使用 setup store 语法 |
| 路由 | Vue Router 4 | 动态路由 + 权限守卫 |
| HTTP | Axios | 统一封装于 `src/utils/request.ts` |
| 图标 | `@element-plus/icons-vue` + 本地 svg sprite | |
| 工具库 | VueUse（`@vueuse/core`） | 优先复用，不重复造轮子 |
| 代码规范 | ESLint + Prettier + husky/lint-staged | 提交前自动校验 |

> 引入任何新依赖前必须说明理由；能用 Element Plus / VueUse / 现有 utils 解决的，不允许加新库。

## 目录结构约定

```
src/
├── api/                    # 接口层，按业务模块划分，不得在组件内直接写请求
│   └── {module}/
│       └── index.ts        # 导出 {Module}API 对象
├── components/             # 跨模块复用的全局组件（自动注册）
├── composables/            # 跨模块复用的组合式函数 useXxx
├── directives/             # 自定义指令，如 v-hasPerm
├── enums/                  # 枚举与常量字典
├── layouts/                # 布局骨架（侧边栏/顶栏/标签栏/内容区）
├── router/                 # 静态路由 + 动态路由 + 守卫
├── store/modules/          # Pinia 模块
├── styles/                 # 全局样式、变量、Element Plus 覆盖
├── types/                  # 全局与模块类型声明（*.d.ts 或 *.ts）
├── utils/                  # request / storage / 通用工具
└── views/                  # 页面，按业务模块划分
    └── {module}/
        ├── index.vue       # 列表主页（必须）
        └── components/     # 仅该模块使用的子组件（表单弹窗等）
```

命名规则：
- 目录、文件名统一 **kebab-case**；Vue 组件文件用 **PascalCase.vue** 或目录 + `index.vue`。
- 页面路由 path 与 `views/{module}` 目录保持一致。

## 常用命令
```bash
pnpm dev          # 本地开发
pnpm build:prod   # 生产构建
pnpm preview      # 预览构建产物
pnpm lint         # ESLint 检查并修复
pnpm type-check   # vue-tsc 类型检查
```

## 环境
- 环境变量文件：`.env.development` / `.env.production`，变量必须以 `VITE_` 开头。
- 接口地址统一走 `VITE_APP_BASE_API`，本地通过 Vite `server.proxy` 解决跨域，**不允许在代码里硬编码域名或端口**。