@qilitt-mickey/vue3-temp-skill 1.1.23 → 1.1.24

package/SKILL.md

@@ -70,7 +70,8 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 | addon / 查 Re* 名 / 装依赖 | `references/project-inventory.md` |
 | **启用精简模板已删的 addon（装包 + 改配置）** | `references/addon-enable.md`（与功能模块同读） |
 | 写完代码后（闸门，非功能命中） | `references/code-quality.md` |
-| 设计交接块 / **design-handoff/v1 JSON** / 上游令牌产出落地 | `references/design-handoff.md`（+ `design-system`） |
+| 设计交接块 / **design-handoff/v1 JSON** / 上游令牌产出落地 | `references/design-handoff.md`（+ `design-system`） |
+| **设计模式**（设计 Skill 产出存在时触发） | `crud-pages.md` 设计模式样板 + `design-system.md` Step 3.5 |
 
 ### 标准业务面
 

package/package.json

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

package/references/code-quality.md

@@ -46,6 +46,20 @@ lint / type-check **过了也不能放过**下列项。发现即改代码，禁
 | 新菜单路由 | 父级无 `icon` 或业务页二次挂 `Layout` | `icons` + `core-kernel` |
 | 列表查询区 `el-form` / 查询按钮 | 写了 `size="small"`（紧凑主题用户未要求） | 不写 size，用 default=`--control-height` |
 | 本轮新增 addon 并引用对应 `Re*` / Vant / 微信 | 已装包但 `tsconfig exclude` 仍含该路径，或 `addon-enable` 要求的 build/src 未改 | 按 **`addon-enable.md`** 对应章节恢复后重跑 type-check |
+| `design-visual.scss` / `design-layout.scss` 存在 | `index.scss` 未 `@use` 加载，或加载顺序不在 `element-plus` 之前 | `design-tokens` → `design-visual` → `design-layout` → `element-plus` |
+| `design-visual.scss` 规则体内出现硬编码值 | 非令牌引用的裸 hex / px / rgba 值 | 全部改为 `var()` 引用令牌 |
+| 视觉层 / 构图层新增规则 | `dark.scss` 缺少对应暗色覆盖 | 每条新规则在 `html.dark` 内有对应覆盖 |
+
+### 设计模式专项检查（设计 Skill 产出存在时）
+
+| 检查项 | 失败条件 | 修复 |
+|--------|---------|------|
+| 列表页页面标题区 | 设计模式下列表页无 `.vts-page-header`（标题+描述+操作） | 按 `crud-pages.md` 设计模式样板 D2 补充 |
+| 列表页筛选区 | 设计模式下仍用 `bg-bg_color p-5` 而非 `.vts-filter-area` | 升级为 `.vts-filter-area` |
+| 列表页表格区 | 设计模式下表格区无 `.vts-table-area` 包裹 | 外包 `.vts-table-area` |
+| 设计模式值引用 | 页面代码中 CSS 钩子类对应的值非令牌引用 | 值来自 `design-tokens.scss` 令牌变量 |
+
+> **放松说明**：设计模式下，允许页面级结构 CSS（`.vts-page-header` 等布局类）。项目 Skill 的禁止项（"禁止另建独立重写层文件"等）在**设计模式**下不适用于页面代码中的布局结构实现，仅对全局样式文件生效。
 
 ## 选型与硬约束
 

package/references/crud-pages.md

@@ -43,7 +43,7 @@ useTableSearch(formQuery, searchFn, url)
 |---|------|
 | L1 | `el-card` + `class="vts-page-card"` + `ref="content"`（禁止挂 `div`） |
 | L2 | 不要写 `height: calc(100vh - …)` / 不要用 JS 测顶栏定高（壳层 + `.vts-page-card` 已填满） |
-| L3 | 查询区 `bg-bg_color p-5`；展示区 `ReTableBar class="bg-bg_color"` |
+| L3 | 查询区 `class="vts-filter-area"`（含容器感+分隔线，等效旧 `bg-bg_color p-5`）；展示区 `ReTableBar` 外包 `.vts-table-area` |
 | L4 | `ReGrid` `:gap="[0,20]"` + cols；表单项 `w-[100%] !mr-0`；`@should-show-collapse` |
 | L5 | 查询区 `<ReGridItem suffix>`（查询 / 重置 / 展开收起） |
 | L6 | 表格绑 `ref="multipleTableRef"` + `tableHeight`；分页在 `ReTableBar` `#default` 内、表格下方 |
@@ -249,7 +249,256 @@ function handleSizeChange(size: number) {
 </template>
 ```
 
-补充：`ReTableOperate` 用 `:list`；`defineOptions.name` === 路由 `name`；`svgLoading` 来自 `useApp()`；列表定高走壳层令牌 + `vts-page-card`。
+补充：`ReTableOperate` 用 `:list`；`defineOptions.name` === 路由 `name`；`svgLoading` 来自 `useApp()`；列表定高走壳层令牌 + `vts-page-card`。
+
+## 列表设计模式样板（设计 Skill 产出存在时使用）
+
+> **触发条件**：存在 `design-handoff/v1` JSON、用户指定设计规范、或命中 `design-system` 模块且设计 Skill 产出可用。
+>
+> **与出厂模式的区别**：出厂模式（上文 L1-L9）直接堆 `el-card` + 查询区 + 表格，无页面标题区。设计模式按设计 Skill 的 `list-page.md` 区域拆分，包含完整的页面标题区、筛选区容器、操作栏、表格区。
+>
+> **结构变化**：
+> - 新增 `.vts-page-header`（标题 + 描述 + 标题区操作按钮）
+> - 查询区从 `bg-bg_color p-5` 升级为 `.vts-filter-area`（有容器感 + 分隔线）
+> - 表格区外包 `.vts-table-area`（有圆角边框包裹）
+> - 主操作按钮（新增/导入）从 `ReTableBar #buttons` 移到 `.vts-page-header__actions`
+
+| # | 必须 |
+|---|------|
+| D1 | `el-card` + `class="vts-page-card"` + `ref="content"`（同 L1） |
+| D2 | `.vts-page-header`：标题 18px 加粗 + 描述 13px tertiary + 右侧操作按钮（新增/导入） |
+| D3 | `.vts-filter-area`：筛选区容器（独立背景 + 圆角 + 底部分隔线） |
+| D4 | `.vts-action-bar`：表格上方操作栏（批量删除等 + 右侧刷新/列设置） |
+| D5 | `.vts-table-area`：表格区包裹（圆角 + 边框） |
+| D6 | 表头：品牌色浅底 + 字重 600 + 底部强调线（由 `design-visual.scss` 全局提供） |
+| D7 | 行 hover：品牌色极浅底 + 过渡（由 `design-visual.scss` 全局提供） |
+| D8 | 其余同 L4-L9（ReGrid / ReTableBar / RePagination / ReTableOperate） |
+
+```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";
+import { ReGridItem } from "@/components/ReGridItem";
+import { RePagination } from "@/components/RePagination";
+import { ReTableBar } from "@/components/ReTableBar";
+import { ReTableOperate, resolveOperateColumnWidth } from "@/components/ReTableOperate";
+import { useApp } from "@/hooks/useApp";
+import { useTableSearch } from "@/hooks/useTableSearch";
+import { message } from "@/utils/message";
+
+defineOptions({ name: "CustomerList" });
+
+const { svgLoading } = useApp();
+const formQuery = reactive<CustomerQuery>({ keyword: "", status: undefined });
+
+const {
+  content,
+  otherRef,
+  tableHeight,
+  paginationRef,
+  loading,
+  formRef,
+  multipleTableRef,
+  pagination,
+  onSearch,
+  tableData,
+  gridRef,
+  showCollapse,
+  collapsed,
+  collapsedToggle,
+  upBold,
+  downBold,
+  reset,
+} = useTableSearch(
+  formQuery,
+  getCustomerList,
+  `${import.meta.env.VITE_API_BASE_URL}/console/customer/list`,
+);
+
+const tableList = computed(() => tableData.value.tableList as Customer[]);
+
+const operateLimit = 3;
+
+const operateButtons: OperateButton[] = [
+  {
+    label: $t("删除"),
+    type: "danger",
+    icon: "i-ep:delete",
+    onClick: (row) => handleDelete(row as Customer),
+  },
+];
+
+onMounted(() => onSearch());
+
+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>
+    <el-card
+      ref="content"
+      class="vts-page-card"
+      shadow="never"
+    >
+      <!-- D2: 页面标题区 -->
+      <div class="vts-page-header">
+        <div class="vts-page-header__info">
+          <span class="vts-page-header__title">{{ $t("客户列表") }}</span>
+          <span class="vts-page-header__desc">{{ $t("管理客户的售价、类型与库存信息") }}</span>
+        </div>
+        <div class="vts-page-header__actions">
+          <el-button
+            type="primary"
+            v-auth="['admin']"
+            @click="handleAdd"
+          >
+            {{ $t("新增") }}
+          </el-button>
+          <el-button v-auth="['admin']">{{ $t("导入") }}</el-button>
+        </div>
+      </div>
+
+      <!-- D3: 筛选区容器 -->
+      <div class="vts-filter-area">
+        <el-form
+          ref="formRef"
+          :inline="true"
+          :model="formQuery"
+        >
+          <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>
+            <ReGridItem suffix>
+              <div class="flex flex-end">
+                <el-button
+                  type="primary"
+                  :loading="loading"
+                  @click="pagination.currentPage = 1; pagination.pageSize = 10; onSearch()"
+                >
+                  {{ $t("查询") }}
+                </el-button>
+                <el-button @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>
+
+      <div ref="otherRef">
+        <!-- 统计/页签等额外模块；无则删除整段 -->
+      </div>
+
+      <!-- D4+D5: 操作栏 + 表格区 -->
+      <div class="vts-table-area">
+        <ReTableBar :columns="[]" @refresh="onSearch">
+          <template #title>
+            <span class="truncate font-size-16 font-bold">{{ $t("展示列表") }}</span>
+          </template>
+          <template #buttons>
+            <el-button type="danger" 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"
+                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="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>
+              <RePagination
+                ref="paginationRef"
+                :size="size"
+                :pagination="pagination"
+                @handle-current-change="handleCurrentChange"
+                @handle-size-change="handleSizeChange"
+              />
+            </div>
+          </template>
+        </ReTableBar>
+      </div>
+    </el-card>
+  </div>
+</template>
+```
+
+**设计模式与出厂模式的关键差异**：
+
+| 差异点 | 出厂模式 | 设计模式 |
+|--------|---------|---------|
+| 页面标题 | 无 | `.vts-page-header` 含标题+描述+操作 |
+| 筛选区 | `bg-bg_color p-5` | `.vts-filter-area`（容器感+分隔线） |
+| 主操作按钮位置 | `ReTableBar #buttons` | `.vts-page-header__actions` |
+| 表格区 | 无包裹 | `.vts-table-area`（圆角边框） |
+| 表头底色 | EP 默认浅灰 | 由 `design-visual.scss` 全局提供品牌色浅底+强调线 |
+| 行 hover | EP 默认灰色 | 由 `design-visual.scss` 全局提供品牌色极浅底 |
 
 ## 操作列按钮过多（ReTableOperate · 强制）
 

package/references/design-handoff.md

@@ -147,6 +147,40 @@ tags: [handoff, design-tokens, upstream, artifacts, json]
 
 细则见 `design-system` 7.5.8。缺档 → 回退至 default（base），回执注明。
 
+### `visual` → 视觉表现令牌（`design-tokens.scss` 视觉段 + `design-visual.scss`）
+
+有 `visual` 字段时写入 `design-tokens.scss` 的「视觉表现令牌」段；`design-visual.scss` 规则结构不动，只通过令牌值变化生效。
+
+| JSON 字段 | CSS 变量 | 用途 |
+|-----------|----------|------|
+| `visual.shadowCardRest` | `--shadow-card-rest` | 卡片静态阴影 |
+| `visual.shadowCardHover` | `--shadow-card-hover` | 卡片悬停阴影 |
+| `visual.shadowButtonHover` | `--shadow-button-hover` | 按钮悬停阴影 |
+| `visual.shadowInputFocus` | `--shadow-input-focus` | 输入框聚焦光环 |
+| `visual.shadowDialog` | `--shadow-dialog` | 弹窗阴影 |
+| `visual.transitionBase` | `--transition-base` | 基础过渡曲线 |
+| `visual.buttonHoverTransform` | `--transform-button-hover` | 按钮 hover 变换 |
+| `visual.tableHeaderBorderBottom` | `--table-header-border-bottom` | 表头强调底线 |
+| `visual.menuActiveBorderRight` | `--menu-active-border-right` | 菜单激活强调条 |
+
+缺项 → 保留出厂默认值，回执标明。
+
+### `layout` → 页面构图令牌（`design-tokens.scss` 构图段 + `design-layout.scss`）
+
+有 `layout` 字段时写入 `design-tokens.scss` 的「页面构图令牌」段；`design-layout.scss` 规则结构不动。
+
+| JSON 字段 | CSS 变量 | 用途 |
+|-----------|----------|------|
+| `layout.pageHeaderMargin` | `--page-header-margin` | 标题区下边距 |
+| `layout.filterAreaRadius` | `--filter-area-radius` | 筛选区圆角 |
+| `layout.filterAreaPaddingY` | `--filter-area-padding-y` | 筛选区上下内边距 |
+| `layout.filterAreaPaddingX` | `--filter-area-padding-x` | 筛选区左右内边距 |
+| `layout.actionBarGap` | `--action-bar-gap` | 操作栏按钮间距 |
+| `layout.tableAreaBorderRadius` | `--table-area-border-radius` | 表格区圆角 |
+| `layout.emptyStatePadding` | `--empty-state-padding` | 空状态间距 |
+
+缺项 → 保留出厂默认值，回执标明。
+
 ### 卡片页签关闭色（设计约束）
 
 - 关闭 hover：圆形底 `--layout-bg`（=`tokens.layoutBg`）+ 图标 `--error-6` / `tokens.error`（`#F5222D`）
@@ -158,11 +192,11 @@ tags: [handoff, design-tokens, upstream, artifacts, json]
 
 | # | 落点 | 写入 |
 |---|------|------|
-| A | `src/styles/design-tokens.scss` | 令牌 CSS；深色侧栏时追加 `--sidebar-*` |
+| A | `src/styles/design-tokens.scss` | 令牌 CSS；深色侧栏时追加 `--sidebar-*`；`visual` / `layout` 段 |
 | B | `theme.scss` 当前 `html[data-theme]` | `--vts-theme-*` → `--sidebar-*` |
 | C | `public/platform-config.json` | `EpThemeColor` / `Theme` / `DarkMode` / **`ShowModel`**；`Version` 自增 |
-| D | `index.scss` | `design-tokens` 的 `@use` 最前；按需 `--vts-margin` / `--vts-tag-card-*` |
-| E | `dark.scss` / 语义色 | 跟 `--primary-*` / `--error-*` |
+| D | `index.scss` | `design-tokens` → `design-visual` → `design-layout` 最先；按需 `--vts-margin` / `--vts-tag-card-*` |
+| E | `dark.scss` / 语义色 | 跟 `--primary-*` / `--error-*`；视觉层+构图层暗色覆盖 |
 | F | 冲突清单 | `design-system` 第四节 |
 | G | 规范识别回执 | 动手改文件前输出 |
 | H | （可选）`design/design-handoff.json` | 若用户要求落盘，写入校验后的 JSON 副本 |

package/references/design-system.md

@@ -355,20 +355,40 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 
 > 各规范差异项：`antd` 表头 `#fafafa` 不加边框分隔；`semi` 少阴影轻描边；`vuetify` 控件高度 Material 化（input 40px、button 36px）；按第五节表微调样板中的数值来源即可，**结构不变**。差异值同样只改令牌数据，不另写选择器。
 
-### Step 4 接线 `src/styles/index.scss`
+### Step 3.5 设计模式页面结构（设计 Skill 产出存在时触发）
 
-```scss
-@use 'design-tokens';     // 唯一新增：纯数据令牌，必须最先
-@use 'theme';
-@use 'transition';
-@use 'button';
-@use 'element-plus';      // 模版默认覆盖 + 规范几何重写（已并入）
-@use 'sidebar';
-@use 'dark';
-@use 'vant';
-```
+> **职责边界**：项目 Skill 只做令牌数值桥接（Step 2）和 EP 几何重写（Step 3）。页面布局结构和视觉表现**不在全局 CSS 文件中注入**，而是在**页面代码中直接实现**，遵循设计 Skill 的布局规范。
+
+触发条件：存在 `design-handoff/v1` JSON、用户指定设计规范、或命中 `design-system` 模块且设计 Skill 产出可用。
+
+模版已出厂自带 `design-visual.scss`（视觉基线）和 `design-layout.scss`（构图基线），提供默认的 CSS 钩子类。设计模式下：
+
+1. **令牌值桥接**（Step 2 已完成）：颜色 / 阴影 / 圆角 / 间距 / 字号数值写入 `design-tokens.scss`
+2. **页面结构按设计 Skill 布局规范生成**：
+   - 列表页 → 读设计 Skill 的 `list-page.md` 区域拆分，在页面代码中使用 `.vts-page-header` / `.vts-filter-area` / `.vts-action-bar` / `.vts-table-area` 结构类
+   - 详情页 → 读设计 Skill 的详情页规范，使用 `.vts-detail-container`
+   - 框架壳层 → 读设计 Skill 的 `unified-framework.md`，顶栏 / 侧栏 / 页签 / 内容区的几何和视觉按规范实现
+3. **组件视觉表现**：`design-visual.scss` 提供全局基线（hover/阴影/过渡），页面内无需重复写
+4. **设计 Skill 布局决策的直接实现**：如设计 Skill 规定顶部导航语言切换为内联文字（中/EN）而非下拉框，则在 `lay-navbar` 组件中直接实现该交互，不通过 CSS 覆盖
+
+**关键原则**：设计 Skill 的布局和视觉决策在**页面代码**中实现，不通过全局 CSS 文件注入。项目 Skill 的职责是提供令牌数值和 CSS 钩子类，让页面代码有标准化的引用点。
+
+### Step 4 接线 `src/styles/index.scss`
 
-唯一顺序要求：`design-tokens` 放最前（供后续文件引用）。几何重写已并入 `element-plus.scss`，**不再存在**“重写层必须排在覆盖层之后”的顺序陷阱；模版其余 `@use` 顺序保持不动。
+```scss
+@use 'design-tokens';     // 唯一新增：纯数据令牌，必须最先
+@use 'design-visual';     // 视觉表现层：shadow / hover / transition / 交互态
+@use 'design-layout';     // 页面构图层：区域容器 / 间距节奏
+@use 'theme';
+@use 'transition';
+@use 'button';
+@use 'element-plus';      // 模版默认覆盖 + 规范几何重写（已并入）
+@use 'sidebar';
+@use 'dark';
+@use 'vant';
+```
+
+唯一顺序要求：`design-tokens` 放最前（供后续文件引用）；`design-visual` 和 `design-layout` 紧随其后，在 `element-plus` 之前，确保视觉层在 EP 几何层之前加载。几何重写已并入 `element-plus.scss`，**不再存在**"重写层必须排在覆盖层之后"的顺序陷阱；模版其余 `@use` 顺序保持不动。
 
 **字体接管**：
 - 新模版：`index.scss` 已是 `font-family: var(--font-family, ...) !important`，令牌层定义 `--font-family` 即自动生效，无需改动。
@@ -436,7 +456,11 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 - [ ] 弹窗：`--ds-dialog-bg` 为 **主题色轻渐变**（`primary-bg → component-bg`），非写死蓝渐变；`ElMessageBox` 内容区用 `--message-box-content-padding`（比 `el-dialog` body 更紧凑）
 - [ ] 侧栏：深色主题下 DevTools 检查 `.sidebar-container` computed `background` 为 **`#001529`**（`var(--sidebar-bg)`，非旧版主色纵向渐变）；激活项块色 = `--primary-color` / `brandPrimary`；Logo 区 = `--sidebar-logo-bg`
 - [ ] 第四节冲突清单全部处理完毕（逐条回填）
-- [ ] Step 7 存量扫描已执行且结果已输出
+- [ ] Step 7 存量扫描已执行且结果已输出
+- [ ] 设计模式页面结构（设计 Skill 产出存在时）：列表页含 `.vts-page-header`（标题+描述+操作）、`.vts-filter-area`（筛选区容器）、`.vts-table-area`（表格区）
+- [ ] 视觉基线：`design-visual.scss` 和 `design-layout.scss` 在 `index.scss` 中已加载且顺序在 `element-plus` 之前
+- [ ] 暗色覆盖：视觉层和构图层在 `dark.scss` 中有对应暗色覆盖
+- [ ] 令牌无硬编码：页面代码中引用的 CSS 钩子类值全部来自令牌变量
 
 ---