@qilitt-mickey/vue3-temp-skill 1.0.12 → 1.1.2

package/references/crud-pages.md

@@ -1,316 +1,142 @@
 ---
 skill: crud-pages
-description: 规范查询列表页、表单页、详情/编辑页的标准开发流程，包含 useTableSearch Hook、表单校验、数据回显等核心模式。开发 CRUD 业务页面时调用。
+description: 查询列表页、表单页、标准 CRUD 流程。含 useTableSearch（onSearch/reset）、ReGrid 查询区、表格工具栏。务必按照本文件完整示例编写。
 scope: project
 tags: [vue3, crud, list, form, detail, table, useTableSearch, page]
 ---
 
 # CRUD 页面开发规范
 
-## 查询列表页
-
-### 标准结构
+> 以下示例即规范真相。
+> 须同时遵守 `core-kernel` / `http-api`。详情跳转见 `detail-page`，回显见 `data-writeback`。
 
-查询列表页是后台管理系统最常见的页面类型，使用 `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 真实签名
 
-// useTableSearch 返回表格相关的所有状态和方法
-const {
-  content,       // 表格数据
-  pagination,    // 分页信息
-  loading,       // 加载状态
-  handleSearch,  // 查询
-  handleReset,   // 重置
-  handlePageChange,  // 翻页
-  handleSizeChange,  // 切换每页条数
-} = useTableSearch(formQuery, getXxxListApi);
+```typescript
+useTableSearch(formQuery, searchFn, url)
+// searchFn: (query: CombinedQueryData, url: string) => Promise<Result<T>>
+// 返回含：content, tableData, pagination, loading, formRef, onSearch, reset, tableHeight, ...
+```
 
-// 初始化加载
-handleSearch();
-</script>
+- 查询：`onSearch()`
+- 重置：`reset()`（内部 `formRef.resetFields()`）
+- 列表：`tableData.value.tableList`（或经 computed 断言）
+- 分页：请求带 `pageNo` / `pageSize`；响应 `data.content` / `data.totalCount`
 
-<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>
+见 `core-kernel.md`「列表黄金样板」。本模块补充约定：
 
-    <!-- 数据表格 -->
-    <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>
-```
+1. 查询区用 **`ReGrid` + `ReGridItem`**，折叠与 `collapsed` / `showCollapse` / `collapsedToggle` 配套。
+2. 工具栏用 **`ReTableBar`**，行操作用 **`ReTableOperate`**，分页用 **`RePagination`**。
+3. 查询 / 重置按钮文案 `$t('查询')` / `$t('重置')`，点击绑定 **`onSearch` / `reset`**。
+4. `defineOptions({ name })` 与路由 `name` 一致（keep-alive / 标签）。
+5. 需要权限的按钮加 `v-auth` / `ReAuth`。
 
-### useTableSearch 参数说明
+### API 配套
 
 ```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;
+// src/api/customer.ts — 详见 http-api
+export function getCustomerList(data: CustomerQuery, url: string) {
+  return http.request<Result<CustomerPage>>("post", url, { data });
 }
 ```
 
-### 列表页约定
-
-1. 查询表单使用 `reactive()` 定义，不使用 `ref()`。
-2. 表格数据、分页、Loading 统一由 `useTableSearch` 管理，不要手动维护。
-3. 操作列使用 `ReTableOperate` 组件渲染按钮组。
-4. 工具栏使用 `ReTableBar` 组件包裹。
-5. 表格使用 `ReGrid` 组件（内置分页联动）。
-6. 删除操作必须弹出确认框。
-
-## 表单页
+```typescript
+const { onSearch, reset, tableData, loading, pagination, ... } = useTableSearch(
+  formQuery,
+  getCustomerList,
+  `${import.meta.env.VITE_API_BASE_URL}/console/customer/list`,
+);
+onMounted(() => onSearch());
+```
 
-### 新增/编辑表单
+## 表单页（新增 / 编辑）
 
 ```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";
+import type { Customer } from "@/api/customer";
+import { saveCustomer } from "@/api/customer";
+import { message } from "@/utils/message";
+import { checkReeorPosition } from "@/utils/utils";
 
-defineOptions({ name: "XxxForm" });
+defineOptions({ name: "CustomerForm" });
 
-const route = useRoute();
-const router = useRouter();
 const formRef = ref<FormInstance>();
-const loading = ref(false);
-
-const formData = reactive<XxxForm>({
-  name: "",
+const submitLoading = ref(false);
+const formData = reactive<Customer>({
+  id: "",
   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" }],
+  name: "",
 });
 
-// 编辑模式加载数据
-onMounted(async () => {
-  const id = route.query.id as string;
-  if (id) {
-    const { data } = await getXxxDetailApi(id);
-    Object.assign(formData, data);
-  }
-});
+const rules: FormRules<Customer> = {
+  code: [{ required: true, message: $t("请输入编号"), trigger: "blur" }],
+  name: [{ required: true, message: $t("请输入名称"), trigger: "blur" }],
+};
 
-// 提交
-async function handleSubmit() {
+async function onSubmit() {
   const valid = await formRef.value?.validate().catch(() => false);
-  if (!valid) return;
-
-  loading.value = true;
+  if (!valid) {
+    checkReeorPosition();
+    return;
+  }
+  submitLoading.value = true;
   try {
-    await saveXxxApi(formData);
-    ElMessage.success("保存成功");
-    router.back();
+    const res = await saveCustomer(formData);
+    if (res.status === 200) {
+      message($t("保存成功"), { type: "success" });
+    } else {
+      message(res.statusText || $t("保存失败"), { type: "error" });
+    }
   } finally {
-    loading.value = false;
+    submitLoading.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>
+  <el-form ref="formRef" :model="formData" :rules="rules" label-position="top">
+    <el-form-item :label="$t('编号')" prop="code">
+      <el-input v-model="formData.code" />
+    </el-form-item>
+    <el-form-item :label="$t('名称')" prop="name">
+      <el-input v-model="formData.name" />
+    </el-form-item>
+    <el-button type="primary" :loading="submitLoading" @click="onSubmit">
+      {{ $t("提交") }}
+    </el-button>
+  </el-form>
 </template>
 ```
 
 ### 表单约定
 
-1. 表单数据使用 `reactive()` 定义，配合泛型 `FormRules<T>` 获得类型校验。
-2. 校验规则使用 `FormRules<T>` 类型，确保 rule 的 `field` 与表单字段对应。
-3. 提交前必须调用 `formRef.validate()`，不要跳过校验直接提交。
-4. 编辑模式通过 `route.query.id` 判断，有 id 则加载详情并回填。
-5. 重置使用 `formRef.resetFields()`，不要手动清空字段。
-6. 提交按钮使用 `loading` 状态防止重复提交。
+1. `reactive` + `FormRules` + `formRef.validate()`
+2. 提交按钮必须有 **loading** 防重复
+3. 编辑回填：`Object.assign(formData, detail)`（见 `data-writeback`）
+4. 远程下拉：`ReSelectQuery`（`url` + `value` + `label`，回写用 `edit-data`），见 `form-advanced`
 
-## 详情/编辑页
-
-### 页面跳转传参
+## 路由片段
 
 ```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" });
+{
+  path: "/customer/list",
+  name: "CustomerList",
+  component: () => import("@/views/customer/list/index.vue"),
+  meta: { title: "客户列表", roles: ["admin", "common"] },
 }
 ```
 
-### 详情页数据回显
-
-```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);
-}
-```
+禁止业务模块再挂 Layout。
 
 ## 常见反例
 
-- 不使用 `useTableSearch`，手动管理 loading / pagination / content。
-- 表单使用 `ref({})` 而非 `reactive({})` 定义。
-- 提交时不调用 `validate()`，或调用后不处理 reject。
-- 编辑页通过 `router.params` 传参（应使用 `query`）。
-- 重置表单时手动清空字段而不使用 `resetFields()`。
-- 操作列直接写 `el-button` 而不使用 `ReTableOperate`。
+- 使用 `handleSearch` / `handleReset`（错误命名）
+- 不用 `useTableSearch` 手写一套分页 loading
+- 提交无 loading
+- 业务路由二次 Layout
+- ReSelectQuery 写成不存在的 `:api` / `label-key` API（真实 props 见 form-advanced）