@qilitt-mickey/vue3-temp-skill 1.1.2 → 1.1.4

package/README.md

@@ -6,9 +6,10 @@ Vue 3 企业级中后台项目开发规范技能包 — 让 AI 按团队规范
 
 外置 AI Skill：`/vue3-temp-skill <需求>` → 自动命中模块 → 按项目约定生成 → 自查。
 
-**设计要点（v1.1）**：
+**设计要点**：
 
-- **始终加载** `core-kernel` + `project-inventory` + `code-quality`
+- **始终加载** `core-kernel` + `project-inventory`（生成前）
+- **生成后强制闸门** `code-quality`：重读清单 → 对照落盘文件 → `pnpm type-check` → 最终回复必须含「代码质量审查」结果块（仅列入命中模块不算完成）
 - **Vite / 脚本 / 入口不单独成 Skill**（工程摘要在 core-kernel）
 - **组件 / Hook 分核心与附加**，专项能力按需命中
 - 按 `references/` 内完整示例编写；复用已有封装；选型表指定库勿擅自替换（新依赖须待确认）
@@ -30,13 +31,18 @@ Vue 3 企业级中后台项目开发规范技能包 — 让 AI 按团队规范
 
 ## 模块一览
 
-### 始终加载
+### 始终加载（生成前）
 
 | 模块 | 覆盖 |
 |------|------|
 | core-kernel | 硬约束、壳、CRUD 积木、工程摘要 |
 | project-inventory | 库精确版本 / 组件 / Hook / 选型对照 / **第九节安装表** |
-| code-quality | 生成后审查 |
+
+### 生成后强制闸门
+
+| 模块 | 覆盖 |
+|------|------|
+| code-quality | 清单自查 + `pnpm type-check` + 最终回复「代码质量审查」结果块 |
 
 ### 标准业务面
 
@@ -85,11 +91,12 @@ npx @qilitt-mickey/vue3-temp-skill@latest install all
 
 ## 生成工作流（AI）
 
-1. 解析需求 → 命中路由表  
-2. 读 core-kernel + inventory + code-quality  
+1. 解析需求 → 命中**功能**路由表  
+2. 读 core-kernel + inventory（生成前）  
 3. **addon**：查业务 `package.json`，缺失则按 inventory 第九节精确版本征得确认后 `pnpm add`（含 `-D` 插件）  
-4. 读功能模块；仓库有实现则对齐，用 Skill 示例  
-5. 生成 → 审查 → 修正输出  
+4. 读功能模块；仓库有 Re*/Hook/utils 则复用，页面写法用 Skill 示例  
+5. 生成落盘  
+6. **强制闸门 code-quality**：重读清单 → 自查刚改文件 → `pnpm type-check` → 修正 → 最终回复输出「代码质量审查」结果块（缺块 = 未完成）  
 
 ## 源码位置
 

package/SKILL.md

@@ -8,11 +8,12 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 # Vue 3 项目开发规范技能包
 
 > 用户通过 `/vue3-temp-skill` + 自然语言描述需求，AI 应当：
-> 1. 分析需求，按下方**模块路由表**命中模块（可多模块）
-> 2. **始终加载** `core-kernel` + `code-quality`（含资产索引）
+> 1. 分析需求，按下方**模块路由表**命中功能模块（可多模块）
+> 2. **始终加载** `core-kernel` + `project-inventory`（生成前必读）
 > 3. 加载命中的功能模块详细规范（`references/`）
 > 4. **以本 Skill 内示例为准编写代码**（复用已有封装；选型表指定的库勿擅自替换）
-> 5. 生成完毕后执行质量审查；有问题就地修正
+> 5. **生成完成后强制执行 `code-quality` 闸门**（见工作流第 6 步）：重读清单 → 对照刚改文件自查 → 跑 `pnpm type-check` → 不通过就地修正 → 最终回复必须含「代码质量审查」结果块  
+> ⚠️ 仅在「命中模块」里写出 `code-quality` **不算**执行审查；没有审查结果块 = 任务未完成
 
 ---
 
@@ -39,7 +40,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`。  
    - 已装齐 → 直接写代码  
@@ -50,13 +52,20 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 
 ## 模块路由表（AI 内部匹配用）
 
-### 始终加载（无需关键词）
+### 始终加载（生成前必读）
 
 | 模块 | 文件 | 职责 |
 |------|------|------|
 | **core-kernel** | `references/core-kernel.md` | 硬约束、应用壳、CRUD 积木、工程摘要、资产分层 |
-| **code-quality** | `references/code-quality.md` | 生成后审查清单 |
-| **project-inventory** | `references/project-inventory.md` | 库/组件/Hook/工具/选型对照（随 core 一并查阅） |
+| **project-inventory** | `references/project-inventory.md` | 库/组件/Hook/工具/选型对照 |
+
+### 生成后强制闸门（不是「命中模块」，写完代码后必须单独执行）
+
+| 模块 | 文件 | 职责 |
+|------|------|------|
+| **code-quality** | `references/code-quality.md` | **写完/改完代码之后**再执行：对照清单自查 + `pnpm type-check` + 输出审查结果块；失败则修正后重跑 |
+
+> `code-quality` **不要**只放进「命中模块」列表交差。它是闸门：生成前可预览清单，但**正式审查必须在落盘之后**，并在最终回复中可见。
 
 ### 标准业务面（按需）
 
@@ -103,8 +112,8 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 
 ### 匹配规则
 
-1. 单模块清晰 → 该模块 + 始终加载三件套。  
-2. 多模块组合 → 同时加载（例：带权限客户列表 = `crud-pages` + `permission-auth` + `http-api`）。  
+1. 单模块清晰 → 该模块 + 始终加载（core-kernel + project-inventory）；结束后跑 code-quality 闸门。  
+2. 多模块组合 → 同时加载功能模块（例：带权限客户列表 = `crud-pages` + `permission-auth` + `http-api`），结束后同样强制 code-quality。  
 3. 兜底 → 仅始终加载，并询问是否专项能力。  
 4. 业务开发默认**不**改 `vite.config.ts` / `build/**`；仅当用户明确要求改构建时，参考 `core-kernel` 工程摘要后再动。  
 5. **按用户说的效果匹配**（不要求用户懂代码/指令名）：  
@@ -173,7 +182,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(); // 查询
@@ -182,6 +191,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` 内，避免无数据时贴查询区
 
 ### 路由
 
@@ -200,12 +213,13 @@ reset();    // 重置（配合 formRef.resetFields）
 
 ### 1. 需求分析
 
-提取字段、查询、交互；按路由表列出模块 ID。
+提取字段、查询、交互；按路由表列出**功能**模块 ID（不含把 `code-quality` 当功能命中）。
 
-### 2. 加载规范
+### 2. 加载规范（生成前）
 
-- 必读：`core-kernel.md`、`project-inventory.md`、`code-quality.md`
+- 必读：`core-kernel.md`、`project-inventory.md`
 - 加读：命中的功能模块 md
+- 可顺带浏览 `code-quality.md` 约束，但**不能替代**第 6 步正式审查
 
 ### 3. 依赖与插件探查（命中 addon 时必做）
 
@@ -221,15 +235,40 @@ reset();    // 重置（配合 formRef.resetFields）
 
 ### 5. 生成代码
 
-完整可运行：类型、API、页面、路由片段（如需要）、样式约定。
+完整可运行：类型、API、页面、路由片段（如需要）、样式约定。  
+**本步结束后不得直接结束对话**，必须进入第 6 步。
+
+### 6. 自动质量审查闸门（强制 · 生成后）
 
-### 6. 自动质量审查（必须）
+> 目标：杜绝「命中了 code-quality 但没真正审查」的假完成。
 
-见下方清单；不通过则修正后再输出。
+按顺序执行（缺一不可）：
+
+1. **重读** `references/code-quality.md`（生成后再读一次，不要只靠记忆）。
+2. **对照刚写入/修改的文件**逐项过清单（尤其：选型、HTTP/`Result`、列表布局、权限、无多余 console）。
+3. **跑命令**（在业务项目根目录）：优先 `pnpm type-check`；若项目有 `pnpm lint` 且改动含 `.vue/.ts`，尽量一并跑。失败则修代码后重跑，直到通过或明确阻塞原因。
+4. **就地修正**：审查发现的问题必须改完再进入第 7 步；禁止带着已知规范问题收工。
+5. **写入最终回复的「代码质量审查」结果块**（格式见下）；无此块视为任务未完成。
+
+#### 最终回复必含结构
+
+```markdown
+## 命中模块
+- <功能模块…>（勿把 code-quality 仅列在此处代替审查）
+
+## 代码质量审查
+- 闸门：已执行 code-quality（生成后）
+- 清单：选型 / 类型 / 组件 / API / 安全 / 业务 / 列表布局(如适用) / 风格 → 通过 | 已修正：…
+- 命令：`pnpm type-check` → 通过 | 失败原因…
+- 待确认：…
+
+## 变更说明
+- …
+```
 
 ### 7. 输出
 
-说明命中了哪些模块；列出待确认项（接口路径、字段类型、是否允许新依赖 / 是否已安装 addon）。
+在完成第 6 步结果块之后，再说明变更与待确认项（接口路径、字段类型、是否允许新依赖 / 是否已安装 addon）。
 
 ---
 
@@ -247,6 +286,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.2",
+  "version": "1.1.4",
   "description": "Vue 3 企业级中后台项目开发规范技能包 — core-kernel 架构、按需功能模块",
   "bin": {
     "vue3-temp-skill": "./bin/cli.js"

package/references/code-quality.md

@@ -1,14 +1,37 @@
 ---
 skill: code-quality
-description: AI 生成代码的质量审查清单。在生成或修改任何 Vue/TypeScript 代码后，必须对照此清单逐项自查，确保代码符合项目规范。适用于代码审查、AI 代码自检、Code Review 场景。
+description: 生成后强制质量闸门。写完/改完 Vue/TS 代码后必须重读本清单、对照落盘文件自查、跑 type-check，并在最终回复输出「代码质量审查」结果块。仅把本模块列入命中模块不算完成。
 scope: project
-tags: [code-review, quality, checklist, lint, typescript, vue3, security, performance]
+tags: [code-review, quality, checklist, lint, typescript, vue3, security, performance, gate]
 ---
 
-# 代码质量审查清单
+# 代码质量审查清单（生成后强制闸门）
+
+> **何时执行**：任意 `/vue3-temp-skill` 任务在**文件已写入或修改之后**，结束对话前必须执行本闸门。  
+> **不算完成**：只在「命中模块」里写 `code-quality`；或只跑了 type-check 却未对照本清单；或最终回复无「代码质量审查」结果块。  
+> **须按** Skill 功能模块示例 + 本清单审查；不通过必须修正后再收工。
+
+## 强制执行协议（AI 必须按序做）
+
+1. **重读本文件**（生成后再读，禁止仅凭开场记忆勾选）。
+2. **列出本轮改动文件路径**，逐文件对照下方清单相关项。
+3. **执行命令**（业务项目根目录）：
+   - 必跑：`pnpm type-check`（若无该脚本则用 `pnpm exec vue-tsc --noEmit`）
+   - 建议：`pnpm lint`（存在且改动含 `.vue/.ts/.tsx` 时）
+4. **失败则修代码 → 重跑命令**，直到通过或写出明确阻塞（缺依赖、环境等）。
+5. **在最终回复追加结果块**（缺此块 = 未完成）：
+
+```markdown
+## 代码质量审查
+- 闸门：已执行 code-quality（生成后）
+- 改动文件：`path/a`、`path/b`、…
+- 清单：选型 ✅ / 类型 ✅ / 组件 ✅ / API ✅ / 安全 ✅ / 业务 ✅ / 列表布局 ✅或N/A / 风格 ✅
+- 已修正：…（无则写「无」）
+- 命令：`pnpm type-check` → 通过 | 失败：…
+- 待确认：…
+```
 
-> **使用说明**：生成或修改代码后逐项对照。不通过必须修正后再输出。  
-> 须按 Skill 模块内示例与本清单审查。
+---
 
 ## 〇、项目选型（最高优先级）
 
@@ -22,6 +45,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 +250,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`）。
+
 ## 八、代码风格检查
 
 ### 必须通过
@@ -240,25 +276,23 @@ const fullName = computed(() => `${user.firstName} ${user.lastName}`);
 
 ## 审查流程
 
-1. **生成代码后**：逐项对照以上清单。
-2. **发现问题**：立即修正，不要输出有问题的代码。
-3. **不确定项**：标注 `// TODO: 需要确认` 注释提醒开发者。
-4. **严重问题**：如果存在安全漏洞或类型错误，必须修正后再输出。
+1. **生成/改码落盘之后**（不是生成前）：执行上方「强制执行协议」。
+2. **发现问题**：立即修正并重跑 `pnpm type-check`，不要带着已知问题收工。
+3. **不确定项**：写入结果块「待确认」，必要时在代码加 `// TODO: 需要确认`。
+4. **严重问题**（安全 / 类型错误 / 列表布局硬约束违反）：必须修正后再输出最终回复。
+5. **最终回复**：必须含「代码质量审查」结果块；禁止只用「命中模块含 code-quality」代替。
 
 ## 快速自检命令
 
 完成代码修改后，运行以下命令验证：
 
 ```bash
-# TypeScript 类型检查
-npx vue-tsc --noEmit
+# 必跑：TypeScript 类型检查（优先用项目脚本）
+pnpm type-check
 
-# ESLint 检查
-npx eslint src/ --ext .vue,.ts,.tsx
-
-# Stylelint 检查
-npx stylelint "src/**/*.{css,scss,vue}"
-
-# 全量检查（推荐）
+# 建议：全量检查
 pnpm lint
+
+# 无 type-check 脚本时的回退
+pnpm exec vue-tsc --noEmit
 ```

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` 必须按样板绑定，否则动态高度失效。
 
 ---
 

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/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` |