@qilitt-mickey/vue3-temp-skill 1.1.12 → 1.1.13

package/package.json

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

package/references/code-quality.md

@@ -35,7 +35,7 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 - [ ] 列表方法名 `onSearch` / `reset`；HTTP 用 `@/utils/http` + `Result<T>`
 - [ ] 业务路由未二次挂 Layout
 - [ ] 独立详情：`showLink:false` + `activePath` + `toDetail` + `initToDetail`（细则 `detail-page`）
-- [ ] 列表布局按 `crud-pages` 黄金样板（`el-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内）
+- [ ] 列表布局按 `crud-pages` 黄金样板（`el-card.vts-page-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内；内容区无外层滚动条）
 
 ## TypeScript
 

package/references/core-kernel.md

@@ -24,7 +24,7 @@ tags: [vue3, kernel, conventions, layout, router, http, crud, inventory]
 | 9 | i18n：`$t('中文key')` |
 | 10 | 禁止用 `v-html` 渲染不可信内容 |
 | 11 | 新依赖须用户确认；已有封装须复用；选型表指定库勿擅自替换 |
-| 12 | 列表布局按 **`crud-pages` 黄金样板**（`el-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内） |
+| 12 | 列表布局按 **`crud-pages` 黄金样板**（`el-card.vts-page-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内；仅表格体内滚动） |
 | 13 | addon 按 `project-inventory` 第九节精确版本安装；禁止 `@latest` |
 | 14 | 样式契约见下文「样式契约」 |
 
@@ -119,6 +119,8 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 
 ### 独立功能页容器
 
+定高且内部滚动（与列表卡同类场景）：
+
 ```vue
 <div
   :style="{ height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)` }"
@@ -126,6 +128,7 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 >
 ```
 
+查询列表定高卡 → `crud-pages`（`el-card.vts-page-card` + `tableHeight`）。
 ## 六、资产分层
 
 附加 Hook/组件按功能模块加载（WebSocket、微信、附件、图表等）→ 见各专项与 `project-inventory`。

package/references/crud-pages.md

@@ -21,20 +21,29 @@ useTableSearch(formQuery, searchFn, url)
 - 查询 / 重置：`onSearch()` / `reset()`
 - 列表：`tableData.value.tableList`
 - 分页请求：`pageNo` / `pageSize`；响应：`data.content` / `data.totalCount`
-- 高度：`tableHeight = content − formRef − paginationRef − otherRef − 50`
+- 高度：`tableHeight` 由 Hook 按「卡片内容区底边 − 表格顶边 − 分页」实测；左右分栏、`--vts-card-padding`、工具栏、`otherRef`（表上方）均自动消化；空数据仍保留表格占位高度。业务页只绑定，不手算魔法数
+
+## 内容区滚动约定
+
+| 场景 | 做法 |
+|------|------|
+| 查询列表（定高） | `el-card.vts-page-card` + 固定 `height: calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`；表格绑 `tableHeight`；**仅表格体内滚动**；分页在表格下方；整页无外层滚动条 |
+| 树 + 表分栏 | 同上；左侧树、右侧表共用定高卡，高度仍走 `useTableSearch` 几何实测 |
+| 长表单 / 详情 / 说明类 | 可用 `minHeight` 同公式；内容超出时由 `.app-main` 内 `el-scrollbar` 滚动 |
+| Card 内边距 | 一律走 `--vts-card-padding`（桥接 `--card-padding`）；换规范只改令牌，列表高度由 Hook 跟随 |
 
 ## 列表黄金样板（唯一完整示例）
 
 | # | 必须 |
 |---|------|
-| L1 | `el-card` + `ref="content"`（禁止挂 `div`） |
+| L1 | `el-card` + `class="vts-page-card"` + `ref="content"`（禁止挂 `div`） |
 | L2 | 固定 `height: calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`（禁止只用 `minHeight`） |
 | L3 | 查询区 `bg-bg_color p-5`；展示区 `ReTableBar class="bg-bg_color"` |
 | L4 | `ReGrid` `:gap="[0,20]"` + cols；表单项 `w-[100%] !mr-0`；`@should-show-collapse` |
 | L5 | 操作列 `<ReGridItem suffix>` |
-| L6 | 表格绑 `tableHeight`；分页在 `ReTableBar` `#default` 内 |
+| L6 | 表格绑 `ref="multipleTableRef"` + `tableHeight`；分页在 `ReTableBar` `#default` 内、表格下方 |
 | L7 | `RePagination`：`:pagination` + `@handle-current-change` / `@handle-size-change` |
-| L8 | 查询条件外模块包一根元素绑 `otherRef` |
+| L8 | 查询与表之间的额外模块包一根元素绑 `otherRef`（须在表格上方，高度计入 `tableTop`） |
 
 ```vue
 <script setup lang="ts">
@@ -112,6 +121,7 @@ function handleSizeChange(size: number) {
   <div>
     <el-card
       ref="content"
+      class="vts-page-card"
       shadow="never"
       :style="{
         height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`,
@@ -312,8 +322,8 @@ async function onSubmit() {
 | 错误 | 正确 |
 |------|------|
 | `handleSearch` / 手写分页 | `onSearch` / `useTableSearch` |
-| `ref="content"` 挂 div / 只用 minHeight | `el-card` + 固定 height |
-| 不绑 `tableHeight` / 分页在卡片外 | 样板 L6/L7 |
+| `ref="content"` 挂 div / 只用 minHeight / 缺 `vts-page-card` | `el-card.vts-page-card` + 固定 height |
+| 不绑 `tableHeight` / 分页在卡片外 / 手写魔法数扣高度 | 样板 L6/L7；高度交给 `useTableSearch` |
 | 额外模块不绑 `otherRef` | L8 |
 | 裸 `router.push` 开详情 | `toDetail`（见 detail-page） |
 | `ReTableOperate :buttons` | `:list` |

package/references/design-system.md

@@ -415,7 +415,8 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 - [ ] 控件高度：input/button 计算高度 = 规范值（24/32/40 或规范预设）
 - [ ] 圆角：input、button、card、dialog 均为规范圆角
 - [ ] 表格：表头底色/文字色/字重符合规范
-- [ ] 卡片内边距：`.el-card__body` = 规范值（AntD 24px），不再是 5px
+- [ ] 卡片内边距：`.el-card__body` = 规范 `--vts-card-padding`（桥接 `--card-padding`）
+- [ ] 定高列表页：`el-card.vts-page-card` + `useTableSearch` 的 `tableHeight`；换 `--card-padding` 后列表仍无外层滚动条、分页完整、仅表格体内滚动
 - [ ] 表单标签：computed font-weight 为规范值（AntD/Semi = 400，非 700）
 - [ ] 弹窗：`--ds-dialog-bg` 为 **主题色轻渐变**（`primary-bg → component-bg`），非写死蓝渐变；`ElMessageBox` 内容区用 `--message-box-content-padding`（比 `el-dialog` body 更紧凑）
 - [ ] 侧栏：深色主题下 DevTools 检查 `.sidebar-container` computed `background` 为 **渐变**（非单色 `#001529`）；激活项块色 = `--primary-6`；Logo 区 = `--sidebar-logo-bg`
@@ -608,6 +609,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 5. `lay-content/index.vue`：`padding-top` 用 `--vts-layout-header-offset*`，禁止写死旧顶栏组合；**禁止**与 `$storage.configure.headerHeight` 双向联动  
 6. `lay-header`：布局/标签页变化须 `nextTick` 重测，且仅在高度变化时写回 `$storage.configure.headerHeight`  
 7. DevTools：顶栏 computed = **当前** `--header-height`；菜单项 = **当前** `--el-menu-item-height`（两者须不同）
+8. 定高列表页：`--card-padding` / `--vts-card-padding` 变更后，抽查一页查询列表——内容区无外层滚动条、分页完整、`tableHeight` 随 padding 变化
 
 #### 7.5.4 EP 菜单变量纪律
 

package/references/layout-theme.md

@@ -320,6 +320,17 @@ src/layout/
 | 重测 | 切换 `layout`、`hideTabs`、`hiddenSideBar` 后 `nextTick` 再测一次（避免布局切换后仍用 localStorage 旧值） |
 | 消费 | 业务页通过 `useApp().headerHeight` 读 `$storage.configure.headerHeight`；`lay-content` 的 `padding-top` 仍用 `--vts-layout-header-offset*`（勿与 storage 双向绑定，避免重测循环） |
 
+### 内容区高度与滚动
+
+| 场景 | 卡片 / 高度 | 滚动落点 |
+|------|-------------|----------|
+| 查询列表 | `el-card.vts-page-card` + 固定 `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`；表格绑 `useTableSearch().tableHeight` | 仅 `el-table` 体内；分页在表格下方 |
+| 树 + 表分栏 | 同上定高卡；左右并排，高度走 Hook 几何实测 | 同查询列表 |
+| 长表单 / 详情 / 说明 | 同公式可用 `minHeight`；不绑 `tableHeight` | `.app-main` 内 `el-scrollbar` |
+| Card 内边距 | `--vts-card-padding` → `--card-padding` | 换规范只改令牌；列表高度由 Hook 实测跟随 |
+
+`.vts-page-card`：`overflow: hidden`，`.el-card__body` 高度 100%。样式在 `element-plus.scss`。
+
 ### 混合布局路由结构
 
 混合模式（mix）左侧栏只展示**一级**菜单，页面组件须挂在 **`children`** 下：

package/references/project-inventory.md

@@ -220,7 +220,7 @@
 | **useApp** | 全局应用状态（布局、字典、登出等） | `baseCodeGet(codeType)`、`filterValue()`、`headerHeight`、`svgLoading` |
 | **useDetail** | 列表→详情：写顶部 tag 并跳转 | `toDetail(name, params, title?, 'query'\|'params')`、`initToDetail(name)`、`getParameter`；路由配 `showLink:false`（不进侧栏）+`activePath`（见 `detail-page`） |
 | **useFormCheck** | 多表单校验聚合 | 追踪各字段校验状态，emit `form-validate` 事件 |
-| **useTableSearch** | 列表页搜索/分页/Loading/动态表高 | `content`（须绑 `el-card`）、`otherRef`（查询条件外模块的统一根元素，高度自动从 `tableHeight` 扣除）、`tableHeight`、`paginationRef`、`tableData`、`pagination`、`loading`、`onSearch()`、`reset()`、`formRef`、`gridRef`、`collapsed` / `showCollapse` / `collapsedToggle` |
+| **useTableSearch** | 列表页搜索/分页/Loading/动态表高 | `content`（须绑 `el-card.vts-page-card`）、`multipleTableRef`（建议绑 `el-table`）、`otherRef`（表上方额外模块）、`tableHeight`（卡片底边 − 表格顶边 − 分页；空数据仍有占位高）、`paginationRef`、`tableData`、`pagination`、`loading`、`onSearch()`、`reset()`、`formRef`、`gridRef`、`collapsed` / `showCollapse` / `collapsedToggle` |
 | **useTags** | 多标签页管理 | 右键菜单（刷新/关闭/关闭其他/全屏） |
 | **useTheme** | 主题切换（暗色/亮色） | 主题色生成、布局预设、缓存重置 |
 | **useWebSocket** | WebSocket 通信 | `subscribe()`、`send()`、`sendRaw()`、`isConnected` |