mirror of
https://github.com/imdap/ruoyi-plus-vben5.git
synced 2026-04-29 21:11:25 +08:00
a4736a49f8
* chore: update deps * feat: use jsonc/x language * chore: update eslint 10.0 * fix: no-useless-assignment * feat: add CLAUDE.md * chore: ignore * feat: claude * fix: lint * chore: suppot eslint v10 * fix: lint * fix: lint * fix: type check * fix: unit test * fix: Suggested fix * fix: unit test * chore: update stylelint v17 * chore: update all major deps * fix: echarts console warn * chore: update vitest v4 * feat: add skills ignores * chore: update deps * chore: update deps * fix: cspell * chore: update deps * chore: update tailwindcss v4 * chore: remove postcss config * fix: no use catalog * chore: tailwind v4 config * fix: tailwindcss v4 sort * feat: use eslint-plugin-better-tailwindcss * fix: Interference between enforce-consistent-line-wrapping, jsx-curly-brace-presence and Prettier * fix: Interference between enforce-consistent-line-wrapping, jsx-curly-brace-presence and Prettier * fix(lint): resolve prettier and better-tailwindcss formatting conflicts * fix(tailwind): update theme references and lint sources * style(format): normalize apps docs and playground vue files * style(format): normalize core ui-kit components * style(format): normalize effects ui and layout components
149 lines
7.3 KiB
Markdown
149 lines
7.3 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 技术栈
|
||
|
||
1. 基于 **pnpm workspaces** + **Turborepo** 的 Vue 3 + TypeScript + Vite monorepo 项目。
|
||
2. 提供多个 UI 组件库版本（Ant Design Vue、Element Plus、Naive UI、TDesign），共享同一套使用tailwindcss+shadcn-vue的UI组件库核心框架。
|
||
3. 要求 Node ≥ 20.19.0，pnpm ≥ 10。
|
||
4. 使用 **prettier** + **eslint** + **stylelint** 进行代码检查和格式化。
|
||
5. 使用 **vitest** 进行单元测试。
|
||
6. 使用 **commitlint** 进行提交规范。
|
||
7. 使用 **czg** 进行提交规范。
|
||
8. 使用 **lefthook** 进行提交规范。
|
||
9. 使用 **vsh** 进行代码检查和格式化。
|
||
10. 使用 **turbo** 进行构建。
|
||
11. 使用 **vite** 进行开发。
|
||
12. 使用 **vue-tsc** 进行类型检查。
|
||
|
||
```bash
|
||
# 其他检查
|
||
pnpm check:circular # 循环依赖扫描
|
||
pnpm check:dep # depcheck 依赖检查
|
||
pnpm check:cspell # 拼写检查
|
||
|
||
# 清理
|
||
pnpm clean # 删除 dist、node_modules 等产物
|
||
pnpm reinstall # clean + 重新安装
|
||
|
||
# 交互式规范提交
|
||
pnpm commit # czg 提交向导
|
||
```
|
||
|
||
Turbo 任务通过 `dependsOn: ["^build"]` 级联，构建某个应用时会自动先构建其所有依赖包。
|
||
|
||
## Monorepo 目录结构
|
||
|
||
```text
|
||
apps/
|
||
backend-mock/ # 基于 Nitro 的 mock API 服务（h3 路由 + faker.js 数据）
|
||
web-antd/ # Ant Design Vue 应用
|
||
web-ele/ # Element Plus 应用
|
||
web-naive/ # Naive UI 应用
|
||
web-tdesign/ # TDesign Vue 应用
|
||
|
||
packages/
|
||
@core/ # 框架核心（不依赖具体 UI 库）
|
||
base/ # 共享工具、缓存、颜色处理、类型定义
|
||
composables/ # 核心 Vue composable
|
||
preferences/ # PreferenceManager 类（响应式、持久化配置）
|
||
ui-kit/ # UI 组件片段：form-ui、layout-ui、menu-ui、popup-ui、shadcn-ui、tabs-ui
|
||
effects/ # 高层模块，可依赖 @core 和 UI 库
|
||
access/ # 路由/菜单生成与权限指令
|
||
common-ui/ # 通用 UI 组件（ApiComponent、IconPicker、VCropper、Tippy 等）
|
||
hooks/ # useAppConfig 等
|
||
layouts/ # BasicLayout、登录页、各类 widgets
|
||
plugins/ # Motion 等插件
|
||
request/ # RequestClient（axios 封装 + 拦截器体系）
|
||
constants/ # 全局常量（LOGIN_PATH 等）
|
||
icons/ # Iconify 图标封装
|
||
locales/ # vue-i18n 初始化、loadLocalesMap 工具
|
||
preferences/ # 对外暴露 @core/preferences 的公共 API
|
||
stores/ # Pinia 全局 store：useAccessStore、useUserStore、useTabbarStore
|
||
styles/ # 全局 CSS / TailwindCSS 基础样式
|
||
types/ # 共享 TypeScript 类型
|
||
utils/ # 共享工具函数（mergeRouteModules、mapTree 等）
|
||
|
||
internal/
|
||
lint-configs/ # ESLint、Prettier、Stylelint、commitlint 配置包
|
||
node-utils/ # 构建时 Node 工具
|
||
tailwind-config/ # 共享 Tailwind 配置
|
||
tsconfig/ # 基础 tsconfig
|
||
vite-config/ # 共享 Vite 配置工厂 + 插件集合
|
||
|
||
scripts/
|
||
vsh/ # CLI 工具（lint、check-dep、check-circular、publint）
|
||
turbo-run/ # 交互式 turbo 运行器
|
||
|
||
playground/ # 组件演示场
|
||
docs/ # VitePress 文档
|
||
```
|
||
|
||
## 核心架构说明
|
||
|
||
### 应用启动流程
|
||
|
||
每个应用的 `src/main.ts` 调用 `bootstrap(namespace)`（位于 `src/bootstrap.ts`），依次执行：
|
||
|
||
1. 初始化**组件适配器**（`src/adapter/component/index.ts`）——将通用表单组件名映射到具体 UI 库的组件。
|
||
2. 调用 `initSetupVbenForm()`（`src/adapter/form.ts`）配置通用表单系统。
|
||
3. 依次初始化 i18n、Pinia stores、权限指令、Tippy、路由、MotionPlugin，最后挂载到 `#app`。
|
||
|
||
### 偏好设置系统
|
||
|
||
`@vben/preferences` 导出单例 `preferences`（`PreferenceManager`）。它是响应式的，自动持久化到 localStorage（以应用 namespace 为前缀），并驱动主题 CSS 变量的更新。各应用在 `src/preferences.ts` 中调用 `defineOverridesPreferences()` 覆盖默认值，无需修改核心代码。
|
||
|
||
### 权限/访问系统
|
||
|
||
`@vben/access`（`packages/effects/access`）支持三种访问模式：
|
||
|
||
- **frontend**：根据用户角色过滤静态路由。
|
||
- **backend**：从接口（`getAllMenusApi`）获取菜单并动态注册路由。
|
||
- **mixed**：同时使用以上两种方式。
|
||
|
||
路由守卫（`src/router/guard.ts`）在登录后首次导航时调用 `generateAccess()`，将结果存入 `useAccessStore`，再重定向到目标页。`v-access` 指令和 `<AccessControl>` 组件用于按权限码或角色控制 UI 元素显示。
|
||
|
||
### 请求客户端
|
||
|
||
`@vben/request` 将 Axios 封装为 `RequestClient`。每个应用在 `src/api/request.ts` 中创建自己的实例，挂载以下拦截器：
|
||
|
||
- **请求拦截**：自动附加 Bearer Token 和 Accept-Language 头。
|
||
- **`defaultResponseInterceptor`**：解包 `{ code, data, message }` 响应格式。
|
||
- **`authenticateResponseInterceptor`**：处理 401，自动刷新 token 或跳转登录。
|
||
- **`errorMessageResponseInterceptor`**：调用 `message.error()` 显示错误。
|
||
|
||
在 API 文件中从 `#/api/request` 引入 `requestClient`（自动解包响应）或 `baseRequestClient`（原始响应）。
|
||
|
||
### 路由组织
|
||
|
||
- `src/router/routes/modules/*.ts`：需要权限验证的动态路由。
|
||
- `src/router/routes/core/`：始终可访问的路由（登录页、404 等）。
|
||
- `mergeRouteModules(import.meta.glob(...))` 用于聚合路由模块文件。
|
||
- 动态路由在运行时由权限系统注册。
|
||
|
||
### 适配器模式
|
||
|
||
每个 UI 库应用在 `src/adapter/` 下提供适配器，将 `@vben/common-ui` 的通用 form/modal/drawer 组件桥接到具体组件库。这是 `web-antd`、`web-ele` 等应用之间的主要差异所在。
|
||
|
||
### 全局 Pinia Store
|
||
|
||
- `useAccessStore`：token、路由、菜单、锁屏、登录过期状态。
|
||
- `useUserStore`：用户信息、角色、homePath。
|
||
- `useTabbarStore`：已打开标签页管理。
|
||
|
||
所有 store 通过 `@vben/stores` 的 `initStores(app, { namespace })` 统一初始化。
|
||
|
||
### Mock 后端
|
||
|
||
`apps/backend-mock` 是一个 Nitro 服务器，可单独启动：`pnpm -F @vben/backend-mock start`。Vite 开发服务器通过 `vite.config.ts`（位于 `internal/vite-config`）将 API 请求代理到该服务。
|
||
|
||
## 开发约定
|
||
|
||
- **路径别名**：`#/*` 指向各应用的 `./src/*`（在 `package.json#imports` 中定义）。
|
||
- **依赖版本管理**：内部包使用 `workspace:*`，第三方包使用 `catalog:`（版本集中在 `pnpm-workspace.yaml#catalog` 中管理）。
|
||
- **提交规范**：遵循 Conventional Commits（`feat`、`fix`、`chore`、`docs`、`refactor`、`perf`、`test`、`ci`、`style`、`types`、`revert`），由 lefthook + commitlint 强制执行。
|
||
- **pre-commit 钩子**（lefthook）：自动对暂存文件执行 prettier + eslint + stylelint，推荐使用 `pnpm commit`（czg）提交。
|
||
- **新增页面**：在 `src/views/` 下创建 `.vue` 文件，在 `src/router/routes/modules/` 下添加路由模块；若使用 backend 模式，还需确保后端接口返回对应菜单数据。
|
||
- **国际化**：统一使用 `$t('key')`，locale 文件位于 `packages/locales/`，项目级国际化文件位于 `src/locales/langs`。
|