# CLAUDE.md

本文档为 Claude Code (claude.ai/code) 在此仓库中处理代码时提供指导。

## 项目概述

RuoYi-Vue 3.9.0 —— 一个 Vue 3 企业级后台管理系统（若依管理系统）。此为**前端**项目；通过 Vite 代理 REST API 连接到 Java Spring Boot 后端。

## 命令

- `npm run dev` —— 启动开发服务器（端口 80，将 `/dev-api` 代理到 `http://localhost:8081`）
- `npm run build:prod` —— 生产环境构建（输出目录：`dist/`）
- `npm run build:stage` —— 预发布环境构建
- `npm run preview` —— 预览生产构建产物

未配置任何测试框架。

## 架构

### 技术栈
Vue 3.5 + Vite 6 + Pinia 3 + Vue Router 4 + Element Plus 2.10 + Axios。使用 `unplugin-auto-import`，因此无需手动导入 Vue/Pinia API（如 ref、computed、defineStore 等）。

### 路径别名
- `@` → `./src`
- `~` → 项目根目录

### 主要目录
- `src/api/` —— 按后端领域组织的 API 模块（system/、monitor/、tool/）
- `src/views/` —— 页面组件，与 API 模块结构对应
- `src/store/modules/` —— Pinia 存储：`user`、`permission`、`app`、`settings`、`tagsView`、`dict`
- `src/layout/` —— 外壳布局（侧边栏、导航栏、标签视图、主内容区）
- `src/components/` —— 全局组件，在 main.js 中注册（Pagination、DictTag、Editor、FileUpload、ImageUpload、ImagePreview、RightToolbar）
- `src/plugins/` —— 插件系统：auth、cache、modal、tab、download
- `src/directive/` —— 自定义 Vue 指令（基于权限的元素可见性）
- `src/utils/` —— 共享工具函数（request.js、auth.js、ruoyi.js、validate.js、dict.js）
- `vite/` —— Vite 插件配置（auto-import、svg-icons、compression、setup-extend）

### 路由与权限
路由是**从后端动态加载**的（`GET /getRouters`）。系统包含两种路由类型：
- `src/router/index.js` 中的 `constantRoutes` —— 公共路由（登录、注册、404、401、首页）
- 动态路由 —— 从后端 API 获取，通过 `src/store/modules/permission.js` 中的 `filterAsyncRouter()` 转换为 Vue Router 路由

组件解析使用 `import.meta.glob('./../../views/**/*.vue')`，将后端返回的路由组件字符串（如 `"system/user/index"`）映射到实际的 Vue 组件。

三种特殊组件类型：`Layout`（主外壳）、`ParentView`（嵌套路由包装器）、`InnerLink`（iframe 嵌入）。

路由 meta 选项：`hidden`、`alwaysShow`、`noCache`、`title`、`icon`、`breadcrumb`、`activeMenu`、`roles`、`permissions`。

### 认证流程
1. JWT 令牌通过 js-cookie 存储在 cookie 中（`Admin-Token`）
2. `src/permission.js` —— 全局路由守卫，每次导航时检查令牌
3. 首次认证导航时：获取用户信息（`/getInfo`），生成动态路由
4. 令牌通过 axios 拦截器以 `Authorization: Bearer {token}` 头部注入
5. 权限检查：`*:*:*` = 全部权限，`admin` = 超级管理员角色
6. 权限格式遵循 `模块:实体:操作` 模式（例如 `system:user:edit`）

### API 层（`src/utils/request.js`）
- Axios 实例，基础 URL 来自环境变量 `VITE_APP_BASE_API`
- 10 秒超时
- 防重复提交：1 秒内阻止相同的 POST/PUT 请求
- 响应码：200=成功，401=会话过期（自动弹出注销提示），500=错误，601=警告
- `download()` 导出方法，处理带 blob 验证的文件下载

### 环境文件
- `.env.development` —— `VITE_APP_BASE_API = '/dev-api'`
- `.env.production` —— `VITE_APP_BASE_API = '/prod-api'`
- `.env.staging` —— 预发布环境配置
- 后端代理目标在 `vite.config.js` 中配置（`baseUrl` 变量）

### 全局属性（可通过 Options API 的 `this.` 或 `getCurrentInstance()` 访问）
`useDict`、`download`、`parseTime`、`resetForm`、`handleTree`、`addDateRange`、`getConfigKey`、`selectDictLabel`、`selectDictLabels`

### SVG 图标
将 SVG 文件放在 `src/assets/icons/svg/` 目录下。它们会通过 `vite-plugin-svg-icons` 自动注册，使用时用 `<svg-icon icon-class="名称" />`。

## 约定

- 全项目使用中文语言环境（Element Plus zh-cn、界面文本、注释）
- API 模块为每个端点导出独立的函数（例如 `listUser`、`getUser`、`addUser`、`updateUser`、`delUser`）
- 视图遵循 CRUD 模式：带有搜索表单、表格和添加/编辑对话框的列表页
- 字典值通过 `useDict()` 组合式函数加载，并使用 `<dict-tag>` 组件显示
- 组件尺寸存储在 cookie（`size`）中，默认值为 `'default'`
- UI 设置在 `src/settings.js` 中可配置（侧边栏主题、标签视图、顶部导航、固定头部、Logo、页脚）