@qilitt-mickey/vue3-temp-skill 1.2.5 → 1.2.7

package/references/code-quality.md

@@ -1,172 +1,56 @@
 ---
 name: code-quality
-description: 生成后强制质量闸门。写完/改完代码后重读本清单、对照落盘文件、必跑 lint:fix 与 type-check，最终回复含「代码质量审查」结果块。
-scope: project
-tags: [code-review, quality, checklist, lint, typescript, vue3, security, performance, gate]
+description: 修改代码后检查模板规范、类型、业务行为及视觉验收；按实际文件执行工程命令并记录未通过项。
 ---
 
-# 代码质量审查（生成后闸门）
-
-写完/改完 Vue/TS 后执行。最终回复须含结果块；只把本模块写入「命中模块」不算完成。
-
-## 协议（按序）
-
-1. 重读本文件
-2. 列出本轮改动路径，对照下方清单；**硬失败表命中则先改代码再继续**
-3. 业务项目根目录必跑：`pnpm lint:fix` → `pnpm type-check`；**本轮产出或修改了设计变更集（`.design/changeset*.json`）时，同一条命令链追加终态闸：`node <技能目录>/scripts/apply-final-gate.mjs --project <项目根> --container-width <内容区宽>`，取得 `FINAL-GATE: PASS` 才算通过**（该命令串联 changeset-selfcheck → parser match → parser audit → design-audit 四闸，PASS 凭证写入 ledger.json；只做设计侧产出、未落项目时至少实跑 changeset-selfcheck 并附 exit 0 输出原文）。**禁止把 lint/type-check 单独当「全部质量闸门」汇报**——它们不含任何还原度检查
-4. 失败则修代码并重跑，直至通过或写明阻塞
-5. 最终回复追加：
-
-```markdown
-## 代码质量审查
-- 闸门：已执行 code-quality（生成后）
-- 改动文件：`path/a`、`path/b`、…
-- 清单：选型 ✅ / 类型 ✅ / 组件 ✅ / API ✅ / 安全 ✅ / 业务 ✅ / 列表→详情 ✅或N/A / 列表布局 ✅或N/A / 风格 ✅
-- 设计落地：通道活性 ✅ / 锚点契约 ✅ / 结构施工 ✅或N/A / 覆写提权 ✅ / 登记表覆盖率 ✅或N/A（仅本轮无设计变更集时可用 N/A）/ 渲染态验收 ✅或N/A（**同左；有变更集而无 oracle = 硬失败，不得 N/A**）/ 设计闸命令链 ✅（selfcheck + match + audit 输出原文已附）或N/A（无变更集）
-- 硬失败：无 | 已拦截并修正：…
-- 已修正：…（无则写「无」）
-- 命令：`pnpm lint:fix` → …；`pnpm type-check` → …
-- 待确认：仅限新依赖审批 / 需用户决策的外部动作（无则写「无」）；设计变更集落地项一律不得列此（见 design-apply「零缺口交付」）
-```
-
-## 硬失败（对照落盘文件；命中即未通过）
-
-lint / type-check **过了也不能放过**下列项。发现即改代码，禁止搁置已知问题。
-
-| 触发条件（改动里出现） | 未通过条件 | 正确做法 |
-|------------------------|------------|----------|
-| `toDetail` / 独立 `*Detail` 路由 | 路由无 `activePath`，或 `showLink` 非 `false` | `detail-page` 三件套 |
-| 同上 | 默认场景缺 `keepAlive`/`moreTags`（业务未声明不要缓存） | 样板默认写出；不要缓存再删 |
-| 同上 | 详情页无 `initToDetail`，或 `name` 与路由不一致 | 对齐 `defineOptions` |
-| 列表页 | 无 `el-card.vts-page-card` / `100vh` 减顶栏定高 / 无 `tableHeight` / 分页在 ReTableBar 外 / 操作列手写多按钮未用 `ReTableOperate` / 操作列写死 `width` 未用 `resolveOperateColumnWidth` / `ReTableOperate` 未传 `:size="size"` | `crud-pages` L1–L9 |
-| `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` |
-| 本轮新增 addon 并引用对应 `Re*` / Vant / 微信 | 已装包但 `tsconfig exclude` 仍含该路径，或 `addon-enable` 要求的 build/src 未改 | 按 **`addon-enable.md`** 对应章节恢复后重跑 type-check |
-| 设计层（`design-shell.scss` / 页面 `scoped`）新增规则 | 与对手**同权重**（对手为组件 `<style scoped>` 时平手即失效——组件样式在全局之后注入），或对手带 `!important` 而本条没带 | 按 `priority.strategy` 提权；**数权重，不许目测** |
-| 本轮产出/修改了设计变更集（`.design/changeset*.json`） | ① 变更集 `mode` 非 `restore`（缺 mode / 写 design 均为硬错误——无登记表、无基线的轻量变更集落地后必然「只变主题色、布局细节零变化」）；② 变更集 `coverage.page_types` 命中注册基线页型，却缺 `oracle.mockup` 或 `coverage.registry`（基线三件套是还原交付的固有组成）；③ 设计闸未实跑（selfcheck exit 0 输出原文未附 / `match --registry` / `design-audit` 缺任一）；④ notes 的覆盖话术与 coverage 字段矛盾（如无三件套却写「等价覆盖全量」） | 补齐三件套（oracle 值可由规范派生并在 notes 声明「未做浏览器实测」）后重跑全部设计闸；范围疑问停下向用户多轮询问确认——不存在降级出口 |
-| 变更集带 `oracle` | ① `oracle.mockup` 不是本页型的**场景基线图**（对照注册表 `baseline.<页型>.mockup`）；② 基线图色板（图内 `data-mockup-theme`）与本次主题（`changeset.theme`）不一致**且未声明** `oracle.theme_mapping`；③ `oracle.sids` 与 `changes[]` 未双向闭合（存在欠声明 / 无基线点位）。**注意：主题 ≠ 基线图色板本身不是违规**——基线图是场景基线、与主题无关，声明 `theme_mapping`（色值归一）后照常全量施工，**不得**把主题不一致当回流理由缩水成只换主题色 | 视缺口而定：缺 `theme_mapping` → 回流设计侧补声明；`sids` 未闭合 → 回流设计侧补齐后再开工，禁止直接施工 |
-| `element-plus.scss` / `sidebar.scss` 等样式消费层 | `var(--font-size-*)` 用于 `line-height` / `height` 等非字号属性 | 查 TSB：`classifyToken` + `PROPERTY_FORBIDDEN`；`line-height` → `--line-height` 或 `--el-menu-item-height` |
-| `element-plus.scss` 内视觉规则（shadow/hover/transition） | 出现非令牌引用的裸 hex / px / rgba 值 | 全部改为 `var()` 引用令牌 |
-| 视觉规则新增 | `dark.scss` 缺少对应暗色覆盖 | 每条新规则在 `html.dark` 内有对应覆盖 |
-| 设计变更集落地（`design-apply`） | 声明已落地但节点无对应锚点（`anchor.kind` 目标不存在：类未绑 / 变量无消费者 / 属性未挂） | 先补锚点（属「补通道」申报）；锚点缺失即为挂载点缺口，禁止用更宽选择器蒙混 |
-| 同上 | `apply_via` 为 `class_name` / `attribute` / `slot_content` / `data_source` 之一，却只写了 CSS 而没改结构/绑定 | 按 `structure_ops` 施工（改模板 / 绑 `class-name` / 改 formatter / 挂 `data-*`），CSS 换不掉数据驱动点位 |
-| 同上 | 全局覆写与组件 `scoped` 同权重生效失败（收口 `visible:false` / opacity / 几何覆盖不生效） | 按 `priority` 声明提权（`scope_qualified` / `self_plus_important` / `deep_qualified`），不得靠「后置加载」赌注入顺序 |
-| 同上 | 容器语义类挂错节点：把「行/栏」语义类挂到**纵向复合容器**根节点（如把 `.vts-action-bar`（`flex-direction: row`）挂到 `ReTableBar` 根节点，而根节点是「工具栏行 + 表格 + 分页」） | 只能挂到该语义真正对应的那一层（工具栏行在 `ReTableBar` 组件内部）；挂错会让兄弟节点并排、几何与 `tableHeight` 实测失准。修法是**移动挂载点**，不是给根节点补 `flex-direction: column` 打补丁 |
-| 同上 | 词典 `selector` / `css_vars` 指向的选择器在真实 DOM 不存在（死通道 / 死令牌） | 跑 `node parser/index.js audit` 复核；死令牌双删、死通道补消费者挂载点 |
-| 同上 | 变更集带登记表时 `C < A`（有规范子项未落进 `changes[]` / `visible` / `pending`）——组级台账过了但组内子项被静默丢失 | 跑 `node parser/index.js match --registry`；缺口逐条点名回流设计侧，**禁止采信自报的 `coverage` 数字**（parser 当场重算） |
-
-## 选型与硬约束
-
-- [ ] 已读 `core-kernel`；addon/缺依赖时已读 `project-inventory` + **`addon-enable`**
-- [ ] 复用已有 Re* / Hook / utils；选型库未擅自替换；新依赖已待确认
-- [ ] addon 缺包按 inventory 第九节精确版本（禁止 `@latest`）；装包后已按 **`addon-enable`** 恢复配置与 `tsconfig exclude`
-- [ ] 列表方法名 `onSearch` / `reset`；HTTP 用 `@/utils/http` + `Result<T>`
-- [ ] 业务路由未二次挂 Layout
-- [ ] 独立详情：对照路由文件确认 `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
-
-- [ ] props / API / `ref` / `reactive` / 事件参数有明确类型，忌 `any`
-- [ ] `defineProps<Props>()`；忌 `@ts-ignore` / `@ts-nocheck`（除非注释原因）
-- [ ] 类型放 `type.ts` 或 `types/`
-
-## Vue 组件
-
-- [ ] `<script setup lang="ts">` + `defineOptions({ name })`
-- [ ] Props/Emits 在同目录 `type.ts`；`<style lang="scss" scoped>`
-- [ ] 文案用 `$t('中文')`
-
-## API
-
-- [ ] 调用在 `src/api/`；方法跟后端；POST→`data`，GET→`params`
-- [ ] URL：`VITE_API_BASE_URL` + path；忌硬编码域名 / 虚构 `/api` 前缀
-- [ ] `Result<T>`；分页 `content` / `totalCount` / `pageNo` / `pageSize`
-- [ ] 驼峰字段；`Long`/`BigDecimal`→`string`；下载 `responseType: "blob"`
-- [ ] 加解密靠 `VITE_ENCODE_SWITCH`；无单请求 `crypto: true`
-- [ ] 组件调用有 `try/finally` 或 `try/catch`
-
-## 安全
-
-- [ ] 无硬编码密钥/Token/密码
-- [ ] 提交前校验；忌不可信内容 `v-html`
-- [ ] 权限用 `v-auth` / `ReAuth`；敏感操作有确认框
-
-## 性能
-
-- [ ] 路由组件 `() => import()`；大列表分页或虚拟滚动
-- [ ] 图表 `onUnmounted` → `dispose()`；`v-for` 稳定 `:key`
-- [ ] 能 `computed` 不用多余 `watch`；监听器卸载时移除
-
-## 样式
-
-- [ ] `scoped`；色用 CSS 变量；优先 UnoCSS 连字符类（`p-5` 非 `p5`）
-- [ ] 语义色 `bg-bg_color` / `--el-*`；尺寸档位见 `core-kernel` 样式契约（查询区 default 32，禁止误用 small 24）
-- [ ] 图标见 `icons`；忌滥 `!important`；选择器 ≤3 层
-- [ ] 全局 EP 覆盖在 `element-plus.scss`；侧栏色用 `html[data-theme]`
-- [ ] 主色经 `setEpThemeColor()`；颜色处理用 `chroma-js`
-
-### 主题与令牌（改主题/样式时）
-
-- [ ] 令牌 / `platform-config.json` / 侧栏主题三处一致
-- [ ] 未要求时不改出厂主色 / ShowModel / 壳层 / 弹窗几何默认
-- [ ] 组件尺寸三档已落地并桥接 `--el-component-size*`；缺档回退至 default；查询区不写 size
-
-## 业务
-
-- [ ] 提交前 `validate()`；删除有确认；提交有 loading；列表有 `v-loading`
-- [ ] 编辑回显正确（`Object.assign`）；分页切换会拉数
-
-### 列表→详情（改动含 toDetail / *Detail 路由时强制，禁止以 N/A 跳过）
-
-- [ ] **打开落盘路由文件**核对：兄弟绝对 path；`showLink:false`；`activePath`=列表 path；非空 `title`；默认 `keepAlive`+`moreTags`
-- [ ] 仅 `toDetail`；详情 `initToDetail`；`name` 对齐；`toDetail` 第 3 参 title 可辨识
-
-### 列表布局（命中 crud-pages 时）
-
-- [ ] 对照 `crud-pages` L1–L9（不在此复述示例）
-- [ ] 查询区 `vts-filter-area`（禁止旧写法 `bg-bg_color p-5` 裸挂 div）；展示区 `ReTableBar` 外包 `.vts-table-area`
-
-### 高度模式与结构约束（改动内容区高度 / DOM 结构时强制）
-
-- [ ] 定高页靠 `data-content-mode="fixed"` / `vts-page-card` / `vts-page-fill` 三通道之一，禁止 `calc(100vh - …)` / JS 测顶栏
-- [ ] `data-content-mode` 声明在路由组件根节点（`class="main-content"` 处），值仅 `fixed` / `scroll`；未声明时走自动探测兜底（自动分支带 `:not([data-content-mode])` 守卫，与显式声明互斥）
-- [ ] **填满链完整**：定高页从页面根到表格/画布容器，每层需填满的节点都带 `data-fill`（横向分栏用 `data-fill="row"`）；换了视觉容器时属性已平移到新容器，未丢失
-- [ ] **结构层零改动**：`lay-content/index.vue` 的 `.main-content[data-content-mode]` 与 `element-plus.scss` 的 `[data-fill]` 未被设计还原改写（换容器走属性平移，不重写结构层）；亦无「为保高度而放弃设计还原」
-- [ ] `useTableSearch` 结构约束不破坏：`content` 绑定定高容器（换容器后仍绑）；`otherRef` 在表格上方；分页与表格同容器且在其下方；`multipleTableRef` 绑定 el-table（详见 hook 源码 JSDoc「结构约束」节）
-- [ ] 设计变更集（`admin.content.container` 的 `form` 字段，`fixed` / `scroll` / `auto`）翻译为 `data-content-mode` 属性，不得改用其他自定义属性名
-
-### 设计变更集合规（design-apply 时强制，禁止以 N/A 跳过）
-
-- [ ] 变更集外点位零改动（diff 只含变更集提到的文件/选择器）
-- [ ] `visible: false` 模块代码仍存在（只隐藏不删除）
-- [ ] 未修改 `src/components/` Re* 组件库源码（底线一）；未改业务逻辑层 API/状态/事件（底线二）
-- [ ] 两层样式全部落在条目 `style_scope` 作用域内，无全局泄漏；`!important` 仅用于 `priority.strategy=self_plus_important` 或「对手为组件 scoped 且提权后实测仍平手」两种情形，且带理由注释
-- [ ] 无内联硬编码色值；全部走 CSS 变量（css_vars 层）或 `:deep()` 隔离（custom_style_map 层）
-- [ ] 新增视觉规则在 `dark.scss` `html.dark` 有对应覆盖
-- [ ] 能力缺口（词典缺 ID / 缺字段枚举 / 缺 form）已当场落地并写临时映射，未进清单；`缺口清单` 只含意图缺口（设计侧未给值 / 值非法）且已注明回流设计侧；mapping 临时新增后 `node parser/index.js build --dry` 通过
-- [ ] 设计层落点文件 `src/styles/design-shell.scss` 存在且经 `index.scss` 末位 `@use` 加载（缺失即自举重建并申报补通道）
-- [ ] **映射通道活性**：本轮用到的词典条目，其 `selector` / `css_vars` 在真实 DOM 可命中、CSS 变量有消费者（已跑 `audit` 或逐条核对，无死通道 / 死令牌）
-- [ ] **锚点契约**：变更集 `anchor` 声明的锚点存在；`layer=inner` 的点位已解析到内层文本盒（`.cell` / 文本节点宿主），未错落在宿主盒上
-- [ ] **结构施工**：`apply_via` 非 `style_override` 的点位已按 `structure_ops` 改结构/绑定（`class-name` / formatter / `data-*` / 渲染分支），未只用 CSS 冒充落地；申报了结构增量施工
-- [ ] **出厂形态互斥收口（`suppress` 兑现）**：变更集每条带 `form` 的点位，其 `suppress` 清单逐通道收口完毕（优先令牌重映射），交付说明给出「通道 → 收口方式」对照；漏一条 = 出厂旧装饰残留（右竖条 / 旧激活底色块 / hover 才显关闭钮等都属此类）
-- [ ] **覆写提权 / 同权重失效检查**：`priority` 声明的每条规则都**真数过权重**——写出特异度三元组 `(a,b,c)` **逐位比较（先 `b` 后 `c`）**：对手为组件 `<style scoped>` 时本条 `b` 必须严格更高（**平手即判失效**并提权）；对手带 `!important` 时本条必须同样 `!important`；**`html` / `body` 只加 `c` 位，对手 `b` 更高时无效**（如出厂 `body[layout] .sidebar-container .el-menu-item` 为 `b=3`，本层 `html body .sidebar-container .el-menu-item` 只有 `b=2` → 一律失效，须靠**加祖先类**把 `b` 抬平）。**出厂用 `var(--vts-theme-*)` 间接设属性时，先走「令牌重映射」**（在令牌宿主作用域重声明令牌）而不是抢属性。收口（`display:none` 等）与几何覆盖必须实测生效，未被组件 `scoped` / 出厂全局规则反压
-- [ ] **模板源码注释中性**：对模板文件的改动中，注释只描述「这段代码做什么」；语义 ID / 协议步骤号 / 缺口·自举·申报等面向 AI 的纪律条款不得写入模板源码注释（一律留在技能侧文档）
-
-### 渲染态验收（变更集含 `oracle` / 效果图有 `data-sid` 时强制）
-
-- [ ] **oracle 基线可用**：`oracle.mockup` 是本页型的场景基线图（**与本次主题无关**——任何主题都读同一张，不因换主题改图 / 漏读 / 跳抽）；基线图色板（图内 `data-mockup-theme`）与本次主题（`changeset.theme`）不一致时已声明 `oracle.theme_mapping: { "from": "<基线图色板>", "to": "<本次主题>" }`（verify 带 `--from-theme/--to-theme` 做色值归一，几何 / 结构 / 字号逐点照比）；`oracle.sids` 与 `changes[]` 双向闭合（无欠声明点位、无「已声明却无基线」点位）——`parser match` 已自动报出，未报错才算通过
-- [ ] **登记表覆盖率闭合**（变更集带登记表时）：`match --registry` 输出 `C = A`、无缺口，且无「效果图标注缺口」（恒存在子项在效果图上都有同名 `data-sid`）
-- [ ] 项目同名 `data-sid` 元素已渲染，抽取 computed style 与效果图期望值逐点 diff
-- [ ] diff 结果无未解释缺口；有缺口者已按三类（选择器落空 / 权重被压 / 语境错位）归因并修正，未用 `!important` 掩盖
-- [ ] 验收结果写入最终回复（命中 / 缺口 / 归因 / 修正），不得只报「已完成」
-
-## 代码风格
-
-- [ ] `const`/`let`；驼峰；组件大驼峰；无未使用导入；无残留 `console.log`
+# 执行检查
+
+1. 读取本轮修改文件和原有未提交 diff；区分视觉修改、明确授权的业务修改和用户原有工作。
+2. 对照下列硬约束检查实际代码，命中未通过项时修复后重测；仅完成自报清单不得交付。
+3. 在目标项目按 `package.json` 执行 `pnpm lint:fix` 和 `pnpm type-check`；运行 lint 自动修复前核对工作区，检查并避免带入本轮范围外的自动改动。共享组件、入口、布局或构建变化时执行 `pnpm build` 及已有相关测试。
+4. 对依赖或环境导致的失败保留命令、退出码及错误，区分既有错误与新增错误；不虚报通过，不修复无关问题。
+5. 视觉任务执行 `visual-verification.md`，保存原稿/目标截图、逐区域结果和业务基线回归；功能任务执行需求对应交互回归。
+6. 完成条件：工程、业务及本次视觉要求全部有真实检查证据；必需项未通过或未执行时保持未完成。
+
+## 硬约束
+
+| 范围 | 核对要求 |
+|---|---|
+| HTTP | 经 `@/utils/http`；按实际 `Result<T>`、方法和 URL；GET 用 `params`，POST 用 `data`；下载使用 blob 响应 |
+| 类型 | `Long` / `BigDecimal` 用 string；Props、Emits、事件、接口数据明确类型；不以 any 或关闭类型检查掩盖问题 |
+| 列表 | 保留 `useTableSearch` 的 `onSearch` / `reset`、查询、分页、排序、选择、加载及错误行为 |
+| 列表组件 | 复用 ReTableBar / RePagination / ReTableOperate；保留密度、动态列、操作权限、事件分发及 `resolveOperateColumnWidth` 能力 |
+| 高度与滚动 | 保持 `content`、`otherRef`、`multipleTableRef`、分页与表格同容器约束；`data-content-mode` / `data-fill` 随新视图结构正确迁移 |
+| 视觉改版 | 可调整卡片根节点、区域顺序、Slots、Props、布局和项目自有 Re* 表现层；保持对外 API、数据流和功能兼容，不以默认样板外观拒收明确设计 |
+| 路由 | 业务路由不二次挂 Layout；使用 `satisfies RouteConfigsTable`；保留既有路由、菜单和权限 |
+| 详情 | 按 `detail-page` 保留 showLink / activePath / keepAlive / moreTags、toDetail / initToDetail；组件 name 与路由对应 |
+| 权限与安全 | 使用 `v-auth` / ReAuth；保留敏感操作确认；不使用不可信 v-html，不硬编码密码、Token 或密钥 |
+| 回显与提交 | 保持响应式、校验、提交 loading、异常处理和回显；按项目实际实现检查 Object.assign 等写法 |
+| 依赖 | 从实际依赖与锁文件核对；新增包须确认，addon 按精确版本和 addon-enable 接线，不安装 latest |
+| Vue | 使用 script setup lang=ts、defineOptions；类型按项目约定组织；保留 i18n、生命周期清理和稳定 key |
+| 样式 | 使用 CSS 变量、项目令牌和规范 UnoCSS 连字符类；全局与 scoped 穿透语法匹配；不修改 node_modules |
+| 主题 | 有设计时按设计值映射令牌；没有设计时保持当前视觉；保留现有主题/密度能力，未提供的主题不伪造设计匹配结论 |
+| 共享组件 | 核对所有调用处，新增视觉能力保留旧默认；不能为一页还原破坏其他页面 |
+
+## 业务保持检查
+
+- 对照当前工作区采集的业务基线，核对接口、参数、字段、筛选项、列、操作、状态、权限、路由、字典和校验。
+- 搜索、重置、分页、排序、选择、详情、编辑、校验、关闭/取消和错误反馈按受影响范围实际操作。
+- 确认菜单、列、筛选项和按钮的数量仍来自项目；不依据 Demo 增删功能，不把项目数据替换成设计样例。
+- 视觉重构涉及 v-model、事件绑定、条件渲染、Teleport 或组件拆分时，逐项验证数据和事件未断。
+- 新业务仅按用户明确需求验收；没有业务增量授权时把业务语义变更判为未通过。
+- 完成条件：所有受影响业务项通过静态对照与必要的实际操作；仅源码字符串相同不足以证明行为正常。
+
+## 视觉检查
+
+- 按 `design-apply.md` 确定目标映射；按 `visual-verification.md` 检查每个请求区域、状态和视口。
+- 检查真实绘制节点和所有实例，不以类名文本出现证明挂载，不以 CSS 文件存在证明加载。
+- 检查父布局、旧偏移、填满链、滚动条、表头、长文本、操作列、菜单折叠、浮层和共享页面回归。
+- 对无渲染、无原稿、无素材、无法登录和数据环境不完整逐项标记未验证；有设计任务时不得以 N/A 跳过整体视觉验收。
+- 不运行不存在的历史 parser、登记表或终态闸脚本；不把旧脚本输出当作当前工作流的完成证明。
+- 完成条件：原稿、目标和逐项结果可读取，未决差异全部披露。
+
+## 交付记录
+
+- 列出修改范围、目标路由、实际运行命令及结果、业务回归、视觉检查范围和产物路径。
+- 将未解决问题与未执行检查单独列出；不使用「所有闸门通过」覆盖缺失的渲染或业务验证。

package/references/core-kernel.md

@@ -7,7 +7,16 @@ tags: [vue3, kernel, conventions, layout, router, http, crud, inventory]
 
 # 核心内核（core-kernel）
 
-始终加载。库/组件/安装表见 `project-inventory.md`（按需）。列表完整样板见 `crud-pages`；详情跳转见 `detail-page`；HTTP 细节见 `http-api`。
+始终加载。按需读取 `project-inventory.md`、`crud-pages.md`、`detail-page.md` 和 `http-api.md`，并以目标项目当前源码核对示例。
+
+## 设计还原分支
+
+- 有设计输入时同时执行 `design-apply.md`；保留本文件的 HTTP、类型、权限、路由、状态和组件接口约束。
+- 将默认样板的外观、卡片形式、尺寸、间距和视觉排列作为无设计时的默认值；有明确原稿时按原稿调整视图和项目自有组件表现层。
+- 将颜色与尺寸实值落入 CSS 变量，消费层引用变量；不以默认 4px 基数或组件尺寸档位修改原稿精确值。
+- 保留列表 Hook 的引用关系、填满链、滚动可用性及分页/表格同容器要求；视觉容器可更换，引用与状态随之迁移并验证。
+- 仅复用样板中的工程模式，不把样板字段、Demo 数据、菜单或操作复制到已有业务页面。
+- 完成条件：视觉修改满足原稿，工程硬约束与项目原有业务仍成立。
 
 ## 一、硬约束
 
@@ -24,7 +33,7 @@ tags: [vue3, kernel, conventions, layout, router, http, crud, inventory]
 | 9 | i18n：`$t('中文key')` |
 | 10 | 禁止用 `v-html` 渲染不可信内容 |
 | 11 | 新依赖须用户确认；已有封装须复用；选型表指定库勿擅自替换 |
-| 12 | 列表布局按 **`crud-pages` 标准样板**（`el-card.vts-page-card`+`content`、无 `100vh` 减顶栏定高、`tableHeight`、`otherRef`、分页在 ReTableBar 内；仅表格体内滚动） |
+| 12 | 无设计时按 `crud-pages` 默认视图；设计还原时允许换视觉容器，保留 `content`、`tableHeight`、`otherRef`、表格/分页同容器及可用滚动，不硬编码 `100vh` 减顶栏 |
 | 13 | addon 按 `project-inventory` 第九节精确版本安装；禁止 `@latest` |
 | 14 | 样式契约见下文「样式契约」 |
 
@@ -51,7 +60,7 @@ export default {
 
 ### 完整性守则
 
-命中模块须照其**标准样板**整段落盘；样板中的字段默认写出。壳层行为（tag / 侧栏 / keep-alive）以路由 meta + 项目已有实现为准，不假设 Hook 会「全自动」。
+命中模块时复用标准样板的工程结构，并以实际需求填充业务字段；已有页面保留项目字段。壳层行为（tag / 侧栏 / keep-alive）以路由 meta + 项目已有实现为准，逐项核对 Hook 实际能力。
 
 ### 权限
 

package/references/crud-pages.md

@@ -9,7 +9,7 @@ tags: [vue3, crud, list, form, detail, table, useTableSearch, page, layout, 批
 
 遵守 `core-kernel` / `http-api`。独立详情路由 → 同时加载 `detail-page`。回显 → `data-writeback`。
 
-**完整性守则**：列表页必须整段照抄「列表标准样板」；有独立详情时 **同批** 落 `detail-page` 三件套（禁止只写 `toDetail`）。方法名固定 `onSearch` / `reset`。
+复用下方样板的 Hook、事件、类型和路由模式；字段、操作、文案及数据从目标业务读取，不整段复制示例业务。无原稿时采用默认视图；设计还原时按原稿调整视觉容器、间距和排布，保留以下组件实例及高度契约。有独立详情时同批完成 `detail-page` 路由、页面与返回链。方法名使用 `onSearch` / `reset`。
 
 ## useTableSearch
 
@@ -34,7 +34,7 @@ useTableSearch(formQuery, searchFn, url)
 | 长表单 / 详情 / 说明类 | 根节点 `min-height: 100%`（或 `:style="{ minHeight: '100%' }"`）；**禁止** `vts-page-fill` / `h-full` / `overflow-hidden`；超出由 `.app-main` 内 `el-scrollbar` 滚动 |
 | 非 Card 整页填满（地图/流程图/大屏） | 根节点加 `class="vts-page-fill"` + `height: 100%` / `h-full`；**仅此类定高场景** |
 | Card 内边距 | 一律走 `--vts-card-padding`（桥接 `--card-padding`）；换规范 / `--vts-margin` 变化由壳层 flex 链 + Hook 自动跟随 |
-| 设计还原换容器（卡 → 通栏 / 自绘） | 根节点声明 `data-content-mode="fixed"`；新容器及其「体」层挂 `data-fill`；`content` ref 仍绑该容器；视觉（底色/圆角/边框/内边距）全落设计层——**不得因换容器而放弃设计还原，也不得为保高度而拒绝换容器** |
+| 设计还原换容器（卡 → 通栏 / 自绘） | 核对 `useTableSearch` 的 ref 取值；当前模板通过 `content.value.$el` 读 DOM，须将 `content` 绑定到单个 HTMLElement 根节点的表现组件实例，不能直接移到原生 div。页面根声明 `data-content-mode="fixed"`，填满链各层保留 `data-fill`；实际验证表高随查询展开、分页、视口变化重算。 |
 
 ## 高度模式（结构通道：`data-content-mode` + `data-fill`）
 
@@ -64,17 +64,16 @@ useTableSearch(formQuery, searchFn, url)
 规则：
 
 1. 新建列表页**不需要**显式声明——`vts-page-card` 钩子类自动触发定高；
-2. 设计变更集（语义 ID `admin.content.container`，`form: fixed \| scroll`）通过 parser 翻译为本属性；
+2. 设计还原时按原稿滚动归属设置本属性；直接维护页面结构，不调用旧 parser；
 3. 显式声明与自动探测**互斥**（自动分支带 `:not([data-content-mode])` 守卫）——显式 `scroll` 的页面内含 `.vts-page-card` 时，定高分支不得反压；
 4. `useTableSearch` 几何实测要求 `content` 容器处于定高链上——用 `data-content-mode="fixed"` 替代 `vts-page-card` 时同样成立。
 
-### 结构 / 视觉解耦（设计还原保命口径）
+### 设计还原的容器迁移
 
-定高链 = 「**谁定高**」（`data-content-mode`，根节点）+「**谁吸收剩余高度**」（`data-fill`，逐层节点），**只认属性、不认类名**。因此：
-
-- **视觉容器可以整体替换**：`el-card.vts-page-card` → 通栏 `div` / 自绘容器都行，只要把 `data-fill` 平移到新容器（及其「体」层）上，高度链不断、`tableHeight` 实测照常；
-- **视觉改（底色 / 圆角 / 边框 / 内边距 / 阴影 / 内部排布）落在设计层**（`src/styles/design-shell.scss` 或页面 scoped），**禁止改写**壳层结构层（`lay-content` 的 `.main-content[data-content-mode]`、`element-plus.scss` 的 `[data-fill]`）来换取还原效果；
-- **禁止反向妥协**：「为了保证高度正常所以保留出厂卡片/内边距不改」= 放弃设计还原，同样不接受。正确做法是换容器 + 平移 `data-fill`。
+- 按原稿调整底色、圆角、边框、内边距、阴影与排布；需要通栏或自绘视图时替换表现组件，不保留与原稿冲突的默认卡片外观。
+- 将 `data-content-mode` 用于页面滚动归属，将 `data-fill` 用于逐层填满；同时保持 `content.value.$el` 指向实际定高 HTMLElement。原生 div、Fragment、多根或仅 `display: contents` 的组件不能直接充当这个测量边界。
+- 分页与表格保持同容器，`otherRef` 保持表格上方；重构后实际检查查询展开/收起、分页换行、窗口变化和空数据的高度更新。仅平移 class/ref 不算迁移完成。
+- 若原稿布局与当前壳层结构冲突，按 `design-apply.md` 调整几何机制并回归受影响页面；保持上述测量接口与可用滚动，不用业务页魔法高度补偿。
 
 > **壳层原理**（`lay-content`）：`.main-content` 用 `padding: var(--vts-margin)`（不用 margin）；默认可滚动页 `el-scrollbar__view` / `.grow` 为 `min-height:100%; height:auto`；定高页 `.main-content[data-content-mode='fixed']`（或未声明时 `:has(.vts-page-card|.vts-page-fill)` 兜底）为 `height: 100%` 并收回祖先链；`.vts-page-card` 与其 `el-card__body` 是 `data-fill` 的出厂实施例，填满。`html/body/#app/.app-wrapper/.main-container/.app-main` 均为 `height:100%; overflow:hidden`。禁止业务页 `100vh` 减顶栏定高。
 
@@ -83,7 +82,7 @@ useTableSearch(formQuery, searchFn, url)
 
 | # | 必须 |
 |---|------|
-| L1 | `el-card` + `class="vts-page-card"` + `data-fill`（定高链挂载点，换容器时随容器平移）+ `ref="content"`（禁止挂 `div`） |
+| L1 | 默认使用 `el-card.vts-page-card`；设计还原可用符合上文「容器迁移」要求的单根表现组件。`ref="content"` 保持组件 `$el` 契约；保留实际定高链及 `data-fill`。 |
 | L2 | 不要写 `height: calc(100vh - …)` / 不要用 JS 测顶栏定高（壳层 + `.vts-page-card` 已填满） |
 | 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` |
@@ -501,7 +500,7 @@ async function onSubmit() {
 | 错误 | 正确 |
 |------|------|
 | `handleSearch` / 手写分页 | `onSearch` / `useTableSearch` |
-| `ref="content"` 挂 div / `100vh` 减顶栏定高 / 缺 `vts-page-card` | `el-card.vts-page-card`（高度交给壳层） |
+| `content` 不满足 `$el` 测量接口 / 页面魔法高度 / 换容器后高度链断开 | 使用默认卡片或合规单根表现组件，按「容器迁移」实测查询、分页和窗口变化 |
 | 不绑 `tableHeight` / 分页在卡片外 / 手写魔法数扣高度 | 样板 L6/L7；高度交给 `useTableSearch` |
 | 额外模块不绑 `otherRef` | L8 |
 | 只写 `toDetail`、详情路由缺 `activePath` | 三件套整段落盘（见 detail-page） |

package/references/data-screen.md

@@ -7,9 +7,7 @@ tags: [大屏, dataScreen, 数据大屏, 看板, 数据看板, 仪表盘, 全屏
 
 # 数据大屏
 
-> 按本文件示例编写，复用项目已有布局与图表封装；缩放/适配按本规范实现，勿另起一套大屏方案。
-
-规范数据大屏/可视化大屏的等比缩放、响应式适配与布局结构。在开发大屏展示页面时参照。
+先读取原稿的画布尺寸、布局、断点与缩放行为。固定画布使用等比缩放；流式设计按其 grid/flex、响应式单位和断点实现。无明确原稿的固定画布任务才采用下方 1920×1080 默认示例。复用项目图表、数据流与生命周期管理，不把示例的面板和数据当业务需求。
 
 ## 依赖（缺则先装）
 
@@ -26,7 +24,7 @@ pnpm add echarts@6.1.0
 
 ## 布局结构
 
-大屏页面使用固定设计稿尺寸（默认 `1920x1080`），通过 CSS `transform: scale()` 实现等比缩放。
+仅在选定固定画布方案时使用以下结构，将尺寸改为实际原稿尺寸；流式方案使用原稿的排布及断点，不套用本段 `transform: scale()`。
 
 ```vue
 <script setup lang="ts">
@@ -95,8 +93,9 @@ function getScale(width = 1920, height = 1080) {
 
 ## 关键约定
 
-1. 设计稿宽度、高度与 `getScale` 参数保持一致。
-2. 内部元素全部按设计稿像素开发，不要写响应式单位。
-3. 图表组件在 `resize` 时调用 `chart.resize()` 重新自适应（如使用 ECharts）。
-4. 定时器在 `onBeforeUnmount` 中清理。
-5. 大屏通常不需要展示菜单/页头，使用独立布局或全屏路由。
+1. 固定画布的设计尺寸与 `getScale` 参数保持一致；流式原稿保留响应式单位、断点及重排规则。
+2. 将原稿的颜色、字体、间距和尺寸放入项目视觉变量；不使用示例的黑底或像素值覆盖原稿。
+3. 图表组件在容器尺寸变化时调用现有封装的 resize 能力；按实际实现保留监听与销毁。
+4. 定时器、事件监听及观察器在 `onBeforeUnmount` 中清理。
+5. 保留项目已有导航与功能；仅在用户明确的页面范围内采用独立或全屏布局。
+6. 按 `visual-verification.md` 验证所有请求视口、长内容、图表尺寸和业务数据流。完成条件：选定适配方式与原稿一致，布局及图表实测正常，差异已记录。