@qilitt-mickey/vue3-temp-skill 1.0.8

package/references/crud-pages.md

@@ -0,0 +1,316 @@
+---
+skill: crud-pages
+description: 规范查询列表页、表单页、详情/编辑页的标准开发流程，包含 useTableSearch Hook、表单校验、数据回显等核心模式。开发 CRUD 业务页面时调用。
+scope: project
+tags: [vue3, crud, list, form, detail, table, useTableSearch, page]
+---
+
+# CRUD 页面开发规范
+
+## 查询列表页
+
+### 标准结构
+
+查询列表页是后台管理系统最常见的页面类型，使用 `useTableSearch` Hook 统一处理。
+
+```vue
+<script setup lang="ts">
+import { useTableSearch } from "@/hooks/useTableSearch";
+import { getXxxListApi } from "@/api/xxx";
+import type { XxxQueryForm, XxxListItem } from "@/api/types/xxx";
+
+defineOptions({ name: "XxxList" });
+
+// 查询表单
+const formQuery = reactive<XxxQueryForm>({
+  keyword: "",
+  status: undefined,
+  dateRange: [],
+});
+
+// useTableSearch 返回表格相关的所有状态和方法
+const {
+  content,       // 表格数据
+  pagination,    // 分页信息
+  loading,       // 加载状态
+  handleSearch,  // 查询
+  handleReset,   // 重置
+  handlePageChange,  // 翻页
+  handleSizeChange,  // 切换每页条数
+} = useTableSearch(formQuery, getXxxListApi);
+
+// 初始化加载
+handleSearch();
+</script>
+
+<template>
+  <div class="re-xxx-list">
+    <!-- 查询区域 -->
+    <el-form :model="formQuery" inline>
+      <el-form-item label="关键词">
+        <el-input v-model="formQuery.keyword" placeholder="请输入" clearable />
+      </el-form-item>
+      <el-form-item label="状态">
+        <el-select v-model="formQuery.status" placeholder="请选择" clearable>
+          <el-option label="启用" :value="1" />
+          <el-option label="禁用" :value="0" />
+        </el-select>
+      </el-form-item>
+      <el-form-item>
+        <el-button type="primary" @click="handleSearch">查询</el-button>
+        <el-button @click="handleReset">重置</el-button>
+      </el-form-item>
+    </el-form>
+
+    <!-- 工具栏 -->
+    <ReTableBar>
+      <template #left>
+        <el-button type="primary" @click="handleAdd">新增</el-button>
+      </template>
+    </ReTableBar>
+
+    <!-- 数据表格 -->
+    <ReGrid
+      v-loading="loading"
+      :data="content"
+      :pagination="pagination"
+      @page-change="handlePageChange"
+      @size-change="handleSizeChange"
+    >
+      <el-table-column prop="name" label="名称" />
+      <el-table-column prop="status" label="状态">
+        <template #default="{ row }">
+          <el-tag :type="row.status === 1 ? 'success' : 'danger'">
+            {{ row.status === 1 ? "启用" : "禁用" }}
+          </el-tag>
+        </template>
+      </el-table-column>
+      <el-table-column label="操作" width="200" fixed="right">
+        <template #default="{ row }">
+          <ReTableOperate
+            :buttons="[
+              { label: '编辑', type: 'primary', onClick: () => handleEdit(row) },
+              { label: '删除', type: 'danger', onClick: () => handleDelete(row) },
+            ]"
+          />
+        </template>
+      </el-table-column>
+    </ReGrid>
+  </div>
+</template>
+```
+
+### useTableSearch 参数说明
+
+```typescript
+function useTableSearch<TQuery, TResult>(
+  formQuery: TQuery,           // 查询表单（reactive 对象）
+  apiFn: (params: TQuery) => Promise<Result<TResult>>,  // API 函数
+  options?: {
+    immediate?: boolean;       // 是否立即加载（默认 true）
+    defaultPageSize?: number;  // 默认每页条数（默认 10）
+  }
+): {
+  content: Ref<TResult["list"]>;
+  pagination: { currentPage: number; pageSize: number; total: number };
+  loading: Ref<boolean>;
+  handleSearch: () => Promise<void>;
+  handleReset: () => void;
+  handlePageChange: (page: number) => void;
+  handleSizeChange: (size: number) => void;
+}
+```
+
+### 列表页约定
+
+1. 查询表单使用 `reactive()` 定义，不使用 `ref()`。
+2. 表格数据、分页、Loading 统一由 `useTableSearch` 管理，不要手动维护。
+3. 操作列使用 `ReTableOperate` 组件渲染按钮组。
+4. 工具栏使用 `ReTableBar` 组件包裹。
+5. 表格使用 `ReGrid` 组件（内置分页联动）。
+6. 删除操作必须弹出确认框。
+
+## 表单页
+
+### 新增/编辑表单
+
+```vue
+<script setup lang="ts">
+import type { FormInstance, FormRules } from "element-plus";
+import { getXxxDetailApi, saveXxxApi } from "@/api/xxx";
+import type { XxxForm } from "@/api/types/xxx";
+
+defineOptions({ name: "XxxForm" });
+
+const route = useRoute();
+const router = useRouter();
+const formRef = ref<FormInstance>();
+const loading = ref(false);
+
+const formData = reactive<XxxForm>({
+  name: "",
+  code: "",
+  status: 1,
+  remark: "",
+});
+
+const rules = reactive<FormRules<XxxForm>>({
+  name: [{ required: true, message: "请输入名称", trigger: "blur" }],
+  code: [{ required: true, message: "请输入编码", trigger: "blur" }],
+  status: [{ required: true, message: "请选择状态", trigger: "change" }],
+});
+
+// 编辑模式加载数据
+onMounted(async () => {
+  const id = route.query.id as string;
+  if (id) {
+    const { data } = await getXxxDetailApi(id);
+    Object.assign(formData, data);
+  }
+});
+
+// 提交
+async function handleSubmit() {
+  const valid = await formRef.value?.validate().catch(() => false);
+  if (!valid) return;
+
+  loading.value = true;
+  try {
+    await saveXxxApi(formData);
+    ElMessage.success("保存成功");
+    router.back();
+  } finally {
+    loading.value = false;
+  }
+}
+
+// 重置
+function handleReset() {
+  formRef.value?.resetFields();
+}
+</script>
+
+<template>
+  <div class="re-xxx-form">
+    <el-form
+      ref="formRef"
+      :model="formData"
+      :rules="rules"
+      label-width="100px"
+    >
+      <el-form-item label="名称" prop="name">
+        <el-input v-model="formData.name" placeholder="请输入" />
+      </el-form-item>
+      <el-form-item label="编码" prop="code">
+        <el-input v-model="formData.code" placeholder="请输入" />
+      </el-form-item>
+      <el-form-item label="状态" prop="status">
+        <el-radio-group v-model="formData.status">
+          <el-radio :value="1">启用</el-radio>
+          <el-radio :value="0">禁用</el-radio>
+        </el-radio-group>
+      </el-form-item>
+      <el-form-item label="备注" prop="remark">
+        <el-input v-model="formData.remark" type="textarea" :rows="3" />
+      </el-form-item>
+      <el-form-item>
+        <el-button type="primary" :loading="loading" @click="handleSubmit">
+          保存
+        </el-button>
+        <el-button @click="handleReset">重置</el-button>
+      </el-form-item>
+    </el-form>
+  </div>
+</template>
+```
+
+### 表单约定
+
+1. 表单数据使用 `reactive()` 定义，配合泛型 `FormRules<T>` 获得类型校验。
+2. 校验规则使用 `FormRules<T>` 类型，确保 rule 的 `field` 与表单字段对应。
+3. 提交前必须调用 `formRef.validate()`，不要跳过校验直接提交。
+4. 编辑模式通过 `route.query.id` 判断，有 id 则加载详情并回填。
+5. 重置使用 `formRef.resetFields()`，不要手动清空字段。
+6. 提交按钮使用 `loading` 状态防止重复提交。
+
+## 详情/编辑页
+
+### 页面跳转传参
+
+```typescript
+// 列表页跳转到详情页
+function handleView(row: XxxListItem) {
+  router.push({
+    path: "/xxx/detail",
+    query: { id: row.id },
+  });
+}
+
+// 列表页跳转到编辑页
+function handleEdit(row: XxxListItem) {
+  router.push({
+    path: "/xxx/edit",
+    query: { id: row.id },
+  });
+}
+
+// 列表页跳转到新增页
+function handleAdd() {
+  router.push({ path: "/xxx/add" });
+}
+```
+
+### 详情页数据回显
+
+```typescript
+// 编辑页加载数据并回填
+onMounted(async () => {
+  const id = route.query.id as string;
+  if (!id) return;
+
+  loading.value = true;
+  try {
+    const { data } = await getXxxDetailApi(id);
+    // 使用 Object.assign 保持 reactive 响应性
+    Object.assign(formData, data);
+  } finally {
+    loading.value = false;
+  }
+});
+```
+
+### 多表单校验
+
+当一个页面有多个表单区域时，需要统一校验：
+
+```typescript
+async function handleSubmitAll() {
+  const results = await Promise.all([
+    formRef1.value?.validate().catch(() => false),
+    formRef2.value?.validate().catch(() => false),
+    formRef3.value?.validate().catch(() => false),
+  ]);
+
+  if (results.some(r => r === false)) {
+    ElMessage.warning("请完善表单信息");
+    return;
+  }
+
+  // 合并数据提交
+  const submitData = {
+    ...formData1,
+    ...formData2,
+    ...formData3,
+  };
+  await saveApi(submitData);
+}
+```
+
+## 常见反例
+
+- 不使用 `useTableSearch`，手动管理 loading / pagination / content。
+- 表单使用 `ref({})` 而非 `reactive({})` 定义。
+- 提交时不调用 `validate()`，或调用后不处理 reject。
+- 编辑页通过 `router.params` 传参（应使用 `query`）。
+- 重置表单时手动清空字段而不使用 `resetFields()`。
+- 操作列直接写 `el-button` 而不使用 `ReTableOperate`。