---
description: TypeScript / Vue3 通用编码规范，适用于所有 .ts / .vue / .scss 文件
globs: ["src/**/*.{ts,vue,js,scss,css}"]
alwaysApply: true
---

# 编码规范

## TypeScript
1. **禁止 `any`**。不确定类型用 `unknown` 后收窄，或定义显式类型；实在无法确定的第三方数据用 `Record<string, unknown>`。
2. 业务数据结构必须有 **显式 interface**，统一放在 `src/types/`，命名 `XxxVO / XxxForm / XxxQuery`，不内联在组件里。
3. 使用 `import type { Xxx } from '@/types/xxx'` 导入纯类型，避免运行时冗余引入。
4. 枚举统一定义在 `src/enums/`，使用 `const` 对象 + `as const` 或 `enum`，**禁止散落的魔法字符串/数字**。
5. 空值处理优先用可选链 `?.` 与空值合并 `??`，避免多层 `&&` 嵌套。
6. 不允许使用 `// @ts-ignore`、`eslint-disable` 掩盖问题；确有必要的必须写清原因。

## Vue 组件
1. 组件一律 `<script setup lang="ts">`，禁止 Options API。
2. `defineProps` / `defineEmits` 必须带类型：
   ```vue
   const props = defineProps<{ modelValue: string; disabled?: boolean }>()
   const emit = defineEmits<{ (e: 'update:modelValue', v: string): void }>()
   ```
3. Props 命名 camelCase，模板中绑定用 kebab-case；禁止在子组件内直接修改 props。
4. 单向数据流：子组件通过 emit 或 `defineExpose` 暴露方法，父组件通过 `ref` 调用。
5. 响应式选择：基础数据用 `ref`，对象表单用 `reactive`；**禁止对 `reactive` 整体重新赋值**，需要重置时用 `Object.assign`。
6. 副作用统一写在 `watch` / `watchEffect` / `onMounted`，并注意在 `onUnmounted` 清理定时器与事件监听。
7. 计算属性必须无副作用；有副作用的逻辑放到方法或 watch。
8. `v-if` 与 `v-for` 不得同处一个元素；`v-for` 必须提供稳定 `:key`（禁止用 index）。
9. 组件文件超过 300 行必须拆分；表单弹窗拆成独立子组件。

## 模板与样式
1. 模板保持简洁，复杂判断抽成 computed，禁止在模板里写长表达式。
2. 样式必须 `<style scoped lang="scss">`；覆盖 Element Plus 内部样式用 `:deep()`，且必须限定父级作用域，禁止全局裸写。
3. 颜色、圆角、间距等使用 `src/styles/variables.scss` 中的变量，**禁止硬编码色值**。
4. 布局优先使用 Element Plus 的 `el-row/el-col` 与 flex 工具类，不写魔法 `margin-top: 17px`。

## 注释与命名
1. 注释只解释"为什么"，不解释"做了什么"。禁止无意义注释、禁止注释掉的代码块。
2. 函数/变量命名见名知意，布尔值用 `is/has/can` 前缀，事件处理用 `handleXxx`，接口调用用 `fetchXxx / createXxx / updateXxx / deleteXxx`。
3. 代码中不得出现 `console.log`、调试代码与 TODO 之外的临时标记。

## Git 提交
使用 Conventional Commits：`feat|fix|refactor|perf|style|docs|chore|test(scope): subject`，一次提交只做一件事。