@qilitt-mickey/vue3-temp-skill 1.0.8

package/references/build-optim.md

@@ -0,0 +1,282 @@
+---
+skill: build-optim
+description: 规范 Vite 构建配置、代码分割策略、性能优化手段和开发工具链（ESLint、Stylelint、Commitlint）。在修改构建配置或优化工具链时调用。
+scope: project
+tags: [vue3, vite, build, optimization, eslint, stylelint, commitlint, husky, performance]
+---
+
+# 构建优化与工程化配置
+
+## Vite 构建配置
+
+### 核心配置
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import UnoCSS from "unocss/vite";
+import { resolve } from "path";
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    UnoCSS(),
+    // 自动导入：Element Plus / Vant 组件按需引入
+    AutoImport({
+      imports: ["vue", "vue-router", "pinia"],
+      dts: "src/auto-imports.d.ts",
+    }),
+    Components({
+      resolvers: [
+        ElementPlusResolver(),
+        VantResolver(),
+      ],
+      dts: "src/components.d.ts",
+    }),
+  ],
+
+  resolve: {
+    alias: {
+      "@": resolve(__dirname, "src"),
+    },
+  },
+
+  build: {
+    target: "es2020",
+    minify: "oxc",
+    sourcemap: false,
+
+    rollupOptions: {
+      output: {
+        // 手动分包
+        manualChunks: {
+          "vue-vendor": ["vue", "vue-router", "pinia"],
+          "ui-vendor": ["element-plus"],
+          "chart-vendor": ["echarts"],
+        },
+        // 产物目录结构
+        chunkFileNames: "assets/js/[name]-[hash].js",
+        entryFileNames: "assets/js/[name]-[hash].js",
+        assetFileNames: "assets/[ext]/[name]-[hash].[ext]",
+      },
+    },
+
+    // 代码分割阈值
+    chunkSizeWarningLimit: 1000,
+  },
+
+  // 开发服务器
+  server: {
+    port: 8848,
+    host: true,
+    proxy: {
+      "/api": {
+        target: "http://localhost:8080",
+        changeOrigin: true,
+      },
+    },
+  },
+});
+```
+
+### 构建约定
+
+1. 使用 Vite 8.x（基于 Rolldown 构建引擎），不要使用 Webpack 相关配置。
+2. `manualChunks` 必须将 Vue 生态、UI 库、图表库分开打包。
+3. 压缩使用 `oxc`（Oxc 编译器），不使用 terser。
+4. 生产环境关闭 `sourcemap`。
+5. 静态资源按类型分目录输出（js/css/img/font）。
+6. 单个 chunk 超过 1000KB 时发出警告。
+
+## 代码分割策略
+
+### 路由级懒加载
+
+所有页面组件必须使用动态 `import()` 懒加载：
+
+```typescript
+// 正确
+component: () => import("@/views/system/user/index.vue")
+
+// 错误（会导致首屏加载全部页面）
+component: SystemUser
+```
+
+### 大型库按需引入
+
+```typescript
+// ECharts 按需引入
+import * as echarts from "echarts/core";
+import { BarChart, LineChart, PieChart } from "echarts/charts";
+import { GridComponent, TooltipComponent, TitleComponent } from "echarts/components";
+import { CanvasRenderer } from "echarts/renderers";
+
+echarts.use([
+  BarChart, LineChart, PieChart,
+  GridComponent, TooltipComponent, TitleComponent,
+  CanvasRenderer,
+]);
+
+// 或者使用完整引入（仅在确实需要全部图表类型时）
+// import * as echarts from "echarts";
+```
+
+### 分包建议
+
+| 分包名 | 包含内容 | 预估大小 |
+|--------|---------|---------|
+| vue-vendor | vue, vue-router, pinia | ~150KB |
+| ui-vendor | element-plus | ~300KB（按需引入后更小） |
+| chart-vendor | echarts | ~400KB（按需引入后更小） |
+| editor-vendor | wangeditor | ~200KB |
+| workflow-vendor | bpmn-js | ~500KB |
+
+## UnoCSS 配置
+
+```typescript
+// uno.config.ts
+import { defineConfig, presetWind3, presetAttributify, presetRemToPx } from "unocss";
+
+export default defineConfig({
+  presets: [
+    presetWind3(),        // Tailwind Wind 兼容
+    presetAttributify(),  // 属性化模式
+    presetRemToPx(),      // rem 转 px（适配移动端）
+  ],
+  shortcuts: {
+    "flex-center": "flex items-center justify-center",
+    "flex-between": "flex items-center justify-between",
+    "card-base": "rounded-lg bg-white p-4 shadow-sm",
+  },
+  safelist: [
+    // 动态类名需要加入 safelist
+    "text-red-500", "text-green-500", "text-blue-500",
+  ],
+});
+```
+
+## 代码质量工具链
+
+### 工具分工
+
+| 工具 | 职责 | 配置文件 |
+|------|------|---------|
+| oxlint | 高速 lint 检查（替代部分 ESLint 规则） | `oxlintrc.json` |
+| ESLint | 代码规范（@antfu/eslint-config） | `eslint.config.ts` |
+| Stylelint | CSS/SCSS 规范 | `stylelint.config.js` |
+| Prettier | 代码格式化 | `prettier.config.js` |
+| Husky | Git Hooks 管理 | `.husky/` |
+| Commitlint | 提交信息规范 | `commitlint.config.js` |
+
+### ESLint 配置
+
+```typescript
+// eslint.config.ts
+import antfu from "@antfu/eslint-config";
+
+export default antfu({
+  unocss: true,
+  vue: true,
+  typescript: true,
+  rules: {
+    "no-console": "warn",
+    "no-debugger": "error",
+    "vue/no-v-html": "off",
+    "@typescript-eslint/no-explicit-any": "warn",
+  },
+});
+```
+
+### Stylelint 配置
+
+```javascript
+// stylelint.config.js
+export default {
+  extends: [
+    "stylelint-config-standard-scss",
+    "stylelint-config-recess-order",
+  ],
+  rules: {
+    "selector-class-pattern": null,  // 允许 BEM / kebab-case
+    "no-descending-specificity": null,
+    "scss/at-mixin-pattern": null,
+  },
+};
+```
+
+### Commitlint 规范
+
+```javascript
+// commitlint.config.js
+export default {
+  extends: ["@commitlint/config-conventional"],
+  rules: {
+    "type-enum": [2, "always", [
+      "feat",     // 新功能
+      "fix",      // 修复
+      "docs",     // 文档
+      "style",    // 格式
+      "refactor", // 重构
+      "perf",     // 性能
+      "test",     // 测试
+      "chore",    // 构建/工具
+      "revert",   // 回退
+    ]],
+    "subject-case": [0],
+    "subject-max-length": [2, "always", 100],
+  },
+};
+```
+
+### Husky Git Hooks
+
+```bash
+# .husky/pre-commit
+npx oxlint --fix
+npx lint-staged
+
+# .husky/commit-msg
+npx commitlint --edit "$1"
+```
+
+### lint-staged 配置
+
+```json
+// package.json
+{
+  "lint-staged": {
+    "*.{vue,ts,tsx,js,jsx}": ["eslint --fix"],
+    "*.{css,scss,vue}": ["stylelint --fix"],
+    "*.{vue,ts,tsx,js,jsx,css,scss,json,md}": ["prettier --write"]
+  }
+}
+```
+
+### 工具链约定
+
+1. oxlint 负责高速检查，ESLint 负责深度规范，两者互补不冲突。
+2. 提交前自动运行 `oxlint --fix` + `lint-staged`。
+3. 提交信息必须遵循 Conventional Commits 格式：`type(scope): description`。
+4. 不要在代码中使用 `// eslint-disable`，除非有充分理由并附注释说明。
+5. Stylelint 检查 SCSS 和 `<style>` 块中的样式。
+
+## 性能优化清单
+
+1. 路由懒加载：所有页面组件使用 `() => import()`。
+2. 组件按需引入：Element Plus / Vant 通过 `unplugin-vue-components` 自动导入。
+3. 图片优化：使用 `van-image` 的 `lazy-load` 属性，大屏图片使用 WebP 格式。
+4. 虚拟滚动：超过 1000 行的列表使用 `vxe-table` 的虚拟滚动。
+5. 请求去重：http 封装内置请求去重，相同请求自动取消前一个。
+6. 组件缓存：使用 `<keep-alive>` 缓存频繁切换的页面组件。
+7. 第三方库按需引入：ECharts、lodash 等只引入使用到的模块。
+8. 预加载：关键资源使用 `<link rel="preload">`，非关键资源使用 `<link rel="prefetch">`。
+
+## 常见反例
+
+- 页面组件不使用懒加载，直接 `import` 静态引入。
+- ECharts 完整引入而不按需导入（增加 400KB+ 体积）。
+- 构建配置中使用 `terser` 而不是 `oxc`（Vite 8 推荐 Oxc）。
+- 没有配置 `manualChunks`，所有依赖打成一个巨大 chunk。
+- 跳过 Git Hooks 直接提交代码（`--no-verify`）。
+- 在代码中大量使用 `eslint-disable` 注释。

package/references/code-quality.md

@@ -0,0 +1,235 @@
+---
+skill: code-quality
+description: AI 生成代码的质量审查清单。在生成或修改任何 Vue/TypeScript 代码后，必须对照此清单逐项自查，确保代码符合项目规范。适用于代码审查、AI 代码自检、Code Review 场景。
+scope: project
+tags: [code-review, quality, checklist, lint, typescript, vue3, security, performance]
+---
+
+# 代码质量审查清单
+
+> **使用说明**：在 AI 生成或修改代码后，逐项对照以下检查点。任何一项不通过，必须修正后再输出。此清单面向"小白"开发者，确保 AI 产出的代码能通过团队 Code Review。
+
+## 一、TypeScript 类型检查
+
+### 必须通过
+
+- [ ] 所有 `props` 有明确的类型定义，不使用 `any`。
+- [ ] 所有 API 返回值声明了泛型类型 `Result<T>`。
+- [ ] `ref()` 和 `reactive()` 声明了类型：`ref<string>("")`、`reactive<FormType>({})`。
+- [ ] 事件处理函数声明了参数类型：`(e: Event)`、`(row: UserInfo)`。
+- [ ] 组件 `defineProps` 使用泛型方式 `defineProps<Props>()`，不使用运行时声明。
+- [ ] 不使用 `@ts-ignore` 或 `@ts-nocheck`，除非有注释说明原因。
+- [ ] 类型定义放在 `type.ts` 或 `types/` 目录，不内联在组件中。
+
+### 常见错误示例
+
+```typescript
+// ❌ 错误：使用 any
+const data = ref<any>(null);
+const list = ref([]);  // 推断为 any[]
+
+// ✅ 正确：明确类型
+const data = ref<UserInfo | null>(null);
+const list = ref<UserListItem[]>([]);
+
+// ❌ 错误：API 无返回类型
+function getList(params) {
+  return http.request("post", url, { data: params });
+}
+
+// ✅ 正确：声明完整类型
+function getListApi(params: ListQuery): Promise<Result<ListResult>> {
+  return http.request<Result<ListResult>>("post", url, { data: params });
+}
+```
+
+## 二、Vue 组件规范检查
+
+### 必须通过
+
+- [ ] 使用 `<script setup lang="ts">`，不使用 Options API。
+- [ ] 使用 `defineOptions({ name: "ComponentName" })` 声明组件名。
+- [ ] `script` 标签第一行是 `import type { ... } from "./type"`。
+- [ ] Props 和 Emits 类型定义在同目录 `type.ts` 文件中。
+- [ ] 样式使用 `<style lang="scss" scoped>`。
+- [ ] 组件 class 名使用 `re-` 前缀（自定义组件）或有意义的业务前缀。
+- [ ] 没有硬编码中文文案（应使用 `$t()` 或配置化）。
+
+### 常见错误示例
+
+```vue
+<!-- ❌ 错误：Options API -->
+<script>
+export default {
+  data() { return { count: 0 } },
+  methods: { increment() { this.count++ } }
+}
+</script>
+
+<!-- ✅ 正确：Composition API + script setup -->
+<script setup lang="ts">
+import type { MyComponentProps } from "./type";
+defineOptions({ name: "MyComponent" });
+const props = defineProps<MyComponentProps>();
+const count = ref(0);
+function increment() { count.value++; }
+</script>
+```
+
+## 三、API 调用规范检查
+
+### 必须通过
+
+- [ ] API 调用封装在 `src/api/` 目录的函数中，不在组件中直接写 `http.request`。
+- [ ] 所有接口使用 POST 方法，参数通过 `data` 传递。
+- [ ] 接口函数命名符合 `[动作][模块]Api` 格式。
+- [ ] 接口参数和返回值有完整类型定义。
+- [ ] 下载请求设置了 `responseType: "blob"`。
+- [ ] 敏感数据（密码、身份证号）使用了加密请求 `crypto: true`。
+- [ ] 组件中 API 调用有 `try/finally` 或 `try/catch` 处理异常。
+
+### 常见错误示例
+
+```typescript
+// ❌ 错误：在组件中直接调用 http
+const res = await http.request("post", "/api/user/list", { data: params });
+
+// ✅ 正确：封装到 api/ 目录
+// src/api/user.ts
+export function getUserListApi(params: UserQuery) {
+  return http.request<Result<UserListResult>>("post", "/api/user/list", { data: params });
+}
+
+// ❌ 错误：使用 GET 方法
+http.request("get", "/api/user/list", { params });
+
+// ✅ 正确：统一 POST
+http.request("post", "/api/user/list", { data: params });
+```
+
+## 四、安全规范检查
+
+### 必须通过
+
+- [ ] 不在前端代码中硬编码密钥、Token、密码。
+- [ ] 用户输入在提交前做了前端校验（必填、格式、长度）。
+- [ ] XSS 防护：用户输入展示使用 `v-text` 而非 `v-html`，除非已做消毒处理。
+- [ ] 权限按钮使用 `v-auth` 指令控制，不手动判断角色。
+- [ ] 敏感操作（删除、提交）有二次确认弹窗。
+- [ ] 不在前端做安全校验（前端校验仅为体验优化，后端必须同步校验）。
+
+### 安全检查清单
+
+```typescript
+// ❌ 危险：v-html 直接渲染用户输入
+<div v-html="userInput" />
+
+// ✅ 安全：使用 v-text 或 {{ }} 插值
+<span v-text="userInput" />
+<span>{{ userInput }}</span>
+
+// ❌ 危险：硬编码密钥
+const apiKey = "sk-abc123456";
+
+// ✅ 安全：从环境变量或后端获取
+const apiKey = import.meta.env.VITE_API_KEY;
+```
+
+## 五、性能检查
+
+### 必须通过
+
+- [ ] 页面组件使用 `() => import()` 懒加载。
+- [ ] 列表数据量超过 100 行时使用了分页或虚拟滚动。
+- [ ] 图表组件在 `onUnmounted` 中调用了 `dispose()`。
+- [ ] 没有不必要的 `watch`（能用 `computed` 的场景不用 `watch`）。
+- [ ] `v-for` 循环使用了唯一且稳定的 `:key`，不使用 `index` 作为 key（列表会变动时）。
+- [ ] 大数组操作使用 `computed` 缓存结果，不在 template 中直接调用方法。
+- [ ] 图片使用了懒加载（移动端 `van-image lazy-load`）。
+- [ ] 事件监听器在组件卸载时正确移除（`onUnmounted` 中 `removeEventListener`）。
+
+### 常见错误示例
+
+```typescript
+// ❌ 错误：watch 可以用 computed 替代
+watch(searchText, () => {
+  filteredList.value = list.value.filter(item => item.name.includes(searchText.value));
+});
+
+// ✅ 正确：使用 computed
+const filteredList = computed(() =>
+  list.value.filter(item => item.name.includes(searchText.value))
+);
+
+// ❌ 错误：template 中调用方法（每次渲染都执行）
+<template>{{ getFullName(user) }}</template>
+
+// ✅ 正确：使用 computed 缓存
+const fullName = computed(() => `${user.firstName} ${user.lastName}`);
+```
+
+## 六、样式规范检查
+
+### 必须通过
+
+- [ ] 样式使用 `scoped`，不会污染全局。
+- [ ] 颜色使用 CSS 变量（`var(--el-color-primary)`），不硬编码。
+- [ ] 优先使用 UnoCSS 原子类（`flex-center`、`mb-4`）。
+- [ ] 不使用 `!important`，除非覆盖第三方组件样式且有注释说明。
+- [ ] 不使用深层嵌套选择器（不超过 3 层）。
+- [ ] 移动端不使用固定 `px` 宽度，使用 `rem` 或百分比。
+- [ ] 新增全局样式时，同步在 `dark.scss` 中添加暗黑模式覆盖。
+- [ ] 不直接修改 `--el-color-primary`，而是通过 `setEpThemeColor()` 设置（保证色阶同步更新）。
+- [ ] 使用 `chroma-js` 处理颜色，不使用 `color`、`polished` 等其他库。
+- [ ] 侧边栏相关样式通过 `html[data-theme]` 选择器设置，不写在 `:root` 中。
+- [ ] 覆盖 Element Plus 组件的全局样式放在 `src/styles/element-plus.scss`，不在组件内写。
+
+## 七、业务逻辑检查
+
+### 必须通过
+
+- [ ] 表单提交前调用了 `validate()`。
+- [ ] 删除操作有确认弹窗（`ElMessageBox.confirm` 或 `showConfirmDialog`）。
+- [ ] 提交按钮有 `loading` 状态防止重复提交。
+- [ ] 列表页有加载状态（`v-loading`）。
+- [ ] 空数据有占位提示（`el-empty` 或 `van-empty`）。
+- [ ] 编辑页正确加载并回显了已有数据。
+- [ ] 路由跳转使用了正确的参数传递方式（`query` 而非 `params`）。
+- [ ] 分页切换正确触发了数据加载。
+
+## 八、代码风格检查
+
+### 必须通过
+
+- [ ] 使用 `const` / `let`，不使用 `var`。
+- [ ] 字符串使用双引号（遵循 ESLint 配置），模板字符串用于变量拼接。
+- [ ] 函数和变量使用驼峰命名。
+- [ ] 组件名使用大驼峰（`UserList`），文件名使用短横线（`user-list.vue`）。
+- [ ] 常量使用全大写下划线分隔（`MAX_PAGE_SIZE`）。
+- [ ] 没有未使用的变量、导入或参数。
+- [ ] 没有 `console.log` 残留（生产代码中）。
+
+## 审查流程
+
+1. **生成代码后**：逐项对照以上清单。
+2. **发现问题**：立即修正，不要输出有问题的代码。
+3. **不确定项**：标注 `// TODO: 需要确认` 注释提醒开发者。
+4. **严重问题**：如果存在安全漏洞或类型错误，必须修正后再输出。
+
+## 快速自检命令
+
+完成代码修改后，运行以下命令验证：
+
+```bash
+# TypeScript 类型检查
+npx vue-tsc --noEmit
+
+# ESLint 检查
+npx eslint src/ --ext .vue,.ts,.tsx
+
+# Stylelint 检查
+npx stylelint "src/**/*.{css,scss,vue}"
+
+# 全量检查（推荐）
+pnpm lint
+```