From 6b04e80d410dcf9addbd391460ab75ea96ced55c Mon Sep 17 00:00:00 2001
From: Leo <98382335+gaoziman@users.noreply.github.com>
Date: Sun, 6 Jul 2025 18:58:13 +0800
Subject: [PATCH] =?UTF-8?q?docs(claude):=20=E6=96=B0=E5=A2=9E=20NovaDialog?=
 =?UTF-8?q?=20=E8=87=AA=E5=AE=9A=E4=B9=89=E5=BC=B9=E6=A1=86=E7=BB=84?=
 =?UTF-8?q?=E4=BB=B6=E4=BD=BF=E7=94=A8=E8=A7=84=E8=8C=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 在 CLAUDE.md 中新增自定义弹框组件使用规范
- 明确禁止使用原生 n-modal，强制使用 NovaDialog
- 提供完整的使用指南和代码示例
- 详细说明组件属性、事件、方法和插槽
- 列出已完成集成的页面作为参考
- 修复文档中 Vue 模板语法引起的 ESLint 错误
- 确保后续开发严格遵循统一的弹框使用规范
---
 CLAUDE.md | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 172 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 7e09b83..945b27f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -406,6 +406,178 @@ const searchForm = ref<UserSearchForm>({})
 2. 自定义组件放在 `src/components/` 下
 3. 使用TypeScript定义组件Props和Emits
 
+## 🔥 自定义弹框组件规范（强制要求）
+
+**在开发任何新页面或功能时，如果需要使用弹框/模态框，必须使用项目封装的 NovaDialog 组件，严禁使用 Naive UI 原生的 n-modal 组件。**
+
+### NovaDialog 组件位置
+- 组件文件：`src/components/common/NovaDialog.vue`
+- 这是项目专门封装的统一弹框组件
+
+### 使用方式
+
+#### 1. 导入组件
+```typescript
+import NovaDialog from '@/components/common/NovaDialog.vue'
+```
+
+#### 2. 创建弹框引用
+```typescript
+// 为每个弹框创建独立的引用
+const userDialogRef = ref()
+const editDialogRef = ref()
+const deleteDialogRef = ref()
+```
+
+#### 3. 模板中使用
+```vue
+<template>
+  <!-- 用户表单弹框示例 -->
+  <NovaDialog
+    ref="userDialogRef"
+    :title="modalTitle"
+    :width="800"
+    height="auto"
+    confirm-text="确定"
+    cancel-text="取消"
+    @nova-confirm="handleSubmit"
+    @nova-cancel="handleCancel"
+  >
+    <template #content>
+      <div class="px-3 py-2">
+        <!-- 弹框内容 -->
+        <n-form ref="formRef" :model="formData">
+          <!-- 表单内容 -->
+        </n-form>
+      </div>
+    </template>
+  </NovaDialog>
+
+  <!-- 仅查看类弹框示例（无确认按钮） -->
+  <NovaDialog
+    ref="viewDialogRef"
+    title="查看详情"
+    :width="600"
+    height="auto"
+    cancel-text="关闭"
+    :show-confirm="false"
+    @nova-cancel="handleClose"
+  >
+    <template #content>
+      <div class="p-3">
+        <!-- 查看内容 -->
+      </div>
+    </template>
+  </NovaDialog>
+</template>
+```
+
+#### 4. 控制弹框显示/隐藏
+```typescript
+// 显示弹框
+function handleAdd() {
+  modalTitle.value = '新增用户'
+  // 初始化表单数据
+  formData.value = { /* ... */ }
+  userDialogRef.value?.novaOpen()
+}
+
+// 隐藏弹框
+function handleCancel() {
+  userDialogRef.value?.novaClose()
+}
+
+// 提交成功后关闭弹框
+async function handleSubmit() {
+  try {
+    await submitForm()
+    coiMsgSuccess('操作成功')
+    userDialogRef.value?.novaClose()
+  } catch (error) {
+    coiMsgError('操作失败')
+  }
+}
+```
+
+### NovaDialog 核心属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | string | '' | 弹框标题 |
+| width | number | 500 | 弹框宽度(px) |
+| height | string | 'auto' | 弹框高度 |
+| confirm-text | string | '确定' | 确认按钮文字 |
+| cancel-text | string | '取消' | 取消按钮文字 |
+| show-confirm | boolean | true | 是否显示确认按钮 |
+| show-cancel | boolean | true | 是否显示取消按钮 |
+
+### NovaDialog 核心事件
+
+| 事件 | 说明 |
+|------|------|
+| @nova-confirm | 点击确认按钮时触发 |
+| @nova-cancel | 点击取消按钮时触发 |
+
+### NovaDialog 核心方法
+
+| 方法 | 说明 |
+|------|------|
+| novaOpen() | 显示弹框 |
+| novaClose() | 隐藏弹框 |
+
+### 插槽支持
+
+| 插槽 | 说明 |
+|------|------|
+| #header | 自定义弹框头部内容 |
+| #content | 弹框主体内容（必需） |
+
+### 已完成的集成示例
+- ✅ 角色管理页面：`src/views/system/role/index.vue`
+- ✅ 用户管理页面：`src/views/system/user/index.vue`
+
+### 严格禁止行为
+- ❌ 使用 `n-modal` 组件创建新弹框
+- ❌ 使用 `v-model:show` 控制弹框显示/隐藏
+- ❌ 忽略 NovaDialog 组件直接使用原生弹框
+
+### 为什么必须使用 NovaDialog？
+1. **统一用户体验**：确保所有弹框具有一致的视觉风格和交互行为
+2. **维护便利性**：统一的组件便于后续样式调整和功能增强
+3. **团队协作**：统一的组件API减少开发人员的学习成本
+4. **质量保证**：封装的组件经过充分测试，避免重复开发和潜在bug
+
+## 📝 Vue3组件文件结构规范（强制要求）
+
+**所有Vue3组件必须严格按照以下顺序组织代码块**
+
+### 组件代码块排布顺序
+```vue
+<script setup lang="ts">
+// 脚本内容
+</script>
+
+<template>
+  <!-- 模板内容 -->
+</template>
+
+<style scoped>
+/* 样式内容 */
+</style>
+```
+
+### 强制要求
+- ✅ 必须按照 `template` → `script` → `style` 的顺序排布
+- ✅ 使用 `<script setup lang="ts">` 语法
+- ✅ 样式块使用 `scoped` 属性确保样式隔离
+- ✅ 每个代码块之间保持一个空行间隔
+
+### 严格禁止行为
+- ❌ 任何其他顺序的代码块排布
+- ❌ 使用 `<script>` 而非 `<script setup>`
+- ❌ 省略 `lang="ts"` 属性
+- ❌ 在全局组件中省略 `scoped` 属性
+
 ## 文档资源
 
 项目包含完整的文档系统：