cmpt-huitu-cli 1.0.0 → 1.0.2

package/templates/default/.trae/rules/project-rules.md

@@ -0,0 +1,711 @@
+你是一名前端架构师，React/Vue/Angular 专家。
+
+# 模板项目规则提示词
+
+> 本文档定义了基于 Vue 3 + Vite + Element Plus 的慧图标准模板项目的开发规则、最佳实践和注意事项。
+
+## 📋 目录
+
+- [项目概述](#项目概述)
+- [技术栈](#技术栈)
+- [目录结构规范](#目录结构规范)
+- [代码规范](#代码规范)
+- [命名规范](#命名规范)
+- [配置规范](#配置规范)
+- [开发规范](#开发规范)
+- [最佳实践](#最佳实践)
+- [注意事项](#注意事项)
+
+---
+
+## 📖 项目概述
+
+这是一个基于 **Monorepo** 架构的 Vue 3 标准项目模板，使用 `cmpt-huitu-cli`
+工具创建。项目集成了共享的 UI 组件库（`cmpt-huitu-ui`）和工具函数库（`cmpt-huitu-utils`），遵循统一的开发规范，便于团队协作和代码复用。
+
+### 核心特性
+
+- ✅ **Vue 3.5+**：使用 Composition API 和 `<script setup>` 语法
+- ✅ **Vite 7**：极速构建工具，支持 HMR
+- ✅ **Element Plus**：企业级 UI 组件库
+- ✅ **Pinia**：Vue 3 官方状态管理
+- ✅ **Vue Router 4**：官方路由管理器
+- ✅ **TypeScript 支持**：自动导入类型声明
+- ✅ **ESLint + Prettier**：代码格式化和检查
+- ✅ **共享包集成**：cmpt-huitu-ui、cmpt-huitu-utils
+
+---
+
+## 🛠 技术栈
+
+### 核心框架
+
+- **Vue**: `^3.5.18`
+- **Vite**: `^7.1.5`
+- **Vue Router**: `^4.5.1`
+- **Pinia**: `^3.0.3`
+
+### UI 框架
+
+- **Element Plus**: `^2.11.1`
+- **@element-plus/icons-vue**: `^2.3.2`
+
+### 共享包
+
+- **cmpt-huitu-ui**: `^1.0.0` - UI 组件库
+- **cmpt-huitu-utils**: `^1.0.0` - 工具函数库
+
+### 工具库
+
+- **axios**: `^1.11.0` - HTTP 客户端
+- **dayjs**: `^1.11.18` - 时间处理
+- **lodash-es**: `^4.17.21` - 工具函数
+- **nprogress**: `^0.2.0` - 进度条
+
+---
+
+## 📁 目录结构规范
+
+```
+项目根目录/
+├── public/                      # 静态资源目录（不会被 Vite 处理）
+│   ├── config/                 # 配置文件目录
+│   │   └── envCfg.js          # 环境配置文件（必需修改）
+│   ├── images/                 # 图片资源
+│   │   └── favicon.ico        # 网站图标
+│   └── static/                 # 静态文件
+│
+├── src/                        # 源代码目录
+│   ├── assets/                # 资源文件（会被 Vite 处理）
+│   │   ├── images/           # 图片资源
+│   │   │   ├── 404/         # 404 页面图片
+│   │   │   └── login/       # 登录页图片
+│   │   └── empty.png        # 空状态图片
+│   │
+│   ├── components/            # 全局组件目录
+│   │   └── error/           # 错误处理组件
+│   │       └── error.vue
+│   │
+│   ├── routers/              # 路由配置目录
+│   │   ├── modules/         # 路由模块（自动导入）
+│   │   │   └── example.js  # 示例路由模块
+│   │   ├── base.js         # 基础路由（登录、404等）
+│   │   ├── guard.js        # 路由守卫
+│   │   └── index.js        # 路由入口（自动合并 modules）
+│   │
+│   ├── services/            # API 服务目录
+│   │   └── login.js        # 登录服务
+│   │
+│   ├── stores/             # Pinia 状态管理目录
+│   │   ├── index/         # Store 模块
+│   │   │   ├── global.js  # 全局状态
+│   │   │   └── template.js # 模板状态
+│   │   └── index.js       # Store 入口
+│   │
+│   ├── styles/             # 样式目录
+│   │   ├── theme/         # 主题配置
+│   │   │   ├── variables.scss # 主题变量
+│   │   │   └── README.md  # 主题文档
+│   │   └── index.scss     # 全局样式入口
+│   │
+│   ├── utils/              # 工具函数目录
+│   │   ├── auth.js        # 认证工具
+│   │   ├── errorCode.js   # 错误码定义
+│   │   ├── index.js       # 工具函数入口
+│   │   ├── requestAxios.js # Axios 封装
+│   │   ├── RequestCache.js # 请求缓存
+│   │   └── theme.js       # 主题切换工具
+│   │
+│   ├── views/              # 页面视图目录
+│   │   ├── login/         # 登录页
+│   │   │   └── index.vue
+│   │   ├── about.vue      # 关于页面
+│   │   └── home.vue       # 首页
+│   │
+│   ├── types/              # TypeScript 类型定义（可选）
+│   │
+│   ├── app.vue            # 根组件
+│   ├── main.js            # 应用入口
+│   ├── components.d.ts    # 组件自动导入类型（自动生成）
+│   └── imports.d.ts       # 自动导入类型（自动生成）
+│
+├── vite/                   # Vite 插件配置目录
+│   └── plugins/           # 插件配置
+│       ├── autoComponents.js # 组件自动导入
+│       ├── autoImport.js    # API 自动导入
+│       ├── compression.js   # 压缩配置
+│       ├── externals.js     # 外部化配置
+│       ├── index.js         # 插件入口
+│       └── visualizer.js    # 打包分析
+│
+├── .env                    # 环境变量文件（本地开发，不提交）
+├── .env.production        # 生产环境变量
+├── .env.development       # 开发环境变量
+├── .gitignore            # Git 忽略文件
+├── eslint.config.js      # ESLint 配置
+├── index.html            # HTML 模板
+├── jsconfig.json         # JavaScript 项目配置（VSCode 智能提示）
+├── package.json          # 项目配置
+├── README.md             # 项目说明
+└── vite.config.js        # Vite 配置文件
+```
+
+### 目录说明
+
+#### `public/` - 静态资源
+
+- **不会被 Vite 处理**，原样复制到输出目录
+- **必需配置**：`public/config/envCfg.js` - 环境配置
+- 存放不会被频繁修改的静态资源
+
+#### `src/assets/` - 资源文件
+
+- **会被 Vite 处理**，支持导入和路径别名
+- 存放会被代码引用的资源（图片、字体等）
+- 支持动态导入和路径别名 `@/assets/...`
+
+#### `src/routers/modules/` - 路由模块
+
+- **自动导入**：Vite 会自动扫描并合并所有 `.js` 文件
+- 每个模块导出一个路由对象或数组
+- 文件名建议使用 `模块名.js` 格式
+
+#### `src/stores/` - 状态管理
+
+- 使用 Pinia，按模块组织
+- 每个模块一个文件，文件名即 store id
+
+#### `src/services/` - API 服务
+
+- 按功能模块组织 API 请求
+- 每个文件对应一个业务模块
+- 统一使用 `@/utils/requestAxios.js` 封装的 axios 实例
+
+---
+
+## 📝 代码规范
+
+### Vue 组件规范
+
+#### 1. 使用 `<script setup>` 语法
+
+```vue
+<script setup>
+  // ✅ 推荐：使用 Composition API + <script setup>
+  import { ref, computed, onMounted } from 'vue'
+
+  const count = ref(0)
+  const doubled = computed(() => count.value * 2)
+
+  onMounted(() => {
+    console.log('mounted')
+  })
+</script>
+```
+
+#### 1.1 组件文件命名
+
+- **组件文件名**：使用 **camelCase（小驼峰）**，如 `userProfile.vue`、`home.vue`
+- **组件注册名**：在模板中使用时，保持 camelCase 或转换为 PascalCase（Vue 会自动处理）
+
+#### 2. 编译器宏无需导入
+
+```vue
+<script setup>
+  // ✅ 正确：defineProps、defineEmits 是编译器宏，无需导入
+  const props = defineProps({
+    title: String,
+  })
+
+  const emit = defineEmits(['update'])
+
+  // ❌ 错误：不要导入编译器宏
+  // import { defineProps, defineEmits } from 'vue'
+</script>
+```
+
+#### 3. 组件命名
+
+- **组件文件名**：使用 **camelCase（小驼峰）**，如 `userProfile.vue`、`home.vue`
+- **组件注册名**：在模板中使用时，Vue 会自动处理大小写转换（camelCase ↔ PascalCase）
+- **Props 定义**：使用对象形式，提供类型和默认值
+
+```vue
+<script setup>
+  // ✅ 推荐：完整的 props 定义
+  const props = defineProps({
+    title: {
+      type: String,
+      required: true,
+    },
+    count: {
+      type: Number,
+      default: 0,
+    },
+  })
+</script>
+```
+
+#### 4. 样式规范
+
+- **使用 Scoped 样式**：避免样式污染
+- **使用 CSS 变量**：利用主题系统
+- **SCSS 语法**：使用 `@use` 替代 `@import`（避免弃用警告）
+
+```vue
+<style lang="scss" scoped>
+  // ✅ 推荐：使用 scoped 和 SCSS
+  .container {
+    padding: var(--spacing-md);
+    color: var(--main-font-color);
+  }
+</style>
+```
+
+### 路由规范
+
+#### 1. 路由模块化
+
+在 `src/routers/modules/` 下创建路由模块：
+
+```javascript
+// src/routers/modules/user.js
+export default {
+  path: '/user',
+  name: 'User',
+  component: () => import('@/views/user/index.vue'),
+  meta: {
+    title: '用户管理',
+    requiresAuth: true, // 需要登录
+  },
+  children: [
+    {
+      path: 'list',
+      name: 'UserList',
+      component: () => import('@/views/user/list.vue'),
+    },
+  ],
+}
+```
+
+#### 2. 路由命名
+
+- **路由 name**：使用 PascalCase，与组件名对应
+- **路由 path**：使用 kebab-case，与菜单路径对应
+
+#### 3. 路由元信息
+
+使用 `meta` 字段存储路由元信息：
+
+```javascript
+{
+  meta: {
+    title: '页面标题',        // 页面标题
+    requiresAuth: true,       // 是否需要登录
+    roles: ['admin'],         // 权限角色
+    keepAlive: true,          // 是否缓存
+    hidden: false,            // 是否在菜单中隐藏
+  },
+}
+```
+
+### 状态管理规范
+
+#### 1. Store 定义
+
+使用 `defineStore` 定义 store：
+
+```javascript
+// src/stores/user.js
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+
+export const useUserStore = defineStore('user', () => {
+  // State
+  const userInfo = ref(null)
+  const token = ref('')
+
+  // Getters
+  const isLoggedIn = computed(() => !!token.value)
+
+  // Actions
+  function setUserInfo(info) {
+    userInfo.value = info
+  }
+
+  function logout() {
+    userInfo.value = null
+    token.value = ''
+  }
+
+  return {
+    userInfo,
+    token,
+    isLoggedIn,
+    setUserInfo,
+    logout,
+  }
+})
+```
+
+#### 2. Store 使用
+
+在组件中使用：
+
+```vue
+<script setup>
+  import { useUserStore } from '@/stores/user'
+
+  const userStore = useUserStore()
+
+  // 访问 state
+  console.log(userStore.userInfo)
+
+  // 调用 action
+  userStore.setUserInfo({ name: 'John' })
+
+  // 使用 getter
+  if (userStore.isLoggedIn) {
+    // ...
+  }
+</script>
+```
+
+### API 请求规范
+
+#### 1. 统一使用封装的 axios 实例
+
+```javascript
+// src/services/user.js
+import request from '@/utils/requestAxios'
+
+// ✅ 推荐：统一使用封装的 request
+export function getUserList(params) {
+  return request({
+    url: '/api/user/list',
+    method: 'get',
+    params,
+  })
+}
+
+export function createUser(data) {
+  return request({
+    url: '/api/user',
+    method: 'post',
+    data,
+  })
+}
+```
+
+#### 2. 在组件中使用
+
+```vue
+<script setup>
+  import { ref, onMounted } from 'vue'
+  import { getUserList } from '@/services/user'
+
+  const list = ref([])
+
+  onMounted(async () => {
+    try {
+      const res = await getUserList({ page: 1 })
+      list.value = res.data
+    } catch (error) {
+      console.error('获取用户列表失败', error)
+    }
+  })
+</script>
+```
+
+---
+
+## 🏷 命名规范
+
+### 文件命名
+
+| 类型           | 命名规范         | 示例                          |
+| -------------- | ---------------- | ----------------------------- |
+| **Vue 组件**   | camelCase        | `userProfile.vue`、`home.vue` |
+| **路由模块**   | camelCase        | `userManagement.js`           |
+| **Store 模块** | camelCase        | `userStore.js`                |
+| **工具函数**   | camelCase        | `formatDate.js`               |
+| **常量文件**   | UPPER_SNAKE_CASE | `ERROR_CODE.js`               |
+
+### 变量命名
+
+- **变量/函数**：camelCase - `userName`, `getUserInfo()`
+- **常量**：UPPER_SNAKE_CASE - `API_BASE_URL`, `MAX_COUNT`
+- **组件名**：PascalCase - `UserProfile`, `DataTable`
+- **CSS 类名**：kebab-case - `.user-profile`, `.data-table`
+
+### 路径别名
+
+使用 `jsconfig.json` 中定义的路径别名：
+
+| 别名           | 对应路径          | 用途         |
+| -------------- | ----------------- | ------------ |
+| `@/`           | `src/`            | 源代码根目录 |
+| `@public/`     | `public/`         | 静态资源目录 |
+| `@components/` | `src/components/` | 全局组件     |
+| `@views/`      | `src/views/`      | 页面视图     |
+| `@routers/`    | `src/routers/`    | 路由配置     |
+| `@stores/`     | `src/stores/`     | 状态管理     |
+| `@styles/`     | `src/styles/`     | 样式文件     |
+| `@utils/`      | `src/utils/`      | 工具函数     |
+| `@assets/`     | `src/assets/`     | 资源文件     |
+| `@services/`   | `src/services/`   | API 服务     |
+
+```javascript
+// ✅ 推荐：使用路径别名（组件文件名使用 camelCase）
+import { parseTime } from '@/utils'
+import UserList from '@/views/user/list.vue'
+import { useUserStore } from '@/stores/user'
+
+// ❌ 不推荐：使用相对路径
+import { parseTime } from '../../utils'
+```
+
+---
+
+## ⚙️ 配置规范
+
+### 环境配置 (`public/config/envCfg.js`)
+
+**⚠️ 重要：创建项目后必须修改此配置文件**
+
+```javascript
+// public/config/envCfg.js
+const config = {
+  // 登录配置
+  LoginUnifyBase: origin + '/sso',
+  LoginUnifyAuthClientid: 'your-client-id',
+  LoginUnifyAuthTenant: 'your-tenant-name',
+
+  // API 配置
+  apiUrlNew: origin + '/api/',
+
+  // 文件服务配置
+  uploadUrl: origin + '/upload',
+  downloadUrl: origin + '/download',
+
+  // ... 其他配置
+}
+```
+
+### 环境变量 (`.env`)
+
+在项目根目录创建环境变量文件：
+
+```bash
+# .env.development
+VITE_PORT=3001
+VITE_PATH=/
+VITE_MOCK=true
+
+# .env.production
+VITE_PATH=/production-path/
+VITE_MOCK=false
+```
+
+在代码中使用：
+
+```javascript
+// ✅ 正确：使用 import.meta.env
+const apiUrl = import.meta.env.VITE_API_URL
+
+// ❌ 错误：不要使用 process.env（Vite 不支持）
+// const apiUrl = process.env.VITE_API_URL
+```
+
+### Vite 配置
+
+主要配置在 `vite.config.js`，已预配置：
+
+- **路径别名**：`@/`、`@public/` 等
+- **自动导入**：Vue API、组件、Element Plus 组件
+- **SCSS 全局变量**：自动注入 `cmpt-huitu-ui` 样式变量
+- **代理配置**：开发环境 API 代理
+- **构建优化**：代码分割、压缩等
+
+---
+
+## 💻 开发规范
+
+### 1. 开发流程
+
+```bash
+# 1. 安装依赖
+pnpm install
+
+# 2. 启动开发服务器
+pnpm dev
+
+# 3. 代码检查
+pnpm lint
+
+# 4. 构建生产版本
+pnpm build
+
+# 5. 预览构建结果
+pnpm preview
+```
+
+### 2. Git 提交规范
+
+遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
+
+```bash
+# 功能新增
+git commit -m "feat: 添加用户管理页面"
+
+# 问题修复
+git commit -m "fix: 修复登录后跳转错误"
+
+# 文档更新
+git commit -m "docs: 更新 README"
+
+# 代码重构
+git commit -m "refactor: 重构用户服务代码"
+
+# 样式调整
+git commit -m "style: 调整页面布局"
+```
+
+### 3. 代码审查要点
+
+- ✅ 是否遵循命名规范
+- ✅ 是否使用路径别名而非相对路径
+- ✅ 是否正确处理异步操作（try-catch）
+- ✅ 是否使用共享包而非重复实现
+- ✅ 样式是否使用 scoped 或 CSS 变量
+- ✅ 是否移除未使用的导入和代码
+
+---
+
+## ✨ 最佳实践
+
+### 1. 使用共享包
+
+优先使用 `cmpt-huitu-ui` 和 `cmpt-huitu-utils`：
+
+```javascript
+// ✅ 推荐：使用共享工具函数
+import { parseTime, cache, modal } from 'cmpt-huitu-utils'
+
+// ✅ 推荐：使用共享 UI 组件
+import { HTable, VexTable, HtDialog } from 'cmpt-huitu-ui'
+
+// ❌ 不推荐：重复实现已有功能
+// function formatTime(time) { ... } // 已有 parseTime
+```
+
+### 2. 组件复用
+
+- 通用组件放在 `src/components/`
+- 页面级组件放在对应的 `views/` 子目录
+- 复杂逻辑抽离为 Composable 函数
+
+### 3. 性能优化
+
+- 使用路由懒加载
+- 大组件使用异步组件
+- 合理使用 `v-memo` 和 `v-once`
+- 图片使用懒加载
+
+```javascript
+// ✅ 路由懒加载（文件名使用 camelCase）
+component: () => import('@/views/user/index.vue')
+
+// ✅ 异步组件（文件名使用 camelCase）
+const AsyncComponent = defineAsyncComponent(() => import('@/components/heavyComponent.vue'))
+```
+
+### 4. 错误处理
+
+统一错误处理：
+
+```javascript
+// ✅ 推荐：统一错误处理
+try {
+  const res = await getUserList()
+  // 处理成功
+} catch (error) {
+  console.error('获取用户列表失败', error)
+  ElMessage.error('获取用户列表失败，请稍后重试')
+}
+```
+
+### 5. 类型安全
+
+利用自动生成的类型文件：
+
+```typescript
+// components.d.ts 和 imports.d.ts 由插件自动生成
+// 提供完整的类型提示
+```
+
+---
+
+## ⚠️ 注意事项
+
+### 1. 必须修改的配置
+
+- ✅ **`public/config/envCfg.js`** - 环境配置（API 地址、登录配置等）
+- ✅ **`index.html`** - 页面标题、项目名称
+- ✅ **`package.json`** - 项目名称、描述（CLI 会自动修改）
+- ✅ **`vite.config.js`** - 如需自定义构建配置
+
+### 2. 共享包依赖
+
+- ✅ 使用 `workspace:*` 在 Monorepo 中开发
+- ✅ CLI 创建项目时自动转换为版本号（如 `^1.0.0`）
+- ✅ 不要手动修改 `package.json` 中的共享包版本
+
+### 3. 样式变量
+
+- ✅ 使用 `cmpt-huitu-ui` 提供的全局 SCSS 变量
+- ✅ 自定义主题变量放在 `src/styles/theme/variables.scss`
+- ✅ 使用 `@use` 替代 `@import`（避免弃用警告）
+
+### 4. 路由模块
+
+- ✅ 路由模块自动导入，无需手动注册
+- ✅ 404 路由会自动添加到最后
+- ✅ 路由守卫在 `src/routers/guard.js` 中统一处理
+
+### 5. 环境变量
+
+- ✅ 只在 `.env` 文件中使用，不要提交到 Git
+- ✅ 使用 `VITE_` 前缀
+- ✅ 在代码中使用 `import.meta.env.VITE_XXX`
+
+### 6. 构建优化
+
+- ✅ 生产构建会自动压缩和优化
+- ✅ 使用 `pnpm preview` 预览生产构建结果
+- ✅ 构建产物在 `dist/` 目录
+
+---
+
+## 📚 相关文档
+
+- [Vue 3 官方文档](https://cn.vuejs.org/)
+- [Vite 官方文档](https://cn.vite.dev/)
+- [Element Plus 文档](https://element-plus.org/zh-CN/)
+- [Pinia 文档](https://pinia.vuejs.org/zh/)
+- [Vue Router 文档](https://router.vuejs.org/zh/)
+
+---
+
+## 🔄 更新日志
+
+- **v1.0.0** (2026-01-04)
+  - 初始版本
+  - 集成 Vue 3 + Vite + Element Plus
+  - 集成 cmpt-huitu-ui 和 cmpt-huitu-utils
+  - 完整的开发规范和最佳实践
+
+---
+
+**维护者**: 慧图前端团队  
+**最后更新**: 2026-01-04