初始化

2026-03-05 21:27:11 +08:00
commit 130de0fd5d
140 changed files with 21972 additions and 0 deletions
--- a/.cursor/skills/component-scaffold/references/component-templates.md
+++ b/.cursor/skills/component-scaffold/references/component-templates.md
@@ -0,0 +1,117 @@
+# Component Scaffold — 组件模板
+
+> 主流程见 SKILL.md，本文档为各类 Vue 3 组件的完整模板。
+>
+> **⚠️ 双前端区分**：本文件中使用 `el-*` 组件的模板**仅适用于管理端** (`Case-Database-Frontend-admin/`)。
+> 用户端 (`Case-Database-Frontend-user/`) 使用 Headless UI + Tailwind CSS，**禁止引入 Element Plus**。
+
+## 基础 UI 组件
+
+```vue
+<script setup>
+const props = defineProps({
+  title: { type: String, required: true },
+  loading: { type: Boolean, default: false },
+})
+const emit = defineEmits(['refresh'])
+</script>
+<template>
+  <div class="rounded-lg border border-gray-200 p-4" data-testid="component-name">
+    <h3 class="text-lg font-semibold mb-2">{{ props.title }}</h3>
+    <slot />
+    <el-button v-if="props.loading" :loading="true" class="mt-2" />
+  </div>
+</template>
+```
+
+## 表格组件 (Element Plus)
+
+```vue
+<script setup>
+import { useTable } from '@/hooks/useTable'
+const props = defineProps({ apiUrl: { type: String, required: true }, columns: { type: Array, required: true } })
+const { loading, dataList, pagination, loadData } = useTable((params) => request.get(props.apiUrl, { params }))
+onMounted(() => loadData())
+</script>
+<template>
+  <div class="space-y-4">
+    <el-table v-loading="loading" :data="dataList" border stripe data-testid="data-table">
+      <el-table-column v-for="col in columns" :key="col.prop" v-bind="col" />
+      <el-table-column label="操作" fixed="right" width="180">
+        <template #default="{ row }"><slot name="actions" :row="row" /></template>
+      </el-table-column>
+    </el-table>
+    <el-pagination v-model:current-page="pagination.current" v-model:page-size="pagination.size" :total="pagination.total"
+      layout="total, sizes, prev, pager, next" @current-change="loadData" @size-change="loadData" />
+  </div>
+</template>
+```
+
+## 表单对话框组件
+
+```vue
+<script setup>
+const props = defineProps({ visible: { type: Boolean, required: true }, title: { type: String, required: true }, formData: { type: Object, default: () => ({}) } })
+const emit = defineEmits(['update:visible', 'submit'])
+const formRef = ref()
+const form = reactive({ ...props.formData })
+const rules = { name: [{ required: true, message: '请输入名称', trigger: 'blur' }] }
+async function handleSubmit() { await formRef.value?.validate(); emit('submit', { ...form }) }
+</script>
+<template>
+  <el-dialog :model-value="visible" :title="title" width="600px" @update:model-value="emit('update:visible', $event)">
+    <el-form ref="formRef" :model="form" :rules="rules" label-width="100px">
+      <el-form-item label="名称" prop="name"><el-input v-model="form.name" placeholder="请输入" /></el-form-item>
+      <slot name="form-fields" :form="form" />
+    </el-form>
+    <template #footer>
+      <el-button @click="emit('update:visible', false)">取消</el-button>
+      <el-button type="primary" @click="handleSubmit">确认</el-button>
+    </template>
+  </el-dialog>
+</template>
+```
+
+## 复合组件 (Compound + provide/inject)
+
+Provider 组件：provide 状态 + actions。子组件：inject 消费。keys.ts 定义 Symbol + useDataPanel()。消费者组合：`<DataPanelProvider :fetch-fn="orderApi.list"><DataPanelContent /></DataPanelProvider>`
+
+## 组件设计决策树
+
+```
+≥3 个布尔 prop 控制渲染？→ 拆分为显式变体组件
+多个子组件共享状态？→ provide/inject 复合组件
+业务逻辑 > 50 行？→ 提取 composable
+>2 处复用？→ 放入 src/components/，使用 slot
+否则 → 基础 UI 组件模板
+```
+
+## 逻辑提取规则 (CRITICAL)
+
+纯转换逻辑必须提取到 `ComponentName.utils.ts`，组件只保留 UI 和事件。文件结构：`ComponentName.vue` + `ComponentName.utils.ts` + `ComponentName.utils.test.ts` + `ComponentName.test.ts`（可选）+ `index.ts`
+
+## 复杂度阈值
+
+| 指标 | 阈值 | 动作 |
+|---|---|---|
+| 组件总行数 | > 200 | ⚠️ 考虑拆分 |
+| 组件总行数 | > 400 | 🔴 必须拆分 |
+| script 逻辑行数 | > 50 | 提取 composable |
+| 布尔 Props | ≥ 3 | 拆分为变体组件 |
+
+## Prop 反模式与显式变体
+
+❌ 4 个布尔 = 16 种状态，v-if 地狱。✅ 显式变体：`AdminEditPanel` / `PublicReadonlyPanel` / `DraftPreviewPanel`，通过 slot 复用共享子组件。Slot vs Prop：简单数据用 Prop，自定义渲染用 Slot，控制显示用有无 slot 内容。
+
+## 错误处理规范
+
+| 场景 | 组件 |
+|------|------|
+| 操作成功/失败即时反馈 | ElMessage |
+| 需用户确认 | ElMessageBox |
+| 异步持续状态 | ElNotification |
+| 页面级加载失败 | 内联错误 UI + 重试按钮 |
+
+## UI 设计反模式
+
+居中一切、紫色渐变、大圆角、过度阴影、空白页大插图、过多动画 → 以 Element Plus 为基准，优先功能清晰度。
--- a/.cursor/skills/component-scaffold/references/naming-conventions.md
+++ b/.cursor/skills/component-scaffold/references/naming-conventions.md
@@ -0,0 +1,32 @@
+# 组件命名规范
+
+## 文件命名
+
+| 类型 | 命名 | 示例 |
+|------|------|------|
+| 组件文件 | PascalCase.vue | `UserProfile.vue` |
+| 测试文件 | PascalCase.test.ts | `UserProfile.test.ts` |
+| 样式文件 | 内联 `<style scoped>` | `UserProfile.vue` |
+| Composable | use + PascalCase.ts | `useUserProfile.ts` |
+| 工具函数 | camelCase.ts | `formatDate.ts` |
+
+## Props 接口
+
+```typescript
+// ✅ Good: use JSDoc typedef for props-like structure
+/**
+ * @typedef {Object} UserProfileProps
+ */
+
+// ❌ Bad: ambiguous generic name
+/** @typedef {Object} Props */
+```
+
+## 组件类型
+
+| 类型 | 目录 | 特征 |
+|------|------|------|
+| UI 组件 | `components/ui/` | 无业务逻辑，纯展示 |
+| Feature 组件 | `components/features/` | 包含业务逻辑 |
+| Layout 组件 | `components/layout/` | 页面布局 |
+| Form 组件 | `components/forms/` | 表单及验证 |
--- a/.cursor/skills/component-scaffold/references/vue-api-reference.md
+++ b/.cursor/skills/component-scaffold/references/vue-api-reference.md
@@ -0,0 +1,481 @@
+# Vue.ts 3 API Reference
+
+Quick reference with links to official Vue.ts documentation.
+
+## Official Documentation
+
+**Main Site:** https://vuejs.org
+
+## Table of Contents
+
+1. [Getting Started](#getting-started)
+2. [Essentials](#essentials)
+3. [Components In-Depth](#components-in-depth)
+4. [Reusability](#reusability)
+5. [Built-in Components](#built-in-components)
+6. [API Reference](#api-reference)
+7. [TypeScript Patterns](#typescript-patterns)
+
+---
+
+## Getting Started
+
+### Introduction
+**URL:** https://vuejs.org/guide/introduction.html
+- What is Vue?
+- Progressive Framework
+- Single-File Components
+- API Styles (Options vs Composition)
+- Which to choose?
+
+### Quick Start
+**URL:** https://vuejs.org/guide/quick-start.html
+- Creating a Vue Application
+- Using Vue from CDN
+- With build tools (Vite)
+- IDE Setup
+
+### Creating an Application
+**URL:** https://vuejs.org/guide/essentials/application.html
+- Application instance
+- Root component
+- Mounting the app
+- App configurations
+
+---
+
+## Essentials
+
+### Template Syntax
+**URL:** https://vuejs.org/guide/essentials/template-syntax.html
+- Text interpolation
+- Raw HTML (v-html)
+- Attribute bindings (v-bind)
+- TypeScript expressions
+- Directives
+
+### Reactivity Fundamentals
+**URL:** https://vuejs.org/guide/essentials/reactivity-fundamentals.html
+- `ref()` - Reactive state for primitives
+- `reactive()` - Reactive objects
+- Reactive proxy vs original
+- `nextTick()` - DOM update timing
+
+### Computed Properties
+**URL:** https://vuejs.org/guide/essentials/computed.html
+- Basic usage
+- Computed caching vs methods
+- Writable computed
+- Best practices
+
+### Class and Style Bindings
+**URL:** https://vuejs.org/guide/essentials/class-and-style.html
+- Binding HTML classes
+- Binding inline styles
+- Object syntax
+- Array syntax
+
+### Conditional Rendering
+**URL:** https://vuejs.org/guide/essentials/conditional.html
+- `v-if`, `v-else-if`, `v-else`
+- `v-show`
+- v-if vs v-show
+- v-if with v-for
+
+### List Rendering
+**URL:** https://vuejs.org/guide/essentials/list.html
+- `v-for` with arrays
+- `v-for` with objects
+- `v-for` with ranges
+- Maintaining state with `key`
+- Array change detection
+
+### Event Handling
+**URL:** https://vuejs.org/guide/essentials/event-handling.html
+- Listening to events (`v-on` / `@`)
+- Method handlers
+- Inline handlers
+- Event modifiers (.stop, .prevent, etc.)
+- Key modifiers
+
+### Form Input Bindings
+**URL:** https://vuejs.org/guide/essentials/forms.html
+- `v-model` basics
+- Text, textarea inputs
+- Checkboxes, radio buttons
+- Select dropdowns
+- Modifiers (.lazy, .number, .trim)
+
+### Lifecycle Hooks
+**URL:** https://vuejs.org/guide/essentials/lifecycle.html
+- Lifecycle diagram
+- `onMounted()`, `onUpdated()`, `onUnmounted()`
+- `onBeforeMount()`, `onBeforeUpdate()`, `onBeforeUnmount()`
+- `onErrorCaptured()`, `onActivated()`, `onDeactivated()`
+
+### Watchers
+**URL:** https://vuejs.org/guide/essentials/watchers.html
+- `watch()` - Watch specific sources
+- `watchEffect()` - Auto-track dependencies
+- Deep watchers
+- Eager watchers (immediate)
+- Callback flush timing
+- Stopping watchers
+
+### Template Refs
+**URL:** https://vuejs.org/guide/essentials/template-refs.html
+- Accessing DOM elements
+- Refs inside v-for
+- Function refs
+- Component refs
+
+### Components Basics
+**URL:** https://vuejs.org/guide/essentials/component-basics.html
+- Defining components
+- Using components
+- Passing props
+- Listening to events
+- Slots
+
+---
+
+## Components In-Depth
+
+### Registration
+**URL:** https://vuejs.org/guide/components/registration.html
+- Global registration
+- Local registration
+- Component name casing
+
+### Props
+**URL:** https://vuejs.org/guide/components/props.html
+- Props declaration
+- Prop types and validation
+- Prop passing details
+- One-way data flow
+- Boolean casting
+- Prop validation
+
+### Events
+**URL:** https://vuejs.org/guide/components/events.html
+- Emitting and listening to events
+- Event arguments
+- Declaring emitted events
+- Events validation
+- Usage with v-model
+
+### Component v-model
+**URL:** https://vuejs.org/guide/components/v-model.html
+- Basic usage
+- v-model arguments
+- Multiple v-model bindings
+- Custom modifiers
+
+### Fallthrough Attributes
+**URL:** https://vuejs.org/guide/components/attrs.html
+- Attribute inheritance
+- Disabling inheritance
+- Accessing fallthrough attributes
+- Multi-root nodes
+
+### Slots
+**URL:** https://vuejs.org/guide/components/slots.html
+- Default slot content
+- Named slots
+- Scoped slots
+- Renderless components
+
+### Provide / Inject
+**URL:** https://vuejs.org/guide/components/provide-inject.html
+- Basic usage
+- App-level provide
+- Working with reactivity
+- Working with Symbol keys
+
+### Async Components
+**URL:** https://vuejs.org/guide/components/async.html
+- Basic usage
+- Loading and error states
+- Using with Suspense
+
+---
+
+## Reusability
+
+### Composables
+**URL:** https://vuejs.org/guide/reusability/composables.html
+- What is a composable?
+- Mouse tracker example
+- Async state example
+- Conventions and best practices
+- Usage restrictions
+- Extracting composables
+
+### Custom Directives
+**URL:** https://vuejs.org/guide/reusability/custom-directives.html
+- Introduction
+- Directive hooks
+- Hook arguments
+- Function shorthand
+- Object literals
+- Usage on components
+
+### Plugins
+**URL:** https://vuejs.org/guide/reusability/plugins.html
+- Introduction
+- Writing a plugin
+- Plugin options
+- Provide / inject with plugins
+
+---
+
+## Built-in Components
+
+### Transition
+**URL:** https://vuejs.org/guide/built-ins/transition.html
+- Basic usage
+- CSS-based transitions
+- TypeScript hooks
+- Reusable transitions
+- Appear on initial render
+- Transition between elements
+- Transition modes
+
+### TransitionGroup
+**URL:** https://vuejs.org/guide/built-ins/transition-group.html
+- Basic usage
+- Move transitions
+- Staggering list transitions
+
+### KeepAlive
+**URL:** https://vuejs.org/guide/built-ins/keep-alive.html
+- Basic usage
+- Include / exclude
+- Max cached instances
+- Lifecycle of cached instance
+
+### Teleport
+**URL:** https://vuejs.org/guide/built-ins/teleport.html
+- Basic usage
+- Using with components
+- Multiple teleports on same target
+- Disabling teleport
+
+### Suspense
+**URL:** https://vuejs.org/guide/built-ins/suspense.html
+- Async dependencies
+- Loading state
+- Error handling
+- Combining with Transitions
+- **Note:** Experimental feature
+
+---
+
+## API Reference
+
+### Global API
+**URL:** https://vuejs.org/api/application.html
+- Application API
+- General API
+
+### Composition API - Setup
+**URL:** https://vuejs.org/api/composition-api-setup.html
+- `setup()` function
+- `<script setup>` syntax
+
+### Composition API - Reactivity Core
+**URL:** https://vuejs.org/api/reactivity-core.html
+- `ref()`, `computed()`, `reactive()`, `readonly()`
+- `watchEffect()`, `watchPostEffect()`, `watchSyncEffect()`
+- `watch()`
+- `isRef()`, `unref()`, `toRef()`, `toRefs()`, `toValue()`
+- `isProxy()`, `isReactive()`, `isReadonly()`
+
+### Composition API - Reactivity Utilities
+**URL:** https://vuejs.org/api/reactivity-utilities.html
+- `isRef()`, `unref()`, `toRef()`, `toRefs()`, `toValue()`
+- `isProxy()`, `isReactive()`, `isReadonly()`
+- `shallowRef()`, `triggerRef()`, `customRef()`
+- `shallowReactive()`, `shallowReadonly()`
+
+### Composition API - Reactivity Advanced
+**URL:** https://vuejs.org/api/reactivity-advanced.html
+- `shallowRef()`, `triggerRef()`, `customRef()`
+- `shallowReactive()`, `shallowReadonly()`
+- `toRaw()`, `markRaw()`
+- `effectScope()`, `getCurrentScope()`, `onScopeDispose()`
+
+### Composition API - Lifecycle Hooks
+**URL:** https://vuejs.org/api/composition-api-lifecycle.html
+- `onMounted()`, `onUpdated()`, `onUnmounted()`
+- `onBeforeMount()`, `onBeforeUpdate()`, `onBeforeUnmount()`
+- `onErrorCaptured()`, `onRenderTracked()`, `onRenderTriggered()`
+- `onActivated()`, `onDeactivated()`, `onServerPrefetch()`
+
+### Composition API - Dependency Injection
+**URL:** https://vuejs.org/api/composition-api-dependency-injection.html
+- `provide()`, `inject()`
+- `hasInjectionContext()`
+
+### Composition API - Helpers
+**URL:** https://vuejs.org/api/composition-api-helpers.html
+- `useAttrs()`, `useSlots()`
+- `useModel()`, `useTemplateRef()`
+- `useId()`, `useCssModule()`
+
+### Options API - State
+**URL:** https://vuejs.org/api/options-state.html
+- `data`, `props`, `computed`
+- `methods`, `watch`, `emits`
+- `expose`
+
+### Options API - Rendering
+**URL:** https://vuejs.org/api/options-rendering.html
+- `template`, `render`
+- `compilerOptions`
+
+### Options API - Lifecycle
+**URL:** https://vuejs.org/api/options-lifecycle.html
+- `beforeCreate`, `created`
+- `beforeMount`, `mounted`
+- `beforeUpdate`, `updated`
+- `beforeUnmount`, `unmounted`
+- `errorCaptured`, `renderTracked`, `renderTriggered`
+- `activated`, `deactivated`, `serverPrefetch`
+
+### Options API - Composition
+**URL:** https://vuejs.org/api/options-composition.html
+- `provide`, `inject`
+- `mixins`, `extends`
+
+### Options API - Misc
+**URL:** https://vuejs.org/api/options-misc.html
+- `name`, `inheritAttrs`, `components`, `directives`
+
+### Component Instance
+**URL:** https://vuejs.org/api/component-instance.html
+- `$data`, `$props`, `$el`, `$refs`
+- `$parent`, `$root`, `$slots`, `$attrs`
+- `$watch()`, `$emit()`, `$forceUpdate()`, `$nextTick()`
+
+### Built-in Directives
+**URL:** https://vuejs.org/api/built-in-directives.html
+- `v-text`, `v-html`, `v-show`, `v-if`, `v-else`, `v-else-if`, `v-for`
+- `v-on`, `v-bind`, `v-model`
+- `v-slot`, `v-pre`, `v-once`, `v-memo`, `v-cloak`
+
+### Built-in Components
+**URL:** https://vuejs.org/api/built-in-components.html
+- `<Transition>`, `<TransitionGroup>`
+- `<KeepAlive>`, `<Teleport>`, `<Suspense>`
+
+### Built-in Special Elements
+**URL:** https://vuejs.org/api/built-in-special-elements.html
+- `<component>`, `<slot>`
+
+### Built-in Special Attributes
+**URL:** https://vuejs.org/api/built-in-special-attributes.html
+- `key`, `ref`, `is`
+
+### Single-File Component Syntax
+**URL:** https://vuejs.org/api/sfc-syntax.html
+- Language blocks
+- Automatic name inference
+- Pre-processors
+- Src imports
+- Custom blocks
+
+### SFC `<script setup>`
+**URL:** https://vuejs.org/api/sfc-script-setup.html
+- Basic syntax
+- Top-level bindings
+- Using components
+- Using custom directives
+- defineProps(), defineEmits()
+- defineExpose(), defineOptions(), defineSlots(), defineModel()
+- useSlots(), useAttrs()
+- Normal `<script>` alongside `<script setup>`
+
+### SFC CSS Features
+**URL:** https://vuejs.org/api/sfc-css-features.html
+- Scoped CSS
+- CSS modules
+- `v-bind()` in CSS
+- `<style>` with `src` imports
+
+---
+
+## TypeScript Patterns
+
+### TypeScript with Composition API
+**URL:** https://vuejs.org/guide/extras/composition-api-faq.html
+- Define props with runtime object syntax
+- Define emits with array/object syntax
+- Use JSDoc for complex shapes
+- Keep composables in `use*.ts`
+- Prefer clear runtime validation for public component APIs
+
+### TypeScript with Options API
+**URL:** https://vuejs.org/guide/essentials/component-basics.html
+- Use `props` runtime validation
+- Keep event names explicit in `emits`
+- Avoid implicit global properties where possible
+- Prefer composition API for new code
+
+### Overview
+**URL:** https://vuejs.org/guide/scaling-up/tooling.html
+- IDE support
+- Linting and formatting integration
+- Volar extension basics
+- Build-tool and plugin usage notes
+
+---
+
+## Additional Resources
+
+### Best Practices
+**URL:** https://vuejs.org/guide/best-practices/production-deployment.html
+- Production deployment
+- Performance
+- Accessibility
+- Security
+
+### Scaling Up
+**URL:** https://vuejs.org/guide/scaling-up/sfc.html
+- Single-File Components
+- Tooling
+- Routing
+- State management
+- Testing
+- Server-Side Rendering (SSR)
+
+### Style Guide
+**URL:** https://vuejs.org/style-guide/
+- Priority A: Essential (Error Prevention)
+- Priority B: Strongly Recommended
+- Priority C: Recommended
+- Priority D: Use with Caution
+
+### Vue Router
+**URL:** https://router.vuejs.org/
+- Official routing library
+
+### Pinia
+**URL:** https://pinia.vuejs.org/
+- Official state management library
+
+### Vite
+**URL:** https://vitejs.dev/
+- Recommended build tool
+
+---
+
+## Quick Search Tips
+
+When searching official docs:
+1. Use the search bar at https://vuejs.org
+2. For API details, go directly to https://vuejs.org/api/
+3. For guides and concepts, start at https://vuejs.org/guide/
+4. For examples, check https://vuejs.org/examples/
+
+All documentation is available in multiple languages using the language selector.