@teamix-evo/skills 0.4.0 → 0.6.0

package/src/teamix-evo-design-opentrek/pages/list-page/patterns/card-list.md

@@ -0,0 +1,558 @@
+# 卡片视图列表页 (card-list)
+
+> 路由自 `../SKILL.md`
+> 覆盖三种卡片视图子类型：**pure-card** / **standard-card** / **view-toggle**
+> 核心组件：**CardGrid** > **ItemCard** × N → **CardActionBar**
+> 全局规则继承：[L1 框架](../../../rules/page-frame.json) / [布局模式](../../../rules/layout-rules.json) / [CRUD 流转](../../../rules/page-flow.json) / [SearchCombo](../_shared/search-combo-spec.md)
+> **本文件为业务卡片三件套（ItemCard/CardGrid/CardActionBar）的唯一规范来源**（v7.3 起：`rules/card-component.json` 已废止，所有规格下沉至此 §9）
+
+---
+
+## 0. 术语区分（强制）
+
+| 术语 | 定位 | 别名 | 规范来源 |
+|------|------|------|------|
+| **ContentCard** | 页面主内容**白色容器**，padding 24px，每页**单例** | 白卡容器 / shadcn-Card | `rules/component-specs.json` C7-Card |
+| **ItemCard** | CardGrid 内的**单个数据项卡片**，可重复 N 次 | 业务卡片 / 卡片视图列表项 | 本文件 §9.1 |
+
+> **规则**：本 pattern 及任何引用本 pattern 的文档，禁止只写 "Card"，必须显式使用 `ContentCard` 或 `ItemCard` 区分。
+
+---
+
+## 1. 子类型差异矩阵【唯一真相源】
+
+| 维度 | pure-card | standard-card | view-toggle |
+|------|-----------|---------------|-------------|
+| 触发关键词 | "纯卡片"/"卡片管理"/"智能体列表" | "卡片列表"/"分类卡片"/"资源卡片" | "视图切换"/"列表卡片切换" |
+| layout.type | SINGLE_COL | TWO_COL | TWO_COL |
+| layout 模式 | 模式A-CARD | 模式D-CARD | 模式D + ViewToggle |
+| Sidebar | 无 | **有 (240px)** | **有 (240px)** |
+| ViewToggle (ToggleGroup 复用) | 无 | 无 | **必需，ActionToolbar 右侧 Tab 样式** |
+| ItemCard.density | minimal / standard / complex（按信息量选） | 同 pure-card | 仅 **standard** |
+| ItemCard.iconStyle | **avatar**（32×32 圆角） | **avatar** | **tile**（40×40 大方块） |
+| ItemCard 标题字号 | 14px / 500 | 14px / 500 | 16px / 500 |
+| CardGrid.preset | compact / standard / feature | compact / standard / feature | **comfortable** |
+| CardActionBar.mode | density 默认（hover-fade / hover-slidebar） | 同 pure-card | **always-visible**（覆写 density 默认） |
+| Pagination 默认条数 | 12 | 12 | 10（卡片）/ 10（列表） |
+| 其他特殊 | ToggleGroup 胶囊筛选位于 ActionToolbar 右侧 | 同 pure-card | DataTable + BulkActionBar 与 CardGrid 同级，由 ViewToggle 切换可见 |
+
+> **density / iconStyle / cardGridPreset / actionBarMode 的详细规格见本文件 §9 三件套完整规范。**
+
+---
+
+## 2. 通用布局骨架（三个子类型共享，差异仅 Sidebar / ViewToggle）
+
+```
+┌─[Sidebar]*─────────┬─────────────────────────────────────────┤
+│                    │  PageContainer → ContentWrapper          │
+│  * pure-card 无    │  ┌─ ContentCard (白卡容器) ──────────┐  │
+│                    │  │ PageHeader (标题 18px/500)              │  │
+│                    │  │ ActionToolbar:                       │  │
+│                    │  │   [创建] [导入]                       │  │
+│                    │  │   [SearchCombo] [筛选 ToggleGroup]    │  │
+│                    │  │   [ViewToggle]*                       │  │
+│                    │  │ CardGrid (preset=*)                   │  │
+│                    │  │   ┌─ItemCard───────┐ × N              │  │
+│                    │  │   │  CardTitleRow     │              │  │
+│                    │  │   │  [CardDescRow]    │              │  │
+│                    │  │   │  [CardFieldRow×N] │              │  │
+│                    │  │   │  [CardSuppleRow]  │              │  │
+│                    │  │   │  CardActionBar    │              │  │
+│                    │  │   └───────────────────┘              │  │
+│                    │  │ Pagination                            │  │
+│                    │  └────────────────────────────────────┘  │
+└────────────────────┴─────────────────────────────────────────┘
+```
+
+> Sidebar 由 [`page-frame.json`](../../../rules/page-frame.json) L1 自动继承（TWO_COL 显示 / SINGLE_COL 隐藏），本 pattern 不重复声明。
+> ContentCard 内左右对齐遵循 [分层 padding 模型 v7.5](../SKILL.md#5-1-card-内左右对齐稳定规则硬约束)（Card.paddingX 20px 唯一来源）。
+
+---
+
+## 3. 必需组件清单
+
+| 组件 | 来源规范 | 子类型适用 |
+|------|----------|------------|
+| Sidebar | rules/page-frame.json (L1 框架自动继承) | standard-card / view-toggle |
+| ContentCard | rules/component-specs.json C7-Card | 全部 |
+| PageHeader | rules/common-components.json | 全部 |
+| ActionToolbar | — | 全部 |
+| SearchCombo | _shared/search-combo-spec.md | 全部 |
+| ToggleGroup（胶囊筛选 / ViewToggle 复用） | rules/common-components.json | 全部（ViewToggle 仅 view-toggle 必需） |
+| **CardGrid** | **本文件 §9.2** | 全部 |
+| **ItemCard** × N | **本文件 §9.1** | 全部 |
+| **CardActionBar** | **本文件 §9.3** | 全部 |
+| Pagination | rules/common-components.json | 全部 |
+| DataTable | _shared/column-meta-rules.md + action-column-spec.md | view-toggle 切换列表视图时 |
+| BulkActionBar | — | view-toggle 列表视图 |
+
+---
+
+## 4. ItemCard density 选型矩阵
+
+| 信息量条件 | 推荐 density |
+|-----------|--------------|
+| 字段 ≤1 行 + 仅名称+状态 + 大量浏览 | minimal |
+| 字段 ≤2 行 + 操作可发现性要求高 | **standard**（默认） |
+| 字段 ≥3 行 + 需展示详情/指标/进度 | complex |
+| 信息量不确定 | standard |
+
+> view-toggle 子类型锁死 standard。
+
+---
+
+## 5. 嵌套约束（合并三处冗余为唯一一处）
+
+| 父子关系 | 状态 | 适用子类型 |
+|----------|------|----------|
+| ContentWrapper → ContentCard | ALLOW | 全部 |
+| ContentCard → PageHeader / ActionToolbar / CardGrid / Pagination | ALLOW | 全部 |
+| ContentCard → DataTable + BulkActionBar | ALLOW | view-toggle（与 CardGrid 同级，切换可见） |
+| ActionToolbar → SearchCombo / ToggleGroup / ViewToggle | ALLOW | 全部（ViewToggle 仅 view-toggle） |
+| **CardGrid → ItemCard** | ALLOW | 全部 |
+| **ItemCard → CardActionBar** | ALLOW（slot 引用） | 全部 |
+| ContentWrapper → CardGrid 直挂 | FORBID | 必须经 ContentCard 包裹 |
+| ContentCard → ContentCard | FORBID | 白卡容器为单例 |
+| ItemCard → ItemCard | FORBID | 业务卡片禁止嵌套 |
+| CardGrid → 任何非 ItemCard 子节点 | FORBID | Grid 仅承载业务卡片 |
+
+> 卡片组件级硬约束（hover/states/CSS 规则）见 §9。
+
+---
+
+## 6. CRUD 流转 + 操作行为
+
+> 卡片视图操作行为 **完全沿用** ListPage 标准流转，本节仅列出卡片视图要点。
+>
+> - 人可读跨页流转规则 → [`flows.md` §3 CRUD 速查](../../../flows.md#3-crud-流转速查)
+> - 机读结构（URL / Toast / navType）→ [`rules/page-flow.json`](../../../rules/page-flow.json) `crudFlow`
+>
+> 卡片视图要点：
+> - 查看 → DetailPage（保留筛选）
+> - 编辑 → FormPage / Sheet（保存后返回原页）
+> - 删除 → Dialog 二次确认（level3）→ 刷新列表
+> - 批量（仅 view-toggle 列表视图）→ BulkActionBar 启用
+
+---
+
+## 7. 验证清单（按子类型分组）
+
+### 通用项（三个子类型共同检查）
+
+- [ ] ItemCard.density 全页一致（同一页面禁止混用）
+- [ ] CardGrid 使用 `var(--card-grid-min-*)` token，禁止硬编码 minWidth 字面量
+- [ ] CardActionBar.mode ∈ {hover-slidebar, hover-fade, always-visible} 三态之一
+- [ ] CardActionBar position: absolute（不撑开卡片高度）
+- [ ] 危险操作（删除）使用 var(--destructive) 底色 + 始终最后位置
+- [ ] ContentCard 内左右对齐遵循分层 padding 模型 v7.5（20px 唯一来源）
+
+### 子类型差异项
+
+| 验证项 | pure-card | standard-card | view-toggle |
+|--------|-----------|---------------|-------------|
+| layout | SINGLE_COL | TWO_COL + Sidebar | TWO_COL + Sidebar |
+| ViewToggle 存在性 | ❌ | ❌ | ✅ Tab 样式 |
+| ItemCard.iconStyle | avatar | avatar | tile |
+| 标题字号 | 14px | 14px | 16px |
+| CardGrid.preset | compact / standard / feature | compact / standard / feature | comfortable |
+| Pagination | 12 条/页 | 12 条/页 | 10 条/页 |
+| ActionBar 显示时机 | hover 触发 | hover 触发 | 常驻底部 |
+
+---
+
+## 8. 业务字段绑定（产品配置）
+
+> AI 在生成卡片视图列表页时，在确定子类型 + ItemCard variant 后，**必读**：
+> - [`products/{产品}/cards.json`](../../../products/ai-gateway/cards.json)：ItemCard slot 与产品业务字段的绑定（v7.2 新增）
+> - [`products/{产品}/states.json`](../../../products/ai-gateway/states.json)：操作可用性矩阵
+
+### 8.1 cards.json Schema（v7.3 起本文件为唯一规范）
+
+```jsonc
+{
+  "$default": {
+    "component": "ItemCard",
+    "variant": { "density": "standard", "iconStyle": "avatar" },
+    "slots": {
+      "title":         { "field": "<业务字段名>", "avatar": { "source": "icon | colorClass | hash", "fallback": "colorHash" } },
+      "description":   { "field": "<业务字段名>", "lineClamp": 1 },
+      "fields":        [{ "label": "<标签>", "field": "<业务字段名>" }],
+      "supplementary": { "fields": ["<字段1>", "<字段2>"] },
+      "actions":       ["<操作 ID，引用 states.json>"]
+    },
+    "grid": { "component": "CardGrid", "preset": "standard" }
+  }
+}
+```
+
+- **加载阶段**：阶段 ②.5（与 `columns.json` / `states.json` 同阶段）
+- **范例文件**：[`products/ai-gateway/cards.json`](../../../products/ai-gateway/cards.json)
+- **actions 引用**：必须指向 `states.json` 已声明的操作，避免重复定义
+
+### 8.2 子类型 → 三件套参数映射
+
+| 子类型 | itemCard.density | itemCard.iconStyle | cardGridPreset | actionBarMode |
+|-------|------------------|---------------------|----------------|---------------|
+| pure-card | minimal / standard / complex | avatar | compact / standard / feature（与 density 一一对应） | 由 density 决定（hover-fade / hover-slidebar） |
+| standard-card | minimal / standard / complex | avatar | compact / standard / feature（与 density 一一对应） | 由 density 决定（hover-fade / hover-slidebar） |
+| view-toggle | standard（锁死） | tile | comfortable | **always-visible**（覆写 density 默认） |
+
+---
+
+## 9. 业务卡片三件套完整规格【唯一规范来源】
+
+> 本节规格自 v7.3 起从 `rules/card-component.json` 下沉至此。`common-components.json` 中 ItemCard/CardGrid/CardActionBar 的 `specRef` 指向本节锚点。
+> 三件套用于列表页卡片视图；未来如 Dashboard / Workspace / Overview 需要复用，可直接引用本节锚点。
+
+### 9.1 ItemCard（业务卡片）
+
+- **level**: ORGANISM
+- **layer**: business
+- **shadcnComponent**: Card（基于白卡容器扩展）
+- **场景**：CardGrid 内的单个数据项卡片，含 Title/Description/Field/Supplementary/ActionBar 等 slot，可重复多次出现。
+
+#### 9.1.1 variants 变体
+
+| 维度 | 选项 | 默认 | 说明 |
+|------|------|------|------|
+| density | minimal / standard / complex | standard | 信息密度，按 §4 选型矩阵决定 |
+| iconStyle | avatar / tile | avatar | avatar=32×32 圆角（pure-card / standard-card）；tile=40×40 大方块（view-toggle） |
+| titleFontSize | 14px / 16px | — | iconStyle=avatar → 14px/500；iconStyle=tile → 16px/500 |
+
+**iconStyle.avatar 详细**：
+- size: 32×32（常规/复杂）/ 24×24（极简）
+- shape: 圆角矩形 `var(--input-radius)`
+- fallback: 首字母色块 + Glossy 光泽（见 §9.1.6）
+
+**iconStyle.tile 详细**：
+- size: 40×40
+- shape: 大方块（直角或微圆角）
+- fallback: 纯图标，无首字母回退
+
+#### 9.1.2 slots（5 个 slot 区，按 density 决定使用）
+
+| Slot | minimal | standard | complex | 元素与样式 |
+|------|---------|----------|---------|-----------|
+| **CardTitleRow** | 必需 | 必需 | 必需 | icon + title + [badge] + [statusDot] |
+| **CardDescriptionRow** | 禁止 | 必需 | 必需 | text（standard: 12px/lineClamp 1；complex: 14px/lineClamp 2）；color: `var(--gray-tertiary)` |
+| **CardFieldRow** | 禁止 | 0-2 行（可选） | 2-4 行（可选） | fieldIcon(12×12) + fieldLabel(12px) + fieldValue(14px standard / 12px complex) |
+| **CardSupplementaryRow** | 1 行（必需） | 0-1 行（可选） | 1 行（必需） | 元信息：创建人/时间/地域；icon(12×12) + label(12px) + value(12px) |
+| **CardActionBar** | 必需 | 必需 | 必需 | 通过 slot 引用（见 §9.3） |
+
+**CardTitleRow 元素**：
+- icon: minimal=24×24；standard=Avatar 32×32(avatar) / Icon 40×40(tile)；complex=Avatar 32×32；borderRadius `var(--input-radius)`；flex-shrink 0
+- title: 由 variants.titleFontSize 决定；font-weight 500；color `var(--gray-primary)`；单行 truncate
+- badge（可选）: 10px / padding 1px 4px / border-radius 2px；用于「企业版」「Beta」标识
+- statusDot（可选）: 6px 圆点；位置标题尾部或卡片右上角
+
+**CardDescriptionRow CSS**：
+```css
+.card-desc {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  display: -webkit-box;
+  -webkit-line-clamp: N;        /* standard=1 / complex=2 */
+  -webkit-box-orient: vertical;
+}
+```
+
+#### 9.1.3 rowGap（slot 间垂直间距，仅 standard 模式）
+
+| from → to | gap |
+|-----------|-----|
+| CardTitleRow → CardDescriptionRow | 4px |
+| CardDescriptionRow → CardFieldRow | 8px |
+| CardFieldRow → CardSupplementaryRow | 4px |
+
+#### 9.1.4 structureByDensity（density 结构概览）
+
+| density | rowsAscii | 高度 | actionBarMode |
+|---------|-----------|------|----------------|
+| minimal | CardTitleRow → CardSupplementaryRow → CardActionBar | ~100px | hover-fade |
+| standard | CardTitleRow → CardDescriptionRow → CardFieldRow(0-2) → CardSupplementaryRow(0-1) → CardActionBar | ~160px | hover-slidebar（默认）/ always-visible（view-toggle 覆写）|
+| complex | CardTitleRow → CardDescriptionRow(line-clamp:2) → CardFieldRow×2-4 → CardSupplementaryRow → CardActionBar(1-2行) | 240px+ | hover-slidebar |
+
+#### 9.1.5 states（卡片整体状态）
+
+| state | border | background | shadow | actionBar |
+|-------|--------|------------|--------|-----------|
+| default | 1px solid `var(--gray-border)` | `var(--card)` | none | 由 actionBarMode 决定：hover-* 隐藏 / always-visible 常驻 |
+| hover | 1px solid `var(--primary)` + breathing | `var(--card)` | `var(--shadow-sm)` | 可见 |
+| focus | 2px solid `var(--primary)` | `var(--card)` | `var(--shadow-sm)` | 可见 |
+| disabled | 1px solid `var(--gray-border)` | `var(--gray-fill)` | none | 隐藏 |
+
+**hover.breathingBorder CSS**：
+```css
+@keyframes breathing { 0%,100% { opacity:0.5 } 50% { opacity:1 } }
+.card-hover-breathing { animation: breathing 2s ease-in-out infinite; }
+```
+应用在 hover 状态下的 border。
+
+**clickBehavior**：
+- 卡片主体点击：跳转 DetailPage 或进入编辑
+- ActionBar 点击：执行对应 action，事件 `stopPropagation` 不影响卡片 hover
+
+#### 9.1.6 avatarPreset（色块头像系统，iconStyle=avatar 且无图片时）
+
+**colorClasses**（9 种）：`bg-primary` / `bg-success` / `bg-type-mcp` / `bg-warning` / `bg-data-8` / `bg-data-1` / `bg-destructive` / `bg-brand-3` / `bg-data-4`
+
+**fallbackPriority**：
+1. avatar 字段为有效颜色 class → 色块 + 首字母
+2. avatar 字段为有效图片 URL → `<img>`
+3. avatar 字段为空 → `name.charAt(0)` hash 到预设色 + 首字母
+
+**blockStyle**：
+- size: 32×32
+- borderRadius: `var(--input-radius)`
+- textColor: `#fff`
+- fontWeight: 600
+- fontSize: 14px
+- content: `name.charAt(0).toUpperCase()`
+
+**glossy 光泽 CSS**（色块右侧叠加半透明白色渐变）：
+```css
+.avatar-gloss {
+  position: absolute;
+  width: 18px; height: 32px;
+  right: 0; top: 0;
+  background: linear-gradient(180deg, rgba(255,255,255,0.4) 0%, rgba(255,255,255,0.2) 40%, transparent 100%);
+  pointer-events: none;
+}
+```
+
+#### 9.1.7 constraints（硬约束）
+
+- 标题：必须包含，禁止无标题卡片
+- 标题长度：单行省略 (truncate)
+- 描述长度：standard 1 行 / complex 最多 2 行 (`-webkit-line-clamp: 2`)
+- 卡片嵌套：禁止业务卡片嵌套业务卡片（最多 1 级）
+- 样式一致性：同一页面内 ItemCard 的 density + iconStyle 必须保持一致
+- 深色模式：所有图标使用 mask-image 方案（见 [boundaries.md I1-I4](../../../boundaries.md)）
+
+#### 9.1.8 tokens（设计 token 映射）
+
+| 用途 | token |
+|------|-------|
+| background | `--card` |
+| border | `--gray-border` |
+| borderHover | `--primary` |
+| shadowHover | `--shadow-sm` |
+| radius | `--radius-lg` (12px) |
+| iconRadius | `--input-radius` (8px) |
+| titleColor | `--gray-primary` |
+| fieldColor | `--gray-secondary` |
+| descColor | `--gray-tertiary` |
+| disabledBg | `--gray-fill` |
+| transitionDuration | `--duration-normal` (200ms) |
+| transitionEasing | `--easing-ease` |
+
+---
+
+### 9.2 CardGrid（卡片网格）
+
+- **level**: ORGANISM
+- **layer**: business
+- **shadcnImpl**: null
+- **场景**：承载多个 ItemCard，使用 CSS Grid `auto-fill` + `minmax` 自动响应式列数。
+
+#### 9.2.1 props
+
+| prop | 取值 | 说明 |
+|------|------|------|
+| minWidth | 必须引用 `var(--card-grid-min-*)` | 最小列宽（H2 修复，禁止字面量） |
+| gap | `var(--card-gap)` 默认 16px | 卡片间距 |
+| alignContent | literal: `'start'` | 防止卡片拉伸变形 |
+| children | `ItemCard[]` | 仅承载业务卡片 |
+
+#### 9.2.2 CSS 实现
+
+```css
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(
+    auto-fill,
+    minmax(var(--card-grid-min, var(--card-grid-min-standard)), 1fr)
+  );
+  gap: var(--card-gap, 16px);
+  align-content: start;
+}
+```
+
+#### 9.2.3 presets（4 套预设；pagination 已移除，真相源回归 §1 矩阵）
+
+| preset | minWidth | iconStyle | density | usedBy |
+|--------|----------|-----------|---------|--------|
+| **compact** | `var(--card-grid-min-compact)` (240px) | avatar | minimal | pure-card / standard-card |
+| **standard** | `var(--card-grid-min-standard)` (300px) | avatar | standard | pure-card / standard-card |
+| **feature** | `var(--card-grid-min-feature)` (360px) | avatar | complex | pure-card / standard-card |
+| **comfortable** | `var(--card-grid-min-comfortable)` (320px) | tile | standard | view-toggle |
+
+> Token 定义见 `rules/design-tokens.css`。
+
+#### 9.2.4 responsive（参考列数，由 auto-fill 自动计算，无需手写断点）
+
+| viewport | columns |
+|----------|---------|
+| ≥1400px | 4 |
+| 1080-1400px | 3 |
+| 768-1080px | 2 |
+| <768px | 1 |
+
+#### 9.2.5 constraints（硬约束）
+
+- 禁止手动写 `grid-template-columns` 字面量（必须用 `minmax + var(--min-width)`）
+- 禁止 `alignContent: stretch`（会导致卡片高度被拉伸变形）
+- 禁止在 CardGrid 与 ItemCard 之间插入额外 wrapper
+
+---
+
+### 9.3 CardActionBar（卡片操作栏）
+
+- **level**: MOLECULAR
+- **layer**: business
+- **shadcnImpl**: null
+- **场景**：ItemCard 底部的操作栏 — 滑条式 (SlideBar) 设计，白底 + 主要文字色 + 等分宽度（v7.3.1 从主色底调整为白底以提升可读性与表单化一致性）。
+
+#### 9.3.1 props
+
+| prop | 取值 | 说明 |
+|------|------|------|
+| actions | `Array<{ label, onClick, destructive? }>` | 操作列表 |
+| mode | `'hover-slidebar' \| 'hover-fade' \| 'always-visible'` | 三态，默认由 ItemCard.density 决定，pattern 可覆写 |
+| rows | 1 \| 2 | complex 模式可分行 |
+
+#### 9.3.2 containerSpec（容器规格）
+
+```css
+.card-action-bar {
+  position: absolute;
+  bottom: 0; left: 0; right: 0;
+  background: var(--card);                 /* v7.3.1 白底 */
+  border-top: 1px solid var(--gray-line);  /* v7.3.1 顶部分割线代替主色底边 */
+  display: flex;
+  z-index: 2;
+}
+```
+
+> **硬约束**：
+> - 禁止撑开卡片高度（必须 `position: absolute`）
+> - 背景色与 ContentCard 保持一致（`var(--card)`），全局调整背景时不需修改本节
+
+#### 9.3.3 actionButtonSpec（按钮规格）
+
+| 属性 | 值 |
+|------|---|
+| flex | 1（等分宽度） |
+| padding | 8px |
+| text-align | center |
+| color | `var(--gray-primary)`（v7.3.1 主要文字色） |
+| font-size | 13px |
+| font-weight | 500 |
+| cursor | pointer |
+| border-right | `1px solid var(--gray-line)`（v7.3.1 按钮间分隔为浅分割线） |
+| last-child | border-right: none |
+| hover-bg | `var(--gray-fill)`（v7.3.1 浅灰样式 hover） |
+| hover-color | `var(--primary)`（v7.3.1 hover 文字高亮为主色，提高可交互发现性） |
+
+**destructive 按钮**（醒目警示，保留原色机制）：
+- background: `transparent`（默认跟随白底）
+- color: `var(--destructive)`（红色文字表警示）
+- hover-bg: `var(--destructive-bg)`（浅红背景 #FEF2F2）
+- hover-color: `var(--destructive)`（保持红色）
+- 位置：始终放在最后
+
+#### 9.3.4 modes 实现表（三态完整 CSS，名称与 ItemCard.structureByDensity.actionBarMode 完全一致）
+
+##### hover-slidebar（默认；适用 standard / complex density）
+- trigger: 鼠标 hover 卡片
+- method: `transform: translateY(100%)` → `translateY(0)`
+- duration: 200ms / easing: ease
+- visual: 白底上滑，顶部 1px 浅灰分割线与上方内容区分
+
+```css
+.card-action-bar { transform: translateY(100%); transition: transform .2s ease; }
+.card:hover .card-action-bar { transform: translateY(0); }
+```
+
+> **禁止**：使用 `max-height`（触发 reflow，性能差）
+
+##### hover-fade（适用 minimal density）
+- trigger: 鼠标 hover 卡片
+- method: visibility + opacity 切换
+- duration: 200ms / easing: ease
+
+```css
+.card-action-bar { visibility: hidden; opacity: 0; transition: all .2s ease; }
+.card:hover .card-action-bar { visibility: visible; opacity: 1; }
+```
+
+> **禁止**：使用 `display: none`（会导致卡片高度变化）
+
+##### always-visible（view-toggle 子类型覆写）
+- trigger: 无需 hover，常驻底部可见
+- method: 静态显示，无动画
+
+```css
+.card-action-bar {
+  transform: none;
+  visibility: visible;
+  opacity: 1;
+  position: absolute;
+  bottom: 0;
+}
+```
+
+> **禁止**：跟随 hover 状态切换可见性
+
+#### 9.3.5 rowsRule（按钮行规则）
+
+**single（rows=1）**：
+- max: 4 个按钮
+- buttonGap: 8px
+- overflow: 操作 >5 个时，剩余进入「更多 ▾」Dropdown
+
+**double（rows=2）**：
+- row1: 高频操作（管理/编辑/详情等，≤4 个）
+- row2: 低频操作 + 「更多 ▾」（续费/导出/删除等）
+- buttonGap: 8px
+- rowGap: 4px
+
+#### 9.3.6 actionBehavior（操作触发后的页面流转，引用 page-flow.json crudFlow）
+
+| action | confirm | target | after |
+|--------|---------|--------|-------|
+| 查看/详情 | false | DetailPage | 返回保持筛选 |
+| 编辑 | false | FormPage / Sheet | 保存后返回原页 |
+| 导出 | false | 文件下载 | — |
+| 删除 | Dialog 二次确认（level3）| API 调用 | 刷新列表 |
+
+#### 9.3.7 constraints（硬约束）
+
+- **样式**：禁止使用文字按钮或 Primary Button 替代滑条式样式
+- **背景**：`var(--card)` 白底（v7.3.1），与 ContentCard 保持一致；禁止使用主色底
+- **文字**：`var(--gray-primary)` 主要文字色（v7.3.1）；hover 转 `var(--primary)` 提示可点击
+- **动画**：仅使用本节 §9.3.4 三态（hover-slidebar / hover-fade / always-visible），禁止 `display:none` / `max-height`
+- **位置**：必须 `position: absolute; bottom: 0`，不撑开卡片高度
+- **危险操作**：`color: var(--destructive)` 红色文字（v7.3.1 从红底调整），始终放在最后；hover-bg `var(--destructive-bg)`
+- **按钮分隔**：相邻按钮使用 `1px solid var(--gray-line)` 右边框（v7.3.1 浅灰分割线），最后一个按钮无右边框
+
+---
+
+## 10. 渲染流程（AI 生成卡片视图列表页时的引用顺序）
+
+1. **列表 pattern 路由** → 确定 layout（模式A-CARD / 模式D-CARD / 模式D + ViewToggle）
+2. **读取本文件** → 通过 §1 差异矩阵确认子类型；通过 §9 确认 ItemCard / CardGrid / CardActionBar 的 variant 与 preset
+3. **读取 `products/{产品}/cards.json`** → 取 ItemCard slot 的业务字段映射（§8）
+4. **读取 `products/{产品}/states.json`** → 取 actions 可用性（按状态机过滤）
+5. **渲染** CardGrid > ItemCard × N > slots（按 variant 决定 slot 启用/禁用，参考 §9.1.4 structureByDensity）
+6. **应用** `rules/design-tokens.css` 变量（特别是 `--card-grid-min-*` / `--card-gap` / `--primary` / `--gray-*`）→ 完成样式
+
+---
+
+## 附录：版本变迁
+
+| 版本 | 变更 |
+|------|------|
+| v7.1 | 卡片规范从 `card-component-rules.md` 升格为 `rules/card-component.json` 业务组件 contract（ItemCard/CardGrid/CardActionBar 注册到 common-components.json） |
+| v7.2 | 三 patterns（pure-card-list / standard-card-list / view-toggle-list）合并为本文件；contract 修复 H1-H4 |
+| **v7.3** | **`rules/card-component.json` 废止**：完整规格下沉至本文件 §9（ItemCard / CardGrid / CardActionBar 的 variants / slots / states / hover / avatar / modes / constraints / tokens）；术语区分迁至 §0；cards.json Schema 迁至 §8.1；pageTypeMapping 迁至 §8.2；renderingFlow 迁至 §10。`common-components.json` 中 specRef 改指本文件锚点。 |

package/src/teamix-evo-design-opentrek/pages/list-page/patterns/drawer-list.md

@@ -0,0 +1,76 @@
+# 抽屉中列表页 (drawer)
+
+> 路由自 `../SKILL.md`
+> 布局模式: 模式D (内嵌 Sheet/Dialog)
+> 核心差异: 列表嵌入在 Sheet 中，用于选择关联数据
+
+## 1. 布局骨架
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  主页面内容 (ListPage / FormPage / DetailPage)                              │
+│  ...                                                                  │
+│  ┌───────────────────────────────────────────┐                        │
+│  │  Sheet (右侧滑出, 宽度 600-900px)         │                        │
+│  │  ┌───── SheetHeader ──────────────────┐ │                        │
+│  │  │ 选择关联实例              [× 关闭]    │ │                        │
+│  │  ├─────────────────────────────────────┤ │                        │
+│  │  │  ActionToolbar (SearchCombo 等)     │ │                        │
+│  │  │  ──┬──────────────────────────┬──  │ │                        │
+│  │  │     DataTable (含选择框)          │ │                        │
+│  │  │  ☑|ID|名称|状态|...|操作         │ │                        │
+│  │  │  ☐|i-xxx|test|●运行中|...|选择   │ │                        │
+│  │  │  ────────────────────────────── │ │                        │
+│  │  │  Pagination                      │ │                        │
+│  │  ├─────────────────────────────────────┤ │                        │
+│  │  │  [取消]  [确定] (底部操作栏)        │ │                        │
+│  │  └─────────────────────────────────────┘ │                        │
+│  └───────────────────────────────────────────┘                        │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## 2. 核心差异
+
+| 维度 | 标准列表 | 抽屉中列表 |
+|------|----------|-----------|
+| 容器 | PageContainer | **Sheet** |
+| 触发方式 | 直接访问 URL | **点击按钮/链接打开 Sheet** |
+| 选择返回 | 跳转页面 | **选择后点击确定关闭 Sheet，返回选中数据** |
+| 宽度 | 全宽/自适应 | **固定宽度 (600-900px)** |
+| 关闭方式 | 浏览器返回/面包屑 | **点击 × / 遮罩层 / Esc** |
+| 底部操作栏 | 无 | **必需 [取消] [确定]** |
+
+## 3. Sheet 交互规范
+
+| 交互 | 行为 |
+|------|------|
+| 打开 Sheet | 点击触发按钮，从右侧滑出，宽度 600-900px |
+| 选择数据 | 勾选选择框，支持单选/多选(由业务决定) |
+| 确认选择 | 点击"确定"关闭 Sheet，返回选中数据到主页面 |
+| 取消选择 | 点击"取消"关闭 Sheet，不返回数据 |
+| 关闭 Sheet | 点击 × / 遮罩层 / Esc，丢弃未确认的选择 |
+| 搜索/筛选 | 在 Sheet 内执行搜索/筛选，不跳转页面 |
+| 分页 | 在 Sheet 内分页，不影响主页面 |
+
+## 4. 引用共享规则
+
+| 共享规则 | 路径 | 说明 |
+|----------|------|------|
+| 表格列元规则 | `../_shared/column-meta-rules.md` | 列元规则（显隐/拖拽/排序）
+| 产品列定义 | `products/{产品}/columns.json` | 具体列名/宽度/类型 |
+| 操作列规范 | `../_shared/action-column-spec.md` | 操作列结构 |
+
+> DataTable、Pagination、ActionToolbar 等组件与标准列表页一致，不再重复。
+> 操作列中"管理/查看"等页面跳转操作在抽屉中通常禁用或隐藏。
+
+## 5. 验证清单
+
+> 通用检查项见 `../../../docs/validation-workflow.md` 验证清单。此处仅列出本模式差异项。
+
+| 验证项 | 检查点 | 目标 |
+|--------|--------|------|
+| Sheet滑出 | 右侧滑出，宽度600-900px | 正确 |
+| 遮罩层 | 半透明遮罩，点击关闭 | 正确 |
+| 选择反馈 | 选中行高亮 | 正确 |
+| 确定/取消 | 确定返回数据，取消丢弃 | 正确 |
+| Esc关闭 | Esc关闭Sheet | 正确 |