@agile-team/wl-skills-ui 1.9.11 → 1.9.12

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.9.12] - 2026-08-06
+
+### Added
+
+- 新增 `standards/component-structures.json` 复合控件结构契约，首批登记 common-core 多标签、人员/部门/树选择、多选、混合数字输入与 BaseToolbar 分裂按钮的边框所有者、高度策略、状态、内部无描边层和 Teleport 出口。
+- 新增 R040 未知复合结构审查规则与真实 DOM fixtures；已登记结构正常通过，疑似新结构要求人工核对后再增加精准适配，不执行机械修复。
+- 新增 Chromium 浏览器视觉回归及发布门禁，覆盖主题防反覆盖、按钮/圆角、textarea focus、数字输入单描边、复合输入自然增高、长文本提示、表格行状态和定制区域豁免。
+
+### Changed
+
+- `prepublishOnly` 升级为完整 `release:check`，npm 发布前必须同时通过代码、文档、构建、包内容及真实浏览器视觉回归；测试页和截图不进入 npm 包。
+
+### Fixed
+
+- 真实浏览器回归发现并修复复合多标签内部 editor 仍继承 Element Plus 默认 inset 的问题；仅在已登记的 `.com-input-multi-tag-wrap` 结构中清除子 wrapper 描边，普通输入与其他 picker 不受影响。
+
 ## [1.9.11] - 2026-08-06
 
 ### Fixed

package/README.md

@@ -115,6 +115,7 @@ wl-skills-ui/
 │   │   ├── table.mjs             # R001 R002 R003 R014 R039
 │   │   ├── form.mjs              # R006 R007 R008
 │   │   ├── button.mjs            # R004 R005 R015 R038
+│   │   ├── componentStructure.mjs # R040 复合结构登记审查
 │   │   ├── tag.mjs               # R009 R010 R012
 │   │   ├── dialog.mjs            # R011
 │   │   ├── color.mjs             # R016 R017 R018
@@ -166,9 +167,12 @@ wl-skills-ui/
 │   └── ag-grid-page/TPL-AG-GRID.md
 │
 ├── standards/                    # 团队规范文档
+│   ├── component-structures.json # 复合控件结构契约单一事实源
 │   ├── ui/                       # UI 规范（01-table / 02-button / ...）
 │   └── engineering/              # 工程规范（import 顺序 / 命名 / SCSS 结构）
 │
+├── tests/visual/                 # Chromium 真实浏览器视觉回归与基准图
+│
 ├── bin/                          # CLI
 │   └── wl-ui.js                  # 统一入口（init/update/diff/clean/doctor/prompts/scan/fix/add-preset）
 │
@@ -208,7 +212,7 @@ yarn add @agile-team/wl-skills-ui
 |---|---|---|
 | `element-plus` | **`2.2.6-prod.3`** | 集团 jh- 定制版；EP 2.3.0 起引入 `.el-input__wrapper`，与 jh-ui 3.x 不兼容 |
 | `@jhlc/jh-ui` | **`3.1.0`** | SCSS 皮肤包，`.com-text` label 包裹 + `.has-colon` 冒号注入（wl-skills-ui 已统一屏蔽表单冒号） |
-| `@agile-team/wl-skills-ui` | `^1.9.11` | 已对齐上述组合的 DOM 假设、客户主题锁、圆角契约、复合输入、表格长文本兜底与定制页样式边界 |
+| `@agile-team/wl-skills-ui` | `^1.9.12` | 已对齐上述组合的 DOM 假设、客户主题锁、圆角契约、复合输入、表格长文本兜底与定制页样式边界 |
 
 三种识别方式，任选其一：
 
@@ -222,7 +226,13 @@ yarn add @agile-team/wl-skills-ui
 
 ## 版本亮点
 
-当前 v1.9.11：
+当前 v1.9.12：
+
+- **复合结构有清单**：`standards/component-structures.json` 登记边框所有者、内部无描边层、高度策略、状态与 Teleport 出口；首批覆盖 common-core 多标签、人员/部门/树选择、多选、混合数字框及 BaseToolbar 分裂按钮。
+- **未知结构先评审**：新增 R040，对疑似复合 Element wrapper 只报告、不自动修复，要求先核对真实 DOM 并登记契约，禁止继续放大普通 Element 选择器。
+- **发版前真实浏览器门禁**：新增 Chromium 视觉回归，验证客户主题防反覆盖、按钮与圆角、textarea focus、数字框单描边、复合输入自然增高、长文本省略/提示、表格行状态和定制区域豁免；截图基准不进入 npm 产物。
+
+上一版 v1.9.11：
 
 - **复合输入不再误伤**：common-core 多标签/人员选择器不再被普通 input 的固定高度压缩；无标签时保持 26px 紧凑基线，标签换行时容器自然增高。
 - **视觉契约保持统一**：复合输入外层继续使用统一 6px 圆角及默认、hover、品牌 focus、error、disabled 边框，内部编辑 input 不重复描边；普通 input/select/date/input-number 原有规则不变。
@@ -717,7 +727,7 @@ export const myRules = [
 
 ## 规范清单
 
-### UI 规则（R001-R039，按 layer 自动分组）
+### UI 规则（R001-R040，按 layer 自动分组）
 
 | Rule | Layer | Vendor    | 说明                                 |
 | ---- | ----- | --------- | ------------------------------------ |
@@ -750,6 +760,30 @@ export const myRules = [
 | R037 | L1    | element   | 空/异常反馈建议统一操作入口          |
 | R038 | L1    | element   | 创建类主按钮缺 primary 填充主题色    |
 | R039 | L1    | element   | 普通数据列缺省略与悬停完整提示       |
+| R040 | L2    | common-core | 未登记复合控件结构需人工评审       |
+
+### 维护者防回归
+
+复合控件必须先登记结构契约，再增加精准样式；包发版必须经过 Chromium 基准图对比：
+
+```bash
+# Windows 默认使用已安装的 Edge Chromium；非 Windows 首次安装一次
+pnpm exec playwright install chromium
+
+# 日常验证
+pnpm test
+pnpm test:visual
+
+# 仅在设计变更已经人工确认时更新基准图
+pnpm test:visual:update
+
+# 完整发版门禁（含 lint、契约、SCSS、文档、构建、包校验、视觉回归）
+pnpm release:check
+```
+
+机制与准入细则见 [复合控件结构契约](docs/composite-component-contracts.md) 和
+[浏览器视觉回归](docs/visual-regression.md)。视觉基准依赖字体、浏览器与操作系统渲染，
+必须在相同环境中比较；当前项目基准由 Windows Edge Chromium 生成。
 
 ### 工程规范
 

package/docs/compat-matrix.md

@@ -11,7 +11,7 @@
 | `element-plus` | **`2.2.6-prod.3`** | 集团 jh- 定制版，搭配 `@jhlc/jh-ui` 使用，DOM 仍为 `.el-input > .el-input__inner` 直挂结构（**EP 2.3.0 起才引入 `.el-input__wrapper`**） |
 | `@jhlc/jh-ui` | **`3.1.0`** | SCSS 皮肤包，`.com-text` label 包裹、`.has-colon ::after` 冒号注入、`.el-form-item--default { margin-bottom: 24px }` 等强约束 |
 | `@jhlc/common-core` | `3.1.0` 或 `3.1.0-prod.x` | 基础 util/types，`@jhlc/jh-ui` 间接依赖 |
-| `@agile-team/wl-skills-ui` | `^1.9.11` | 已对齐 jh-ui 3.1.0 + EP 2.2.6-prod.3 的 DOM 假设、客户主题锁、6px 基础圆角、紧凑表单、复合多标签输入、表格行状态、分裂按钮、包级长文本提示、定制页样式边界与 Vite 4 开发转换 |
+| `@agile-team/wl-skills-ui` | `^1.9.12` | 已对齐 jh-ui 3.1.0 + EP 2.2.6-prod.3 的 DOM 假设、客户主题锁、6px 基础圆角、紧凑表单、复合结构契约、表格行状态、分裂按钮、包级长文本提示、定制页样式边界与 Vite 4 开发转换 |
 
 ## 项目集群当前实测
 
@@ -35,7 +35,7 @@
 
 ## 适配建议
 
-- 集团内项目：**统一锚定 `element-plus@2.2.6-prod.3` + `@jhlc/jh-ui@3.1.0`**，与 wl-skills-ui v1.9.11 三方对齐。
+- 集团内项目：**统一锚定 `element-plus@2.2.6-prod.3` + `@jhlc/jh-ui@3.1.0`**，与 wl-skills-ui v1.9.12 三方对齐。
 - Skin 项目除全局样式外，在 `main.ts` 引入一次 `@agile-team/wl-skills-ui/runtime/auto`；Native 项目的 `installCommonPreset()` 已包含相同包级保护，不要重复安装。
 - 升级 `element-plus` 到 2.3+ 前，必须同步升级 `@jhlc/jh-ui` 到对应支持版本，否则 `.com-text` / `.el-input__inner` DOM 与 EP `__wrapper` 体系不兼容。
 - 新项目接入：见 README 「快速接入」章节，默认会按本表声明 peerDependency 范围。

package/docs/composite-component-contracts.md

@@ -0,0 +1,43 @@
+# 复合控件结构契约
+
+## 目标
+
+复合控件经常同时包含 Element Plus 外壳、内部输入编辑器、标签容器以及 Teleport
+弹层。普通 `.el-input` / `.el-input__wrapper` 选择器无法判断谁负责边框和高度，直接扩大
+覆盖会导致固定高度裁切、边框消失或双描边。
+
+`standards/component-structures.json` 是这类结构的单一事实源。它不修改 common-core，
+只记录 wl-skills-ui 已核对和允许治理的 DOM 契约。
+
+## 每项必须声明
+
+- `rootSelector`：组件结构边界。
+- `ownerSelector`：唯一负责默认、hover、focus、error、disabled 边框的节点。
+- `innerBorderlessSelectors`：必须保持无描边的内部编辑器。
+- `heightPolicy`：固定单行高度、最小高度自然增长或内容驱动。
+- `states`：必须回归的交互状态。
+- `portalSelectors`：下拉、Tooltip、Dialog 等 Teleport 出口；没有则可省略。
+- `fixture`：从真实 DOM 最小化得到的结构样本。
+- `knownRootClasses`：供 R040 识别已登记结构。
+
+## 新复合控件准入流程
+
+1. 在浏览器中复制真实 DOM，确认 Element Plus / jh-ui / common-core 版本。
+2. 提取最小 fixture，保留会影响选择器匹配的 class、父子层级和 Teleport 出口。
+3. 在 `standards/component-structures.json` 登记边框所有者、高度策略与状态。
+4. 运行 `pnpm test`；结构测试会校验 selector 唯一命中和 fixture 完整性。
+5. 只为已登记结构增加精准 SCSS，并在 `tests/visual` 补充状态断言或截图。
+6. 运行 `pnpm release:check` 后方可发布。
+
+R040 只做审查提示，不自动改业务代码。已登记根类不会重复报告；发现疑似未知复合
+wrapper 时，应先按上述流程确认，不能直接扩大全局 Element 选择器。
+
+## 当前首批结构
+
+- common-core 多标签输入与人员选择多选。
+- 部门选择、树选择和 Element 多选封装。
+- 同节点 wrapper + 子 wrapper 的混合数字输入。
+- BaseToolbar 分裂按钮及其动作菜单 Teleport 出口。
+
+组件结构变化时，测试会先在 fixture/selector 契约处失败，从而把风险阻断在发版前，
+不会等十余个业务项目升级后再发现。

package/docs/visual-regression.md

@@ -0,0 +1,49 @@
+# 浏览器视觉回归
+
+## 覆盖目标
+
+`tests/visual` 使用真实 Vue、Element Plus、Skin SCSS 和 `runtime/auto`，在 Chromium 中
+验证最终计算样式与关键区域截图。它补充现有 Node DOM/SCSS 契约测试，专门发现
+“选择器存在但浏览器层叠后没生效”以及“修一处却破坏另一处”的问题。
+
+当前覆盖：
+
+- 客户主色被平台 JS 改写后由主题锁恢复。
+- 主按钮、禁用态、功能色和统一圆角。
+- textarea focus 品牌边框与轻焦点环。
+- 数字输入只有一个边框所有者。
+- common-core 复合多标签外壳自然增高、内层无双描边。
+- Element Table 长文本真实溢出、省略号与按需完整提示。
+- 表格选中行柔和状态色、BaseToolbar 分裂按钮与定制区域豁免。
+
+## 使用
+
+```bash
+# Windows 默认复用已安装的 Edge Chromium；非 Windows 首次安装一次
+pnpm exec playwright install chromium
+
+# 对比现有基准
+pnpm test:visual
+
+# 调试
+pnpm test:visual:ui
+
+# 设计变更经评审确认后才更新基准
+pnpm test:visual:update
+
+# 发版完整门禁
+pnpm release:check
+```
+
+截图基准按 Playwright 的浏览器/平台规则保存，不随 npm 包发布。Windows 默认使用企业
+环境已有的 Edge Chromium，也可通过 `WL_UI_BROWSER_CHANNEL` 显式指定 Playwright 通道。
+视觉像素受操作系统、浏览器版本和字体渲染影响，生成与比较必须使用相同环境；当前
+基准为 Windows Edge Chromium。
+升级 Playwright、Chromium 或字体后，应单独提交基准变化并人工审图，不能把更新截图当成
+消除失败的常规手段。
+
+## 增加场景
+
+优先向现有固定尺寸区域加入最小状态，不复制整套业务页面。每个缺陷至少提供一个
+计算样式断言；只有颜色、边框、布局关系需要肉眼整体判断时再补截图。动态时间、随机数、
+动画和远程资源不得进入基准页。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.9.11",
+  "version": "1.9.12",
   "description": "企业级 UI 风格对齐框架 — Vue + Element Plus 项目通用化妆/原生双模式（tokens / element / vendors / layouts / runtime / scanner / fixer / skills）",
   "type": "module",
   "main": "./es/index.js",
@@ -48,6 +48,9 @@
     "prepare": "npm run build",
     "sync:tokens": "node -e \"import('fs').then(fs=>fs.copyFileSync('design/tokens/base.css','dist/tokens.css'))\"",
     "test": "node --test scanner/__tests__/*.test.mjs",
+    "test:visual": "playwright test --config tests/visual/playwright.config.ts",
+    "test:visual:ui": "playwright test --config tests/visual/playwright.config.ts --ui",
+    "test:visual:update": "playwright test --config tests/visual/playwright.config.ts --update-snapshots",
     "check:scss": "node scripts/check-scss.mjs",
     "docs:check": "node scripts/check-docs.mjs",
     "scan": "node scanner/index.mjs scan",
@@ -60,8 +63,8 @@
     "verify:package": "node scripts/verify-package.mjs",
     "verify": "npm run lint && npm test && npm run check:scss && npm run docs:check && npm run build && npm run verify:package",
     "pack:dry": "npm pack --dry-run --ignore-scripts",
-    "release:check": "npm run verify && npm pack --dry-run --ignore-scripts",
-    "prepublishOnly": "npm run verify"
+    "release:check": "npm run verify && npm run test:visual && npm pack --dry-run --ignore-scripts",
+    "prepublishOnly": "npm run release:check"
   },
   "files": [
     "dist",
@@ -92,8 +95,10 @@
     "@commitlint/cli": "^20.5.3",
     "@commitlint/config-conventional": "^20.5.3",
     "@element-plus/icons-vue": "^2.3.0",
+    "@playwright/test": "^1.62.1",
     "@typescript-eslint/eslint-plugin": "^8.59.2",
     "@typescript-eslint/parser": "^8.59.2",
+    "@vitejs/plugin-vue": "^6.0.8",
     "@vue/eslint-config-typescript": "^14.7.0",
     "commitizen": "^4.3.1",
     "cz-customizable": "^7.5.4",
@@ -106,6 +111,7 @@
     "sass": "1.77.8",
     "tsup": "^8.3.0",
     "typescript": "^5.4.0",
+    "vite": "^8.2.0",
     "vue": "^3.4.0"
   },
   "peerDependencies": {

package/scanner/rules/componentStructure.mjs

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import { issue, lineOf } from "./_shared.mjs";
+
+const registry = JSON.parse(
+  readFileSync(
+    new URL("../../standards/component-structures.json", import.meta.url),
+    "utf8",
+  ),
+);
+const knownRootClasses = new Set(
+  registry.contracts.flatMap((contract) => contract.knownRootClasses || []),
+);
+
+const CLASS_ATTRIBUTE = /class\s*=\s*["']([^"']+)["']/g;
+const COMPOSITE_NAME = /(?:multi|multiple|picker|tags?|input-number|split)/i;
+
+export function findUnknownCompositeRoots(template) {
+  const findings = [];
+  let match;
+  while ((match = CLASS_ATTRIBUTE.exec(template)) !== null) {
+    const classValue = match[1];
+    const classes = classValue.split(/\s+/).filter(Boolean);
+    if (classes.some((name) => knownRootClasses.has(name))) continue;
+
+    const isHybridElementWrapper =
+      classes.includes("el-input") && classes.includes("el-input__wrapper");
+    const looksComposite = COMPOSITE_NAME.test(classValue);
+    const nearby = template.slice(match.index, match.index + 1600);
+    const containsInputStructure =
+      /<el-(?:input|select|autocomplete|cascader)\b|el-(?:input|select)__wrapper/.test(
+        nearby,
+      );
+
+    if (isHybridElementWrapper || (looksComposite && containsInputStructure)) {
+      findings.push({ index: match.index, classValue });
+    }
+  }
+  CLASS_ATTRIBUTE.lastIndex = 0;
+  return findings;
+}
+
+export const componentStructureRules = [
+  {
+    id: "R040",
+    category: "composite",
+    severity: "review",
+    name: "未知复合控件结构必须先登记边框与高度契约",
+    check(template, file, lineOffset) {
+      return findUnknownCompositeRoots(template).map((finding) =>
+        issue(
+          file,
+          lineOf(template, finding.index, lineOffset),
+          "R040",
+          "composite",
+          "review",
+          `发现未登记的疑似复合控件结构：class="${finding.classValue}"`,
+          "先核对真实 DOM，明确 root/边框所有者/内部无描边层/高度策略/Teleport 出口，再登记到 standards/component-structures.json；禁止直接扩大普通 Element 选择器。",
+          { layer: "L2", vendor: "common-core" },
+        ),
+      );
+    },
+  },
+];

package/scanner/rules/index.mjs

@@ -17,6 +17,7 @@ import { colorRules } from "./color.mjs";
 import { dialogRules } from "./dialog.mjs";
 import { tagRules } from "./tag.mjs";
 import { componentFamilyRules } from "./componentFamily.mjs";
+import { componentStructureRules } from "./componentStructure.mjs";
 import { semanticRules } from "./semantic.mjs";
 
 export const BUILT_IN_RULES = [
@@ -27,6 +28,7 @@ export const BUILT_IN_RULES = [
   ...dialogRules,
   ...tagRules,
   ...componentFamilyRules,
+  ...componentStructureRules,
   ...semanticRules,
 ];
 

package/skills/vendors/jh-components/SKILL.md

@@ -34,6 +34,7 @@ applyTo: "**/*.vue"
 - EP 2.2.x `.el-input__inner` 26px 高度、圆角 / focus / error 三态
 - jh-picker / reference-picker 的 `.com-picker` / `.com-reference-picker` 输入高度兜底
 - common-core 多标签/人员选择器的 `.com-input-multi-tag-wrap` 使用 26px 最小高度并允许标签换行自然增高；只由外层绘制统一状态边框，内部编辑 input 不重复描边
+- common-core 复合结构统一登记在 `standards/component-structures.json`；R040 遇到未登记的疑似 picker/multiple/tag 混合 wrapper 时只提示人工核对，不允许直接放大通用 Element 选择器
 - jh-select / jh-date-picker 的 `.el-select.is-focus` / `.el-input.is-focus` 兼容
 - 必填星号在 inline-flex label 下显式声明颜色
 
@@ -52,6 +53,7 @@ applyTo: "**/*.vue"
 - ❌ jh-pagination 未对齐到右侧（同 R011）
 - ❌ jh-form 内不用 `size="small"` 控件（同 R006）
 - ❌ 发现新的复杂 `<jh-*>` 组件后只在页面局部写补丁，而不沉淀到 L2 Project Vendors
+- ❌ 新复合结构未登记边框所有者、高度策略、内部无描边层与 Teleport 出口就直接写全局覆盖（R040）
 
 ## Repair
 

package/standards/component-structures.json

@@ -0,0 +1,220 @@
+{
+  "version": "1.0.0",
+  "description": "复合/组合控件结构契约单一事实源。登记边框所有者、高度策略、内部无描边层和 Teleport 出口，防止普通 Element 选择器误识别。",
+  "heightPolicies": [
+    "fixed-control-height",
+    "auto-with-control-min-height",
+    "content-driven"
+  ],
+  "contracts": [
+    {
+      "id": "common-core.multi-tag-input",
+      "vendor": "common-core",
+      "family": "form-composite",
+      "source": "lowcode-engine/packages/common/common-lowcode/components/src/schema-component/base-input-group/input/com/multi-tag-input.vue",
+      "fixture": "scanner/__tests__/component-fixtures/common-core-multi-tag-input.html",
+      "rootSelector": ".com-input-multi-tag-wrap.el-input.el-input__wrapper",
+      "ownerSelector": ".com-input-multi-tag-wrap.el-input__wrapper",
+      "innerBorderlessSelectors": [
+        ".com-input-multi-tag-wrap .el-input__wrapper"
+      ],
+      "knownRootClasses": [
+        "com-input-multi-tag-wrap"
+      ],
+      "heightPolicy": "auto-with-control-min-height",
+      "states": [
+        "default",
+        "hover",
+        "focus",
+        "error",
+        "disabled"
+      ],
+      "assertions": [
+        {
+          "target": "root",
+          "selector": ".el-input__wrapper:not(.com-input-multi-tag-wrap)",
+          "matches": false
+        },
+        {
+          "target": "inner",
+          "selector": ".com-input-multi-tag-wrap .el-input__wrapper",
+          "matches": true
+        }
+      ],
+      "risk": "外壳同时携带 el-input 与 el-input__wrapper，内部又包含真实 input wrapper；误套固定高度会裁切标签，内外同时描边会出现双边框。"
+    },
+    {
+      "id": "common-core.user-picker-multiple",
+      "vendor": "common-core",
+      "family": "picker-composite",
+      "source": "lowcode-engine/packages/common/common-lowcode/components/src/schema-component/base-input-group/user-picker/com/multiple-picker.vue",
+      "fixture": "scanner/__tests__/component-fixtures/common-core-user-picker-multiple.html",
+      "rootSelector": ".com-userPicker.picker-wrap",
+      "ownerSelector": ".com-userPicker .com-input-multi-tag-wrap.el-input__wrapper",
+      "innerBorderlessSelectors": [
+        ".com-userPicker .com-input-multi-tag-wrap .el-input__wrapper"
+      ],
+      "portalSelectors": [
+        ".user-picker-popper",
+        ".com-userPicker-dialog"
+      ],
+      "knownRootClasses": [
+        "com-userPicker"
+      ],
+      "heightPolicy": "auto-with-control-min-height",
+      "states": [
+        "default",
+        "hover",
+        "focus",
+        "error",
+        "disabled",
+        "open"
+      ],
+      "risk": "多标签外壳、Tooltip 和 append-to-body Dialog 同时存在，页面内样式与 Teleport 浮层必须分别验证。"
+    },
+    {
+      "id": "common-core.dept-picker-multiple",
+      "vendor": "common-core",
+      "family": "picker-composite",
+      "source": "lowcode-engine/packages/common/common-lowcode/components/src/schema-component/base-input-group/dept-picker/com/multiple-picker.vue",
+      "fixture": "scanner/__tests__/component-fixtures/common-core-dept-picker-multiple.html",
+      "rootSelector": ".com-deptPicker.picker-wrap",
+      "ownerSelector": ".com-deptPicker .el-input__wrapper",
+      "innerBorderlessSelectors": [],
+      "portalSelectors": [
+        ".com-deptPicker-dialog"
+      ],
+      "knownRootClasses": [
+        "com-deptPicker"
+      ],
+      "heightPolicy": "fixed-control-height",
+      "states": [
+        "default",
+        "hover",
+        "focus",
+        "error",
+        "disabled",
+        "open"
+      ],
+      "risk": "输入触发器与 append-to-body Dialog 分离，作用域或弹层规则调整时容易只覆盖一侧。"
+    },
+    {
+      "id": "common-core.tree-picker",
+      "vendor": "common-core",
+      "family": "picker-composite",
+      "source": "lowcode-engine/packages/common/common-lowcode/components/src/schema-component/base-input-group/tree-picker/com-pc/tree-picker.vue",
+      "fixture": "scanner/__tests__/component-fixtures/common-core-tree-picker.html",
+      "rootSelector": ".com-treePicker.picker-wrap",
+      "ownerSelector": ".com-treePicker-input .el-input__wrapper",
+      "innerBorderlessSelectors": [],
+      "portalSelectors": [
+        ".com-treePicker-dialog"
+      ],
+      "knownRootClasses": [
+        "com-treePicker"
+      ],
+      "heightPolicy": "fixed-control-height",
+      "states": [
+        "default",
+        "hover",
+        "focus",
+        "error",
+        "disabled",
+        "open"
+      ],
+      "risk": "外部触发输入、树弹窗和弹窗内搜索输入属于不同层级，通用输入规则不能把三者视为一个边框所有者。"
+    },
+    {
+      "id": "common-core.select-multiple",
+      "vendor": "common-core",
+      "family": "select-composite",
+      "source": "lowcode-engine/packages/common/common-lowcode/components/src/schema-component/base-input-group/select/com/select.vue",
+      "fixture": "scanner/__tests__/component-fixtures/common-core-select-multiple.html",
+      "rootSelector": ".el-select.com-select-multiple",
+      "ownerSelector": ".el-select.com-select-multiple .el-select__wrapper",
+      "innerBorderlessSelectors": [
+        ".el-select.com-select-multiple .el-select__input"
+      ],
+      "portalSelectors": [
+        ".el-select__popper"
+      ],
+      "knownRootClasses": [
+        "com-select-multiple"
+      ],
+      "heightPolicy": "auto-with-control-min-height",
+      "states": [
+        "default",
+        "hover",
+        "focus",
+        "error",
+        "disabled",
+        "open"
+      ],
+      "risk": "Tag、过滤输入和 Teleport 下拉层共存；必须保留多选自然增高并避免内部 editor 重复描边。"
+    },
+    {
+      "id": "common-core.input-number-mixed-wrapper",
+      "vendor": "common-core",
+      "family": "number-composite",
+      "source": "lowcode-engine/packages/common/common-lowcode/components/src/schema-component/base-input-group/input-number/com/input-number.vue",
+      "fixture": "scanner/__tests__/component-fixtures/common-core-input-number-mixed.html",
+      "rootSelector": ".el-input-number.el-input__wrapper",
+      "ownerSelector": ".el-input-number.el-input__wrapper",
+      "innerBorderlessSelectors": [
+        ".el-input-number.el-input__wrapper > .el-input > .el-input__wrapper"
+      ],
+      "knownRootClasses": [
+        "el-input-number"
+      ],
+      "heightPolicy": "fixed-control-height",
+      "states": [
+        "default",
+        "hover",
+        "focus",
+        "error",
+        "disabled"
+      ],
+      "assertions": [
+        {
+          "target": "root",
+          "selector": ".el-input-number.el-input__wrapper",
+          "matches": true
+        },
+        {
+          "target": "inner",
+          "selector": ".el-input-number.el-input__wrapper > .el-input > .el-input__wrapper",
+          "matches": true
+        }
+      ],
+      "risk": "根节点本身是 wrapper，内部仍含 Element input wrapper；只能由根节点绘制唯一状态边框。"
+    },
+    {
+      "id": "common-core.base-toolbar-split-button",
+      "vendor": "common-core",
+      "family": "action-composite",
+      "source": "common-core BaseToolbar split-button rendered DOM",
+      "fixture": "scanner/__tests__/component-fixtures/common-core-base-toolbar-split.html",
+      "rootSelector": ".base-toolbar-box .action-button-wrap > .el-dropdown > .el-button-group",
+      "ownerSelector": ".base-toolbar-box .action-button-wrap > .el-dropdown > .el-button-group",
+      "innerBorderlessSelectors": [
+        ".base-toolbar-box .action-button-wrap > .el-dropdown > .el-button-group > .el-dropdown__caret-button"
+      ],
+      "portalSelectors": [
+        ".el-dropdown-menu.action-dropdown-menu"
+      ],
+      "knownRootClasses": [
+        "action-button-wrap"
+      ],
+      "heightPolicy": "content-driven",
+      "states": [
+        "default",
+        "hover",
+        "focus",
+        "active",
+        "disabled",
+        "open"
+      ],
+      "risk": "主动作和箭头是两个交互区但必须共享一个视觉外轮廓；下拉菜单中的业务按钮需扁平化且不能污染普通菜单。"
+    }
+  ]
+}

package/standards/rules.json

@@ -44,6 +44,10 @@
     "layout": {
       "label": "页面骨架 / 操作组合",
       "standardsDoc": "skills/layouts/list-page/SKILL.md"
+    },
+    "composite": {
+      "label": "复合控件结构契约",
+      "standardsDoc": "standards/component-structures.json"
     }
   },
   "rules": [
@@ -464,6 +468,22 @@
       "manualReason": "需按组件语义选择 base/small/round 等圆角 token",
       "scanner": "scanner/rules/semantic.mjs",
       "skills": ["tokens/index"]
+    },
+    {
+      "id": "R040",
+      "category": "composite",
+      "severity": "review",
+      "title": "未知复合控件结构必须先登记边框与高度契约",
+      "rationale": "复合输入可能同时包含 Element 外壳、内部 editor 与 Teleport 浮层；直接套用普通 input 规则会造成固定高度裁切、边框消失或双描边。",
+      "appliesTo": [
+        "project-owned composite input wrapper",
+        ".el-input.el-input__wrapper",
+        "picker/multiple/tag wrapper containing Element input"
+      ],
+      "autoFixable": false,
+      "manualReason": "必须核对真实 DOM，明确边框所有者、高度策略、内部无描边层与 Teleport 出口",
+      "scanner": "scanner/rules/componentStructure.mjs",
+      "skills": ["vendors/jh-components"]
     }
   ]
 }

package/standards/ui/03-form.md

@@ -70,6 +70,10 @@ textarea 不强制 26px 高度，只继承统一圆角、字体和状态样式
 复合控件只能由最外层 wrapper 绘制默认、hover、focus、error、disabled 边框；内部编辑 input
 必须保持无描边，避免边框消失、内容裁切或出现双描边。
 
+所有非薄封装复合控件必须登记到 `standards/component-structures.json`，明确根节点、边框
+所有者、内部无描边层、高度策略、状态与 Teleport 出口，并提供真实 DOM fixture。R040
+发现疑似未知结构时只要求人工评审，不自动改写；禁止在结构未确认前扩大全局 Element 选择器。
+
 ---
 
 ## 规则：紧凑业务表单字号统一为 12px

package/styles/vendors/_jh-ui.scss

@@ -186,6 +186,17 @@
       0 0 0 1px var(--el-disabled-border-color, #e4e7ed) inset !important;
   }
 
+  // 内部 editor 只负责文字录入。Element Plus 默认会给子 wrapper 再画一层 inset，
+  // 必须在已登记的复合结构内精准清除；不触碰普通 input 或其他 picker。
+  &.com-input-multi-tag-wrap.el-input__wrapper
+    .el-input
+    > .el-input__wrapper {
+    border: 0 !important;
+    outline: none !important;
+    background: transparent !important;
+    box-shadow: none !important;
+  }
+
   &.com-picker .el-input > .el-input__inner,
   &.com-reference-picker .el-input > .el-input__inner,
   &.com-reference-picker-input .el-input > .el-input__inner,