@agile-team/wl-skills-ui 1.9.16 → 1.10.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to **@agile-team/wl-skills-ui** will be documented in this f
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.10.0] - 2026-08-15
+
+> 来源：wl-ui-ep（危废/环保子系统）存量改造实战沉淀，全部经过"线上翻车 → 定位 → 修复 → 验证"闭环。
+
+### Added
+
+- 新增 `renderAutoTag(value, dictKey, fieldName?)` / `renderAutoTagByLabel(label, fieldName?)` 文案语义自动判色 Tag：按字典渲染出的文案关键词判色（状态词实心 Tag、分类/形态词镂空 Tag、中性词原样纯文本兜底），零配色表覆盖存量项目上百字典列；规则表 `AUTO_STATUS_RULES` / `AUTO_CLASSIFY_RULES` / `autoTagTypeByLabel` 同步导出可扩展。
+- 新增 `ensureDefaultAlignment` / `normalizeColumnAlignmentsWith(cols, { defaultAlign: "center" })` 默认对齐补齐：无显式 `align/cellStyle/headerClass` 的列补默认居中（含表头 class 桥接，兼容共享 AG 适配层只认 class 的场景），递归分组 children；不传 options 保持原有"仅桥接显式声明"行为，向后兼容。
+- 新增规范文档 `standards/ui/06-legacy-migration-lessons.md`：二级表头、滚动条双轨、默认居中、状态 Tag、操作图标配色、禁用按钮可辨识、搜索区间距、分页位置、联邦门户样式污染规避、字典列审计机制十条实战沉淀。
+- `check:scss` 新增反模式守门：包内出现 `.ag-header-row` 强制 height 直接报错（防二级表头破坏模式回流）。
+
+### Fixed
+
+- AG Grid 二级（分组）表头不渲染：移除 `.ag-header-row { height: 36px !important }` 强制行高，改由 `--ag-header-height` / 新增 `--ag-group-header-height` 变量驱动；并增加 `:has(.ag-header-row-column-group)` 两行兜底（真实存在分组行时强制两行各 36px），兼容共享 AG 适配层不透传 `groupHeaderHeight` 的存量场景。
+- 表格滚动条改为"默认隐藏 → 悬停显示主题色（单档）"双轨实现：Chrome 121+ / Firefox 走标准 `scrollbar-color`，旧 Chromium 走 webkit 伪元素 + CSS 变量继承（`--wk-sb-thumb`），根治"容器:hover 直选伪元素在部分 Chromium 不触发重绘导致悬停不显示"的缺陷；横向条悬停展开 8px 主题色。
+- 操作列编辑图标 hover 由绿改警示黄：与查看蓝/删除红拉开三色区分，绿留给成功/审核语义（业务定案）。
+
 ## [1.9.16] - 2026-08-11
 
 ### Fixed

package/README.md

@@ -730,9 +730,13 @@ export const myRules = [
 | ------------------------------------------------ | -------------------------------------------------- |
 | `defineColumns(cols)`                            | 列定义，应用自动映射并桥接显式列对齐               |
 | `normalizeColumnAlignments(cols)`                | 仅桥接显式 `align/headerAlign`，不设置默认对齐      |
+| `normalizeColumnAlignmentsWith(cols, opts)`      | 桥接 + 默认对齐补齐（`{ defaultAlign: "center" }`，属性可退出） |
+| `ensureDefaultAlignment(col, align)`             | 单列默认对齐补齐（递归分组 children，尊重显式声明） |
 | `renderOps(items)`                               | 操作列图标按钮组（view/edit/del/log/ok/send 预设） |
 | `renderTagNode(v, map)`                          | 状态 Tag 渲染                                      |
 | `renderClassifyTag(v, map)`                      | 分类 Tag 渲染                                      |
+| `renderAutoTag(v, dictKey, fieldName?)`          | 字典列文案语义自动判色 Tag（状态实心/分类镂空/中性纯文本兜底，存量改造验证） |
+| `renderAutoTagByLabel(label, fieldName?)`        | 同上，已解析文案直调版                             |
 | `renderBadge(v)` / `renderCountBadge(v)`         | 编号 / 计数徽标                                    |
 | `renderRatingLevel(v)`                           | 评级颜色                                           |
 | `registerColumnAutoMap(field, config)`           | 注册新字段自动渲染                                 |

package/es/{chunk-53TF2NQQ.js → chunk-FB4NHDR3.js}

@@ -29,6 +29,26 @@ function normalizeColumnAlignment(column) {
 function normalizeColumnAlignments(columns) {
   return columns.map((column) => normalizeColumnAlignment(column));
 }
+function ensureDefaultAlignment(column, defaultAlign) {
+  const normalizedChildren = Array.isArray(column.children) ? column.children.map((child) => ensureDefaultAlignment(child, defaultAlign)) : column.children;
+  const hasExplicit = column.align !== void 0 || column.cellStyle !== void 0 || column.headerClass !== void 0;
+  if (hasExplicit) {
+    return normalizedChildren === column.children ? column : { ...column, children: normalizedChildren };
+  }
+  return {
+    ...column,
+    align: defaultAlign,
+    headerAlign: defaultAlign,
+    children: normalizedChildren
+  };
+}
+function normalizeColumnAlignmentsWith(columns, options = {}) {
+  const { defaultAlign = null } = options;
+  return columns.map((column) => {
+    const withDefault = defaultAlign == null ? column : ensureDefaultAlignment(column, defaultAlign);
+    return normalizeColumnAlignment(withDefault);
+  });
+}
 var ENABLE_STATUS_MAP = {
   0: { label: "\u505C\u7528", type: "danger" },
   1: { label: "\u542F\u7528", type: "success" }
@@ -145,6 +165,52 @@ function renderDictClassifyTag(value, dictKey, typeColorMap) {
     () => label
   );
 }
+var AUTO_STATUS_RULES = [
+  [/驳回|拒绝|停用|作废|报废|超标|异常|超期|逾期|不合格|失效|无效|惩罚|隐患/, "danger"],
+  [/已完成|已结束|完成|正常|有效|启用|合格|达标|通过|已处置|已确认|已审批|在用|使用中|奖励/, "success"],
+  [/待|进行中|审批中|整改中|处置中|评估中|调查|预警|管控|注意/, "warning"],
+  [/新建|未开始|草稿|暂存|历史|撤回|无|否|未/, "info"]
+];
+var AUTO_CLASSIFY_RULES = [
+  [/危废|危险|惩罚|事故|气态/, "danger"],
+  [/奖励|安全/, "success"],
+  [/一般|普通|计划外/, "warning"],
+  [/液态|固态|半固态/, "info"]
+];
+var CLASSIFY_HINT = /类型|类别|级别|维度|形态|相态|气态|液态|固态/;
+function matchRules(label, rules) {
+  for (const [re, type] of rules) {
+    if (re.test(label)) return type;
+  }
+  return null;
+}
+function autoTagTypeByLabel(label, fieldName) {
+  const statusType = matchRules(label, AUTO_STATUS_RULES);
+  if (statusType !== null) return { type: statusType, plain: false };
+  const isClassify = CLASSIFY_HINT.test(label) || /type|level|category|class/i.test(fieldName ?? "");
+  if (isClassify) {
+    return { type: matchRules(label, AUTO_CLASSIFY_RULES) ?? "", plain: true };
+  }
+  return null;
+}
+function renderAutoTagByLabel(label, fieldName) {
+  const tag = autoTagTypeByLabel(label, fieldName);
+  if (tag === null) return label;
+  return h(
+    ElTag,
+    { type: tag.type, size: "small", effect: tag.plain ? "plain" : "light" },
+    () => label
+  );
+}
+function renderAutoTag(value, dictKey, fieldName) {
+  if (value === null || value === void 0 || value === "") return null;
+  let label = String(value);
+  if (dictResolver) {
+    const resolved = dictResolver(dictKey, value);
+    if (resolved) label = resolved;
+  }
+  return renderAutoTagByLabel(label, fieldName ?? dictKey);
+}
 function renderBadge(value) {
   if (value === null || value === void 0 || value === "") return null;
   return h("span", { class: "jh-riskno-badge" }, String(value));
@@ -356,4 +422,4 @@ registerColumnAutoMaps({
   }
 });
 
-export { AUDIT_STATUS_MAP, ENABLE_STATUS_MAP, RATING_LEVEL_COLORS, VERIFY_STATUS_MAP, clearColumnAutoMap, defineColumns, getColumnAutoMap, normalizeColumnAlignment, normalizeColumnAlignments, registerColumnAutoMap, registerColumnAutoMaps, registerDictColorMap, registerDictColorMaps, renderAuditStatus, renderBadge, renderClassifyTag, renderCountBadge, renderDangerText, renderDictClassifyTag, renderEnableStatus, renderOps, renderRatingLevel, renderTagNode, renderTagSlot, renderVerifyStatus, setDictResolver };
+export { AUDIT_STATUS_MAP, AUTO_CLASSIFY_RULES, AUTO_STATUS_RULES, ENABLE_STATUS_MAP, RATING_LEVEL_COLORS, VERIFY_STATUS_MAP, autoTagTypeByLabel, clearColumnAutoMap, defineColumns, ensureDefaultAlignment, getColumnAutoMap, normalizeColumnAlignment, normalizeColumnAlignments, normalizeColumnAlignmentsWith, registerColumnAutoMap, registerColumnAutoMaps, registerDictColorMap, registerDictColorMaps, renderAuditStatus, renderAutoTag, renderAutoTagByLabel, renderBadge, renderClassifyTag, renderCountBadge, renderDangerText, renderDictClassifyTag, renderEnableStatus, renderOps, renderRatingLevel, renderTagNode, renderTagSlot, renderVerifyStatus, setDictResolver };

package/es/common-preset.d.ts

@@ -1,7 +1,7 @@
 import * as vue from 'vue';
 import { VNode } from 'vue';
 import { T as TagMapItem, J as JhTagNode } from './types-DtmxwMWV.js';
-export { r as registerDictColorMap, a as registerDictColorMaps, b as renderDictClassifyTag, s as setDictResolver } from './renderers-DlFRBX9K.js';
+export { r as registerDictColorMap, a as registerDictColorMaps, b as renderDictClassifyTag, s as setDictResolver } from './renderers-DKcXOFnF.js';
 
 declare const RISK_LEVEL_MAP: Record<string | number, TagMapItem>;
 declare const renderRiskLevel: (v: string | number | null | undefined) => JhTagNode | null;

package/es/common-preset.js

@@ -1,6 +1,6 @@
 import { installUiRuntimeGuards } from './chunk-QLPJLXY6.js';
-import { renderTagNode, renderClassifyTag, registerColumnAutoMaps, renderRatingLevel, renderBadge } from './chunk-53TF2NQQ.js';
-export { registerDictColorMap, registerDictColorMaps, renderDictClassifyTag, setDictResolver } from './chunk-53TF2NQQ.js';
+import { renderTagNode, renderClassifyTag, registerColumnAutoMaps, renderRatingLevel, renderBadge } from './chunk-FB4NHDR3.js';
+export { registerDictColorMap, registerDictColorMaps, renderDictClassifyTag, setDictResolver } from './chunk-FB4NHDR3.js';
 import './chunk-Q3N5QNRZ.js';
 
 // runtime/presets/common.ts

package/es/index.d.ts

@@ -1,6 +1,6 @@
 import { C as ColumnLike } from './types-DtmxwMWV.js';
 export { E as ElTagType, J as JhTagNode, a as OpChip, O as OpItem, b as OpLink, c as OpPreset, T as TagMapItem } from './types-DtmxwMWV.js';
-export { A as AUDIT_STATUS_MAP, E as ENABLE_STATUS_MAP, R as RATING_LEVEL_COLORS, V as VERIFY_STATUS_MAP, r as registerDictColorMap, a as registerDictColorMaps, c as renderAuditStatus, d as renderBadge, e as renderClassifyTag, f as renderCountBadge, g as renderDangerText, b as renderDictClassifyTag, h as renderEnableStatus, i as renderOps, j as renderRatingLevel, k as renderTagNode, l as renderTagSlot, m as renderVerifyStatus, s as setDictResolver } from './renderers-DlFRBX9K.js';
+export { A as AUDIT_STATUS_MAP, c as AUTO_CLASSIFY_RULES, d as AUTO_STATUS_RULES, E as ENABLE_STATUS_MAP, R as RATING_LEVEL_COLORS, V as VERIFY_STATUS_MAP, e as autoTagTypeByLabel, r as registerDictColorMap, a as registerDictColorMaps, f as renderAuditStatus, g as renderAutoTag, h as renderAutoTagByLabel, i as renderBadge, j as renderClassifyTag, k as renderCountBadge, l as renderDangerText, b as renderDictClassifyTag, m as renderEnableStatus, n as renderOps, o as renderRatingLevel, p as renderTagNode, q as renderTagSlot, t as renderVerifyStatus, s as setDictResolver } from './renderers-DKcXOFnF.js';
 import 'vue';
 
 type ColumnAlignment = "left" | "center" | "right";
@@ -15,6 +15,25 @@ type ColumnAlignment = "left" | "center" | "right";
 declare function normalizeColumnAlignment<T extends ColumnLike>(column: T): T;
 /** 批量规范化列定义；只桥接显式对齐意图，不设置全局默认对齐。 */
 declare function normalizeColumnAlignments<T extends ColumnLike>(columns: T[]): T[];
+interface DefaultAlignmentOptions {
+    /**
+     * 无显式 align 时补齐的默认对齐。
+     * - "center"（推荐）表头/内容默认居中
+     * - "left" / "right" 其他默认
+     * - 不传或 null 不补齐，保持调用方现状（向后兼容）
+     */
+    defaultAlign?: ColumnAlignment | null;
+}
+/**
+ * 为无显式对齐声明的列补齐默认对齐（含表头）。
+ *
+ * - 列已有 align / cellStyle / headerClass 时一律不动（业务意图优先）；
+ * - 递归处理分组列 children；
+ * - 与 normalizeColumnAlignment 兼容：补齐产物仍可被桥接函数消费。
+ */
+declare function ensureDefaultAlignment<T extends ColumnLike>(column: T, defaultAlign: ColumnAlignment): T;
+/** 桥接 + 可选默认对齐的统一入口（推荐列定义管线使用）。 */
+declare function normalizeColumnAlignmentsWith<T extends ColumnLike>(columns: T[], options?: DefaultAlignmentOptions): T[];
 
 /**
  * runtime/core/registry.ts — COLUMN_AUTO_MAP 注册中心 + defineColumns
@@ -209,4 +228,4 @@ declare function uninstallSplitGridResizeGuard(): void;
  */
 declare function installUiRuntimeGuards(): void;
 
-export { BRAND_THEME_TOKENS, type ColumnAlignment, ColumnLike, type OverflowTooltipGuardOptions, type PresetConfig, SPLIT_GRID_RESIZE_EVENT, type SplitGridResizeDetail, clearColumnAutoMap, createPreset, defineColumns, getColumnAutoMap, getInstalledPresets, installBrandThemeLock, installOverflowTooltipGuard, installPreset, installSplitGridResizeGuard, installUiRuntimeGuards, normalizeColumnAlignment, normalizeColumnAlignments, registerColumnAutoMap, registerColumnAutoMaps, uninstallOverflowTooltipGuard, uninstallSplitGridResizeGuard };
+export { BRAND_THEME_TOKENS, type ColumnAlignment, ColumnLike, type DefaultAlignmentOptions, type OverflowTooltipGuardOptions, type PresetConfig, SPLIT_GRID_RESIZE_EVENT, type SplitGridResizeDetail, clearColumnAutoMap, createPreset, defineColumns, ensureDefaultAlignment, getColumnAutoMap, getInstalledPresets, installBrandThemeLock, installOverflowTooltipGuard, installPreset, installSplitGridResizeGuard, installUiRuntimeGuards, normalizeColumnAlignment, normalizeColumnAlignments, normalizeColumnAlignmentsWith, registerColumnAutoMap, registerColumnAutoMaps, uninstallOverflowTooltipGuard, uninstallSplitGridResizeGuard };

package/es/index.js

@@ -1,6 +1,6 @@
 export { SPLIT_GRID_RESIZE_EVENT, installOverflowTooltipGuard, installSplitGridResizeGuard, installUiRuntimeGuards, uninstallOverflowTooltipGuard, uninstallSplitGridResizeGuard } from './chunk-QLPJLXY6.js';
-import { registerColumnAutoMaps } from './chunk-53TF2NQQ.js';
-export { AUDIT_STATUS_MAP, ENABLE_STATUS_MAP, RATING_LEVEL_COLORS, VERIFY_STATUS_MAP, clearColumnAutoMap, defineColumns, getColumnAutoMap, normalizeColumnAlignment, normalizeColumnAlignments, registerColumnAutoMap, registerColumnAutoMaps, registerDictColorMap, registerDictColorMaps, renderAuditStatus, renderBadge, renderClassifyTag, renderCountBadge, renderDangerText, renderDictClassifyTag, renderEnableStatus, renderOps, renderRatingLevel, renderTagNode, renderTagSlot, renderVerifyStatus, setDictResolver } from './chunk-53TF2NQQ.js';
+import { registerColumnAutoMaps } from './chunk-FB4NHDR3.js';
+export { AUDIT_STATUS_MAP, AUTO_CLASSIFY_RULES, AUTO_STATUS_RULES, ENABLE_STATUS_MAP, RATING_LEVEL_COLORS, VERIFY_STATUS_MAP, autoTagTypeByLabel, clearColumnAutoMap, defineColumns, ensureDefaultAlignment, getColumnAutoMap, normalizeColumnAlignment, normalizeColumnAlignments, normalizeColumnAlignmentsWith, registerColumnAutoMap, registerColumnAutoMaps, registerDictColorMap, registerDictColorMaps, renderAuditStatus, renderAutoTag, renderAutoTagByLabel, renderBadge, renderClassifyTag, renderCountBadge, renderDangerText, renderDictClassifyTag, renderEnableStatus, renderOps, renderRatingLevel, renderTagNode, renderTagSlot, renderVerifyStatus, setDictResolver } from './chunk-FB4NHDR3.js';
 export { BRAND_THEME_TOKENS, installBrandThemeLock } from './chunk-Q3N5QNRZ.js';
 
 // runtime/presets/registry.ts

package/es/presets/security.js

@@ -1,4 +1,4 @@
-import { renderTagNode, registerDictColorMaps, registerColumnAutoMaps } from '../chunk-53TF2NQQ.js';
+import { renderTagNode, registerDictColorMaps, registerColumnAutoMaps } from '../chunk-FB4NHDR3.js';
 import { installBrandThemeLock } from '../chunk-Q3N5QNRZ.js';
 
 // runtime/presets/security.ts

package/es/{renderers-DlFRBX9K.d.ts → renderers-DKcXOFnF.d.ts}

@@ -34,6 +34,29 @@ declare function registerDictColorMap(dictKey: string, colorMap: Record<string,
 declare function registerDictColorMaps(maps: Record<string, Record<string, string>>): void;
 /** 渲染动态字典分类 Tag，适用于 logicType=dict 的类型/来源/方式/规则类型等列 */
 declare function renderDictClassifyTag(value: string | number | null | undefined, dictKey: string, typeColorMap?: Record<string, string>): VNode | null;
+/** 状态类关键词 → 实心 Tag 颜色（顺序即优先级：危险 > 成功 > 警示 > 中性） */
+declare const AUTO_STATUS_RULES: Array<[RegExp, string]>;
+/** 分类/级别/形态类关键词 → 镂空 Tag 颜色 */
+declare const AUTO_CLASSIFY_RULES: Array<[RegExp, string]>;
+/**
+ * 按已解析文案判语义 Tag 类型；中性文案返回 null（调用方保持纯文本）。
+ * 返回 { type, plain }：plain=true 表示分类/级别类（镂空 outline，低视觉权重）。
+ */
+declare function autoTagTypeByLabel(label: string, fieldName?: string): {
+    type: string;
+    plain: boolean;
+} | null;
+/**
+ * 文案语义 Tag（label 版）：已拿到展示文案时直接调用。
+ * 状态类 → 浅色实心 Tag；分类/级别/形态类 → 镂空 Tag；
+ * 中性文案原样返回字符串（defaultSlot 直接可用，零视觉变化兜底）。
+ */
+declare function renderAutoTagByLabel(label: string, fieldName?: string): VNode | string;
+/**
+ * 文案语义 Tag（字典版）：传字典 key，内部经 setDictResolver 解析文案后判色。
+ * 未注入 resolver 时按 value 原文判色（多数字典 value 即文案的存量场景可用）。
+ */
+declare function renderAutoTag(value: string | number | null | undefined, dictKey: string, fieldName?: string): VNode | string | null;
 /** 蓝色圆角徽标（编号类） */
 declare function renderBadge(value: string | number | null | undefined): VNode | null;
 /** 绿色圆角徽标（数值类） */
@@ -48,4 +71,4 @@ declare const renderVerifyStatus: (v: string | number | null | undefined) => JhT
 /** 渲染操作列按钮组（图标 + 胶囊 + 文字链接，自动 stopPropagation） */
 declare function renderOps(items: OpItem[]): VNode;
 
-export { AUDIT_STATUS_MAP as A, ENABLE_STATUS_MAP as E, RATING_LEVEL_COLORS as R, VERIFY_STATUS_MAP as V, registerDictColorMaps as a, renderDictClassifyTag as b, renderAuditStatus as c, renderBadge as d, renderClassifyTag as e, renderCountBadge as f, renderDangerText as g, renderEnableStatus as h, renderOps as i, renderRatingLevel as j, renderTagNode as k, renderTagSlot as l, renderVerifyStatus as m, registerDictColorMap as r, setDictResolver as s };
+export { AUDIT_STATUS_MAP as A, ENABLE_STATUS_MAP as E, RATING_LEVEL_COLORS as R, VERIFY_STATUS_MAP as V, registerDictColorMaps as a, renderDictClassifyTag as b, AUTO_CLASSIFY_RULES as c, AUTO_STATUS_RULES as d, autoTagTypeByLabel as e, renderAuditStatus as f, renderAutoTag as g, renderAutoTagByLabel as h, renderBadge as i, renderClassifyTag as j, renderCountBadge as k, renderDangerText as l, renderEnableStatus as m, renderOps as n, renderRatingLevel as o, renderTagNode as p, renderTagSlot as q, registerDictColorMap as r, setDictResolver as s, renderVerifyStatus as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.9.16",
+  "version": "1.10.0",
   "description": "企业级 UI 风格对齐框架 — Vue + Element Plus 项目通用化妆/原生双模式（tokens / element / vendors / layouts / runtime / scanner / fixer / skills）",
   "type": "module",
   "main": "./es/index.js",

package/standards/ui/06-legacy-migration-lessons.md

@@ -0,0 +1,149 @@
+# 规范 06：存量改造踩坑沉淀（Legacy Migration Lessons）
+
+> 来源：wl-ui-ep（危废/环保子系统）存量改造实战验证，2026-08。
+> 每条都经历过"线上翻车 → 定位 → 修复 → 验证"闭环，新项目直接受益，不再重踩。
+
+---
+
+## 1. AG Grid 二级（分组）表头不渲染
+
+**症状**：列定义带 `children` 的分组列，渲染出来"扁平成一级"，分组行消失。
+
+**根因**：全局样式对 `.ag-header-row` 强制了 `height: auto !important`（或任意强制行高）。
+ag-grid 内部按变量计算分组行高与各行 `top` 定位，强制 height 让分组行高度算成 0。
+
+**正确姿势**（已固化到 `vendors/_ag-grid.scss`）：
+
+```scss
+// 变量驱动，行高交给 ag-grid
+.ag-root-wrapper {
+  --ag-header-height: 36px;
+  --ag-group-header-height: 36px;
+}
+// 分组兜底：真实存在分组行时强制两行各 36px（:has 只在分组时命中）
+.ag-header:has(.ag-header-row-column-group) { /* height: 2×36 */ }
+```
+
+**守门**：`npm run check:scss` 含反模式扫描，包内出现 `.ag-header-row` 强制 height 直接报错。
+
+---
+
+## 2. 滚动条悬停不显示 / 灰色不主题色
+
+**症状**：容器 hover 时滚动条不出现；或滚动条是灰的、与品牌色无关。
+
+**根因**：
+- 「容器:hover 直选 `::-webkit-scrollbar-thumb`」在部分 Chromium 版本**不触发滚动条重绘**；
+- 灰色系配色没接品牌 token。
+
+**正确姿势**（已固化，双轨）：
+
+```scss
+// a) Chrome 121+ / Firefox：标准属性，容器 hover 换值必定生效
+.box { scrollbar-width: thin; scrollbar-color: transparent transparent; }
+.box:hover { scrollbar-color: var(--el-color-primary) transparent; }
+// b) 旧 Chromium：webkit 伪元素 + CSS 变量继承（继承链更新可靠触发重绘）
+.box { --wk-sb-thumb: transparent; }
+.box:hover { --wk-sb-thumb: var(--el-color-primary); }
+.box::-webkit-scrollbar-thumb { background-color: var(--wk-sb-thumb); }
+```
+
+交互标准：**默认隐藏 → 悬停容器显示主题色（单档）→ 离开即隐藏**。不做深浅两档。
+
+---
+
+## 3. 表头/内容默认居中，属性可退出
+
+**约定**：列定义不写 `align` 时默认表头+内容居中；显式声明 `align: "left"` 等以列为准。
+
+**固化**：`runtime` 的 `normalizeColumnAlignmentsWith(cols, { defaultAlign: "center" })`：
+无显式 align/cellStyle/headerClass 的列补齐默认居中（含表头 class 桥接，兼容共享
+AG 适配层只认 class 的场景），递归分组 children；存量项目保持
+`normalizeColumnAlignments(cols)` 不传 options 即不补齐，向后兼容。
+
+---
+
+## 4. 状态列 Tag：文案语义自动判色
+
+**场景**：存量项目几十个列表页、上百个字典列，逐字段配颜色表不现实。
+
+**固化**：`renderAutoTag(value, dictKey, fieldName?)` / `renderAutoTagByLabel(label, fieldName?)`
+按字典渲染出的**文案关键词**判色，零配色表：
+
+| 文案关键词 | 效果 |
+|---|---|
+| 驳回/停用/作废/超标/逾期/异常… | 实心 danger |
+| 已完成/正常/合格/已审批/启用… | 实心 success |
+| 待/进行中/审批中/整改中/预警… | 实心 warning |
+| 新建/草稿/未开始/历史… | 实心 info |
+| XX类型/形态（气态/液态/固态…） | 镂空 Tag（视觉权重低于状态） |
+| 单位/职务/周期等中性词 | **原样纯文本**（零视觉变化兜底） |
+
+规则表 `AUTO_STATUS_RULES` / `AUTO_CLASSIFY_RULES` 已导出，可按项目扩展。
+
+---
+
+## 5. 操作列图标：默认统一浅主题蓝，悬停出语义色
+
+**定案**：查看/编辑/删除图标**默认一律浅主题蓝**（整列安静不花哨），**悬停**才显示
+各自语义色——查看蓝、编辑黄、删除红。三类图标静态各涂一色被业务明确否决（太花）。
+
+编辑 hover 用警示黄而非绿：与查看蓝/删除红拉开三色区分，绿留给成功/审核语义。
+（已固化到 `vendors/_base-components.scss` 的 `jh-op-*`。）
+
+---
+
+## 6. 禁用按钮可辨识
+
+**坑**：「语义按钮统一白字」规则若不带 `:not(.is-disabled)`，禁用态白字叠灰底文字消失。
+
+**正确姿势**：白字规则排除 `.is-disabled`；禁用态用**语义淡色**——语义 light-8 浅底 +
+light-5 文字（各语义色按钮禁用后仍可辨识"这是哪类按钮"）。已固化到 `element/_button.scss`。
+
+---
+
+## 7. 搜索区间距标准
+
+| 位置 | 标准值 |
+|---|---|
+| 搜索项之间（横向） | 16px |
+| 搜索区容器左右 padding | 12px |
+| label ↔ 控件 | 10px |
+| 行间（纵向） | 6px |
+
+（`vendors/_base-query-toolbar.scss` 已按此标准实现。）
+
+---
+
+## 8. 分页器位置
+
+表格**右侧下方**：`.list-page__pager { display:flex; justify-content:flex-end }`
+（`layouts/_list-page.scss` 已固化）。不允许分页器贴着表格左缘或顶在表格正下方左侧。
+
+---
+
+## 9. 样式污染规避（联邦门户共存场景）
+
+**教训**（多子系统经门户联邦挂载、共享同一 document）：
+
+1. **`:root` / `body` / `#app` 是全体共享锚点**——在多子系统门户里 `#app` 是门户的容器，
+   不是自己子系统的。写在这三类锚点上的规则等于泼向所有子系统。
+2. **token 互相剥除**：两个子系统都往 `:root body` 写 `--el-color-*` 且带 `!important`
+   时，后加载者胜——先进入的子系统皮肤被剥（真实事故：删除按钮红底被剥成白字白底）。
+3. **防外溢固化**：怕被外来样式污染的自身组件，锚定**项目独有类名** + `!important`
+   （如 divider 间距、图标字号），别人命中不了、自己稳定。
+
+**正确姿势**：规则尽量落在**项目/组件独有类**或本包 `managed-scope`（含
+`data-wl-ui-skin="off"` 豁免）内；需要全局 token 时只写一遍且接受统一皮肤源。
+
+---
+
+## 10. 字典列扫描审计机制
+
+存量项目"哪些列该上 Tag 而没上"靠肉眼不可维护。配套审计脚本思路（wl-skills-kit
+提供 `audit-status-columns.mjs`）：
+
+- 扫描列定义中 `formatter: (row) => xDict.fmt(row.field)` 写法；
+- 按列 label 语义分级：状态/类型类 → 建议转 `renderAutoTag`；中性（单位/职务）→ 保持；
+- `--fix` 自动转换 + 补 import + 清理无引用 formatter；转换的 dict/字段取自 const 定义
+  （无歧义源），最坏情况走中性纯文本兜底，零风险。

package/styles/vendors/_ag-grid.scss

@@ -42,6 +42,10 @@
   --ag-font-family: var(--wk-font-family-sans);
   --ag-row-height: 26px;
   --ag-header-height: 36px;
+  // 分组表头（二级表头）行高：单列声明，ag-grid 内部按层级定位各行 top。
+  // 教训（wl-ui-ep ea6ab20）：不要用 .ag-header-row { height:auto !important }
+  // 之类的强制行高——会破坏分组行高内部计算，分组行算成 0 → 二级表头不渲染。
+  --ag-group-header-height: 36px;
   --ag-cell-horizontal-padding: 8px;
   --ag-checkbox-checked-color: var(--el-color-primary);
   --ag-input-focus-border-color: var(--el-color-primary);
@@ -59,8 +63,21 @@
   min-height: 36px !important;
 }
 
-.ag-header-row {
-  height: 36px !important;
+// 行高由上方 --ag-header-height / --ag-group-header-height 变量驱动，
+// 不再强制 .ag-header-row 的 height（强制行高与 ag-grid 分组行定位冲突）。
+// 分组表头兜底（wl-ui-ep 76f9dfa 验证）：真实存在分组行时强制两行各 36px，
+// 兼容共享 AG 适配层不透传 groupHeaderHeight 的存量场景；:has 只在分组时命中。
+.ag-header:has(.ag-header-row-column-group) {
+  height: calc(var(--ag-header-height, 36px) * 2) !important;
+  min-height: calc(var(--ag-header-height, 36px) * 2) !important;
+}
+.ag-header:has(.ag-header-row-column-group) .ag-header-row-column-group {
+  top: 0 !important;
+  height: var(--ag-header-height, 36px) !important;
+}
+.ag-header:has(.ag-header-row-column-group) .ag-header-row-column {
+  top: var(--ag-header-height, 36px) !important;
+  height: var(--ag-header-height, 36px) !important;
 }
 
 .ag-header-cell {
@@ -289,36 +306,56 @@
   letter-spacing: 0.02em;
 }
 
-// ── 滚动条 ────────────────────────────────────────────────────────────────────
-.ag-body-viewport::-webkit-scrollbar {
-  width: 4px;
-}
-.ag-body-viewport::-webkit-scrollbar-thumb {
-  background-color: rgba(0, 0, 0, 0.15);
-  border-radius: 2px;
+// ── 滚动条：默认隐藏，悬停显示主题色（双轨实现） ────────────────────────────
+// 教训（wl-ui-ep 695d664）：灰色系/「容器:hover 直选伪元素」在部分 Chromium
+// 不触发滚动条重绘，导致悬停不显示。双轨：
+//   a) Chrome 121+ / Firefox 走标准 scrollbar-color（容器 hover 换值必定生效）；
+//   b) 旧 Chromium 走 webkit 伪元素 + CSS 变量继承（--wk-sb-thumb 从容器继承，
+//      继承链更新可靠触发重绘）。
+.ag-body-viewport {
+  scrollbar-width: thin;
+  scrollbar-color: transparent transparent;
+  --wk-sb-thumb: transparent;
+  &:hover {
+    scrollbar-color: var(--el-color-primary) transparent;
+    --wk-sb-thumb: var(--el-color-primary);
+  }
 }
-.ag-body-viewport::-webkit-scrollbar-thumb:hover {
-  background-color: rgba(0, 0, 0, 0.3);
+.ag-body-viewport::-webkit-scrollbar {
+  width: 6px;
 }
 .ag-body-viewport::-webkit-scrollbar-track {
   background: transparent;
 }
+.ag-body-viewport::-webkit-scrollbar-thumb {
+  background-color: var(--wk-sb-thumb);
+  border-radius: 6px;
+}
 
+// 横向滚动条：静默 4px → 悬停展开 8px 主题色
+.ag-body-horizontal-scroll-viewport {
+  --wk-sbh-thumb: transparent;
+  &:hover {
+    --wk-sbh-thumb: var(--el-color-primary);
+  }
+}
 .ag-body-horizontal-scroll-viewport::-webkit-scrollbar {
   height: 4px;
 }
 .ag-body-horizontal-scroll-viewport::-webkit-scrollbar-track {
-  background: transparent;
+  background: rgba(0, 0, 0, 0.04);
+  border-radius: 4px;
 }
 .ag-body-horizontal-scroll-viewport::-webkit-scrollbar-thumb {
-  background-color: transparent;
-  border-radius: 2px;
+  background-color: var(--wk-sbh-thumb);
+  border-radius: 4px;
 }
-.ag-body-horizontal-scroll-viewport:hover::-webkit-scrollbar-thumb {
-  background-color: rgba(0, 0, 0, 0.2);
+.ag-body-horizontal-scroll-viewport:hover::-webkit-scrollbar {
+  height: 8px;
 }
-.ag-body-horizontal-scroll-viewport:hover::-webkit-scrollbar-thumb:hover {
-  background-color: rgba(0, 0, 0, 0.35);
+.ag-body-horizontal-scroll-viewport:hover::-webkit-scrollbar-track {
+  background: rgba(var(--el-color-primary-rgb), 0.08);
+  border-radius: 4px;
 }
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package/styles/vendors/_base-components.scss

@@ -54,11 +54,11 @@
         background: rgba(var(--el-color-primary-rgb), 0.09);
       }
   }
-  // 编辑 — hover 翠绿
+  // 编辑 — hover 警示黄（wl-ui-ep 定案：查看蓝/编辑黄/删除红三色区分，原绿与成功语义撞色）
   &.jh-op-edit {
     &:hover:not(:disabled) {
-        color: var(--el-color-success);
-        background: rgba(43, 178, 104, 0.09);
+        color: var(--el-color-warning);
+        background: rgba(234, 154, 19, 0.12);
       }
   }
   // 删除/作废 — hover 红