cmpt-huitu-cli 1.0.13 → 1.0.15

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

@@ -53,16 +53,16 @@ trigger: always_on
 
 - **Element Plus**: `^2.11.1`
 - **@element-plus/icons-vue**: `^2.3.2`
+- **ECharts**: `^5.5.0` (通过 `cmpt-huitu-ui` 集成)
 
 ### 共享包
 
-- **cmpt-huitu-ui**: `^1.0.0` - UI 组件库
-- **cmpt-huitu-utils**: `^1.0.0` - 工具函数库
+- **cmpt-huitu-ui**: `workspace:*` - UI 组件库
+- **cmpt-huitu-utils**: `workspace:*` - 工具函数库
 
 ### 工具库
 
 - **axios**: `^1.11.0` - HTTP 客户端
-- **dayjs**: `^1.11.18` - 时间处理
 - **lodash-es**: `^4.17.21` - 工具函数
 - **nprogress**: `^0.2.0` - 进度条
 
@@ -166,24 +166,25 @@ trigger: always_on
 
 - **会被 Vite 处理**，支持导入和路径别名
 - 存放会被代码引用的资源（图片、字体等）
-- 支持动态导入和路径别名 `@/assets/...`
+- 支持动态导入和路径别名 `@assets/...`
 
 #### `src/routers/modules/` - 路由模块
 
 - **自动导入**：Vite 会自动扫描并合并所有 `.js` 文件
-- 每个模块导出一个路由对象或数组
+- 每个模块导出一个路由对象数组 `export default [...]`
 - 文件名建议使用 `模块名.js` 格式
 
 #### `src/stores/` - 状态管理
 
 - 使用 Pinia，按模块组织
 - 每个模块一个文件，文件名即 store id
+- 推荐使用 Options API 风格定义 Store (与模板保持一致)，但也支持 Composition API
 
 #### `src/services/` - API 服务
 
 - 按功能模块组织 API 请求
 - 每个文件对应一个业务模块
-- 统一使用 `@/utils/requestAxios.js` 封装的 axios 实例
+- 统一使用 `@utils/requestAxios.js` 封装的 axios 实例
 
 ---
 
@@ -207,31 +208,10 @@ trigger: always_on
 </script>
 ```
 
-#### 1.1 组件文件命名
+#### 2. 组件命名
 
 - **组件文件名**：使用 **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）
+- **组件注册名**：在模板中使用时，Vue 会自动处理大小写转换
 - **Props 定义**：使用对象形式，提供类型和默认值
 
 ```vue
@@ -250,7 +230,7 @@ trigger: always_on
 </script>
 ```
 
-#### 4. 样式规范
+#### 3. 样式规范
 
 - **使用 Scoped 样式**：避免样式污染
 - **使用 CSS 变量**：利用主题系统
@@ -270,34 +250,31 @@ trigger: always_on
 
 #### 1. 路由模块化
 
-在 `src/routers/modules/` 下创建路由模块：
+在 `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'),
+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. 路由元信息
+#### 2. 路由元信息
 
 使用 `meta` 字段存储路由元信息：
 
@@ -306,7 +283,6 @@ export default {
   meta: {
     title: '页面标题',        // 页面标题
     requiresAuth: true,       // 是否需要登录
-    roles: ['admin'],         // 权限角色
     keepAlive: true,          // 是否缓存
     hidden: false,            // 是否在菜单中隐藏
   },
@@ -317,38 +293,26 @@ export default {
 
 #### 1. Store 定义
 
-使用 `defineStore` 定义 store：
+使用 `defineStore` 定义 store，模板默认使用 Options API 风格：
 
 ```javascript
-// src/stores/user.js
+// src/stores/index/global.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
-  }
+export const globalStore = defineStore('global', {
+  state: () => ({
+    themeVal: 'light',
+    isLoading: false,
+  }),
 
-  function logout() {
-    userInfo.value = null
-    token.value = ''
-  }
-
-  return {
-    userInfo,
-    token,
-    isLoggedIn,
-    setUserInfo,
-    logout,
-  }
+  actions: {
+    changeGlobalTheme(theme) {
+      this.themeVal = theme
+    },
+    setIsLoadingStore(status) {
+      this.isLoading = status
+    },
+  },
 })
 ```
 
@@ -358,20 +322,17 @@ export const useUserStore = defineStore('user', () => {
 
 ```vue
 <script setup>
-  import { useUserStore } from '@/stores/user'
+  import { globalStore } from '@/stores/index/global'
+  import { storeToRefs } from 'pinia'
 
-  const userStore = useUserStore()
+  // 1. 实例化 Store
+  const store = globalStore()
 
-  // 访问 state
-  console.log(userStore.userInfo)
+  // 2. 解构 state 需要使用 storeToRefs 保持响应式
+  const { themeVal } = storeToRefs(store)
 
-  // 调用 action
-  userStore.setUserInfo({ name: 'John' })
-
-  // 使用 getter
-  if (userStore.isLoggedIn) {
-    // ...
-  }
+  // 3. 解构 actions 可以直接使用
+  const { changeGlobalTheme } = store
 </script>
 ```
 
@@ -381,7 +342,7 @@ export const useUserStore = defineStore('user', () => {
 
 ```javascript
 // src/services/user.js
-import request from '@/utils/requestAxios'
+import { axiosInstance as request } from '@/utils/requestAxios'
 
 // ✅ 推荐：统一使用封装的 request
 export function getUserList(params) {
@@ -401,24 +362,15 @@ export function createUser(data) {
 }
 ```
 
-#### 2. 在组件中使用
+#### 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>
+在某些场景（如通用组件库）中，可以使用依赖注入获取 request 实例：
+
+```javascript
+import { getCurrentInstance } from 'vue'
+
+const { proxy } = getCurrentInstance()
+// proxy.$request 也是可用的
 ```
 
 ---
@@ -435,19 +387,13 @@ export function createUser(data) {
 | **工具函数**   | 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` 中定义的路径别名：
+使用 `vite.config.js` 中定义的路径别名：
 
 | 别名           | 对应路径          | 用途         |
 | -------------- | ----------------- | ------------ |
+| `~/`           | `./`              | 项目根目录   |
 | `@/`           | `src/`            | 源代码根目录 |
 | `@public/`     | `public/`         | 静态资源目录 |
 | `@components/` | `src/components/` | 全局组件     |
@@ -458,16 +404,7 @@ export function createUser(data) {
 | `@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'
-```
+| `@plugins/`    | `src/plugins/`    | 插件配置     |
 
 ---
 
@@ -490,7 +427,6 @@ const config = {
 
   // 文件服务配置
   uploadUrl: origin + '/upload',
-  downloadUrl: origin + '/download',
 
   // ... 其他配置
 }
@@ -505,85 +441,17 @@ const config = {
 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 提交规范
+### ECharts 引入规范
 
-遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
-
-```bash
-# 功能新增
-git commit -m "feat: 添加用户管理页面"
+**允许全量引入**：为了避免构建时的 `install` 导出警告，并简化开发，本项目允许直接全量引入 ECharts。
 
-# 问题修复
-git commit -m "fix: 修复登录后跳转错误"
-
-# 文档更新
-git commit -m "docs: 更新 README"
-
-# 代码重构
-git commit -m "refactor: 重构用户服务代码"
-
-# 样式调整
-git commit -m "style: 调整页面布局"
+```javascript
+// packages/ui/index.js
+import * as echarts from 'echarts'
 ```
 
-### 3. 代码审查要点
-
-- ✅ 是否遵循命名规范
-- ✅ 是否使用路径别名而非相对路径
-- ✅ 是否正确处理异步操作（try-catch）
-- ✅ 是否使用共享包而非重复实现
-- ✅ 样式是否使用 scoped 或 CSS 变量
-- ✅ 是否移除未使用的导入和代码
-
 ---
 
 ## ✨ 最佳实践
@@ -594,13 +462,10 @@ git commit -m "style: 调整页面布局"
 
 ```javascript
 // ✅ 推荐：使用共享工具函数
-import { parseTime, cache, modal } from 'cmpt-huitu-utils'
+import { cache } from 'cmpt-huitu-utils'
 
 // ✅ 推荐：使用共享 UI 组件
-import { HTable, VexTable, HtDialog } from 'cmpt-huitu-ui'
-
-// ❌ 不推荐：重复实现已有功能
-// function formatTime(time) { ... } // 已有 parseTime
+import { HTable, VexTable } from 'cmpt-huitu-ui'
 ```
 
 ### 2. 组件复用
@@ -614,40 +479,20 @@ import { HTable, VexTable, HtDialog } from 'cmpt-huitu-ui'
 - 使用路由懒加载
 - 大组件使用异步组件
 - 合理使用 `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('获取用户列表失败，请稍后重试')
+  // requestAxios 已有统一的错误拦截提示，通常无需再次弹窗
 }
 ```
 
-### 5. 类型安全
-
-利用自动生成的类型文件：
-
-```typescript
-// components.d.ts 和 imports.d.ts 由插件自动生成
-// 提供完整的类型提示
-```
-
 ---
 
 ## ⚠️ 注意事项
@@ -657,37 +502,26 @@ try {
 - ✅ **`public/config/envCfg.js`** - 环境配置（API 地址、登录配置等）
 - ✅ **`index.html`** - 页面标题、项目名称
 - ✅ **`package.json`** - 项目名称、描述（CLI 会自动修改）
-- ✅ **`vite.config.js`** - 如需自定义构建配置
 
 ### 2. 共享包依赖
 
 - ✅ 使用 `workspace:*` 在 Monorepo 中开发
-- ✅ CLI 创建项目时自动转换为版本号（如 `^1.0.0`）
+- ✅ CLI 创建项目时自动转换为版本号
 - ✅ 不要手动修改 `package.json` 中的共享包版本
 
 ### 3. 样式变量
 
-- ✅ 使用 `cmpt-huitu-ui` 提供的全局 SCSS 变量
+- ✅ 自动注入了 `cmpt-huitu-ui` 的全局 SCSS 变量（在 vite.config.js 中配置）
 - ✅ 自定义主题变量放在 `src/styles/theme/variables.scss`
-- ✅ 使用 `@use` 替代 `@import`（避免弃用警告）
 
 ### 4. 路由模块
 
-- ✅ 路由模块自动导入，无需手动注册
+- ✅ 路由模块自动导入，**必需导出数组**
 - ✅ 404 路由会自动添加到最后
-- ✅ 路由守卫在 `src/routers/guard.js` 中统一处理
-
-### 5. 环境变量
 
-- ✅ 只在 `.env` 文件中使用，不要提交到 Git
-- ✅ 使用 `VITE_` 前缀
-- ✅ 在代码中使用 `import.meta.env.VITE_XXX`
+### 5. 跨平台兼容性
 
-### 6. 构建优化
-
-- ✅ 生产构建会自动压缩和优化
-- ✅ 使用 `pnpm preview` 预览生产构建结果
-- ✅ 构建产物在 `dist/` 目录
+- ✅ **禁止**在 `package.json` 的 `dependencies` 中硬编码平台特定依赖（如 `@esbuild/darwin-arm64`），这会导致 Windows 环境安装失败。
 
 ---
 
@@ -701,15 +535,4 @@ try {
 
 ---
 
-## 🔄 更新日志
-
-- **v1.0.0** (2026-01-04)
-  - 初始版本
-  - 集成 Vue 3 + Vite + Element Plus
-  - 集成 cmpt-huitu-ui 和 cmpt-huitu-utils
-  - 完整的开发规范和最佳实践
-
----
-
-**维护者**: 慧图前端团队  
-**最后更新**: 2026-01-04
+**最后更新**: 2026-01-14