---
description: "Vue 3 + Vite 前端开发规范（TypeScript）。管理端使用 Element Plus，用户端使用 Headless UI + Tailwind（禁止 Element Plus）"
globs:
  - "**/*.vue"
  - "Case-Database-Frontend-user/src/**/*.ts"
  - "Case-Database-Frontend-admin/src/**/*.ts"
alwaysApply: false
---

# Vue 3 / Vite Standards + 双前端上下文

> **双前端区分**：管理端 (`Case-Database-Frontend-admin/`) 使用 Element Plus；
> 用户端 (`Case-Database-Frontend-user/`) 使用 Headless UI + Tailwind CSS，**禁止引入 Element Plus**。

## 组件与脚本约束

- 默认使用 `<script setup>` + Composition API
- Props/Emits 显式声明，避免隐式双向修改
- 页面与组件职责分离：页面编排，组件渲染
- 可复用逻辑抽离到 composables / utils

### Emits 命名约定

- `defineEmits` 中自定义事件使用 **camelCase**（`addItem`、`removeItem`）
- `update:xxx` 前缀保留给 v-model 双向绑定约定
- 模板中 `@add-item` 和 `@addItem` 均可（Vue 自动转换），但 defineEmits 源头必须 camelCase

```vue
<!-- ❌ kebab-case -->
defineEmits<{ 'add-item': []; 'remove-item': [id: number] }>()

<!-- ✅ camelCase -->
defineEmits<{ addItem: []; removeItem: [id: number] }>()
```

## 状态与数据流

- 全局状态使用 Pinia；局部状态留在组件内
- 单向数据流：`props down, events up`
- 远端请求统一经 service/api 层，不在模板内混写

### Props 数据流模式（⚠️ 必须遵守）

子组件**禁止**直接修改 prop 或 prop 的嵌套属性。变更必须通过 emit 通知父组件。

**模式 A：子组件接收对象 prop，需修改其字段**

```vue
<!-- ❌ 直接 v-model 绑定 prop 字段（触发 vue/no-mutating-props） -->
<AppInput v-model="form.username" />

<!-- ✅ 拆分为 :model-value + emit -->
<AppInput
  :model-value="form.username"
  @update:model-value="emit('update:form', { ...props.form, username: $event })"
/>
```

**模式 B：子组件中继 v-model 到子子组件**

```vue
<!-- ❌ 用 v-model 直接绑定动态 prop key -->
<RadioGroup v-model="radios[f.key]" />

<!-- ✅ 拆分并向上 emit -->
<RadioGroup
  :model-value="radios[f.key]"
  @update:model-value="emit('update:radio', f.key, $event)"
/>
```

**模式 C：事件回调中修改 prop（隐蔽变体）**

```vue
<!-- ❌ 在事件处理中直接赋值 prop 属性 -->
<LogicTable @update="(k, v) => logics[k] = v" />

<!-- ✅ 转发为 emit -->
<LogicTable @update="(k, v) => emit('update:logic', k, v)" />
```

**父组件响应模式（状态持有方）：**

```vue
<!-- 父组件持有 reactive 状态，处理 update 事件 -->
<ChildForm
  :form="formData"
  @update:form="Object.assign(formData, $event)"
/>
<!-- 或逐字段更新 -->
<FilterBody
  :radios="radios"
  @update:radio="(key, val) => radios[key] = val"
/>
```

## 性能与可维护性

- 列表必须 `key` 稳定；重计算走 `computed`
- 禁止在模板调用高开销函数

### SFC 行数限制（强制）

- template <= 80 行，script <= 60 行，整个 SFC <= 150 行
- 超出 script 60 行 → 提取 composable (`use<Name>.ts`)
- 超出 SFC 150 行 → 拆分子组件

### 组件设计决策（新建和修改时均适用）

- >=3 个布尔 prop → 拆分为显式变体组件
- 多子组件共享状态 → provide/inject
- script > 60 行 → 提取 `use<Name>.ts` composable
- 同一 UI 结构出现 >=3 次 → 提取基础组件

## 可访问性与一致性

- 表单项必须有可读 label / 提示
- 错误状态、空状态、加载状态必须可见
- 命名、目录、导出方式保持一致

## 验证清单

- [ ] ESLint 无错误
- [ ] 子组件不直接修改 prop（无 `v-model="prop.field"` 或 `prop[key] = val` 模式）
- [ ] defineEmits 使用 camelCase 命名（非 kebab-case）
- [ ] 关键交互具备加载/错误处理
- [ ] 组件结构清晰，可复用逻辑已抽离
- [ ] UI 语义与可访问性基础达标

---

## 双前端上下文规则

Agent 在生成代码前必须先判断目标前端：

- 路径含 `Case-Database-Frontend-user/` → **用户端模式**
- 路径含 `Case-Database-Frontend-admin/` → **管理端模式**
- 路径含 `Case-Database-Frontend-shared/` → **共享层模式**（纯 JS，无 UI 依赖）

### 用户端规则

- **移动端优先**：断点顺序 `默认(xs) → sm → md → lg → xl`
- 触摸目标最小 44x44px，交互元素间距 >= 8px
- UI 组件使用 Tailwind CSS + 自定义组件（非 Element Plus）
- 图片必须指定 `width`、`height`、`alt`，推荐 WebP
- 路由懒加载：每个页面独立 chunk
- 禁止在用户端引入 Element Plus
- 权限模型：登录态 + 会员等级
- API 基础路径：`/api/`
- 首屏 LCP 目标 <= 2.5s（移动网络），单路由 chunk <= 200KB

### 管理端规则

- **桌面端优先**：以 1280px 宽度为基准，支持 >= 1024px
- 优先使用 Element Plus 标准组件（`el-table`、`el-form`、`el-dialog`）
- 每个操作必须有权限检查（`v-permission`）
- 危险操作必须有二次确认（`el-popconfirm`）
- 表单使用 `el-form` + `:rules` 验证，弹窗关闭时重置
- 分页统一 `el-pagination`，默认 page_size: 10
- 表格操作列固定右侧（`fixed="right"`）
- API 基础路径：`/admin/`
- 401 → 清除 Token → 登录页；403 → Toast "无权限"

### 共享层规则

- 只允许纯 TypeScript，禁止引入 Vue、Element Plus、axios
- 导出的函数/常量必须同时适配用户端和管理端
- 修改后需同步通知两个前端的相关使用方

## ESLint 配置注意事项

### vue/block-order 等 Vue 专属规则必须限定文件范围

`vue/block-order` 规则依赖 Vue 文件解析器，**不能**放在全局 `rules` 中，否则对 `.md`、`.json`、`.ts` 等非 Vue 文件生效时会崩溃：

```js
// ❌ 错误：全局规则，对所有文件生效，README.md 会 TypeError 崩溃
export default antfu({
  rules: {
    'vue/block-order': ['error', { order: ['script', 'template', 'style'] }],
  },
});

// ✅ 正确：限定在 *.vue 文件
export default antfu({ ... }, {
  files: ['**/*.vue'],
  rules: {
    'vue/block-order': ['error', { order: ['script', 'template', 'style'] }],
  },
});
```

所有 `vue/*` 前缀的规则若要手动覆盖，都必须放在 `files: ['**/*.vue']` 覆盖块内。

## Tier 3 深度参考

- `.cursor/rules/references/011-vue-deep.md` — 完整 Vue 规范与反模式示例
- `docs/architecture/frontend-strategy.md` — 完整双前端架构说明
- `docs/guides/ui-specs-user.md` — 用户端 UI 规范
- `docs/guides/ui-specs-admin.md` — 管理端 UI 规范