@qilitt-mickey/vue3-temp-skill 1.1.20 → 1.1.21

package/package.json

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

package/references/core-kernel.md

@@ -125,13 +125,25 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 
 ### 独立功能页容器
 
-定高且内部滚动（与列表卡同类场景）——优先 `el-card.vts-page-card`；非 Card 根节点用 `vts-page-fill`：
+页面容器分两类，**禁止混用**：
+
+| 场景 | 根节点 | 滚动落点 |
+|------|--------|----------|
+| 查询列表 | `el-card.vts-page-card` | 仅表格体内（`tableHeight`） |
+| 长表单 / 详情 / 说明 | `bg-bg_color p-5` + `min-height: 100%` | `.app-main` 内 `el-scrollbar` |
+| 定高画布（地图 / 流程图 / 大屏） | `vts-page-fill` + `h-full` + `overflow-hidden` | **页面内部**自管滚动 |
 
 ```vue
+<!-- ✅ 详情 / 长表单（默认） -->
+<div class="bg-bg_color p-5" :style="{ minHeight: '100%' }">
+
+<!-- ✅ 定高画布（仅地图/流程图/大屏等） -->
 <div class="vts-page-fill h-full pos-relative bg-bg_color p-5 overflow-hidden">
+
+<!-- ❌ 详情页禁止 vts-page-fill / h-full / overflow-hidden（会裁切且外层滚不动） -->
 ```
 
-查询列表定高卡 → `crud-pages`（`el-card.vts-page-card` + `tableHeight`，禁止 `100vh` 减顶栏定高）。
+查询列表定高卡 → `crud-pages`；详情容器与三件套 → `detail-page`。
 ## 六、资产分层
 
 附加 Hook/组件按功能模块加载（WebSocket、微信、附件、图表等）→ 见各专项与 `project-inventory`。

package/references/crud-pages.md

@@ -31,11 +31,11 @@ useTableSearch(formQuery, searchFn, url)
 |------|------|
 | 查询列表（定高） | `el-card.vts-page-card`（禁止 `100vh` 减顶栏定高）；表格绑 `tableHeight`；仅表格体内滚动；分页在表格下方；整页无外层滚动条 |
 | 树 + 表分栏 | 同上；左侧树、右侧表共用定高卡，高度仍走 `useTableSearch` 几何实测 |
-| 长表单 / 详情 / 说明类 | 根节点 `min-height: 100%`（或 `:style="{ minHeight: '100%' }"`）；超出由 `.app-main` 内 `el-scrollbar` 滚动 |
-| 非 Card 整页填满 | 根节点加 `class="vts-page-fill"` + `height: 100%` / `h-full` |
+| 长表单 / 详情 / 说明类 | 根节点 `min-height: 100%`（或 `:style="{ minHeight: '100%' }"`）；**禁止** `vts-page-fill` / `h-full` / `overflow-hidden`；超出由 `.app-main` 内 `el-scrollbar` 滚动 |
+| 非 Card 整页填满（地图/流程图/大屏） | 根节点加 `class="vts-page-fill"` + `height: 100%` / `h-full`；**仅此类定高场景** |
 | Card 内边距 | 一律走 `--vts-card-padding`（桥接 `--card-padding`）；换规范 / `--vts-margin` 变化由壳层 flex 链 + Hook 自动跟随 |
 
-> **壳层原理**（`lay-content`）：`.main-content` 用 `padding: var(--vts-margin)`（不用 margin）；定高页 `.main-content:has(.vts-page-card)` / `.vts-page-fill` 为 `height: 100%`；`.vts-page-card` 填满。`html/body/#app/.app-wrapper/.main-container/.app-main` 均为 `height:100%; overflow:hidden`。禁止业务页 `100vh` 减顶栏定高。
+> **壳层原理**（`lay-content`）：`.main-content` 用 `padding: var(--vts-margin)`（不用 margin）；默认可滚动页 `el-scrollbar__view` / `.grow` 为 `min-height:100%; height:auto`；定高页 `.main-content:has(.vts-page-card|.vts-page-fill)` 为 `height: 100%` 并收回祖先链；`.vts-page-card` 填满。`html/body/#app/.app-wrapper/.main-container/.app-main` 均为 `height:100%; overflow:hidden`。禁止业务页 `100vh` 减顶栏定高。
 
 ## 列表标准样板（唯一完整示例）
 
@@ -377,6 +377,7 @@ async function onSubmit() {
 | 额外模块不绑 `otherRef` | L8 |
 | 只写 `toDetail`、详情路由缺 `activePath` | 三件套整段落盘（见 detail-page） |
 | 裸 `router.push` 开详情 | `toDetail` + meta（见 detail-page） |
+| 详情根节点 `vts-page-fill` / `h-full` / `overflow-hidden` | `min-height: 100%` + `bg-bg_color`；滚动交给壳层 `el-scrollbar`（见 detail-page ④） |
 | `ReTableOperate :buttons` | `:list` |
 | 操作列手写多颗 `el-button` / 自造更多菜单 | `ReTableOperate`；过多靠 `limit`（默认 3）进「更多」 |
 | `@show-collapse` | `@should-show-collapse` |

package/references/detail-page.md

@@ -58,6 +58,31 @@ const { id, mark } = getParameter as DetailParameter;
 </script>
 ```
 
+### ④ 详情页容器（滚动约定）
+
+详情 / 编辑 / 查看页是**长内容页**，滚动交给壳层 `.app-main` 内 `el-scrollbar`。**禁止**根节点使用 `vts-page-fill` / `h-full` / `overflow-hidden`（那是定高画布专用）。
+
+```vue
+<template>
+  <div
+    v-loading.lock="pageLoading"
+    class="bg-bg_color p-5"
+    :style="{ minHeight: '100%' }"
+  >
+    <ReHeaderPage />
+    <!-- 表单 / 描述 / 版本记录等 -->
+  </div>
+</template>
+```
+
+| 禁止 | 原因 |
+|------|------|
+| `class="vts-page-fill"` | 触发定高链，内容被裁切、外层滚不动 |
+| `h-full` + `overflow-hidden` | 把超出内容锁死在视口内 |
+| `el-card.vts-page-card` 包整页长表单 | 列表定高卡专用；详情走外层滚动 |
+
+完整布局原理见 `layout-theme`「内容区高度与滚动」；列表页见 `crud-pages`。
+
 ## 概念
 
 | 能力 | 字段 / API | 谁负责 |
@@ -91,3 +116,4 @@ toDetail(name, parameter, title?, model = "query") // model: "query" | "params"
 2. `showLink: false` + `activePath` + 非空 `title` + 默认 `keepAlive`/`moreTags`
 3. 列表只用 `toDetail`，禁止裸 `router.push`
 4. 详情页必调 `initToDetail`；`name` 对齐；参数用 `getParameter`
+5. 详情根容器：`min-height: 100%` + `bg-bg_color`；**禁止** `vts-page-fill` / `h-full` / `overflow-hidden`

package/references/layout-theme.md

@@ -367,8 +367,8 @@ $sideBarWidth: var(--sidebar-width, 208px);
 |------|-------------|----------|
 | 查询列表 | `el-card.vts-page-card`（无 inline `100vh`）；表格绑 `useTableSearch().tableHeight` | 仅 `el-table` 体内；分页在表格下方 |
 | 树 + 表分栏 | 同上定高卡；左右并排，高度走 Hook 几何实测 | 同查询列表 |
-| 非 Card 整页填满 | 根节点 `class="vts-page-fill"` + `height: 100%` / `h-full` | 内部区域自管滚动 |
-| 长表单 / 详情 / 说明 | `min-height: 100%`；不绑 `tableHeight` | `.app-main` 内 `el-scrollbar` |
+| 非 Card 整页填满 | 根节点 `class="vts-page-fill"` + `height: 100%` / `h-full` | 内部区域自管滚动；**仅地图/流程图/大屏** |
+| 长表单 / 详情 / 说明 | `min-height: 100%`；**禁止** `vts-page-fill` / `h-full` / `overflow-hidden`；不绑 `tableHeight` | `.app-main` 内 `el-scrollbar` |
 | Card 内边距 | `--vts-card-padding` → `--card-padding` | 换规范 / `--vts-margin` 只改令牌；列表高度由壳层 + Hook 跟随 |
 
 `.vts-page-card`：flex 填满 `.main-content:has(.vts-page-card)`，`overflow: hidden`，`.el-card__body` 高度 100%。样式在 `element-plus.scss` + `lay-content`。