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

package/SKILL.md

@@ -13,6 +13,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 
 - 面向由 **vue3-web-temp** 脚手架搭出的业务项目（目录名/安装路径因人而异，以当前工作区为准）
 - 业务写法以本包 `references/` 为准；壳层行为（顶部 tag / 侧栏 / keep-alive / `useDetail`）以**当前项目**已有实现为准
+- **双轨**：无设计 handoff → 保持模版出厂令牌；有设计落地 → 读 `design-handoff.md`，按设计规范回填令牌（视觉关键尺寸须为 CSS 变量）
 
 ## 使用方式
 
@@ -24,11 +25,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 过了就算完」
+
 ## 模块路由表
 
 ### 始终加载
@@ -43,7 +53,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 |------|------|
 | addon / 查 Re* 名 / 装依赖 | `references/project-inventory.md` |
 | 写完代码后（闸门，非功能命中） | `references/code-quality.md` |
-| 设计交接块 / 上游令牌产出落地 | `references/design-handoff.md`（+ `design-system`） |
+| 设计交接块 / **design-handoff/v1 JSON** / 上游令牌产出落地 | `references/design-handoff.md`（+ `design-system`） |
 
 ### 标准业务面
 
@@ -60,7 +70,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 | **feedback-loading** | message、loading、确认框 |
 | **base-code-dict** | 字典、baseCode、码表 |
 | **api-check** | 联调、mock、契约、对接后端 |
-| **ui-components** | Re组件、公共组件、type.ts |
+| **ui-components** | 新建 Re*、type.ts、组件目录；**用法见各功能模块**（本文件仅索引） |
 
 ### 专项能力包
 
@@ -112,7 +122,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 +145,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.13",
+  "version": "1.1.15",
   "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,30 @@ 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` / `100vh` 减顶栏定高 / 无 `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` |
+| 列表查询区 `el-form` / 查询按钮 | 写了 `size="small"`（紧凑主题用户未要求） | 不写 size，用 default=`--control-height` |
+
 ## 选型与硬约束
 
 - [ ] 已读 `core-kernel`；addon/缺依赖时已读 `project-inventory`
@@ -34,8 +53,9 @@ 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.vts-page-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内；内容区无外层滚动条）
+- [ ] 独立详情：对照路由文件确认 `showLink:false` + `activePath` + `keepAlive`/`moreTags`（默认）+ `toDetail` + `initToDetail`
+- [ ] 列表布局按 `crud-pages` 黄金样板（`el-card.vts-page-card`+`content`、无 `100vh` 减顶栏、`tableHeight`、`otherRef`、分页在 ReTableBar 内；内容区无外层滚动条）
+- [ ] 顶栏高度仅 `--header-height` 等 CSS 令牌；禁止 JS 测顶栏 / `platform-config` 顶栏像素字段 / `useApp` 导出顶栏高度
 
 ## TypeScript
 
@@ -73,7 +93,7 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 ## 样式
 
 - [ ] `scoped`；色用 CSS 变量；优先 UnoCSS 连字符类（`p-5` 非 `p5`）
-- [ ] 语义色 `bg-bg_color` / `--el-*`；尺寸档位见 `core-kernel` 样式契约
+- [ ] 语义色 `bg-bg_color` / `--el-*`；尺寸档位见 `core-kernel` 样式契约（查询区 default 32，禁止误用 small 24）
 - [ ] 图标见 `icons`；忌滥 `!important`；选择器 ≤3 层
 - [ ] 全局 EP 覆盖在 `element-plus.scss`；侧栏色用 `html[data-theme]`
 - [ ] 主色经 `setEpThemeColor()`；颜色处理用 `chroma-js`
@@ -83,18 +103,19 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 - [ ] 规范识别回执；令牌 / `platform-config.json` / 侧栏主题一致
 - [ ] 已建 `design-tokens.scss`；`index.scss` 中其 `@use` 最前
 - [ ] 冲突清单已逐条处理（见 `design-system`）
-- [ ] 有上游设计产出时已读 `design-handoff`；`EpThemeColor`/`Theme`/侧栏桥接/`Version` 一致
+- [ ] 有上游设计产出时已读 `design-handoff`：JSON 优先；按**全量令牌核对表 A～E**回填或回执「保留出厂」；`ShowModel: card`；错误色 `#F5222D`；弹窗/壳层改令牌即生效
+- [ ] **无**设计落地时未改出厂主色 / ShowModel / 壳层 / 弹窗几何默认
+- [ ] 组件尺寸三档已落地并桥接 `--el-component-size*`；缺档落到 default；未全局强制 `size="small"`；**查询区不写 size**（三档对照表 ≠ 查询区要用 small）
 
 ## 业务
 
 - [ ] 提交前 `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.vts-page-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内；仅表格体内滚动） |
+| 12 | 列表布局按 **`crud-pages` 黄金样板**（`el-card.vts-page-card`+`content`、无 `100vh` 减顶栏定高、`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
@@ -78,7 +82,7 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 
 | Hook | 用途 | 详例 |
 |------|------|------|
-| `useApp` | headerHeight、字典、svgLoading | — |
+| `useApp` | 字典、svgLoading | — |
 | `useTableSearch` | 列表查询分页 | `crud-pages` |
 | `useDetail` | 详情跳转与顶部 tag | `detail-page` |
 | `useFormCheck` | 多表单校验 | `data-writeback` |
@@ -107,28 +111,27 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 
 ### 组件尺寸
 
-| 场景 | 档位 |
-|------|------|
-| 查询区表单/按钮、工具栏按钮 | default（不写 size） |
-| 表格 / 分页 | `:size="size"`（ReTableBar 透出） |
-| 弹窗内表单 | default |
-| 登录/整屏主表单 | `large` |
-| 移动端 Vant | 见 `mobile-h5` |
+| 场景 | 档位 | 像素（令牌） |
+|------|------|--------------|
+| 查询区表单/按钮、工具栏按钮、弹窗内表单 | **default（不写 size）** | `--control-height`（设计 `--component-size-base`，默认 32px） |
+| 表格 / 分页 | `:size="size"`（ReTableBar 透出） | 随密度切换，与表单档位独立 |
+| 表格行内操作、紧凑工具条 | `small` | `--control-height-sm`（24px） |
+| 登录/整屏主表单主按钮 | `large` | `--control-height-lg`（40px） |
+| 移动端 Vant | 见 `mobile-h5` | — |
 
-存在 `design-tokens.scss` 时：零新增硬编码裸值；适配流程见 `design-system`。
+- **禁止**查询区 / 标准业务表单写 `size="small"`，也**禁止** `el-config-provider` 全局强制 `small`（除非用户明确要求紧凑主题）。
+- 存在 `design-tokens.scss` 时：零新增硬编码裸值；三档桥接与 EP 映射见 `design-system` 7.5.8。
+- 适配流程见 `design-system`。
 
 ### 独立功能页容器
 
-定高且内部滚动（与列表卡同类场景）：
+定高且内部滚动（与列表卡同类场景）——优先 `el-card.vts-page-card`；非 Card 根节点用 `vts-page-fill`：
 
 ```vue
-<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">
 ```
 
-查询列表定高卡 → `crud-pages`（`el-card.vts-page-card` + `tableHeight`）。
+查询列表定高卡 → `crud-pages`（`el-card.vts-page-card` + `tableHeight`，禁止 `100vh` 减顶栏定高）。
 ## 六、资产分层
 
 附加 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
@@ -27,17 +29,20 @@ useTableSearch(formQuery, searchFn, url)
 
 | 场景 | 做法 |
 |------|------|
-| 查询列表（定高） | `el-card.vts-page-card` + 固定 `height: calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`；表格绑 `tableHeight`；**仅表格体内滚动**；分页在表格下方；整页无外层滚动条 |
+| 查询列表（定高） | `el-card.vts-page-card`（禁止 `100vh` 减顶栏定高）；表格绑 `tableHeight`；仅表格体内滚动；分页在表格下方；整页无外层滚动条 |
 | 树 + 表分栏 | 同上；左侧树、右侧表共用定高卡，高度仍走 `useTableSearch` 几何实测 |
-| 长表单 / 详情 / 说明类 | 可用 `minHeight` 同公式；内容超出时由 `.app-main` 内 `el-scrollbar` 滚动 |
-| Card 内边距 | 一律走 `--vts-card-padding`（桥接 `--card-padding`）；换规范只改令牌，列表高度由 Hook 跟随 |
+| 长表单 / 详情 / 说明类 | 根节点 `min-height: 100%`（或 `:style="{ minHeight: '100%' }"`）；超出由 `.app-main` 内 `el-scrollbar` 滚动 |
+| 非 Card 整页填满 | 根节点加 `class="vts-page-fill"` + `height: 100%` / `h-full` |
+| Card 内边距 | 一律走 `--vts-card-padding`（桥接 `--card-padding`）；换规范 / `--vts-margin` 变化由壳层 flex 链 + Hook 自动跟随 |
+
+> **壳层原理**（`lay-content`）：`.main-content` 用 `padding: var(--vts-margin)`（不用 margin）；定高页 `.main-content:has(.vts-page-card)` / `.vts-page-fill` 为 `height: 100%`；`.vts-page-card` 填满。`html/body/#app/.app-wrapper/.main-container/.app-main` 均为 `height:100%; overflow:hidden`。禁止业务页 `100vh` 减顶栏定高。
 
 ## 列表黄金样板（唯一完整示例）
 
 | # | 必须 |
 |---|------|
 | L1 | `el-card` + `class="vts-page-card"` + `ref="content"`（禁止挂 `div`） |
-| L2 | 固定 `height: calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`（禁止只用 `minHeight`） |
+| L2 | 不要写 `height: calc(100vh - …)` / 不要用 JS 测顶栏定高（壳层 + `.vts-page-card` 已填满） |
 | 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>` |
@@ -61,7 +66,7 @@ import { message } from "@/utils/message";
 
 defineOptions({ name: "CustomerList" });
 
-const { headerHeight, svgLoading } = useApp();
+const { svgLoading } = useApp();
 const formQuery = reactive<CustomerQuery>({ keyword: "", status: undefined });
 
 const {
@@ -123,9 +128,6 @@ function handleSizeChange(size: number) {
       ref="content"
       class="vts-page-card"
       shadow="never"
-      :style="{
-        height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`,
-      }"
     >
       <div>
         <el-form
@@ -234,10 +236,12 @@ function handleSizeChange(size: number) {
 </template>
 ```
 
-补充：`ReTableOperate` 用 `:list`；`defineOptions.name` === 路由 `name`；`headerHeight` / `svgLoading` 来自 `useApp()`。
+补充：`ReTableOperate` 用 `:list`；`defineOptions.name` === 路由 `name`；`svgLoading` 来自 `useApp()`；列表定高走壳层令牌 + `vts-page-card`。
 
 ## 列表 → 详情/编辑
 
+有独立详情/编辑路由时：**必须同时命中并深读 `detail-page`**。禁止只抄下面的 `toDetail` 就交卷。
+
 ```typescript
 import { useDetail } from "@/hooks/useDetail";
 const { toDetail } = useDetail();
@@ -254,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`**。
 
 ## 表单页
 
@@ -315,16 +336,17 @@ async function onSubmit() {
 },
 ```
 
-独立详情兄弟路由 → `detail-page`。禁止业务模块再挂 Layout。
+独立详情兄弟路由（含 `activePath` / `keepAlive` / `moreTags`）→ `detail-page`。禁止业务模块再挂 Layout。
 
 ## 反例（短表）
 
 | 错误 | 正确 |
 |------|------|
 | `handleSearch` / 手写分页 | `onSearch` / `useTableSearch` |
-| `ref="content"` 挂 div / 只用 minHeight / 缺 `vts-page-card` | `el-card.vts-page-card` + 固定 height |
+| `ref="content"` 挂 div / `100vh` 减顶栏定高 / 缺 `vts-page-card` | `el-card.vts-page-card`（高度交给壳层） |
 | 不绑 `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);
+}
+```
+
 ## 表单回显
 
 ### 新增/编辑页