@qilitt-mickey/vue3-temp-skill 1.1.12 → 1.1.14

package/SKILL.md

@@ -24,11 +24,20 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 
 1. 先读 `references/core-kernel.md`
 2. 复用仓库已有 `Re*` / Hook / utils；选型表指定库勿擅自替换
-3. 按命中模块内完整示例编写
+3. 按命中模块内**强制完整样板**整段编写（禁止只抄 API 签名、丢掉 meta/配套段落）
 4. 无对应能力 → 标注「待确认」，未经同意不引入新依赖
 5. 真相源：`仓库已有封装` > `本 Skill 示例` > 通用 Vue 习惯
 6. 命中 addon / 缺依赖时再读 `project-inventory.md` 第九节；精确版本安装，禁止 `@latest`
 
+## 抗略读（全模块 · 提高命中率）
+
+按需模块 ≠ 可浅读。命中即须落到该文件的**完整样板 / Must-do**，生成后靠 `code-quality` 硬失败表兜底。
+
+1. **样板字段默认写出**：示例里写明的 `activePath` / `keepAlive` / `roles` / `responseType: "blob"` 等不得改成 `//` 注释再当可选项；仅业务明确不需要时才删除
+2. **关联能力同批落盘**：列表→详情 = `crud-pages` + `detail-page` 三件套；有 API = 同步 `http-api`；有删除 = 确认框；有编辑回显 = `Object.assign`
+3. **Hook ≠ 壳层自动**：`toDetail` 写 tag；侧栏高亮 / keepAlive 靠路由 meta；`http` 加解密靠环境开关，不靠单请求配置
+4. **大范围交付仍须逐模块核对硬失败表**，禁止「lint 过了就算完」
+
 ## 模块路由表
 
 ### 始终加载
@@ -112,7 +121,8 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 
 - HTTP：`import { http } from '@/utils/http'`；方法跟后端（允许 GET/POST）；`Result<T>`；`VITE_API_BASE_URL` → `http-api`
 - 列表：`onSearch` / `reset` + 黄金样板 → `crud-pages`
-- 独立详情：`toDetail` + 路由 meta → `detail-page`
+- 独立详情：`toDetail` **不能替代** `activePath` / `keepAlive` / `moreTags`；三件套 → `detail-page`
+- 权限：`meta.roles` + `v-auth`/`ReAuth` → `permission-auth`
 - 不二次挂 Layout；`script setup` + `defineOptions({ name })`；`$t('中文')`；样式契约 → `core-kernel`
 
 ## 工作流
@@ -134,6 +144,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 ## 代码质量审查
 - 闸门：已执行 code-quality（生成后）
 - 清单：选型 / 类型 / 组件 / API / 安全 / 业务 / 列表→详情(如适用) / 列表布局(如适用) / 风格 → 通过 | 已修正：…
+- 硬失败：无 | 已拦截并修正：…
 - 命令：`pnpm lint:fix` → …；`pnpm type-check` → …
 - 待确认：…
 

package/package.json

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

package/references/api-check.md

@@ -9,6 +9,8 @@ tags: [api, backend, integration, contract, http, checklist, mock]
 
 写法与示例 → **`http-api`**。本文件只做联调核对。权威源：`types/global.d.ts`、`src/utils/http.ts`、`src/api/**`、`mock/**`、`useTableSearch`。
 
+**抗略读**：联调阶段仍须核对「下载是否带 blob」「分页字段是否 content/totalCount」；契约不过 = API 未完成，禁止只靠 lint 放行。
+
 ## 基本信息
 
 - [ ] 业务 path 与后端文档一致；忌把 `/mock/...` 当生产约定

package/references/code-quality.md

@@ -12,7 +12,7 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 ## 协议（按序）
 
 1. 重读本文件
-2. 列出本轮改动路径，对照下方清单
+2. 列出本轮改动路径，对照下方清单；**硬失败表命中则先改代码再继续**
 3. 业务项目根目录必跑：`pnpm lint:fix` → `pnpm type-check`（无脚本则 `pnpm lint` / `pnpm exec eslint . --fix`；`pnpm exec vue-tsc --noEmit`）
 4. 失败则修代码并重跑，直至通过或写明阻塞
 5. 最终回复追加：
@@ -22,11 +22,29 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 - 闸门：已执行 code-quality（生成后）
 - 改动文件：`path/a`、`path/b`、…
 - 清单：选型 ✅ / 类型 ✅ / 组件 ✅ / API ✅ / 安全 ✅ / 业务 ✅ / 列表→详情 ✅或N/A / 列表布局 ✅或N/A / 风格 ✅
+- 硬失败：无 | 已拦截并修正：…
 - 已修正：…（无则写「无」）
 - 命令：`pnpm lint:fix` → …；`pnpm type-check` → …
 - 待确认：…
 ```
 
+## 硬失败（对照落盘文件；命中即未通过）
+
+lint / type-check **过了也不能放过**下列项。发现即改代码，禁止「已知问题后续再说」。
+
+| 触发条件（改动里出现） | 未通过条件 | 正确做法 |
+|------------------------|------------|----------|
+| `toDetail` / 独立 `*Detail` 路由 | 路由无 `activePath`，或 `showLink` 非 `false` | `detail-page` 三件套 |
+| 同上 | 默认场景缺 `keepAlive`/`moreTags`（业务未声明不要缓存） | 样板默认写出；不要缓存再删 |
+| 同上 | 详情页无 `initToDetail`，或 `name` 与路由不一致 | 对齐 `defineOptions` |
+| 列表页 | 无 `el-card.vts-page-card` / 无 `tableHeight` / 分页在 ReTableBar 外 | `crud-pages` L1–L8 |
+| `src/api/**` | 绕过 `@/utils/http`，或虚构 `/api` 前缀，或响应当 `success`/`code` | `http-api` |
+| 下载/导出 API | 无 `responseType: "blob"` | `http-api` / `download-export` |
+| 删除/危险操作 | 无确认框 | `feedback-loading` |
+| 编辑回显 | 整表 `formData = res.data` 破坏响应式 | `Object.assign`（`data-writeback`） |
+| 按钮权限需求 | 裸 `v-if` 角色判断，未用 `v-auth`/`ReAuth` | `permission-auth` |
+| 新菜单路由 | 父级无 `icon` 或业务页二次挂 `Layout` | `icons` + `core-kernel` |
+
 ## 选型与硬约束
 
 - [ ] 已读 `core-kernel`；addon/缺依赖时已读 `project-inventory`
@@ -34,8 +52,8 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 - [ ] addon 缺包按 inventory 第九节精确版本（禁止 `@latest`）
 - [ ] 列表方法名 `onSearch` / `reset`；HTTP 用 `@/utils/http` + `Result<T>`
 - [ ] 业务路由未二次挂 Layout
-- [ ] 独立详情：`showLink:false` + `activePath` + `toDetail` + `initToDetail`（细则 `detail-page`）
-- [ ] 列表布局按 `crud-pages` 黄金样板（`el-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内）
+- [ ] 独立详情：对照路由文件确认 `showLink:false` + `activePath` + `keepAlive`/`moreTags`（默认）+ `toDetail` + `initToDetail`
+- [ ] 列表布局按 `crud-pages` 黄金样板（`el-card.vts-page-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内；内容区无外层滚动条）
 
 ## TypeScript
 
@@ -88,13 +106,12 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 ## 业务
 
 - [ ] 提交前 `validate()`；删除有确认；提交有 loading；列表有 `v-loading`
-- [ ] 编辑回显正确；分页切换会拉数
+- [ ] 编辑回显正确（`Object.assign`）；分页切换会拉数
 
-### 列表→详情（命中 detail-page 时）
+### 列表→详情（改动含 toDetail / *Detail 路由时强制，禁止 N/A 糊弄）
 
-- [ ] 兄弟绝对 path；`showLink:false`；`activePath`=列表 path；非空 `title`
-- [ ] 仅 `toDetail`；详情 `initToDetail`；`name` 对齐
-- [ ] 按需 `keepAlive` / `moreTags`
+- [ ] **打开落盘路由文件**核对：兄弟绝对 path；`showLink:false`；`activePath`=列表 path；非空 `title`；默认 `keepAlive`+`moreTags`
+- [ ] 仅 `toDetail`；详情 `initToDetail`；`name` 对齐；`toDetail` 第 3 参 title 可辨识
 
 ### 列表布局（命中 crud-pages 时）
 

package/references/core-kernel.md

@@ -18,13 +18,13 @@ tags: [vue3, kernel, conventions, layout, router, http, crud, inventory]
 | 3 | 方法跟后端文档，**允许 GET / POST**；POST → `data`，GET → `params` |
 | 4 | 列表用 `useTableSearch`，方法名 **`onSearch` / `reset`** |
 | 5 | 业务路由 **禁止** 再挂 `component: Layout` |
-| 6 | 独立详情/编辑：路由与跳转按 **`detail-page`**（`showLink` / `activePath` / `toDetail` / `initToDetail`） |
+| 6 | 独立详情/编辑：按 **`detail-page` 三件套**（`showLink`+`activePath`+默认`keepAlive`/`moreTags` + `toDetail` + `initToDetail`）；`toDetail`≠自动侧栏高亮/缓存 |
 | 7 | 页面权限 `meta.roles`；按钮 `v-auth` / `ReAuth` |
 | 8 | 环境只用 `import.meta.env.VITE_*` |
 | 9 | i18n：`$t('中文key')` |
 | 10 | 禁止用 `v-html` 渲染不可信内容 |
 | 11 | 新依赖须用户确认；已有封装须复用；选型表指定库勿擅自替换 |
-| 12 | 列表布局按 **`crud-pages` 黄金样板**（`el-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内） |
+| 12 | 列表布局按 **`crud-pages` 黄金样板**（`el-card.vts-page-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内；仅表格体内滚动） |
 | 13 | addon 按 `project-inventory` 第九节精确版本安装；禁止 `@latest` |
 | 14 | 样式契约见下文「样式契约」 |
 
@@ -44,11 +44,15 @@ export default {
       component: () => import("@/views/xxx/list/index.vue"),
       meta: { title: "客户列表", roles: ["admin", "common"] },
     },
-    // 独立详情：兄弟路由 + showLink/activePath，完整约定见 detail-page
+    // 独立详情：兄弟路由 + showLink + activePath + keepAlive/moreTags，见 detail-page 三件套
   ],
 } satisfies RouteConfigsTable;
 ```
 
+### 抗略读
+
+命中模块须照其**强制完整样板**落盘；样板中的字段默认写出。壳层行为（tag / 侧栏 / keep-alive）以路由 meta + 项目已有实现为准，不假设 Hook 会「全自动」。
+
 ### 权限
 
 ```vue
@@ -119,6 +123,8 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 
 ### 独立功能页容器
 
+定高且内部滚动（与列表卡同类场景）：
+
 ```vue
 <div
   :style="{ height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)` }"
@@ -126,6 +132,7 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 >
 ```
 
+查询列表定高卡 → `crud-pages`（`el-card.vts-page-card` + `tableHeight`）。
 ## 六、资产分层
 
 附加 Hook/组件按功能模块加载（WebSocket、微信、附件、图表等）→ 见各专项与 `project-inventory`。

package/references/crud-pages.md

@@ -9,6 +9,8 @@ tags: [vue3, crud, list, form, detail, table, useTableSearch, page, layout]
 
 遵守 `core-kernel` / `http-api`。独立详情路由 → 同时加载 `detail-page`。回显 → `data-writeback`。
 
+**抗略读**：列表页必须整段照抄「列表黄金样板」；有独立详情时 **同批** 落 `detail-page` 三件套（禁止只写 `toDetail`）。方法名固定 `onSearch` / `reset`。
+
 ## useTableSearch
 
 ```typescript
@@ -21,20 +23,29 @@ useTableSearch(formQuery, searchFn, url)
 - 查询 / 重置：`onSearch()` / `reset()`
 - 列表：`tableData.value.tableList`
 - 分页请求：`pageNo` / `pageSize`；响应：`data.content` / `data.totalCount`
-- 高度：`tableHeight = content − formRef − paginationRef − otherRef − 50`
+- 高度：`tableHeight` 由 Hook 按「卡片内容区底边 − 表格顶边 − 分页」实测；左右分栏、`--vts-card-padding`、工具栏、`otherRef`（表上方）均自动消化；空数据仍保留表格占位高度。业务页只绑定，不手算魔法数
+
+## 内容区滚动约定
+
+| 场景 | 做法 |
+|------|------|
+| 查询列表（定高） | `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 跟随 |
 
 ## 列表黄金样板（唯一完整示例）
 
 | # | 必须 |
 |---|------|
-| L1 | `el-card` + `ref="content"`（禁止挂 `div`） |
+| 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 | 表格绑 `tableHeight`；分页在 `ReTableBar` `#default` 内 |
+| L6 | 表格绑 `ref="multipleTableRef"` + `tableHeight`；分页在 `ReTableBar` `#default` 内、表格下方 |
 | L7 | `RePagination`：`:pagination` + `@handle-current-change` / `@handle-size-change` |
-| L8 | 查询条件外模块包一根元素绑 `otherRef` |
+| L8 | 查询与表之间的额外模块包一根元素绑 `otherRef`（须在表格上方，高度计入 `tableTop`） |
 
 ```vue
 <script setup lang="ts">
@@ -112,6 +123,7 @@ function handleSizeChange(size: number) {
   <div>
     <el-card
       ref="content"
+      class="vts-page-card"
       shadow="never"
       :style="{
         height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`,
@@ -228,6 +240,8 @@ function handleSizeChange(size: number) {
 
 ## 列表 → 详情/编辑
 
+有独立详情/编辑路由时：**必须同时命中并深读 `detail-page`**。禁止只抄下面的 `toDetail` 就交卷。
+
 ```typescript
 import { useDetail } from "@/hooks/useDetail";
 const { toDetail } = useDetail();
@@ -244,7 +258,24 @@ function onEdit(row: Customer, mark: "edit" | "view") {
 }
 ```
 
-路由 meta 与详情页 `initToDetail` → **`detail-page`**。
+**同批必落兄弟路由 meta**（完整三件套见 `detail-page`；此处不可省略）：
+
+```typescript
+{
+  path: "/customer/detail",
+  name: "CustomerDetail",
+  component: () => import("@/views/customer/detail/index.vue"),
+  meta: {
+    title: "客户详情",
+    showLink: false,
+    activePath: "/customer/list",
+    keepAlive: true,
+    moreTags: true,
+  },
+},
+```
+
+详情页 `initToDetail` + `defineOptions({ name })` 对齐 → **`detail-page`**。
 
 ## 表单页
 
@@ -305,16 +336,17 @@ async function onSubmit() {
 },
 ```
 
-独立详情兄弟路由 → `detail-page`。禁止业务模块再挂 Layout。
+独立详情兄弟路由（含 `activePath` / `keepAlive` / `moreTags`）→ `detail-page`。禁止业务模块再挂 Layout。
 
 ## 反例（短表）
 
 | 错误 | 正确 |
 |------|------|
 | `handleSearch` / 手写分页 | `onSearch` / `useTableSearch` |
-| `ref="content"` 挂 div / 只用 minHeight | `el-card` + 固定 height |
-| 不绑 `tableHeight` / 分页在卡片外 | 样板 L6/L7 |
+| `ref="content"` 挂 div / 只用 minHeight / 缺 `vts-page-card` | `el-card.vts-page-card` + 固定 height |
+| 不绑 `tableHeight` / 分页在卡片外 / 手写魔法数扣高度 | 样板 L6/L7；高度交给 `useTableSearch` |
 | 额外模块不绑 `otherRef` | L8 |
-| 裸 `router.push` 开详情 | `toDetail`（见 detail-page） |
+| 只写 `toDetail`、详情路由缺 `activePath` | 三件套整段落盘（见 detail-page） |
+| 裸 `router.push` 开详情 | `toDetail` + meta（见 detail-page） |
 | `ReTableOperate :buttons` | `:list` |
 | `@show-collapse` | `@should-show-collapse` |

package/references/data-writeback.md

@@ -2,6 +2,19 @@
 
 > 按本文件示例编写，复用项目已有回显/回填约定与选择器回写方式，勿另起一套表单赋值实现。
 
+**抗略读**：编辑回显**必须** `Object.assign(formData, res.data)`，禁止 `formData = res.data` 破坏响应式。提交按钮默认带 `loading`。
+
+## 强制样板（编辑回显）
+
+```typescript
+async function getDetail() {
+  const { id } = getParameter.value;
+  if (!id) return;
+  const res = await getDetailApi({ id });
+  if (res.status === 200 && res.data) Object.assign(formData, res.data);
+}
+```
+
 ## 表单回显
 
 ### 新增/编辑页

package/references/design-system.md

@@ -415,7 +415,8 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 - [ ] 控件高度：input/button 计算高度 = 规范值（24/32/40 或规范预设）
 - [ ] 圆角：input、button、card、dialog 均为规范圆角
 - [ ] 表格：表头底色/文字色/字重符合规范
-- [ ] 卡片内边距：`.el-card__body` = 规范值（AntD 24px），不再是 5px
+- [ ] 卡片内边距：`.el-card__body` = 规范 `--vts-card-padding`（桥接 `--card-padding`）
+- [ ] 定高列表页：`el-card.vts-page-card` + `useTableSearch` 的 `tableHeight`；换 `--card-padding` 后列表仍无外层滚动条、分页完整、仅表格体内滚动
 - [ ] 表单标签：computed font-weight 为规范值（AntD/Semi = 400，非 700）
 - [ ] 弹窗：`--ds-dialog-bg` 为 **主题色轻渐变**（`primary-bg → component-bg`），非写死蓝渐变；`ElMessageBox` 内容区用 `--message-box-content-padding`（比 `el-dialog` body 更紧凑）
 - [ ] 侧栏：深色主题下 DevTools 检查 `.sidebar-container` computed `background` 为 **渐变**（非单色 `#001529`）；激活项块色 = `--primary-6`；Logo 区 = `--sidebar-logo-bg`
@@ -608,6 +609,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 5. `lay-content/index.vue`：`padding-top` 用 `--vts-layout-header-offset*`，禁止写死旧顶栏组合；**禁止**与 `$storage.configure.headerHeight` 双向联动  
 6. `lay-header`：布局/标签页变化须 `nextTick` 重测，且仅在高度变化时写回 `$storage.configure.headerHeight`  
 7. DevTools：顶栏 computed = **当前** `--header-height`；菜单项 = **当前** `--el-menu-item-height`（两者须不同）
+8. 定高列表页：`--card-padding` / `--vts-card-padding` 变更后，抽查一页查询列表——内容区无外层滚动条、分页完整、`tableHeight` 随 padding 变化
 
 #### 7.5.4 EP 菜单变量纪律
 

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

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`）：

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

@@ -320,6 +320,17 @@ src/layout/
 | 重测 | 切换 `layout`、`hideTabs`、`hiddenSideBar` 后 `nextTick` 再测一次（避免布局切换后仍用 localStorage 旧值） |
 | 消费 | 业务页通过 `useApp().headerHeight` 读 `$storage.configure.headerHeight`；`lay-content` 的 `padding-top` 仍用 `--vts-layout-header-offset*`（勿与 storage 双向绑定，避免重测循环） |
 
+### 内容区高度与滚动
+
+| 场景 | 卡片 / 高度 | 滚动落点 |
+|------|-------------|----------|
+| 查询列表 | `el-card.vts-page-card` + 固定 `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`；表格绑 `useTableSearch().tableHeight` | 仅 `el-table` 体内；分页在表格下方 |
+| 树 + 表分栏 | 同上定高卡；左右并排，高度走 Hook 几何实测 | 同查询列表 |
+| 长表单 / 详情 / 说明 | 同公式可用 `minHeight`；不绑 `tableHeight` | `.app-main` 内 `el-scrollbar` |
+| Card 内边距 | `--vts-card-padding` → `--card-padding` | 换规范只改令牌；列表高度由 Hook 实测跟随 |
+
+`.vts-page-card`：`overflow: hidden`，`.el-card__body` 高度 100%。样式在 `element-plus.scss`。
+
 ### 混合布局路由结构
 
 混合模式（mix）左侧栏只展示**一级**菜单，页面组件须挂在 **`children`** 下：

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"],
       },
     },
   ],

package/references/project-inventory.md

@@ -220,7 +220,7 @@
 | **useApp** | 全局应用状态（布局、字典、登出等） | `baseCodeGet(codeType)`、`filterValue()`、`headerHeight`、`svgLoading` |
 | **useDetail** | 列表→详情：写顶部 tag 并跳转 | `toDetail(name, params, title?, 'query'\|'params')`、`initToDetail(name)`、`getParameter`；路由配 `showLink:false`（不进侧栏）+`activePath`（见 `detail-page`） |
 | **useFormCheck** | 多表单校验聚合 | 追踪各字段校验状态，emit `form-validate` 事件 |
-| **useTableSearch** | 列表页搜索/分页/Loading/动态表高 | `content`（须绑 `el-card`）、`otherRef`（查询条件外模块的统一根元素，高度自动从 `tableHeight` 扣除）、`tableHeight`、`paginationRef`、`tableData`、`pagination`、`loading`、`onSearch()`、`reset()`、`formRef`、`gridRef`、`collapsed` / `showCollapse` / `collapsedToggle` |
+| **useTableSearch** | 列表页搜索/分页/Loading/动态表高 | `content`（须绑 `el-card.vts-page-card`）、`multipleTableRef`（建议绑 `el-table`）、`otherRef`（表上方额外模块）、`tableHeight`（卡片底边 − 表格顶边 − 分页；空数据仍有占位高）、`paginationRef`、`tableData`、`pagination`、`loading`、`onSearch()`、`reset()`、`formRef`、`gridRef`、`collapsed` / `showCollapse` / `collapsedToggle` |
 | **useTags** | 多标签页管理 | 右键菜单（刷新/关闭/关闭其他/全屏） |
 | **useTheme** | 主题切换（暗色/亮色） | 主题色生成、布局预设、缓存重置 |
 | **useWebSocket** | WebSocket 通信 | `subscribe()`、`send()`、`sendRaw()`、`isConnected` |