126 lines
5.2 KiB
Markdown
126 lines
5.2 KiB
Markdown
# 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` 中均配置）。
|