@qilitt-mickey/vue3-temp-skill 1.1.11 → 1.1.13

package/references/crud-pages.md

@@ -1,79 +1,262 @@
 ---
 skill: crud-pages
-description: 查询列表页、表单页、标准 CRUD 流程。含 useTableSearch（onSearch/reset）、ReGrid 查询区、表格工具栏与动态高度布局。务必按照本文件与 core-kernel 完整示例编写。
+description: 查询列表页、表单页、标准 CRUD。含 useTableSearch、列表黄金样板、表单约定。
 scope: project
 tags: [vue3, crud, list, form, detail, table, useTableSearch, page, layout]
 ---
 
 # CRUD 页面开发规范
 
-> 以下示例即规范真相。
-> 须同时遵守 `core-kernel` / `http-api`。详情跳转见 `detail-page`，回显见 `data-writeback`。
-> **查询列表页完整模板以 `core-kernel.md`「列表黄金样板」为准**（技能内完整示例，勿到仓库里找 views 演示页对照）。
+遵守 `core-kernel` / `http-api`。独立详情路由 → 同时加载 `detail-page`。回显 → `data-writeback`。
 
-## 查询列表页
-
-### useTableSearch 真实签名
+## useTableSearch
 
 ```typescript
 useTableSearch(formQuery, searchFn, url)
-// searchFn: (query: CombinedQueryData, url: string) => Promise<Result<T>>
-// 返回含：content, otherRef, tableData, pagination, loading, formRef, onSearch, reset,
-//         tableHeight, paginationRef, gridRef, showCollapse, collapsed,
-//         collapsedToggle, upBold, downBold, multipleTableRef, ...
+// searchFn: (query, url) => Promise<Result<T>>
+// 返回：content, otherRef, tableData, pagination, loading, formRef, onSearch, reset,
+//       tableHeight, paginationRef, gridRef, showCollapse, collapsed, collapsedToggle, …
 ```
 
-- 查询：`onSearch()`
-- 重置：`reset()`（内部 `formRef.resetFields()`）
-- 列表：`tableData.value.tableList`（或经 computed 断言）
-- 分页：请求带 `pageNo` / `pageSize`；响应 `data.content` / `data.totalCount`
-- **高度**：`tableHeight` 由 ResizeObserver 计算，公式 = `content` 高 − `formRef` 高 − `paginationRef` 高 − `otherRef` 高 − 50；`content` / `formRef` / `paginationRef` 必须按黄金样板绑定；**查询条件以外的模块（统计块/页签/提示条等）必须包进一个根元素并绑 `otherRef`**，否则表格动态高度算错
+- 查询 / 重置：`onSearch()` / `reset()`
+- 列表：`tableData.value.tableList`
+- 分页请求：`pageNo` / `pageSize`；响应：`data.content` / `data.totalCount`
+- 高度：`tableHeight` 由 Hook 按「卡片内容区底边 − 表格顶边 − 分页」实测；左右分栏、`--vts-card-padding`、工具栏、`otherRef`（表上方）均自动消化；空数据仍保留表格占位高度。业务页只绑定，不手算魔法数
 
-### 布局硬约束（生成列表页必须全部满足）
+## 内容区滚动约定
 
-| 区域 | 正确写法 | 禁止 |
-|------|---------|------|
-| 外层容器 | `<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`（空数据时分页贴查询区） |
-| 额外模块 | 卡片内查询条件以外的模块包一个根元素绑 `ref="otherRef"`（多个模块合进同一根容器），高度自动从 `tableHeight` 扣除 | 额外模块不绑 `otherRef`（表格溢出/被压扁）；手写固定像素或 `calc()` 猜高度 |
-| 分页 | 放在 `ReTableBar` `#default` 内、表格下方；`RePagination` + `:pagination` + `@handle-current-change` / `@handle-size-change` | 分页在卡片外；虚构 `v-model:current-page` |
+| 场景 | 做法 |
+|------|------|
+| 查询列表（定高） | `el-card.vts-page-card` + 固定 `height: calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`；表格绑 `tableHeight`；**仅表格体内滚动**；分页在表格下方；整页无外层滚动条 |
+| 树 + 表分栏 | 同上；左侧树、右侧表共用定高卡，高度仍走 `useTableSearch` 几何实测 |
+| 长表单 / 详情 / 说明类 | 可用 `minHeight` 同公式；内容超出时由 `.app-main` 内 `el-scrollbar` 滚动 |
+| Card 内边距 | 一律走 `--vts-card-padding`（桥接 `--card-padding`）；换规范只改令牌，列表高度由 Hook 跟随 |
 
-### 完整列表示例
+## 列表黄金样板（唯一完整示例）
 
-见 `core-kernel.md`「列表黄金样板」。本模块补充约定：
+| # | 必须 |
+|---|------|
+| L1 | `el-card` + `class="vts-page-card"` + `ref="content"`（禁止挂 `div`） |
+| L2 | 固定 `height: calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`（禁止只用 `minHeight`） |
+| L3 | 查询区 `bg-bg_color p-5`；展示区 `ReTableBar class="bg-bg_color"` |
+| L4 | `ReGrid` `:gap="[0,20]"` + cols；表单项 `w-[100%] !mr-0`；`@should-show-collapse` |
+| L5 | 操作列 `<ReGridItem suffix>` |
+| L6 | 表格绑 `ref="multipleTableRef"` + `tableHeight`；分页在 `ReTableBar` `#default` 内、表格下方 |
+| L7 | `RePagination`：`:pagination` + `@handle-current-change` / `@handle-size-change` |
+| L8 | 查询与表之间的额外模块包一根元素绑 `otherRef`（须在表格上方，高度计入 `tableTop`） |
 
-1. 查询区用 **`ReGrid` + `ReGridItem`**，折叠与 `collapsed` / `showCollapse` / `collapsedToggle` 配套。
-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`）。
+```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 } from "@/components/ReTableOperate";
+import { useApp } from "@/hooks/useApp";
+import { useTableSearch } from "@/hooks/useTableSearch";
+import { message } from "@/utils/message";
 
-### API 配套
+defineOptions({ name: "CustomerList" });
 
-```typescript
-// src/api/customer.ts — 详见 http-api
-export function getCustomerList(data: CustomerQuery, url: string) {
-  return http.request<Result<CustomerPage>>("post", url, { data });
+const { headerHeight, 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 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"
+      :style="{
+        height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`,
+      }"
+    >
+      <div>
+        <el-form
+          ref="formRef"
+          :inline="true"
+          :model="formQuery"
+          class="bg-bg_color p-5"
+        >
+          <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>
+
+      <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" 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>
+            <RePagination
+              ref="paginationRef"
+              :size="size"
+              :pagination="pagination"
+              @handle-current-change="handleCurrentChange"
+              @handle-size-change="handleSizeChange"
+            />
+          </div>
+        </template>
+      </ReTableBar>
+    </el-card>
+  </div>
+</template>
 ```
 
+补充：`ReTableOperate` 用 `:list`；`defineOptions.name` === 路由 `name`；`headerHeight` / `svgLoading` 来自 `useApp()`。
+
+## 列表 → 详情/编辑
+
 ```typescript
-const { onSearch, reset, tableData, loading, pagination, content, otherRef, tableHeight, ... } =
-  useTableSearch(
-    formQuery,
-    getCustomerList,
-    `${import.meta.env.VITE_API_BASE_URL}/console/customer/list`,
+import { useDetail } from "@/hooks/useDetail";
+const { toDetail } = useDetail();
+
+function onAdd() {
+  toDetail("CustomerDetail", { webId: "0" }, "(新增)");
+}
+function onEdit(row: Customer, mark: "edit" | "view") {
+  toDetail(
+    "CustomerDetail",
+    { id: row.id, text: row.name, mark },
+    mark === "edit" ? `(编辑)【${row.name}】` : `(查看)【${row.name}】`,
   );
-onMounted(() => onSearch());
+}
 ```
 
-## 表单页（新增 / 编辑）
+路由 meta 与详情页 `initToDetail` → **`detail-page`**。
+
+## 表单页
 
 ```vue
 <script setup lang="ts">
@@ -87,12 +270,7 @@ defineOptions({ name: "CustomerForm" });
 
 const formRef = ref<FormInstance>();
 const submitLoading = ref(false);
-const formData = reactive<Customer>({
-  id: "",
-  code: "",
-  name: "",
-});
-
+const formData = reactive<Customer>({ id: "", code: "", name: "" });
 const rules: FormRules<Customer> = {
   code: [{ required: true, message: $t("请输入编号"), trigger: "blur" }],
   name: [{ required: true, message: $t("请输入名称"), trigger: "blur" }],
@@ -107,11 +285,8 @@ async function onSubmit() {
   submitLoading.value = true;
   try {
     const res = await saveCustomer(formData);
-    if (res.status === 200) {
-      message($t("保存成功"), { type: "success" });
-    } else {
-      message(res.statusText || $t("保存失败"), { type: "error" });
-    }
+    if (res.status === 200) message($t("保存成功"), { type: "success" });
+    else message(res.statusText || $t("保存失败"), { type: "error" });
   } finally {
     submitLoading.value = false;
   }
@@ -120,25 +295,14 @@ async function onSubmit() {
 
 <template>
   <el-form ref="formRef" :model="formData" :rules="rules" label-position="top">
-    <el-form-item :label="$t('编号')" prop="code">
-      <el-input v-model="formData.code" />
-    </el-form-item>
-    <el-form-item :label="$t('名称')" prop="name">
-      <el-input v-model="formData.name" />
-    </el-form-item>
-    <el-button type="primary" :loading="submitLoading" @click="onSubmit">
-      {{ $t("提交") }}
-    </el-button>
+    <el-form-item :label="$t('编号')" prop="code"><el-input v-model="formData.code" /></el-form-item>
+    <el-form-item :label="$t('名称')" prop="name"><el-input v-model="formData.name" /></el-form-item>
+    <el-button type="primary" :loading="submitLoading" @click="onSubmit">{{ $t("提交") }}</el-button>
   </el-form>
 </template>
 ```
 
-### 表单约定
-
-1. `reactive` + `FormRules` + `formRef.validate()`
-2. 提交按钮必须有 **loading** 防重复
-3. 编辑回填：`Object.assign(formData, detail)`（见 `data-writeback`）
-4. 远程下拉：`ReSelectQuery`（`url` + `value` + `label`，回写用 `edit-data`），见 `form-advanced`
+约定：提交必有 loading；回填见 `data-writeback`；远程下拉见 `form-advanced`。
 
 ## 路由片段
 
@@ -148,24 +312,19 @@ async function onSubmit() {
   name: "CustomerList",
   component: () => import("@/views/customer/list/index.vue"),
   meta: { title: "客户列表", roles: ["admin", "common"] },
-}
+},
 ```
 
-禁止业务模块再挂 Layout。
-
-## 常见反例
-
-- 使用 `handleSearch` / `handleReset`（错误命名）
-- 不用 `useTableSearch` 手写一套分页 loading
-- 提交无 loading
-- 业务路由二次 Layout
-- ReSelectQuery 写成不存在的 `:api` / `label-key` API（真实 props 见 form-advanced）
-- **`ref="content"` 挂在 `div` 上**（`content.$el` 为空 → `tableHeight` 恒为 0）
-- **卡片内有查询条件以外的模块却不绑 `otherRef`**（高度公式漏减该模块 → 表格溢出卡片或底部被截）；或绑到多个散落元素（`otherRef` 只有一个，多模块需包进同一根容器）
-- 卡片只用 **`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`）
+独立详情兄弟路由 → `detail-page`。禁止业务模块再挂 Layout。
+
+## 反例（短表）
+
+| 错误 | 正确 |
+|------|------|
+| `handleSearch` / 手写分页 | `onSearch` / `useTableSearch` |
+| `ref="content"` 挂 div / 只用 minHeight / 缺 `vts-page-card` | `el-card.vts-page-card` + 固定 height |
+| 不绑 `tableHeight` / 分页在卡片外 / 手写魔法数扣高度 | 样板 L6/L7；高度交给 `useTableSearch` |
+| 额外模块不绑 `otherRef` | L8 |
+| 裸 `router.push` 开详情 | `toDetail`（见 detail-page） |
+| `ReTableOperate :buttons` | `:list` |
+| `@show-collapse` | `@should-show-collapse` |

package/references/data-writeback.md

@@ -100,5 +100,5 @@ const { validateStatus, onValidate } = useFormCheck(['field1', 'field2'])
 
 ## 关联文件
 
-- [src/utils/utils.ts](file:///e:/work/vue3-web-temp/src/utils/utils.ts)
-- [src/hooks/useFormCheck.ts](file:///e:/work/vue3-web-temp/src/hooks/useFormCheck.ts)
+- `src/utils/utils.ts`
+- `src/hooks/useFormCheck.ts`

package/references/design-handoff.md

@@ -0,0 +1,92 @@
+---
+skill: design-handoff
+description: 设计产出物 → 业务项目样式落地。从会话/附件取交接块与令牌 CSS，按覆盖清单写入模版样式与配置。
+scope: project
+tags: [handoff, design-tokens, upstream, artifacts]
+---
+
+# 设计产出 → 模板落地
+
+## 触发
+
+出现以下任一情况时执行本协议（与业务开发的先后跟用户需求：可先定风格再写业务，也可在已有业务上全量重构样式）：
+
+- 会话有「前端落地交接」块 / `【主题色系】` / `:root` 令牌 CSS
+- 用户要求按设计稿 / 规范适配或重构整站风格
+- 用户附带色板、规范或 HTML 原型
+
+## 收集产出（会话 / 附件）
+
+| 优先 | 形态 | 用途 |
+|------|------|------|
+| 1 | 前端落地交接块 | `data-theme` / 侧栏 / DarkMode / 主色 |
+| 2 | 令牌 CSS（`--brand-*` / `--primary-*` 等） | 写入 `design-tokens.scss` |
+| 3 | 几何/间距数值 | 覆盖桥接令牌；缺则保留模版默认 |
+| 4 | HTML/CSS 原型 | 微调 `element-plus.scss` |
+| 5 | 项目已有 `design-tokens.scss` | 读现状 |
+
+定位：扫会话交接块、`## 设计令牌`、`:root {`、附件中的 `--primary-` / 主色表。  
+缺项 →「待确认」；有主色则先落主色与壳桥接，不臆造色阶。
+
+## 覆盖清单
+
+| # | 落点 | 写入 |
+|---|------|------|
+| A | `src/styles/design-tokens.scss` | 令牌 CSS；深色侧栏时追加 `--sidebar-*` |
+| B | `theme.scss` 当前 `html[data-theme]` | `--vts-theme-*` → `--sidebar-*` |
+| C | `public/platform-config.json` | `EpThemeColor` / `Theme` / `DarkMode`；`Version` 自增 |
+| D | `index.scss` | `design-tokens` 的 `@use` 最前 |
+| E | `dark.scss` / 语义色 | 跟 `--primary-*` |
+| F | 冲突清单 | `design-system` 第四节 |
+| G | 规范识别回执 | 动手改文件前输出 |
+
+侧栏派生（交接为深色渐变时）：
+
+```scss
+--sidebar-bg: linear-gradient(180deg, color-mix(in srgb, var(--primary-8) 88%, var(--primary-7)) 0%, var(--primary-9) 52%, color-mix(in srgb, var(--primary-9) 90%, #000) 100%);
+--sidebar-logo-bg: linear-gradient(135deg, color-mix(in srgb, var(--primary-7) 70%, var(--primary-8)) 0%, var(--primary-8) 100%);
+--sidebar-border-color: color-mix(in srgb, var(--primary-6) 22%, transparent);
+--sidebar-menu-text: rgb(255 255 255 / 65%);
+--sidebar-menu-text-hover: #fff;
+--sidebar-menu-active-text: #fff;
+--sidebar-menu-hover-bg: color-mix(in srgb, var(--primary-5) 18%, transparent);
+--sidebar-menu-active-bg: var(--primary-6);
+--sidebar-submenu-bg: color-mix(in srgb, var(--primary-9) 82%, #000);
+--sidebar-active-indicator: var(--primary-5);
+```
+
+`theme.scss`：`--vts-theme-menu-bg: var(--sidebar-bg);` 等 → `layout-theme`。
+
+## 顺序
+
+1. 收集产出 1～4  
+2. 规范识别回执  
+3. A→E  
+4. F  
+5. 验证侧栏/主色  
+6. 若同轮还有业务需求 → 再写/改 views（仅样式任务则到此结束）  
+
+## 交接块字段
+
+```markdown
+## 前端落地交接
+- 设计来源：上游产出
+- 主题色系：<主题中文名>
+- data-theme：<模版 html[data-theme] 值>
+- 侧栏：<深色渐变|浅色>
+- 内容区默认：<亮色|暗黑>
+- 主色：<#HEX>
+
+## 设计令牌（CSS）
+```css
+:root {
+  --brand-primary: #...;
+  --brand-hover: #...;
+  --brand-active: #...;
+  --primary-0: #...;
+  /* --primary-1 … --primary-9 */
+}
+```
+```
+
+仅有交接块无令牌 CSS：写 `--brand-primary` + `EpThemeColor`，待确认注明缺色阶。