@qilitt-mickey/vue3-temp-skill 1.1.1 → 1.1.3

package/README.md

@@ -59,6 +59,7 @@ Vue 3 企业级中后台项目开发规范技能包 — 让 AI 按团队规范
 | graph-relation / workflow-bpmn / flowchart-g6 / data-mapping | 图谱与工作流 |
 | websocket-realtime / mobile-h5 / wechat-js | 实时、移动、微信 |
 | verify-captcha / qrcode-barcode / feedback-ui / seamless-scroll | 验证码、码、反馈 UI |
+| particles | 粒子特效（tsParticles 登录/氛围背景） |
 | data-compare / data-screen / directives-advanced | 对比、大屏、指令 |
 
 ## 安装

package/SKILL.md

@@ -39,7 +39,8 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
    - 选型表已指定三方库（如图谱、流程图、富文本）→ **用指定库，勿擅自换成同类其他库**；确需新库须「待确认」
 3. **按示例编写**：按本包 `references/` 中的**完整示例**与约定写法编写（命名、结构、调用方式以示例为准）。
 4. **无则上报**：清单与 Skill 均无对应能力时，标注「待确认」新依赖，未经用户同意不得引入。
-5. **真相源优先级**：`仓库现有实现` > `本 Skill references 示例` > 通用 Vue 习惯。  
+5. **真相源优先级**：`仓库已有可复用封装（Re* / Hook / utils）` > `本 Skill references 完整示例` > 通用 Vue 习惯。  
+   **禁止**把仓库里的 views 演示页当作规范来源（业务项目可能没有演示页）；列表布局、弹窗写法等以 Skill 内黄金样板为准。  
    命名以代码为准：列表方法 **`onSearch` / `reset`**；响应类型全局 **`Result<T>`**（`types/global.d.ts`）；HTTP 为 **`import { http } from '@/utils/http'`**。
 6. **依赖 / 插件安装（addon 必做）**：命中专项能力时，先读业务项目 `package.json`。  
    - 已装齐 → 直接写代码  
@@ -98,6 +99,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 | **qrcode-barcode** | 二维码/条形码 | 二维码、条形码、qrcode、barcode |
 | **feedback-ui** | 通知栏/水印/时间轴等 | 通知栏、水印、时间轴、打字机 |
 | **seamless-scroll** | 无缝滚动 | 无缝滚动、跑马灯 |
+| **particles** | 粒子特效（登录/氛围背景） | 粒子、粒子特效、tsparticles、登录背景粒子、粒子动画、连线粒子 |
 | **directives-advanced** | 文本一键复制、长标题字号随宽度变小等体验（用户说效果即可，无需知指令名） | 一键复制、点一下复制、不好抄、标题太长、显示不全、字号跟着变小、文字别截断、挤得下；内部映射 v-copy / v-auto-font |
 
 ### 匹配规则
@@ -114,6 +116,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
    - 「编辑标出改了哪些 / 变更汇总」→ `data-compare`  
    - 「导出 Excel / 下载文件」→ `download-export`  
    - 「菜单加图标 / 换图标 / 图标选择器 / 本地 SVG 图标」→ `icons`  
+   - 「粒子背景 / 登录粒子 / 粒子特效」→ `particles`  
    - 只说「自定义指令」未说明效果 → 先追问，禁止默认塞模块  
 6. **HTTP**：方法跟后端文档，**允许 GET/POST**；POST→`data`，GET→`params`；真实 URL 用 `VITE_API_BASE_URL`；`/mock` 仅本地 Fake Server；无单请求 `crypto: true`。
 
@@ -171,7 +174,7 @@ export function getXxxListApi(data: XxxQuery) {
 ### 列表页
 
 ```typescript
-const { content, pagination, loading, onSearch, reset, formRef, tableData, ... } =
+const { content, pagination, loading, onSearch, reset, formRef, tableData, tableHeight, ... } =
   useTableSearch(formQuery, getXxxListApi, `${import.meta.env.VITE_API_BASE_URL}/console/xxx/list`);
 
 onSearch(); // 查询
@@ -180,6 +183,10 @@ reset();    // 重置（配合 formRef.resetFields）
 
 - 方法名必须是 **`onSearch` / `reset`**，不是 handleSearch/handleReset。
 - 配合 `ReGrid` / `ReGridItem` / `ReTableBar` / `RePagination` / `ReTableOperate`。
+- **布局必须按 `core-kernel`「列表黄金样板」完整输出**（技能自包含，不依赖仓库 views 演示页）：
+  - `el-card ref="content"` + 固定 `height`（含 `headerHeight`），禁止只用 `minHeight` / `ref` 挂 `div`
+  - 查询区 `bg-bg_color p-5` + `ReGrid` `:gap="[0, 20]"` + 表单项 `w-[100%] !mr-0`；与 `ReTableBar` 展示区分开
+  - 表格绑 `tableHeight`；分页放在 `ReTableBar` 内，避免无数据时贴查询区
 
 ### 路由
 
@@ -245,6 +252,7 @@ reset();    // 重置（配合 formRef.resetFields）
 **3. API** — `@/utils/http`；方法跟后端（允许 GET/POST）；封装在 `src/api/`；`VITE_API_BASE_URL`；无虚构 `/api` / 无 `crypto: true`
 **4. 安全** — 无危险 v-html；无硬编码密钥  
 **5. 业务** — `onSearch`/`reset`；提交 loading；权限；未二次 Layout  
+**5b. 列表布局** — `el-card`+`content`+固定 height；查询/展示分区；`tableHeight`；分页在 ReTableBar 内  
 **6. 风格** — 无多余 console；`$t('中文')`；`--vts-*` / UnoCSS；图标走 `svg-icon` / `icons` 约定  
 
 完整项见 `references/code-quality.md`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qilitt-mickey/vue3-temp-skill",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Vue 3 企业级中后台项目开发规范技能包 — core-kernel 架构、按需功能模块",
   "bin": {
     "vue3-temp-skill": "./bin/cli.js"

package/references/code-quality.md

@@ -22,6 +22,7 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 - [ ] HTTP 为 `import { http } from '@/utils/http'` + 全局 `Result<T>`
 - [ ] 业务路由未二次挂 Layout
 - [ ] 使用对应 `references/<模块>.md` 示例与约定写法
+- [ ] **查询列表布局**：`el-card ref="content"` + 固定 `height`（含 `headerHeight`）；查询区 `bg-bg_color p-5` + `ReGrid` `gap`/`cols`；表格绑 `tableHeight`；分页在 `ReTableBar` 内
 
 
 ## 一、TypeScript 类型检查
@@ -226,6 +227,18 @@ const fullName = computed(() => `${user.firstName} ${user.lastName}`);
 - [ ] 路由跳转使用了正确的参数传递方式（`query` 而非 `params`）。
 - [ ] 分页切换正确触发了数据加载。
 
+### 查询列表页布局（命中 crud-pages / 列表需求时必查）
+
+- [ ] `ref="content"` 挂在 **`el-card`**（组件），不是原生 `div`。
+- [ ] 卡片样式为固定 **`height: calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`**，不是 `minHeight`。
+- [ ] 查询 `el-form`：`inline` + `class="bg-bg_color p-5"`；`ReGrid` 有 `:gap="[0, 20]"` 与响应式 `cols`。
+- [ ] 表单项有 `class="w-[100%] !mr-0"`；操作按钮用 `<ReGridItem suffix>`。
+- [ ] 折叠事件为 `@should-show-collapse`（不是 `@show-collapse`）。
+- [ ] 展示区用 `ReTableBar class="bg-bg_color"`，与查询区视觉分离。
+- [ ] 表格 `:style="{ height: \`${tableHeight}px\` }"`；`paginationRef` 在表格下方且同属 `ReTableBar` `#default`。
+- [ ] `RePagination` 使用 `:pagination` + `@handle-current-change` / `@handle-size-change`。
+- [ ] `ReTableOperate` 使用 `:list`（不是 `:buttons`）。
+
 ## 八、代码风格检查
 
 ### 必须通过

package/references/core-kernel.md

@@ -28,6 +28,7 @@ tags: [vue3, kernel, conventions, layout, router, http, crud, inventory]
 | 8 | i18n：`$t('中文key')`，key 即中文文案 |
 | 9 | 禁止用 `v-html` 渲染不可信内容 |
 | 10 | 新三方依赖必须用户确认；已有封装须复用，选型表指定库勿擅自替换 |
+| 11 | **查询列表页布局硬约束**（见下方黄金样板）：`el-card` + `ref="content"` + **固定 `height`**（非 `minHeight`）；查询区与表格区分区；表格用 `tableHeight`；分页放在 `ReTableBar` 内 |
 | 11 | addon 缺失时按 `project-inventory` 第九节**精确版本**安装；禁止 `@latest` / 无版本号；Vite 插件与 `build/plugins/*` 成套核对 |
 
 ---
@@ -116,8 +117,23 @@ ReAuth、ReDialog、ReGrid、ReGridItem、RePagination、ReTableBar、ReTableOpe
 
 ### 列表黄金样板
 
+> **布局真相源即本样板**（技能自包含，不依赖业务仓库是否存在演示页）。生成查询列表页必须完整按下方结构输出，禁止简化成「表单 + 裸表格 + 裸分页」——否则会出现字段挤在一起、查询与展示区分不清、无数据时分页贴查询区、页面高度不饱满。
+
+#### 布局硬约束（违反即不合格）
+
+| # | 必须 | 说明 |
+|---|------|------|
+| L1 | `el-card` + `ref="content"` | `useTableSearch` 通过 `content.$el` 算高度；`ref` 必须挂在 **组件**（`el-card`）上，禁止挂在原生 `div` |
+| L2 | 卡片用固定 **`height`** | `height: calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`；**禁止**只写 `minHeight`（否则 `tableHeight` 算不准，表格无法撑满） |
+| L3 | 查询区与展示区分开 | 查询：`el-form` + `class="bg-bg_color p-5"`；展示：`ReTableBar class="bg-bg_color"`；两区视觉分离 |
+| L4 | `ReGrid` 间距与栅格 | `:gap="[0, 20]"` + `:cols="{ xs: 1, sm: 2, md: 2, lg: 3, xl: 4 }"`；表单项 `class="w-[100%] !mr-0"`；事件为 `@should-show-collapse` |
+| L5 | 操作按钮用 `suffix` | `<ReGridItem suffix>`，勿用随意 `index=99` 冒充后缀列 |
+| L6 | 表格动态高度 | `:style="{ height: \`${tableHeight}px\` }"`；分页 **必须在** `ReTableBar` 的 `#default` 内、表格下方，保证空数据时仍占满剩余高度 |
+| L7 | `RePagination` 真实 API | `:pagination="pagination"` + `@handle-current-change` / `@handle-size-change`；**禁止**虚构的 `v-model:current-page` |
+
 ```vue
 <script setup lang="ts">
+import type { OperateButton } from "@/components/ReTableOperate";
 import type { Customer, CustomerQuery } from "@/api/customer";
 import { getCustomerList } from "@/api/customer";
 import { ReGrid } from "@/components/ReGrid";
@@ -159,6 +175,15 @@ const {
 
 const tableList = computed(() => tableData.value.tableList as Customer[]);
 
+const operateButtons: OperateButton[] = [
+  {
+    label: $t("删除"),
+    type: "danger",
+    icon: "i-ep:delete",
+    onClick: (row) => handleDelete(row as Customer),
+  },
+];
+
 onMounted(() => {
   onSearch();
 });
@@ -167,91 +192,147 @@ function handleDelete(row: Customer) {
   message($t("删除成功"), { type: "success" });
   onSearch();
 }
+
+function handleCurrentChange(cur: number) {
+  pagination.currentPage = cur;
+  onSearch();
+}
+
+function handleSizeChange(size: number) {
+  pagination.pageSize = size;
+  onSearch();
+}
 </script>
 
 <template>
-  <div
-    ref="content"
-    :style="{ minHeight: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)` }"
-    class="bg-[var(--el-bg-color)] p-2"
-  >
-    <el-form ref="formRef" :model="formQuery" @keyup.enter="onSearch">
-      <ReGrid ref="gridRef" :collapsed="collapsed" @show-collapse="showCollapse = $event">
-        <ReGridItem :index="0">
-          <el-form-item :label="$t('关键词')" prop="keyword">
-            <el-input v-model="formQuery.keyword" clearable :placeholder="$t('请输入')" />
-          </el-form-item>
-        </ReGridItem>
-        <ReGridItem :index="1">
-          <el-form-item :label="$t('状态')" prop="status">
-            <el-select v-model="formQuery.status" clearable :placeholder="$t('请选择')">
-              <el-option :label="$t('启用')" :value="1" />
-              <el-option :label="$t('禁用')" :value="0" />
-            </el-select>
-          </el-form-item>
-        </ReGridItem>
-        <ReGridItem :index="99" :collapsed="false">
-          <el-form-item>
-            <el-button type="primary" :loading="loading" @click="onSearch">{{ $t("查询") }}</el-button>
-            <el-button @click="reset()">{{ $t("重置") }}</el-button>
-            <el-button
-              v-if="showCollapse"
-              text
-              type="primary"
-              @click="collapsedToggle"
-            >
-              {{ collapsed ? $t("展开") : $t("收起") }}
-              <component :is="collapsed ? downBold : upBold" class="ml-1" />
-            </el-button>
-          </el-form-item>
-        </ReGridItem>
-      </ReGrid>
-    </el-form>
-
-    <ReTableBar
-      :columns="[]"
-      @refresh="onSearch"
-    >
-      <template #buttons>
-        <el-button type="primary" v-auth="['admin']">{{ $t("新增") }}</el-button>
-      </template>
-    </ReTableBar>
-
-    <el-table
-      ref="multipleTableRef"
-      v-loading="loading"
-      :element-loading-svg="svgLoading"
-      :data="tableList"
-      :height="tableHeight"
-      border
-      row-key="id"
+  <div>
+    <!-- L1/L2：ref=content 必须在 el-card；用 height 非 minHeight -->
+    <el-card
+      ref="content"
+      shadow="never"
+      :style="{
+        height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`,
+      }"
     >
-      <el-table-column prop="code" :label="$t('编号')" min-width="120" />
-      <el-table-column prop="name" :label="$t('名称')" min-width="140" />
-      <el-table-column :label="$t('操作')" width="160" fixed="right">
-        <template #default="{ row }">
-          <ReTableOperate
-            :buttons="[
-              { label: $t('编辑'), onClick: () => {} },
-              { label: $t('删除'), type: 'danger', onClick: () => handleDelete(row) },
-            ]"
-          />
+      <!-- L3：查询区独立背景与内边距 -->
+      <div>
+        <el-form
+          ref="formRef"
+          :inline="true"
+          :model="formQuery"
+          class="bg-bg_color p-5"
+        >
+          <!-- L4：gap + cols；事件名 should-show-collapse -->
+          <ReGrid
+            ref="gridRef"
+            :collapsed="collapsed"
+            :gap="[0, 20]"
+            :cols="{ xs: 1, sm: 2, md: 2, lg: 3, xl: 4 }"
+            style="max-height: 300px; overflow-y: auto;"
+            @should-show-collapse="(val) => (showCollapse = val)"
+          >
+            <ReGridItem index="0">
+              <el-form-item :label="$t('关键词')" prop="keyword" class="w-[100%] !mr-0">
+                <el-input
+                  v-model="formQuery.keyword"
+                  clearable
+                  :placeholder="$t('请输入')"
+                />
+              </el-form-item>
+            </ReGridItem>
+            <ReGridItem index="1">
+              <el-form-item :label="$t('状态')" prop="status" class="w-[100%] !mr-0">
+                <el-select v-model="formQuery.status" clearable :placeholder="$t('请选择')">
+                  <el-option :label="$t('启用')" :value="1" />
+                  <el-option :label="$t('禁用')" :value="0" />
+                </el-select>
+              </el-form-item>
+            </ReGridItem>
+            <!-- L5：操作列用 suffix -->
+            <ReGridItem suffix>
+              <div class="flex flex-end">
+                <el-button
+                  type="primary"
+                  size="small"
+                  :loading="loading"
+                  @click="pagination.currentPage = 1; pagination.pageSize = 10; onSearch()"
+                >
+                  {{ $t("查询") }}
+                </el-button>
+                <el-button size="small" @click="reset">
+                  {{ $t("重置") }}
+                </el-button>
+                <el-button
+                  v-if="showCollapse"
+                  type="primary"
+                  link
+                  class="!font-size-12"
+                  @click="collapsedToggle"
+                >
+                  {{ collapsed ? $t("展开") : $t("收起") }}
+                  <el-icon class="el-icon--right">
+                    <component :is="collapsed ? downBold : upBold" />
+                  </el-icon>
+                </el-button>
+              </div>
+            </ReGridItem>
+          </ReGrid>
+        </el-form>
+      </div>
+
+      <!-- L3/L6：展示区在 ReTableBar 内；表格+分页同槽，保证空数据也撑满 -->
+      <ReTableBar class="bg-bg_color" :columns="[]" @refresh="onSearch">
+        <template #title>
+          <span class="truncate font-size-16 font-bold">{{ $t("展示列表") }}</span>
+        </template>
+        <template #buttons>
+          <el-button type="primary" size="small" v-auth="['admin']">
+            {{ $t("新增") }}
+          </el-button>
+        </template>
+        <template #default="{ size }">
+          <div class="vl-parent">
+            <el-table
+              ref="multipleTableRef"
+              v-loading.lock="loading"
+              :element-loading-text="$t('加载中')"
+              :element-loading-spinner="svgLoading"
+              element-loading-svg-view-box="0, 0, 20, 20"
+              :style="{ height: `${tableHeight}px` }"
+              :size="size"
+              :data="tableList"
+              :header-cell-style="{
+                background: 'var(--el-fill-color-light)',
+                color: 'var(--el-text-color-primary)',
+              }"
+              row-key="id"
+            >
+              <el-table-column prop="code" :label="$t('编号')" min-width="120" />
+              <el-table-column prop="name" :label="$t('名称')" min-width="140" />
+              <el-table-column :label="$t('操作')" width="160" fixed="right">
+                <template #default="{ row, $index }">
+                  <ReTableOperate :list="operateButtons" :row="row" :index="$index" />
+                </template>
+              </el-table-column>
+            </el-table>
+
+            <!-- L7：真实分页 API；ref=paginationRef 参与 tableHeight 计算 -->
+            <RePagination
+              ref="paginationRef"
+              :size="size"
+              :pagination="pagination"
+              @handle-current-change="handleCurrentChange"
+              @handle-size-change="handleSizeChange"
+            />
+          </div>
         </template>
-      </el-table-column>
-    </el-table>
-
-    <RePagination
-      ref="paginationRef"
-      v-model:current-page="pagination.currentPage"
-      v-model:page-size="pagination.pageSize"
-      :total="pagination.total"
-      @change="onSearch"
-    />
+      </ReTableBar>
+    </el-card>
   </div>
 </template>
 ```
 
-`useTableSearch(formQuery, searchFn, url)`：`searchFn` 签名为 `(query, url) => Promise<Result<T>>`，分页字段为 `pageNo` / `pageSize`，列表数据取 `data.content`，总数 `data.totalCount`。
+`useTableSearch(formQuery, searchFn, url)`：`searchFn` 签名为 `(query, url) => Promise<Result<T>>`，分页字段为 `pageNo` / `pageSize`，列表数据取 `data.content`，总数 `data.totalCount`。返回值中的 `content` / `tableHeight` / `paginationRef` / `formRef` 必须按样板绑定，否则动态高度失效。
 
 ---
 
@@ -270,7 +351,7 @@ function handleDelete(row: Customer) {
 
 ### 附加 Utils
 
-`uploadManager` / `imageCompression` → file；`changeSummaryService` → data-compare；`websocket/**` / `wechat/**` / `vantRules` / `particles` / `motion` → 对应专项。
+`uploadManager` / `imageCompression` → file；`changeSummaryService` → data-compare；`websocket/**` / `wechat/**` / `vantRules` → 对应专项；`particles` / `particlesOptions` → **particles**；`motion` → feedback-ui / 登录页入场动画。
 
 ---
 

package/references/crud-pages.md

@@ -1,14 +1,15 @@
 ---
 skill: crud-pages
-description: 查询列表页、表单页、标准 CRUD 流程。含 useTableSearch（onSearch/reset）、ReGrid 查询区、表格工具栏。务必按照本文件完整示例编写。
+description: 查询列表页、表单页、标准 CRUD 流程。含 useTableSearch（onSearch/reset）、ReGrid 查询区、表格工具栏与动态高度布局。务必按照本文件与 core-kernel 完整示例编写。
 scope: project
-tags: [vue3, crud, list, form, detail, table, useTableSearch, page]
+tags: [vue3, crud, list, form, detail, table, useTableSearch, page, layout]
 ---
 
 # CRUD 页面开发规范
 
 > 以下示例即规范真相。
 > 须同时遵守 `core-kernel` / `http-api`。详情跳转见 `detail-page`，回显见 `data-writeback`。
+> **查询列表页完整模板以 `core-kernel.md`「列表黄金样板」为准**（技能内完整示例，勿到仓库里找 views 演示页对照）。
 
 ## 查询列表页
 
@@ -17,23 +18,40 @@ tags: [vue3, crud, list, form, detail, table, useTableSearch, page]
 ```typescript
 useTableSearch(formQuery, searchFn, url)
 // searchFn: (query: CombinedQueryData, url: string) => Promise<Result<T>>
-// 返回含：content, tableData, pagination, loading, formRef, onSearch, reset, tableHeight, ...
+// 返回含：content, tableData, pagination, loading, formRef, onSearch, reset,
+//         tableHeight, paginationRef, gridRef, showCollapse, collapsed,
+//         collapsedToggle, upBold, downBold, multipleTableRef, ...
 ```
 
 - 查询：`onSearch()`
 - 重置：`reset()`（内部 `formRef.resetFields()`）
 - 列表：`tableData.value.tableList`（或经 computed 断言）
 - 分页：请求带 `pageNo` / `pageSize`；响应 `data.content` / `data.totalCount`
+- **高度**：`tableHeight` 由 ResizeObserver 根据 `content` / `formRef` / `paginationRef` 计算；三者必须按黄金样板绑定
+
+### 布局硬约束（生成列表页必须全部满足）
+
+| 区域 | 正确写法 | 禁止 |
+|------|---------|------|
+| 外层容器 | `<el-card ref="content" shadow="never" :style="{ height: \`calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)\` }">` | `ref` 挂原生 `div`；只用 `minHeight`；漏 `headerHeight` |
+| 查询区 | `el-form` `:inline="true"` + `class="bg-bg_color p-5"` | 无内边距、无背景、字段横向挤成一团 |
+| 栅格 | `ReGrid` `:gap="[0, 20]"` + `:cols="{ xs: 1, sm: 2, md: 2, lg: 3, xl: 4 }"`；`@should-show-collapse` | 无 `gap`；事件写成 `@show-collapse` |
+| 表单项 | `el-form-item` 加 `class="w-[100%] !mr-0"`；`ReGridItem` 用 `index="0"` 字符串 | 表单项无宽度、彼此贴死 |
+| 查询按钮 | `<ReGridItem suffix>` + `flex flex-end` | 用 `index="99"` 冒充后缀 |
+| 展示区 | `ReTableBar class="bg-bg_color"`，与查询区分离 | 查询与表格糊成一块、无标题栏 |
+| 表格高度 | `:style="{ height: \`${tableHeight}px\` }"` | 不绑 `tableHeight`（空数据时分页贴查询区） |
+| 分页 | 放在 `ReTableBar` `#default` 内、表格下方；`RePagination` + `:pagination` + `@handle-current-change` / `@handle-size-change` | 分页在卡片外；虚构 `v-model:current-page` |
 
 ### 完整列表示例
 
 见 `core-kernel.md`「列表黄金样板」。本模块补充约定：
 
 1. 查询区用 **`ReGrid` + `ReGridItem`**，折叠与 `collapsed` / `showCollapse` / `collapsedToggle` 配套。
-2. 工具栏用 **`ReTableBar`**，行操作用 **`ReTableOperate`**，分页用 **`RePagination`**。
-3. 查询 / 重置按钮文案 `$t('查询')` / `$t('重置')`，点击绑定 **`onSearch` / `reset`**。
+2. 工具栏用 **`ReTableBar`**，行操作用 **`ReTableOperate`**（`:list` 非 `:buttons`），分页用 **`RePagination`**。
+3. 查询 / 重置按钮文案 `$t('查询')` / `$t('重置')`（或模板一致的「搜索」），点击绑定 **`onSearch` / `reset`**。
 4. `defineOptions({ name })` 与路由 `name` 一致（keep-alive / 标签）。
 5. 需要权限的按钮加 `v-auth` / `ReAuth`。
+6. 从 `useApp()` 取 **`headerHeight`**、`svgLoading`（及按需 `filterValue` / `baseCodeGet`）。
 
 ### API 配套
 
@@ -45,11 +63,12 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 ```
 
 ```typescript
-const { onSearch, reset, tableData, loading, pagination, ... } = useTableSearch(
-  formQuery,
-  getCustomerList,
-  `${import.meta.env.VITE_API_BASE_URL}/console/customer/list`,
-);
+const { onSearch, reset, tableData, loading, pagination, content, tableHeight, ... } =
+  useTableSearch(
+    formQuery,
+    getCustomerList,
+    `${import.meta.env.VITE_API_BASE_URL}/console/customer/list`,
+  );
 onMounted(() => onSearch());
 ```
 
@@ -140,3 +159,11 @@ async function onSubmit() {
 - 提交无 loading
 - 业务路由二次 Layout
 - ReSelectQuery 写成不存在的 `:api` / `label-key` API（真实 props 见 form-advanced）
+- **`ref="content"` 挂在 `div` 上**（`content.$el` 为空 → `tableHeight` 恒为 0）
+- 卡片只用 **`minHeight`**，不用固定 **`height`**（页面不饱满、表格高度算错）
+- 查询表单无 `p-5` / 无 `gap` / 表单项无 `w-[100%] !mr-0`（字段挤在一起）
+- 查询区与 `ReTableBar` 无分区（条件与展示糊成一块）
+- 表格不绑 `tableHeight`，分页放在卡片外（无数据时分页直接贴查询条件）
+- `RePagination` 写成 `v-model:current-page`（组件真实 API 为 `:pagination` + handle 事件）
+- `ReTableOperate` 写成 `:buttons`（真实 prop 为 `:list`）
+- `ReGrid` 监听 `@show-collapse`（真实事件为 `@should-show-collapse`）

package/references/form-advanced.md

@@ -203,7 +203,7 @@ function parseAddress(text: string) {
 ## ReDialog 通用弹窗（必用）
 
 > 落点：`src/components/ReDialog`。基于 `el-dialog` 封装：居中、可拖拽、`destroy-on-close`、默认禁止点遮罩关闭、可选全屏切换、内容区 `el-scrollbar`。  
-> 样板参考：`src/views/table/base/index.vue`、`src/views/form/moreForm/MultiFormDialog.vue`。
+> 写法以**本模块下方黄金样板**为准（技能自包含，勿依赖仓库 views 演示页）。
 
 ### Props / 插槽
 

package/references/icons.md

@@ -154,7 +154,7 @@ export default {
 
 ## 五、ReIconPicker 图标选择器
 
-路径：`src/components/ReIconPicker`。演示页：`src/views/form/iconPicker`（`/form/icon-picker`）。
+路径：`src/components/ReIconPicker`。用法以本模块示例为准。
 
 ### 默认图标源
 

package/references/particles.md

@@ -0,0 +1,143 @@
+# 粒子特效（tsParticles）
+
+> 按本文件示例编写，复用项目已有 `@tsparticles/*` 注册与 `src/utils/particles.ts` 配置，勿另起一套粒子实现，勿引入 `particles.js`。
+
+规范登录页 / 氛围页粒子背景的依赖、全局注册、配置与页面用法。在需要粒子背景、登录特效、连线粒子时参照。
+
+## 依赖（缺则先装）
+
+| 包 | 版本 | 用途 |
+|---|---|---|
+| `@tsparticles/slim` | `4.3.1` | 轻量引擎（`loadSlim`） |
+| `@tsparticles/vue3` | `4.3.1` | Vue3 组件 `vue-particles` |
+
+```bash
+pnpm add @tsparticles/slim@4.3.1 @tsparticles/vue3@4.3.1
+```
+
+完整模板一般为 **core** 已装齐；裁剪项目缺失时按上表精确版本安装。构建侧若有 `tsparticles-vendor` 拆包（见 `build/chunks.ts`），模板已接线则勿改。
+
+## 全局注册（`main.ts`）
+
+必须在应用挂载前注册，并用 `loadSlim` 初始化引擎：
+
+```typescript
+import type { Plugin } from "vue";
+import { loadSlim } from "@tsparticles/slim";
+import Particles from "@tsparticles/vue3";
+
+app.use(Particles as unknown as Plugin, {
+  init: async (engine: unknown) => {
+    await loadSlim(engine as Parameters<typeof loadSlim>[0]);
+  },
+});
+```
+
+- 使用 **slim** 包即可覆盖登录背景常见能力；勿默认换成 `@tsparticles/engine` 全量包。
+- 类型断言以仓库现有写法为准（`as unknown as Plugin`）。
+
+## 配置（`src/utils/particles.ts`）
+
+导出名为 **`particlesOptions`**（以仓库为准）。v4 已移除 `particles.color` / `particles.stroke`，必须用 **paint** 系统：
+
+| 旧（勿再用） | 新（v4） |
+|---|---|
+| `particles.color` | `particles.paint[].fill` |
+| `particles.stroke` | `particles.paint[].stroke` |
+| `links.color` 直接传数组/字符串 | `links.color: { value: '...' }`（`IRangeColor`） |
+
+关键约定：
+
+1. **登录背景**：`background.color.value` 用 `transparent`，避免挡住背景图。
+2. **非全屏铺层**：`fullScreen.enable: false`，由页面 CSS 控制 `#tsparticles` 尺寸（见 `src/styles/login.css`）。
+3. **彩色粒子**：用 `paint` 数组（多组 fill）实现；勿写回旧 `color` 字段。
+4. **交互**：项目默认 hover `repulse`、click `push`；业务可按场景改 `interactivity`，但保持配置集中在 `particles.ts`。
+
+精简示例（完整默认值以仓库 `src/utils/particles.ts` 为准）：
+
+```typescript
+export const particlesOptions = {
+  background: {
+    color: { value: "transparent" },
+  },
+  fullScreen: { enable: false },
+  fpsLimit: 120,
+  interactivity: {
+    events: {
+      onClick: { enable: true, mode: "push" },
+      onHover: { enable: true, mode: "repulse" },
+    },
+    modes: {
+      push: { quantity: 4 },
+      repulse: { distance: 200, duration: 0.4 },
+    },
+  },
+  particles: {
+    paint: [
+      {
+        fill: {
+          enable: true,
+          color: { value: "#4a5568" },
+          opacity: 0.95,
+        },
+        stroke: { enable: false },
+      },
+    ],
+    links: {
+      enable: true,
+      color: { value: "#4a5568" },
+      distance: 150,
+      opacity: 0.8,
+      width: 1,
+    },
+    move: {
+      direction: "none",
+      enable: true,
+      outModes: "bounce",
+      speed: 5,
+    },
+    number: {
+      density: { enable: true },
+      value: 80,
+    },
+    shape: { type: "circle" },
+    size: { value: { min: 2.5, max: 6 } },
+  },
+  detectRetina: true,
+};
+```
+
+## 页面用法（登录页）
+
+```vue
+<script setup lang="ts">
+import { particlesOptions } from "@/utils/particles";
+</script>
+
+<template>
+  <vue-particles id="tsparticles" :options="particlesOptions" />
+  <!-- 业务内容 -->
+</template>
+```
+
+配套样式（登录场景）：
+
+```css
+#tsparticles {
+  position: absolute;
+  width: 100%;
+  height: 100%;
+}
+```
+
+- `id` 与 CSS 选择器保持一致（默认 `#tsparticles`）。
+- 粒子层放在页面内容之下，避免挡住表单点击；必要时用 `z-index` / 容器定位调整。
+- 其他氛围页可复用同一配置，或在 `particles.ts` 中导出第二套 options（如 `particlesOptionsDark`），勿在页面内联大段配置。
+
+## 选型与禁止项
+
+1. **只用** `@tsparticles/slim` + `@tsparticles/vue3`，禁止 `particles.js` / `vue-particles`（旧包）等替代库。
+2. **配置集中**在 `src/utils/particles.ts`，页面只引用 `particlesOptions`。
+3. **v4 API**：禁止写 `particles.color`；必须用 `paint.fill` / `paint.stroke`。
+4. 低端设备或弱网场景可降低 `number.value` / `fpsLimit`，勿为特效再引入第二套动画库。
+5. 中后台业务列表页默认不加粒子；仅登录、营销壳、氛围背景等场景使用。

package/references/project-inventory.md

@@ -221,7 +221,7 @@
 | **useApp** | 全局应用状态（布局、字典、登出等） | `baseCodeGet(codeType)`、`filterValue()`、`headerHeight`、`svgLoading` |
 | **useDetail** | 详情页跳转与参数传递 | `toDetail({ id, mark, text })`、`initToDetail()`、`getParameter()` |
 | **useFormCheck** | 多表单校验聚合 | 追踪各字段校验状态，emit `form-validate` 事件 |
-| **useTableSearch** | 列表页搜索/分页/Loading | `content`、`tableData`、`pagination`、`loading`、`onSearch()`、`reset()`、`formRef` |
+| **useTableSearch** | 列表页搜索/分页/Loading/动态表高 | `content`（须绑 `el-card`）、`tableHeight`、`paginationRef`、`tableData`、`pagination`、`loading`、`onSearch()`、`reset()`、`formRef`、`gridRef`、`collapsed` / `showCollapse` / `collapsedToggle` |
 | **useTags** | 多标签页管理 | 右键菜单（刷新/关闭/关闭其他/全屏） |
 | **useTheme** | 主题切换（暗色/亮色） | 主题色生成、布局预设、缓存重置 |
 | **useWebSocket** | WebSocket 通信 | `subscribe()`、`send()`、`sendRaw()`、`isConnected` |
@@ -245,7 +245,7 @@
 | `message.ts` | `message()` | 消息提示封装（ElMessage 包装） |
 | `mitt.ts` | `mitt()` | 全局事件总线 |
 | `motion.tsx` | `MotionComponent` | 入场动画 TSX 组件 |
-| `particles.ts` | `particlesConfig` | 粒子动画配置 |
+| `particles.ts` | `particlesOptions` | 粒子动画配置（tsParticles v4 paint） |
 | `progress/` | `NProgress` | 路由进度条配置 |
 | `responsive.ts` | `ResponsiveStorage` | 响应式存储注入 |
 | `router.ts` | `hasAuth()`、路由扁平化、权限过滤 | 路由工具 |
@@ -308,7 +308,7 @@
 | 文件预览 | `@file-viewer/*` + `ReFileViewer` | 禁止引入 pdf.js / mammoth 等 |
 | 滑块验证 | `vue3-puzzle-vcode` + `ReVerify` | 禁止引入其他验证码库 |
 | 打字机动画 | `typeit` + `ReTypeit` | 禁止引入其他打字机库 |
-| 粒子动画 | `@tsparticles/slim` | 禁止引入 particles.js 等 |
+| 粒子动画 | `@tsparticles/slim` + `@tsparticles/vue3` + `particlesOptions` | 禁止引入 particles.js 等；配置见 `particles` 模块 |
 | 日期处理 | `dayjs` | 禁止引入 moment / date-fns 等 |
 | HTTP 请求 | 项目封装的 `src/utils/http.ts`（基于 axios） | 禁止直接使用 axios / fetch / ky 等 |
 | 状态管理 | `pinia` + `pinia-plugin-persistedstate` | 禁止引入 vuex / zustand 等 |
@@ -362,6 +362,7 @@
 | **verify-captcha** | `vue3-puzzle-vcode@1.1.7` | — | — | `pnpm add vue3-puzzle-vcode@1.1.7` |
 | **qrcode-barcode** | `qrcode@1.5.4` `jsbarcode@3.12.3` | `@types/qrcode@1.5.6` | — | `pnpm add qrcode@1.5.4 jsbarcode@3.12.3` + `pnpm add -D @types/qrcode@1.5.6` |
 | **feedback-ui**（打字机） | `typeit@8.8.7` | — | — | `pnpm add typeit@8.8.7` |
+| **particles** | `@tsparticles/slim@4.3.1` `@tsparticles/vue3@4.3.1` | — | `main.ts` 中 `Particles` + `loadSlim`；可选 `build/chunks.ts` 的 `tsparticles-vendor` | `pnpm add @tsparticles/slim@4.3.1 @tsparticles/vue3@4.3.1` |
 | **api-check** / Mock | —（运行时无额外包） | `vite-plugin-fake-server@2.2.4`（core 通常已有） | `build/plugins/ViteMockServe.ts`；`VITE_USE_MOCK` | 缺失时：`pnpm add -D vite-plugin-fake-server@2.2.4` |
 | **websocket-realtime** / **data-compare** / **seamless-scroll** / **directives-advanced** / **download-export** / **tree-table** | 无额外 npm 包（用项目封装） | — | 见各模块 | 无需安装 |