@qilitt-mickey/vue3-temp-skill 1.1.9 → 1.1.10

package/SKILL.md

@@ -184,7 +184,7 @@ export function getXxxListApi(data: XxxQuery) {
 ### 列表页
 
 ```typescript
-const { content, pagination, loading, onSearch, reset, formRef, tableData, tableHeight, ... } =
+const { content, otherRef, pagination, loading, onSearch, reset, formRef, tableData, tableHeight, ... } =
   useTableSearch(formQuery, getXxxListApi, `${import.meta.env.VITE_API_BASE_URL}/console/xxx/list`);
 
 onSearch(); // 查询
@@ -197,6 +197,7 @@ reset();    // 重置（配合 formRef.resetFields）
   - `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` 内，避免无数据时贴查询区
+  - 卡片内查询条件以外的模块（统计块/页签/提示条等）包一个根元素绑 `otherRef`，高度自动从 `tableHeight` 扣除，不绑则表格高度算错
 
 ### 路由
 
@@ -289,7 +290,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 内  
+**5b. 列表布局** — `el-card`+`content`+固定 height；查询/展示分区；`tableHeight`；分页在 ReTableBar 内；查询条件外的模块绑 `otherRef`  
 **5c. 设计规范遵从（命中 design-system 时必查）** — 已输出识别回执且三点一致；令牌层（唯一新增）已建立、几何重写并入 element-plus.scss、文件名未漂移；第四节硬编码冲突清单逐条处理并回填；公共区域（侧栏/导航/壳变量）已适配；存量裸值扫描已执行；业务代码无裸控件高度/内边距/字号；验证清单全过  
 **5d. 样式契约（每次生成必查）** — UnoCSS 连字符形态（`p-5`/`w-full`；无 `p5`/`w100%`）；颜色语义变量（无 `bg-[#fff] dark:bg-[#303030]`）；组件尺寸档位（查询/工具栏 `small`、表格 `:size="size"`、弹窗表单 default、整屏 `large`）；间距 4px 基数；细则见 `core-kernel`「四之二」  
 **6. 风格** — 无多余 console；`$t('中文')`；`--vts-*` / UnoCSS；图标走 `svg-icon` / `icons` 约定  

package/package.json

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

package/references/code-quality.md

@@ -46,7 +46,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` 内
+- [ ] **查询列表布局**：`el-card ref="content"` + 固定 `height`（含 `headerHeight`）；查询区 `bg-bg_color p-5` + `ReGrid` `gap`/`cols`；表格绑 `tableHeight`；分页在 `ReTableBar` 内；卡片内查询条件以外的模块包根元素绑 `otherRef`
 
 
 ## 一、TypeScript 类型检查
@@ -274,6 +274,7 @@ const fullName = computed(() => `${user.firstName} ${user.lastName}`);
 - [ ] 折叠事件为 `@should-show-collapse`（不是 `@show-collapse`）。
 - [ ] 展示区用 `ReTableBar class="bg-bg_color"`，与查询区视觉分离。
 - [ ] 表格 `:style="{ height: \`${tableHeight}px\` }"`；`paginationRef` 在表格下方且同属 `ReTableBar` `#default`。
+- [ ] 卡片内除查询表单、表格+分页外还有其他模块（统计块/页签/提示条等）时，已包进一个根元素并绑 `ref="otherRef"`（从 `useTableSearch` 解构）；未绑则 `tableHeight` 漏减该模块高度。
 - [ ] `RePagination` 使用 `:pagination` + `@handle-current-change` / `@handle-size-change`。
 - [ ] `ReTableOperate` 使用 `:list`（不是 `:buttons`）。
 

package/references/core-kernel.md

@@ -28,7 +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 | **查询列表页布局硬约束**（见下方黄金样板）：`el-card` + `ref="content"` + **固定 `height`**（非 `minHeight`）；查询区与表格区分区；表格用 `tableHeight`；分页放在 `ReTableBar` 内；查询条件以外的模块绑 `otherRef` 参与高度扣除 |
 | 11 | addon 缺失时按 `project-inventory` 第九节**精确版本**安装；禁止 `@latest` / 无版本号；Vite 插件与 `build/plugins/*` 成套核对 |
 | 12 | **样式契约**（见「四之二」）：UnoCSS 类名必须连字符形态（`p-5`/`w-full`，禁止 `p5`/`w100%`）；颜色按语义取 `--el-*`/`--vts-*` 变量（禁止 `bg-[#fff] dark:bg-[#303030]` 成对硬编码）；组件尺寸按场景档位（查询/工具栏 `small`、表格 `:size="size"`、弹窗表单 default、整屏主表单 `large`）；`design-tokens.scss` 存在时零新增硬编码裸值 |
 
@@ -131,6 +131,7 @@ ReAuth、ReDialog、ReGrid、ReGridItem、RePagination、ReTableBar、ReTableOpe
 | 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` |
+| L8 | 查询条件之外的模块必须绑 `otherRef` | 卡片内除查询表单、表格+分页外还有任何模块（统计块/页签/提示条/子面板等），外层包一个根元素并 `ref="otherRef"`；`tableHeight` 会自动减去它的高度，不绑则表格高度算错（溢出或被压扁）。多个模块合并进**一个**根容器，禁止逐个散落 |
 
 ```vue
 <script setup lang="ts">
@@ -153,6 +154,7 @@ const formQuery = reactive<CustomerQuery>({ keyword: "", status: undefined });
 
 const {
   content,
+  otherRef,
   tableHeight,
   paginationRef,
   loading,
@@ -215,7 +217,7 @@ function handleSizeChange(size: number) {
         height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`,
       }"
     >
-      <!-- L3：查询区独立背景与内边距 -->
+      <!-- L3：查询区独立背景与内边距（formRef 高度自动参与 tableHeight 计算） -->
       <div>
         <el-form
           ref="formRef"
@@ -281,6 +283,14 @@ function handleSizeChange(size: number) {
         </el-form>
       </div>
 
+      <!-- L8：查询条件以外的模块统一包一个根元素绑 otherRef（无额外模块时整段删除）；
+           tableHeight 公式会自动减去它的高度：
+           content 高 − formRef 高 − paginationRef 高 − otherRef 高 − 50；
+           模块自身间距写在内部内容上，根容器保持零高度余量 -->
+      <div ref="otherRef">
+        <!-- 统计/页签/提示等额外模块放这里 -->
+      </div>
+
       <!-- L3/L6：展示区在 ReTableBar 内；表格+分页同槽，保证空数据也撑满 -->
       <ReTableBar class="bg-bg_color" :columns="[]" @refresh="onSearch">
         <template #title>
@@ -335,6 +345,8 @@ function handleSizeChange(size: number) {
 
 `useTableSearch(formQuery, searchFn, url)`：`searchFn` 签名为 `(query, url) => Promise<Result<T>>`，分页字段为 `pageNo` / `pageSize`，列表数据取 `data.content`，总数 `data.totalCount`。返回值中的 `content` / `tableHeight` / `paginationRef` / `formRef` 必须按样板绑定，否则动态高度失效。
 
+**动态高度真相**：`tableHeight = content.offsetHeight − formRef 高 − paginationRef 高 − otherRef 高 − 50`（ResizeObserver 实时计算）。`content` / `formRef` / `paginationRef` 是固定三件套；**页面出现查询条件以外的模块时必须解构 `otherRef` 并绑到这些模块的统一根元素上**（多个模块包进同一个根容器），高度随模块显隐/伸缩自动重算。禁止用写死像素、`calc()` 猜值或自行手写 ResizeObserver 替代该机制。
+
 ---
 
 ## 四之二、样式契约（所有生成代码必须遵循）

package/references/crud-pages.md

@@ -18,7 +18,7 @@ tags: [vue3, crud, list, form, detail, table, useTableSearch, page, layout]
 ```typescript
 useTableSearch(formQuery, searchFn, url)
 // searchFn: (query: CombinedQueryData, url: string) => Promise<Result<T>>
-// 返回含：content, tableData, pagination, loading, formRef, onSearch, reset,
+// 返回含：content, otherRef, tableData, pagination, loading, formRef, onSearch, reset,
 //         tableHeight, paginationRef, gridRef, showCollapse, collapsed,
 //         collapsedToggle, upBold, downBold, multipleTableRef, ...
 ```
@@ -27,7 +27,7 @@ useTableSearch(formQuery, searchFn, url)
 - 重置：`reset()`（内部 `formRef.resetFields()`）
 - 列表：`tableData.value.tableList`（或经 computed 断言）
 - 分页：请求带 `pageNo` / `pageSize`；响应 `data.content` / `data.totalCount`
-- **高度**：`tableHeight` 由 ResizeObserver 根据 `content` / `formRef` / `paginationRef` 计算；三者必须按黄金样板绑定
+- **高度**：`tableHeight` 由 ResizeObserver 计算，公式 = `content` 高 − `formRef` 高 − `paginationRef` 高 − `otherRef` 高 − 50；`content` / `formRef` / `paginationRef` 必须按黄金样板绑定；**查询条件以外的模块（统计块/页签/提示条等）必须包进一个根元素并绑 `otherRef`**，否则表格动态高度算错
 
 ### 布局硬约束（生成列表页必须全部满足）
 
@@ -40,6 +40,7 @@ useTableSearch(formQuery, searchFn, url)
 | 查询按钮 | `<ReGridItem suffix>` + `flex flex-end` | 用 `index="99"` 冒充后缀 |
 | 展示区 | `ReTableBar class="bg-bg_color"`，与查询区分离 | 查询与表格糊成一块、无标题栏 |
 | 表格高度 | `:style="{ height: \`${tableHeight}px\` }"` | 不绑 `tableHeight`（空数据时分页贴查询区） |
+| 额外模块 | 卡片内查询条件以外的模块包一个根元素绑 `ref="otherRef"`（多个模块合进同一根容器），高度自动从 `tableHeight` 扣除 | 额外模块不绑 `otherRef`（表格溢出/被压扁）；手写固定像素或 `calc()` 猜高度 |
 | 分页 | 放在 `ReTableBar` `#default` 内、表格下方；`RePagination` + `:pagination` + `@handle-current-change` / `@handle-size-change` | 分页在卡片外；虚构 `v-model:current-page` |
 
 ### 完整列表示例
@@ -63,7 +64,7 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 ```
 
 ```typescript
-const { onSearch, reset, tableData, loading, pagination, content, tableHeight, ... } =
+const { onSearch, reset, tableData, loading, pagination, content, otherRef, tableHeight, ... } =
   useTableSearch(
     formQuery,
     getCustomerList,
@@ -160,6 +161,7 @@ async function onSubmit() {
 - 业务路由二次 Layout
 - ReSelectQuery 写成不存在的 `:api` / `label-key` API（真实 props 见 form-advanced）
 - **`ref="content"` 挂在 `div` 上**（`content.$el` 为空 → `tableHeight` 恒为 0）
+- **卡片内有查询条件以外的模块却不绑 `otherRef`**（高度公式漏减该模块 → 表格溢出卡片或底部被截）；或绑到多个散落元素（`otherRef` 只有一个，多模块需包进同一根容器）
 - 卡片只用 **`minHeight`**，不用固定 **`height`**（页面不饱满、表格高度算错）
 - 查询表单无 `p-5` / 无 `gap` / 表单项无 `w-[100%] !mr-0`（字段挤在一起）
 - 查询区与 `ReTableBar` 无分区（条件与展示糊成一块）

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`（须绑 `el-card`）、`tableHeight`、`paginationRef`、`tableData`、`pagination`、`loading`、`onSearch()`、`reset()`、`formRef`、`gridRef`、`collapsed` / `showCollapse` / `collapsedToggle` |
+| **useTableSearch** | 列表页搜索/分页/Loading/动态表高 | `content`（须绑 `el-card`）、`otherRef`（查询条件外模块的统一根元素，高度自动从 `tableHeight` 扣除）、`tableHeight`、`paginationRef`、`tableData`、`pagination`、`loading`、`onSearch()`、`reset()`、`formRef`、`gridRef`、`collapsed` / `showCollapse` / `collapsedToggle` |
 | **useTags** | 多标签页管理 | 右键菜单（刷新/关闭/关闭其他/全屏） |
 | **useTheme** | 主题切换（暗色/亮色） | 主题色生成、布局预设、缓存重置 |
 | **useWebSocket** | WebSocket 通信 | `subscribe()`、`send()`、`sendRaw()`、`isConnected` |