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

package/SKILL.md

@@ -29,7 +29,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 - **精简出厂**：模板 `views/` 仅保留登录/首页等壳页面；**业务标准样板**在本包 `references/`（如 `crud-pages`、`detail-page`）
 - **依赖分层**：`package.json` 仅 **core**；**addon** 默认不装；缺包时装依赖后须按 `addon-enable.md` **逐文件恢复配置**（非自动）
 - 壳层行为（顶部 tag / 侧栏 / keep-alive / `useDetail`）以**当前项目**已有实现为准
-- **双轨**：无设计 handoff → 保持模版出厂；有设计落地 → 读 `design-handoff.md` **原子步骤**（`Theme`/`Version`/令牌整组，禁止只改主色）
+- **双轨**：无设计 handoff → 保持模版出厂；有设计落地 → 读 `design-handoff.md` 逐文件修改清单 + 设计 Skill `project-implementation-protocol.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.md`（项目设计系统说明） |
+| **设计模式**（设计 Skill 产出存在时触发） | `crud-pages.md` 设计模式样板 + 设计 Skill `project-implementation-protocol.md`（1:1 还原协议） |
 
 ### 标准业务面
 
@@ -82,7 +83,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 | **data-writeback** | 回显、回填、useFormCheck |
 | **permission-auth** | 权限、v-auth、roles、ReAuth |
 | **layout-theme** | 布局、主题、暗黑、`--vts-*`、UnoCSS |
-| **design-system** | 设计规范、UI 规范、按 XX 规范适配、design-tokens、主题色系、设计交接块 |
+| **design-system** | 设计规范、UI 规范、按 XX 规范适配、design-tokens、主题色系、令牌体系、暗色模式 |
 | **icons** | 图标、svg-icon、Iconify、ReIconPicker、菜单图标 |
 | **feedback-loading** | message、loading、确认框 |
 | **base-code-dict** | 字典、baseCode、码表 |
@@ -132,7 +133,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
    - 导出 Excel → `download-export`
    - 菜单/本地图标 → `icons`
    - 粒子背景 → `particles`
-   - 按 XX / UI 规范适配、设计交接块、整站风格重构 → `design-system` + `layout-theme`；有令牌/交接产出时加读 `design-handoff.md`
+   - 按 XX / UI 规范适配、设计交接块、整站风格重构 → `design-system`（项目设计系统说明）+ `layout-theme`；有令牌/交接产出时加读 `design-handoff.md`（逐文件修改清单）+ 设计 Skill `project-implementation-protocol.md`
    - 列表→独立详情/编辑页 → `crud-pages` + `detail-page`
 6. 独立详情路由：跳转与 meta 见 `detail-page`（`toDetail` / `showLink` / `activePath` / `initToDetail`）
 
@@ -147,7 +148,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 ## 工作流
 
 1. **需求分析**：列出功能模块 ID（不含 `code-quality`）
-2. **加载**：`core-kernel` + 命中模块；addon/缺包时加读 `project-inventory` + **`addon-enable`**；设计规范/交接产出时加读 `design-handoff`
+2. **加载**：`core-kernel` + 命中模块；addon/缺包时加读 `project-inventory` + **`addon-enable`**；设计规范/交接产出时加读 `design-handoff`（逐文件修改清单）+ 设计 Skill `project-implementation-protocol.md`
 3. **依赖**：缺包按 inventory 第九节精确版本，确认后安装；**再按 `addon-enable` 对应章节改配置**
 4. **探查**：复用仓库 `Re*` / Hook / utils
 5. **生成**：可运行代码落盘

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qilitt-mickey/vue3-temp-skill",
-  "version": "1.1.23",
+  "version": "1.1.25",
   "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 |
+| `element-plus.scss` 内视觉规则（shadow/hover/transition） | 出现非令牌引用的裸 hex / px / rgba 值 | 全部改为 `var()` 引用令牌 |
+| 视觉规则新增 | `dark.scss` 缺少对应暗色覆盖 | 每条新规则在 `html.dark` 内有对应覆盖 |
+
+### 设计模式专项检查（设计 Skill 产出存在时）
+
+设计还原的完整检查清单见设计 Skill 的 `project-implementation-protocol.md`。本闸门只检查项目侧落地结果：
+
+| 检查项 | 失败条件 | 修复 |
+|--------|---------|------|
+| 页面区域结构 | JSON `structureRequirements.pageRegions` 指定的区域在页面中缺失 | 按 `crud-pages.md` 设计模式样板 D1-D8 补充 |
+| 框架壳层 | JSON `structureRequirements.frameworkShell` 指定的壳层配置未落地 | 按 `design-handoff.md` 配置文件修改清单 C1-C8 执行 |
+| 交互行为 | JSON `interactionSpecs` 指定的交互未实现 | 按 `project-implementation-protocol.md` 交互保真要求实现 |
+| 令牌引用 | 页面代码中 CSS 钩子类对应的值非令牌引用 | 值来自 `design-tokens.scss` 令牌变量 |
+| 逐文件修改清单 | `design-handoff.md` 清单中有未执行项 | 补齐遗漏项 |
 
 ## 选型与硬约束
 
@@ -101,12 +115,11 @@ lint / type-check **过了也不能放过**下列项。发现即改代码，禁
 
 ### design-system（命中时）
 
-- [ ] 规范识别回执；令牌 / `platform-config.json` / 侧栏主题一致
-- [ ] 已建 `design-tokens.scss`；`index.scss` 中其 `@use` 最前
-- [ ] 冲突清单已逐条处理（见 `design-system`）
-- [ ] 有上游设计产出时已读 `design-handoff`：JSON 优先；**原子步骤**含 `Theme=default`（深色侧栏）+ `--sidebar-*` + **`Version++`** + 主色阶；禁止只改 EpThemeColor；错误色 `#F5222D`
+- [ ] 有设计 Skill 产出时已读 `design-handoff.md` 逐文件修改清单并执行
+- [ ] 设计还原检查对照设计 Skill 的 `project-implementation-protocol.md` 检查清单
+- [ ] 令牌 / `platform-config.json` / 侧栏主题三处一致
 - [ ] **无**设计落地时未改出厂主色 / ShowModel / 壳层 / 弹窗几何默认
-- [ ] 组件尺寸三档已落地并桥接 `--el-component-size*`；缺档回退至 default；未全局强制 `size="small"`；**查询区不写 size**（三档对照表 ≠ 查询区要用 small）
+- [ ] 组件尺寸三档已落地并桥接 `--el-component-size*`；缺档回退至 default；查询区不写 size
 
 ## 业务
 

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,260 @@ 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（含 `structureRequirements` + `pageStructure` 段）、用户指定设计规范、或命中 `design-system` 模块且设计 Skill 产出可用。
+>
+> **1:1 还原要求**：页面区域结构必须按 JSON `structureRequirements.pageRegions` 实现，框架壳层按 `structureRequirements.frameworkShell` 实现。详见设计 Skill 的 `project-implementation-protocol.md`。
+>
+> **与出厂模式的区别**：出厂模式（上文 L1-L9）直接堆 `el-card` + 查询区 + 表格，无页面标题区。设计模式按 JSON `pageStructure` 区域拆分，包含完整的页面标题区、筛选区容器、操作栏、表格区。
+>
+> **结构变化**（以 JSON `structureRequirements.pageRegions` 为准，下方为默认区域）：
+> - 新增 `.vts-page-header`（标题 + 描述 + 标题区操作按钮）— 对应 JSON `pageStructure.regions.header`
+> - 查询区从 `bg-bg_color p-5` 升级为 `.vts-filter-area`（有容器感 + 分隔线）— 对应 `pageStructure.regions.filter`
+> - 表格区外包 `.vts-table-area`（有圆角边框包裹）— 对应 `pageStructure.regions.table`
+> - 主操作按钮（新增/导入）从 `ReTableBar #buttons` 移到 `.vts-page-header__actions`
+> - 若 JSON 指定额外区域（如统计区、页签切换区），按 `pageStructure.regions` 顺序在 `otherRef` 位或独立区域中实现
+
+| # | 必须 |
+|---|------|
+| 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 + 底部强调线（由 `element-plus.scss` 全局提供） |
+| D7 | 行 hover：品牌色极浅底 + 过渡（由 `element-plus.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>
+```
+
+**设计模式与出厂模式的关键差异**：
+
+| 差异点 | 出厂模式 | 设计模式 | JSON 来源 |
+|--------|---------|---------|-----------|
+| 页面标题 | 无 | `.vts-page-header` 含标题+描述+操作 | `structureRequirements.pageRegions.header` |
+| 筛选区 | `bg-bg_color p-5` | `.vts-filter-area`（容器感+分隔线） | `structureRequirements.pageRegions.filter` |
+| 主操作按钮位置 | `ReTableBar #buttons` | `.vts-page-header__actions` | `structureRequirements.pageRegions.header.actions` |
+| 表格区 | 无包裹 | `.vts-table-area`（圆角边框） | `structureRequirements.pageRegions.table` |
+| 表头底色 | EP 默认浅灰 | 由 `element-plus.scss` 全局提供品牌色浅底+强调线 | `visual.tableHeader` |
+| 行 hover | EP 默认灰色 | 由 `element-plus.scss` 全局提供品牌色极浅底 | `visual.rowHover` |
+| 交互行为 | EP 默认 | 按 JSON `interactionSpecs` 实现 | `interactionSpecs` |
 
 ## 操作列按钮过多（ReTableOperate · 强制）