# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

基于 [yudao-ui-admin-vue3](https://gitee.com/yudaocode/yudao-ui-admin-vue3) 的中后台管理前端项目（名为 keyLove），采用 Vue 3 + Vite + Element Plus + TypeScript 技术栈。前端对接芋道后端 Java 服务（Spring Boot / Spring Cloud），通过 RESTful API (`/admin-api`) 通信。

## 常用命令

```bash
# 安装依赖（强制使用 pnpm）
pnpm install

# 本地开发（使用 .env.local 配置）
pnpm dev

# 连接远程开发环境后端
pnpm dev-server

# TypeScript 类型检查
pnpm ts:check

# 构建
pnpm build:local    # 本地构建
pnpm build:dev      # 开发环境
pnpm build:prod     # 生产环境

# 代码规范
pnpm lint:eslint    # ESLint 检查并修复
pnpm lint:format    # Prettier 格式化
pnpm lint:style     # Stylelint 样式检查
```

要求：Node.js >= 16.18.0，pnpm >= 8.6.0。

## 架构概览

### 入口与初始化

`src/main.ts` 按序初始化：i18n → Pinia Store → 全局组件 → Element Plus → FormCreate → Router → 指令（权限、焦点）→ WangEditor 插件 → 挂载。

### 路由与权限系统

- **静态路由**：`src/router/modules/remaining.ts` 定义登录、重定向、404 等固定页面
- **动态路由**：后端返回菜单数据，`src/store/modules/permission.ts` 中的 `generateRoutes()` 将其转换为路由并通过 `router.addRoute()` 动态注册
- **路由守卫**：`src/permission.ts` 实现 beforeEach 守卫，处理 token 校验、用户信息加载、动态路由注入
- **组件动态加载**：`src/utils/routerHelper.ts` 使用 `import.meta.glob('../views/**/*.{vue,tsx}')` 按路径自动匹配视图组件
- **权限指令**：`v-hasPermi` 和 `v-hasRole`（`src/directives/permission/`）用于按钮级权限控制

### HTTP 请求层

- **封装位置**：`src/config/axios/` 目录
  - `config.ts`：基础配置，baseURL = `VITE_BASE_URL + VITE_API_URL`
  - `service.ts`：Axios 实例，包含请求拦截（token 注入、租户 ID 头、API 加密）和响应拦截（401 无感刷新 token、错误码统一处理）
  - `index.ts`：导出 `request` 对象，提供 `get/post/put/delete/download/upload` 方法
- **调用方式**：`import request from '@/config/axios'`，然后 `request.get({ url, params })` / `request.post({ url, data })`

### API 模块约定

API 文件按业务域组织在 `src/api/{模块}/{子模块}/index.ts`，每个文件：
1. 定义 TypeScript VO 接口（如 `TenantVO`）和请求参数接口
2. 导出具名函数（如 `getTenantPage`、`createTenant`、`updateTenant`、`deleteTenant`）
3. 使用 `request.get/post/put/delete` 调用后端接口

主要业务域：`system`（系统管理）、`infra`（基础设施）、`bpm`（工作流）、`crm`、`erp`、`mall`（商城）、`ai`、`iot`、`pay`（支付）、`mp`（微信公众号）

### 状态管理

Pinia Store 位于 `src/store/modules/`，使用 `pinia-plugin-persistedstate` 持久化：
- `user.ts`：用户信息、登录状态
- `permission.ts`：动态路由、菜单
- `dict.ts`：数据字典缓存
- `app.ts`：应用全局状态（布局、主题等）
- `tagsView.ts`：标签页导航
- `locale.ts`：语言设置

每个 Store 导出 `useXxxStoreWithOut()` 函数，用于在 setup 外部获取 Store 实例。

### 视图页面约定

视图文件在 `src/views/{模块}/` 下，典型的 CRUD 页面结构：
- `index.vue`：列表页，包含搜索表单 + 数据表格 + 分页，使用 `ContentWrap` 组件包裹
- `{Entity}Form.vue`：新增/编辑表单弹窗
- 使用 `<Icon icon="ep:xxx" />` 全局图标组件（Iconify）
- 使用 `v-hasPermi="['module:entity:action']"` 控制按钮权限
- 使用 `getIntDictOptions(DICT_TYPE.XXX)` 获取字典数据渲染下拉框

### 环境变量

- `.env`：通用配置（应用标题、端口、租户开关、验证码开关等）
- `.env.local`：本地开发（连接本地后端，`VITE_BASE_URL` 指向本地服务）
- `.env.dev`：远程开发环境
- `.env.prod`：生产环境

关键变量：
- `VITE_BASE_URL`：后端 API 根地址
- `VITE_API_URL`：API 路径前缀（默认 `/admin-api`）
- `VITE_APP_TENANT_ENABLE`：多租户开关
- `VITE_APP_CAPTCHA_ENABLE`：验证码开关

### 核心工具

- `src/utils/auth.ts`：Token 存取（AccessToken / RefreshToken / TenantId）
- `src/utils/dict.ts`：字典工具函数（`getDictOptions`、`getIntDictOptions`）
- `src/utils/routerHelper.ts`：路由生成与组件动态加载
- `src/utils/formatter.ts`：数据格式化
- `src/utils/download.ts`：文件下载
- `src/utils/tree.ts`：树形数据处理
- `src/hooks/web/useTable.ts`：表格数据加载 Hook
- `src/hooks/web/useCrudSchemas.ts`：CRUD Schema 配置 Hook

### 样式系统

- UnoCSS 原子化 CSS（可在模板中直接使用如 `class="!w-240px mb-15px"`）
- SCSS 变量：`src/styles/variables.scss`（通过 Vite 全局注入）
- 全局样式入口：`src/styles/index.scss`

### 国际化

`src/locales/` 下 `zh-CN.ts` 和 `en.ts`，通过 `vue-i18n` 实现。组件中使用 `useI18n()` 的 `t()` 函数。

### 路径别名

`@/` 映射到 `src/`（在 `vite.config.ts` 和 `tsconfig.json` 中均配置）。