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

package/package.json

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

package/references/core-kernel.md

@@ -114,8 +114,7 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 | 场景 | 档位 | 像素（令牌） |
 |------|------|--------------|
 | 查询区表单/按钮、工具栏按钮、弹窗内表单 | **default（不写 size）** | `--control-height`（设计 `--component-size-base`，默认 32px） |
-| 表格 / 分页 | `:size="size"`（ReTableBar 透出） | 随密度切换，与表单档位独立 |
-| 表格行内操作、紧凑工具条 | `small` | `--control-height-sm`（24px） |
+| 表格 / 分页 / **行内操作** | `:size="size"`（ReTableBar 透出） | 随密度切换（small / default / large），与表单档位独立 |
 | 登录/整屏主表单主按钮 | `large` | `--control-height-lg`（40px） |
 | 移动端 Vant | 见 `mobile-h5` | — |
 
@@ -125,13 +124,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` 减顶栏定高。
 
 ## 列表标准样板（唯一完整示例）
 
@@ -60,7 +60,7 @@ import { ReGrid } from "@/components/ReGrid";
 import { ReGridItem } from "@/components/ReGridItem";
 import { RePagination } from "@/components/RePagination";
 import { ReTableBar } from "@/components/ReTableBar";
-import { ReTableOperate } from "@/components/ReTableOperate";
+import { ReTableOperate, resolveOperateColumnWidth } from "@/components/ReTableOperate";
 import { useApp } from "@/hooks/useApp";
 import { useTableSearch } from "@/hooks/useTableSearch";
 import { message } from "@/utils/message";
@@ -96,6 +96,8 @@ const {
 
 const tableList = computed(() => tableData.value.tableList as Customer[]);
 
+const operateLimit = 3;
+
 const operateButtons: OperateButton[] = [
   {
     label: $t("删除"),
@@ -216,9 +218,19 @@ function handleSizeChange(size: number) {
             >
               <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">
+              <el-table-column
+                :label="$t('操作')"
+                :width="resolveOperateColumnWidth({ list: operateButtons, limit: operateLimit, size })"
+                fixed="right"
+              >
                 <template #default="{ row, $index }">
-                  <ReTableOperate :list="operateButtons" :row="row" :index="$index" />
+                  <ReTableOperate
+                    :list="operateButtons"
+                    :row="row"
+                    :index="$index"
+                    :limit="operateLimit"
+                    :size="size"
+                  />
                 </template>
               </el-table-column>
             </el-table>
@@ -250,22 +262,63 @@ function handleSizeChange(size: number) {
 | `limit` | 默认 **`3`**：可见按钮总数阈值（含「更多」槽位） |
 | ≤ `limit` | 全部以文字按钮平铺 |
 | > `limit` | 前 **`limit - 1`** 个平铺，其余进 **「更多」** `el-dropdown` |
-| 过滤顺序 | 先 `auth`（`hasAuth`）→ 再 `show(row)` → 再按 `limit` 折叠 |
-| `size` | 组件默认 `small`（行内紧凑）；可按列改 |
+| 过滤顺序 | 先 `auth`（无权限整项剔除）→ 再按 `show(row)` 决定显隐 → 再按 `limit` 折叠 |
+| `size` | **须与表格一致**：传 ReTableBar `#default` 透出的 `size`（`small` \| `default` \| `large`）；组件默认 `default`；槽宽 / 列宽推算须带同一 `size` |
+| 对齐 | **从左排列**，最多 `limit` 项（含「更多」）；`show:false` **不占位**；每个平铺项（含「更多」）**等宽槽**，槽宽默认按 `list` 最长文案自动适配（可用 `slotMinWidth` 覆盖）；「更多」用 **text + 主题色**（禁止 `link` / 单独 `ml-*`） |
+| 列宽 | **禁止写死** `width="220"` 等；用 `resolveOperateColumnWidth({ list: operateButtons, limit })` 与组件同一套规则推算（`limit × 槽宽 + 留白`） |
 
 示例：`limit=3` 且有 5 个可见按钮 → 平铺 2 个 +「更多」（内含后 3 个）。
 
 ```vue
-<!-- 默认折叠阈值 3 -->
-<ReTableOperate :list="operateButtons" :row="row" :index="$index" />
+<script setup lang="ts">
+import { ReTableOperate, resolveOperateColumnWidth } from "@/components/ReTableOperate";
+
+const operateLimit = 3;
+const operateButtons: OperateButton[] = [/* … */];
+</script>
 
-<!-- 需要多露几个时再改，勿低于 2（否则「更多」几乎占满） -->
-<ReTableOperate :list="operateButtons" :row="row" :index="$index" :limit="4" />
+<ReTableBar ...>
+  <template #default="{ size }">
+    <el-table :size="size" ...>
+      <el-table-column
+        :label="$t('操作')"
+        :width="resolveOperateColumnWidth({ list: operateButtons, limit: operateLimit, size })"
+        fixed="right"
+      >
+        <template #default="{ row, $index }">
+          <ReTableOperate
+            :list="operateButtons"
+            :row="row"
+            :index="$index"
+            :limit="operateLimit"
+            :size="size"
+          />
+        </template>
+      </el-table-column>
+    </el-table>
+  </template>
+</ReTableBar>
 ```
 
-`OperateButton` 常用字段：`label`、`type`、`icon`、`auth`、`show`、`disabled`、`onClick`（见组件 `type.ts`）。危险操作用 `type: 'danger'`；权限写 `auth`，勿在列模板里 `v-if` 角色。
+`limit` / `size` 在列宽、组件上**须一致**；`size` 随 ReTableBar 密度切换（宽松 / 默认 / 紧凑），与查询区表单档位独立（见 `core-kernel` 组件尺寸、`design-system` 7.5.8）。
+
+文案特别长时可传 `slotMinWidth`，列宽推算带上同一参数：
+
+```typescript
+resolveOperateColumnWidth({ list: operateButtons, limit: operateLimit, size, slotMinWidth: 96 });
+```
+
+`OperateButton` 常用字段：`label`、`type`、`icon`、`auth`、`show`、`disabled`、`onClick`（见组件 `type.ts`）。危险操作用 `type: 'danger'`；权限写 `auth`，勿在列模板里 `v-if` 角色。**同一列表的 `list` 顺序须固定**（如始终「填报→查看→催办→…」），靠 `show` 控制显隐，勿按行动态改数组顺序。
+
+操作列建议 `fixed="right"`。模版已在 `element-plus.scss` 为含 `.re-table-operate` 的单元格关闭省略号，避免列宽不足时出现 `..`。
 
-操作列 `width`：按钮多时适当加宽（如 160～220），仍依赖 `limit` 折叠，禁止无限加宽硬塞。
+**反例**：
+- 写死 `width="260"` / 不传 `:size="size"` → 与表格密度不一致、切换紧凑/宽松后按钮错位  
+- 列宽 `resolveOperateColumnWidth` 未传 `size` 或与组件 `:size` 不一致 → 推算宽度与实渲染不符  
+- 前置透明占位 / 为隐藏按钮留空 → 左侧大空档  
+- 平铺项按内容宽度自然撑开、无等宽槽 → 「发起修订」等比二字项把「更多」挤偏  
+- 给「更多」写 `ml-2` 或用 `type="primary" link` → 与 text 按钮档位不一致  
+- 按行拼接不同顺序的 `list` → 同名操作无法对应  
 
 ## 列表 → 详情/编辑
 
@@ -377,6 +430,8 @@ 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）进「更多」 |
+| 「更多」单独 `ml-2` / 操作列左对齐导致行间末位错位 | 右对齐 + 统一间距；见上文「对齐」约定 |
 | `@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`。