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

package/references/detail-page.md

@@ -9,18 +9,13 @@ tags: [vue3, detail, toDetail, useDetail, activePath, showLink, multiTags, keepA
 
 真相源：模版 `useDetail.ts`、`multiTags`、侧栏 `NavVertical`。列表打开独立路由页时按本文件落地。
 
-## 概念
+**反认知偏差（必读）**：`toDetail` 只负责写顶部 tag 并跳转；**侧栏高亮靠 `meta.activePath`，缓存/多开靠 `meta.keepAlive` / `moreTags`**。三者缺一不可，禁止只写 `toDetail`。
 
-| 能力 | 字段 / API |
-|------|------------|
-| 不进左侧菜单 | 路由 `meta.showLink: false` |
-| 顶部 tag（multiTags） | `useDetail().toDetail` → `handleTags('push')` |
-| 侧栏高亮 | 路由 `meta.activePath` = 列表 path |
-| 页面缓存 | `meta.keepAlive`；多开 tag 再加 `moreTags: true` |
+## 详情三件套（强制完整样板 · 整段照抄再改名）
 
-`showLink` 只管侧栏是否显示，不控制顶部 tag。详情不在菜单里 → 必须用 `toDetail` 写 tag；裸 `router.push` 只换路由。
+缺任一段 = 未完成。样板内字段**默认全部写出**（勿改成 `//` 注释再「按需打开」）。仅当业务明确不要缓存/多开时，才删掉对应行。
 
-## 路由（与列表兄弟）
+### ① 兄弟路由 meta
 
 ```typescript
 {
@@ -31,36 +26,27 @@ tags: [vue3, detail, toDetail, useDetail, activePath, showLink, multiTags, keepA
     title: "客户详情",
     showLink: false,
     activePath: "/customer/list",
-    // keepAlive: true,
-    // moreTags: true,
+    keepAlive: true,
+    moreTags: true,
   },
 },
 ```
 
-| 字段 | 要求 |
-|------|------|
-| `title` | 非空 |
-| `showLink: false` | 必填 |
-| `activePath` | = 列表 path |
-| `name` | = `defineOptions({ name })` |
-
-## 列表打开
+### ② 列表页打开
 
 ```typescript
 import { useDetail } from "@/hooks/useDetail";
 const { toDetail } = useDetail();
 
 toDetail("CustomerDetail", { webId: "0" }, "(新增)");
-toDetail("CustomerDetail", { id: row.id, text: row.name, mark: "edit" }, `(编辑)【${row.name}】`);
+toDetail(
+  "CustomerDetail",
+  { id: row.id, text: row.name, mark: "edit" },
+  `(编辑)【${row.name}】`,
+);
 ```
 
-```typescript
-toDetail(name, parameter, title?, model = "query") // model: "query" | "params"
-```
-
-写入 tag 时不要把路由上的 `showLink: false` 原样塞进 `handleTags` 的 meta。
-
-## 详情页
+### ③ 详情页初始化
 
 ```vue
 <script setup lang="ts">
@@ -72,12 +58,36 @@ const { id, mark } = getParameter as DetailParameter;
 </script>
 ```
 
-`initToDetail` 标题：无 id → `(新增)`；`mark===edit'` → `(编辑)【text】`；`view` → `(查看)【text】`。
+## 概念
+
+| 能力 | 字段 / API | 谁负责 |
+|------|------------|--------|
+| 不进左侧菜单 | `meta.showLink: false` | 路由 |
+| 顶部 tag | `toDetail` → `handleTags('push')` | Hook |
+| 侧栏高亮 | `meta.activePath` = 列表 path | 路由 |
+| 页面缓存 / 多开 | `meta.keepAlive` + `moreTags: true` | 路由 |
+
+`showLink` 只管侧栏是否显示，不控制顶部 tag。裸 `router.push` 只换路由、不写 tag。
+
+| 字段 | 要求 |
+|------|------|
+| `title` | 非空 |
+| `showLink: false` | 必填 |
+| `activePath` | = 列表 path（必填） |
+| `keepAlive` / `moreTags` | 默认 `true`；不要缓存/多开再删 |
+| `name` | = `defineOptions({ name })` |
+
+```typescript
+toDetail(name, parameter, title?, model = "query") // model: "query" | "params"
+```
+
+写入 tag 时不要把路由上的 `showLink: false` 原样塞进 `handleTags` 的 meta。
+
+`initToDetail` 标题：无 id → `(新增)`；`mark==='edit'` → `(编辑)【text】`；`view` → `(查看)【text】`。
 
 ## Must-do
 
-1. 兄弟路由 + `showLink: false` + `activePath` + 非空 `title`
-2. 列表只用 `toDetail`，禁止裸 `router.push`
-3. 详情页必调 `initToDetail`；`name` 对齐
-4. 参数用 `getParameter`
-5. 需缓存 / 多开时配 `keepAlive` / `moreTags`
+1. 三件套整段落盘（路由 + `toDetail` + `initToDetail`）
+2. `showLink: false` + `activePath` + 非空 `title` + 默认 `keepAlive`/`moreTags`
+3. 列表只用 `toDetail`，禁止裸 `router.push`
+4. 详情页必调 `initToDetail`；`name` 对齐；参数用 `getParameter`

package/references/download-export.md

@@ -4,6 +4,26 @@
 
 规范文件下载、模板下载、文件流导出与附件预览。在需要下载文件、导出表格或预览附件时参照。
 
+**抗略读**：导出/下载 API **必须**带 `responseType: "blob"`（默认写出，勿当可选项注释掉）；前端用 `blobDown` / 项目已有 `download*`，禁止手写 `URL.createObjectURL` 另起一套（除非仓库无封装）。
+
+## 强制样板（导出）
+
+```typescript
+// api
+export function exportExcel(data: Recordable) {
+  return http.request<Result<Blob>>(
+    "post",
+    `${import.meta.env.VITE_API_BASE_URL}/xxx/export`,
+    { data },
+    { responseType: "blob" },
+  );
+}
+
+// 页面
+const res = await exportExcel(params);
+blobDown(res.data, "导出.xlsx", res);
+```
+
 ## 常用工具
 
 项目集成了 `@pureadmin/utils` 与自定义工具：

package/references/feedback-loading.md

@@ -4,6 +4,25 @@
 
 规范系统 Loading、Message、MessageBox、NoticeBar 等反馈组件的使用。在需要提示用户或阻塞操作时参照。
 
+**抗略读**：删除/危险操作**默认写出** `ElMessageBox.confirm`；列表请求接 `v-loading`；提交默认 `loading` 防重复。提示文案一律 `$t()`。
+
+## 强制样板（删除确认）
+
+```typescript
+import { ElMessageBox } from "element-plus";
+import { message } from "@/utils/message";
+
+async function onDelete(row: { id: string }) {
+  await ElMessageBox.confirm($t("确定删除吗？"), $t("温馨提醒"), {
+    confirmButtonText: $t("确定"),
+    cancelButtonText: $t("取消"),
+    type: "warning",
+  });
+  // await deleteApi({ id: row.id })
+  message($t("删除成功"), { type: "success" });
+}
+```
+
 ## Loading
 
 ### 局部 Loading
@@ -55,6 +74,22 @@ ElMessageBox.confirm($t("确定删除吗？"), $t("温馨提醒"), {
 });
 ```
 
+## ReNoticeBar 通知栏
+
+落点：`src/components/ReNoticeBar`。长文本滚动 / 可关闭提示，用于页内公告条。
+
+```vue
+<script setup lang="ts">
+import ReNoticeBar from "@/components/ReNoticeBar";
+</script>
+
+<template>
+  <ReNoticeBar :text="$t('系统将于今晚维护，请提前保存数据')" />
+</template>
+```
+
+Props / 行为以组件源码为准；颜色走主题令牌，禁止业务写死提示条背景 hex。
+
 ## 关键约定
 
 1. 所有提示文案使用 `$t()`。

package/references/flowchart-g6.md

@@ -231,8 +231,7 @@ defineExpose({ getInstance: () => graph })
 ```vue
 <!-- g6 页面示例 -->
 <template>
-  <div :style="{ height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)` }"
-    class="pos-relative bg-bg_color p-5 overflow-hidden">
+  <div class="vts-page-fill h-full pos-relative bg-bg_color p-5 overflow-hidden">
     <div class="toolbar">
       <el-alert title="antv/g6流程图展示" type="info" :closable="false" />
     </div>

package/references/form-advanced.md

@@ -10,6 +10,8 @@ tags: [form, dialog, ReDialog, ReDialogResize, ReSelectQuery, ReCascader, iconPi
 > 核心选择器与 CRUD 列表筛选项高频相关。  
 > **弹窗**：业务弹窗统一用 `ReDialog` / `ReDialogResize`，禁止业务页直接堆裸 `el-dialog`（除非用户明确要求）。
 
+**抗略读**：弹窗走项目 `ReDialog` 黄金样板（含销毁/禁点遮罩等默认项），勿降级为裸 `el-dialog`。远程下拉用 `ReSelectQuery` 真实 props（`url`/`value`/`label`/`edit-data`），禁止臆造 `:api`。
+
 ## 依赖（缺则先装）
 
 按用到的能力安装（先查 `package.json`）：
@@ -202,7 +204,8 @@ function parseAddress(text: string) {
 
 ## ReDialog 通用弹窗（必用）
 
-> 落点：`src/components/ReDialog`。基于 `el-dialog`：居中、可拖拽、`destroy-on-close`、默认禁点遮罩关闭、可选全屏、内容区 `el-scrollbar`。写法见下方样板。
+> 落点：`src/components/ReDialog`。基于 `el-dialog`：居中、可拖拽、`destroy-on-close`、默认禁点遮罩关闭、内容区 `el-scrollbar`。  
+> **默认值**：`width='50%'`、`maxHeight=500`、`fullscreen=false`（不展示全屏钮）。几何消费 CSS：`--dialog-header-height`（出厂 38）、`--dialog-footer-height`（38）、`--dialog-body-padding`（15）、`--dialog-border-radius`（10）；设计落地后按 handoff 回填令牌即可变观感。
 
 ### Props / 插槽
 
@@ -212,7 +215,7 @@ function parseAddress(text: string) {
 | `title` | 标题文案（也可用 `#title` 插槽） |
 | `width` | 默认 `'50%'` |
 | `maxHeight` | 内容区滚动高度，默认 `500`（number 会拼 `px`） |
-| `fullscreen` | 是否显示右上角全屏按钮，默认 `true` |
+| `fullscreen` | 是否显示右上角全屏按钮，**默认 `false`**（需要时显式 `:fullscreen="true"`） |
 | 默认插槽 | 内容区（包在 scrollbar 内） |
 | `#footer` | 有则渲染底部操作区 |
 | `#title` | 自定义标题 |

package/references/graph-relation.md

@@ -24,7 +24,7 @@ import { useApp } from '@/hooks/useApp'
 import bgImg from './img/relationBg.png'
 
 defineOptions({ name: 'Graph' })
-const { headerHeight, svgLoading } = useApp()
+const { svgLoading } = useApp()
 const graphRef = ref()
 const loading = ref(false)
 const rootId = ref('')
@@ -260,6 +260,6 @@ const legendConfig = ref([
 
 1. 节点/连线类型只需声明项目中实际用到的字段，不必照搬库的完整类型。
 2. 根节点通过 `selfFlag === '1'` 识别，设为 `fixed: true` 固定位置。
-3. 图谱容器必须有明确高度（使用 `calc(100vh - ...)` 计算）。
+3. 图谱容器必须有明确高度（定高页用 `vts-page-fill` / `vts-page-card`；内部画布 `height: 100%` 或 `calc(100% - 偏移)`；禁止业务页 `100vh` 减顶栏定高）。
 4. `setJsonData` 的回调中执行居中、缩放、高亮等初始化操作。
 5. 节点自定义样式通过 `#node` 插槽，class 根据 `data` 字段动态绑定。

package/references/http-api.md

@@ -9,6 +9,31 @@ tags: [axios, http, api, encryption, rsa, aes, download, request]
 
 > 实现落点：`src/utils/http.ts`、`src/api/**`、全局 `Result<T>`。
 
+**抗略读**：接口文件须整段按下方「强制样板」落盘；禁止组件内直接 `axios`/`fetch`。加解密靠 `VITE_ENCODE_SWITCH`，禁止臆造单请求 `crypto: true`。下载接口**默认写出** `responseType: "blob"`（勿注释掉）。
+
+## 强制样板（新建 API 照抄）
+
+```typescript
+import { http } from "@/utils/http";
+
+export function getCustomerList(data: CustomerQuery) {
+  return http.request<Result<CustomerPage>>(
+    "post",
+    `${import.meta.env.VITE_API_BASE_URL}/customer/list`,
+    { data },
+  );
+}
+
+export function downloadCustomer(data: Recordable) {
+  return http.request<Result<Blob>>(
+    "post",
+    `${import.meta.env.VITE_API_BASE_URL}/customer/export`,
+    { data },
+    { responseType: "blob" },
+  );
+}
+```
+
 ## Http 封装架构
 
 项目使用自定义 `Http` 类封装 Axios，位于 `src/utils/http.ts`。核心特性：

package/references/icons.md

@@ -11,6 +11,18 @@ tags: [vue3, icon, svg-icon, ReSvgIcon, ReIconPicker, iconify, ep, ri, unocss, m
 > **真相源**：`src/components/ReSvgIcon`、`src/components/ReIconPicker`、`src/icons/svg`、`main.ts`、`uno.config.ts`、`build/plugins/SvgSpriteLoader.ts` / `SvgLoader.ts`。  
 > 选型表见 `project-inventory`「图标」节；勿另起 IconFont / 未约定的图标库。
 
+**抗略读**：新建菜单/父级路由时 **`meta.icon` 默认写出**（如 `ep:user`），禁止交无图标菜单。页面内优先 `<svg-icon name="..." />`，勿散落未约定图标库。
+
+## 强制样板（菜单 icon）
+
+```typescript
+meta: { title: "客户管理", icon: "ep:user", rank: 10 }
+```
+
+```vue
+<svg-icon name="ep:search" />
+```
+
 ---
 
 ## 依赖（core，模板已装）

package/references/layout-theme.md

@@ -189,40 +189,48 @@ html.dark {
 
 ### 4.1 间距
 
-项目使用 `--vts-margin: 8px` 作为基础间距单元。UnoCSS 配置了 `presetRemToPx({ baseFontSize: 4 })`，因此 UnoCSS 中的间距类直接对应像素值：
+项目内容区内边距走 `--layout-content-padding` → `--vts-margin`（**出厂 8px**；设计 handoff 常覆盖为 24）。UnoCSS `presetRemToPx({ baseFontSize: 4 })` 间距类数字即 px：
 
 | UnoCSS 类 | 实际值 | 用途 |
 |-----------|--------|------|
 | `p-1` / `m-1` | 1px | 微调 |
 | `p-2` / `m-2` | 2px | 紧凑间距 |
 | `p-4` / `m-4` | 4px | 小间距 |
-| `p-8` / `m-8` | 8px | 基础间距（= --vts-margin） |
+| `p-8` / `m-8` | 8px | 常等于出厂 `--vts-margin`（handoff 改 margin 后勿再假设恒等于 8） |
 | `p-12` / `m-12` | 12px | 中等间距 |
 | `p-16` / `m-16` | 16px | 大间距 |
 | `p-20` / `m-20` | 20px | 区块间距 |
 
-### 4.1.1 弹窗 / MessageBox（design-tokens 定义 · element-plus.scss 执行）
+### 4.1.1 弹窗 / MessageBox（design-tokens 定义 · ReDialog / element-plus 执行）
 
-| 令牌 | 默认语义 | 消费位置 |
+| 令牌 | 出厂默认 | 消费位置 |
 |------|---------|---------|
-| `--dialog-header-padding` | 16px 24px | `.el-dialog__header` / `.el-message-box__header` |
-| `--dialog-body-padding` | 24px | `.el-dialog__body`（表单弹窗） |
-| `--message-box-content-padding` | 16px 24px | `.el-message-box__content`（确认框，**比 dialog body 更紧凑**） |
-| `--dialog-footer-padding` | 16px 24px | `.el-dialog__footer` / `.el-message-box__btns` |
-| `--primary-bg` | 主色浅底（上游设计技能常提供） | 渐变顶色 |
-| `--ds-dialog-bg` | `linear-gradient(primary-bg → component-bg)` | `index.scss` → `--vts-dialog-bg` → `.el-dialog` / `.el-message-box` |
+| `--dialog-header-height` | 38px | `.el-dialog__header`（ReDialog） |
+| `--dialog-footer-height` | 38px | `.el-dialog__footer` |
+| `--dialog-body-padding` | 15px | `.el-dialog__body` |
+| `--dialog-border-radius` | 10px | `.el-dialog` |
+| `--message-box-*-padding` | 8px 16px | MessageBox 更紧凑 |
+| `--ds-dialog-bg` | `linear-gradient(primary-bg → component-bg)` | `index.scss` → `--vts-dialog-bg` |
 
-> **禁止**写死 `#e5f3fe → #fefefe` 蓝渐变；换主题时只改 `--primary-bg` / `--brand-primary`，渐变自动跟随。暗黑模式在 `dark.scss` 用 `color-mix` 覆写 `--primary-bg` 后同样生效。
+> **禁止**写死 `#e5f3fe → #fefefe`。  
+> **出厂**保留上表 ReDialog 默认几何；**设计落地**时按 `design-handoff`「全量令牌核对表 · D. 弹窗」回填（如圆角改 `--radius-lg` / 8px），禁止只改品牌色漏弹窗令牌。
 
 ### 4.2 字号
 
-UnoCSS `theme.fontSize` 已显式定义为 px 值（避免被 `presetRemToPx` 转换）：
+**两套并存，勿混用：**
+
+| 体系 | 正文基准 | 用途 |
+|------|----------|------|
+| `design-tokens` `--font-size-base` | **14px** | Element Plus / 令牌化组件 |
+| UnoCSS `text-base` | **16px** | 工具类排版（`theme.fontSize` 显式 px） |
+
+UnoCSS 其余档：
 
 | Token | 大小 | 行高 | 用途 |
 |-------|------|------|------|
 | `text-xs` | 12px | 16px | 辅助文字、标签 |
 | `text-sm` | 14px | 20px | 次要文字、表格 |
-| `text-base` | 16px | 24px | 正文默认 |
+| `text-base` | 16px | 24px | Uno 正文类 |
 | `text-lg` | 18px | 28px | 小标题 |
 | `text-xl` | 20px | 28px | 标题 |
 | `text-2xl` | 24px | 32px | 页面标题 |
@@ -230,12 +238,18 @@ UnoCSS `theme.fontSize` 已显式定义为 px 值（避免被 `presetRemToPx`
 
 ### 4.3 字体
 
-全局字体在 `index.scss` 中定义：
+全局字体走令牌 `--font-family`（`design-tokens.scss` 出厂为系统栈）。
+
+`index.scss` / `reset.scss` 写法：
 
 ```css
-font-family: 'Alibaba PuHuiTi 3.0', 'Microsoft YaHei', Arial, sans-serif;
+font-family: var(--font-family, 'Alibaba PuHuiTi 3.0', 'Microsoft YaHei', Arial, sans-serif);
 ```
 
+- **出厂**：令牌已定义 → 实际为系统栈；PuHui 仅作 fallback  
+- **设计落地**：handoff 覆盖 `--font-family` 即全局生效  
+- **禁止**再写死 `'Alibaba PuHuiTi 3.0' !important` 通配符覆盖令牌
+
 ### 4.4 动画时长
 
 - 全局过渡时长：`--vts-transition-duration: 0.3s`
@@ -253,56 +267,68 @@ font-family: 'Alibaba PuHuiTi 3.0', 'Microsoft YaHei', Arial, sans-serif;
 
 ### 4.6 边框圆角
 
-项目未定义全局圆角 token，遵循 Element Plus 默认值：
-- 按钮/输入框：`4px`
-- 卡片：`8px`（`rounded-lg`）
-- 弹窗：`8px`
+模版**已定义**全局圆角令牌（`design-tokens`）：
+
+| 令牌 | 出厂默认 | 用途 |
+|------|----------|------|
+| `--radius-sm` / `--border-radius-sm` | 4px | 小控件、Tag |
+| `--radius-base` / `--border-radius-base` | 6px | 按钮、输入 |
+| `--radius-lg` / `--border-radius-lg` | 8px | 卡片等 |
+| `--dialog-border-radius` | 10px（出厂 ReDialog） | 弹窗；设计落地可改为 `var(--radius-lg)` |
+
+设计 handoff 可覆盖上述令牌；业务禁止裸写 `border-radius: 4px`。
 
 ---
 
 ## 五、布局系统
 
+> **双轨**：下列数字是 **CSS 变量的出厂默认值**，不是组件内写死的常量。设计落地后按 handoff 回填令牌，壳层自动跟随。
+
 ### 布局模式
 
 项目支持三种布局模式，通过布局配置切换：
 
-1. **垂直布局（Vertical）** — 侧边栏 210px + 顶部导航，后台管理默认布局。
+1. **垂直布局（Vertical）** — 侧边栏 `var(--sidebar-width)`（出厂 **208px**）+ 顶部导航。
 2. **水平布局（Horizontal）** — 顶部导航栏，侧边栏宽度为 0。
-3. **混合布局（Mix）** — 侧边栏 210px（一级菜单）+ 顶部导航（二级菜单）。
+3. **混合布局（Mix）** — 侧边栏同 `--sidebar-width`（一级菜单）+ 顶部导航（二级菜单）。
 
 ### 布局文件结构
 
 ```
 src/layout/
-├── index.vue              # 布局入口
+├── index.vue
 ├── components/
-│   ├── sidebar/           # 侧边栏
-│   ├── navbar/            # 顶部导航
-│   ├── tagsview/          # 标签页
-│   └── settings/          # 设置面板
+│   ├── lay-sidebar/       # 侧边栏
+│   ├── lay-navbar/        # 顶部导航
+│   ├── lay-tag/           # 多标签页
+│   ├── lay-content/       # 内容区
+│   ├── lay-header/        # 顶栏容器
+│   └── lay-setting/       # 设置面板
 └── hooks/
-    └── useLayout.ts       # 布局状态管理
 ```
 
 ### 侧边栏样式架构
 
-`src/styles/sidebar.scss` 使用 SCSS mixin `merge-style($sideBarWidth)` 定义侧边栏样式，通过传入不同宽度被调用 3 次（对应 3 种布局）：
+`src/styles/sidebar.scss` 使用 SCSS mixin `merge-style($sideBarWidth)`；宽度传入**令牌**，禁止写死 210：
 
 ```scss
-// sidebar.scss 核心结构
-@mixin merge-style($sideBarWidth) {
-  // 侧边栏容器、菜单项、子菜单、Logo 等样式
-  // $sideBarWidth 控制展开宽度
-}
+$sideBarWidth: var(--sidebar-width, 208px);
 
-// 垂直布局
-.layout-vertical .sidebar-container { @include merge-style(210px); }
-// 水平布局
-.layout-horizontal .horizontal-header { @include merge-style(0); }
-// 混合布局
-.layout-mix .sidebar-container { @include merge-style(210px); }
+.layout-vertical .sidebar-container { @include merge-style($sideBarWidth); }
+.layout-mix .sidebar-container { @include merge-style($sideBarWidth); }
 ```
 
+壳层几何出厂默认（均在 `design-tokens.scss`，可被 handoff 覆盖）：
+
+| 令牌 | 出厂 | 设计别名 |
+|------|------|----------|
+| `--header-height` | 64px | `--layout-header-height` |
+| `--tabs-height` | 40px | （壳层多标签栏，≠ EP `--tabs-item-height`） |
+| `--sidebar-width` | 208px | `--layout-sider-width` |
+| `--sidebar-collapsed-width` | 64px | `--layout-sider-collapsed-width` |
+| `--layout-content-padding` → `--vts-margin` | 8px | 设计常改 24 |
+| `--layout-footer-height` | 48px | |
+
 **修改侧边栏样式时**，必须检查 3 种布局模式下是否都需要调整。
 
 ### 布局约定
@@ -310,26 +336,40 @@ src/layout/
 1. 页面组件通过 `<router-view>` 嵌套在布局内渲染。
 2. 布局切换通过 store 中的 `layout` 字段控制。
 3. 侧边栏菜单数据来源于路由配置中的 `meta` 信息。
-4. 标签页（TagsView）支持关闭、刷新、关闭其他等操作。
+4. 标签页（TagsView）三种风格：`smart`（灵动）/ `chrome`（谷歌）/ `card`（卡片·设计规范）；由 `configure.showModel` / `platform-config.json` 的 `ShowModel` 控制。设计 handoff 落地时用 `card`。
+
+### 页签风格（ShowModel）
 
-### 顶栏高度（headerHeight）
+| 值 | 设置文案 | 说明 |
+|----|----------|------|
+| `smart` | 灵动 | 底部指示条动画 |
+| `chrome` | 谷歌 | Chrome 梯形页签（模版常见出厂） |
+| `card` | 卡片 | 关闭钮绝对定位不占位；显现时用不透明页签底盖字；再 hover 关闭钮：圆形底 `--layout-bg`/`--bg-layout` + 图标 `--error-6`/`--error-color`=`#F5222D`（勿用 EP `#F56C6C` 偏橘） |
+
+设计落地改色/几何时优先改 `--vts-tag-card-*`（见 `index.scss` `:root`），勿再复制一套选择器。
+
+### 顶栏 / 页签高度
 
 | 环节 | 约定 |
 |------|------|
-| 测量 | `lay-header` 用 `ResizeObserver` 测量 `.fixed-header`，写入 `$storage.configure.headerHeight` |
-| 重测 | 切换 `layout`、`hideTabs`、`hiddenSideBar` 后 `nextTick` 再测一次（避免布局切换后仍用 localStorage 旧值） |
-| 消费 | 业务页通过 `useApp().headerHeight` 读 `$storage.configure.headerHeight`；`lay-content` 的 `padding-top` 仍用 `--vts-layout-header-offset*`（勿与 storage 双向绑定，避免重测循环） |
+| 令牌 | `--header-height` / `--tabs-height` → `--layout-header-offset`；桥接 `--vts-bar-height` / `--vts-tabs-height` / `--vts-layout-header-offset*` |
+| 消费 | `lay-content` 的 `padding-top` 用 `--vts-layout-header-offset*`；定高页用 `.vts-page-card` / `.vts-page-fill` |
+| 禁止 | 业务页用 `100vh` 减顶栏高度；用 JS 测顶栏写 storage；在 `useApp` / `platform-config` 增加顶栏像素字段 |
+
+设计落地改顶栏：只改 `--header-height`（或 handoff `geometry.headerHeight`）。
 
 ### 内容区高度与滚动
 
 | 场景 | 卡片 / 高度 | 滚动落点 |
 |------|-------------|----------|
-| 查询列表 | `el-card.vts-page-card` + 固定 `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`；表格绑 `useTableSearch().tableHeight` | 仅 `el-table` 体内；分页在表格下方 |
+| 查询列表 | `el-card.vts-page-card`（无 inline `100vh`）；表格绑 `useTableSearch().tableHeight` | 仅 `el-table` 体内；分页在表格下方 |
 | 树 + 表分栏 | 同上定高卡；左右并排，高度走 Hook 几何实测 | 同查询列表 |
-| 长表单 / 详情 / 说明 | 同公式可用 `minHeight`；不绑 `tableHeight` | `.app-main` 内 `el-scrollbar` |
-| Card 内边距 | `--vts-card-padding` → `--card-padding` | 换规范只改令牌；列表高度由 Hook 实测跟随 |
+| 非 Card 整页填满 | 根节点 `class="vts-page-fill"` + `height: 100%` / `h-full` | 内部区域自管滚动 |
+| 长表单 / 详情 / 说明 | `min-height: 100%`；不绑 `tableHeight` | `.app-main` 内 `el-scrollbar` |
+| Card 内边距 | `--vts-card-padding` → `--card-padding` | 换规范 / `--vts-margin` 只改令牌；列表高度由壳层 + Hook 跟随 |
 
-`.vts-page-card`：`overflow: hidden`，`.el-card__body` 高度 100%。样式在 `element-plus.scss`。
+`.vts-page-card`：flex 填满 `.main-content:has(.vts-page-card)`，`overflow: hidden`，`.el-card__body` 高度 100%。样式在 `element-plus.scss` + `lay-content`。
+`--vts-margin` 可变（模板默认 8px，设计 handoff 可覆盖）；壳层对 `.main-content` 使用 **padding**（非 margin）承载该间距，定高链为 `height:100%`，避免「高度+外边距」撑出最外层滚动条。
 
 ### 混合布局路由结构
 

package/references/permission-auth.md

@@ -7,6 +7,20 @@ tags: [vue3, permission, auth, directive, hooks, v-auth, role, access-control]
 
 # 权限控制与自定义指令
 
+**抗略读**：有权限需求时，`meta.roles` 与 `v-auth`/`ReAuth` **默认写出**（勿注释成可选项）。禁止 `v-if="roles.includes(...)"` 手写角色判断。
+
+## 强制样板（页面 + 按钮）
+
+```typescript
+// 路由：roles 默认写出
+meta: { title: "用户管理", roles: ["admin", "common"] }
+```
+
+```vue
+<el-button v-auth="['admin']" @click="onDelete">{{ $t("删除") }}</el-button>
+<ReAuth :value="['admin']"><!-- 区域级 --></ReAuth>
+```
+
 ## 权限体系概览
 
 项目权限分为三个层级：
@@ -33,7 +47,7 @@ export default {
       component: () => import("@/views/system/user/index.vue"),
       meta: {
         title: "用户管理",
-        roles: ["admin", "editor"],  // 只有这些角色可以访问
+        roles: ["admin", "editor"],
       },
     },
     {
@@ -42,7 +56,7 @@ export default {
       component: () => import("@/views/system/config/index.vue"),
       meta: {
         title: "系统配置",
-        roles: ["admin"],  // 仅管理员可访问
+        roles: ["admin"],
       },
     },
   ],