@teamix-evo/skills 0.5.0 → 0.6.0

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

@@ -0,0 +1,70 @@
+# 可展开列表页 (expandable)
+
+> 路由自 `../SKILL.md`
+> 布局模式: 模式D
+> 核心差异: DataTable 行内展开显示子数据/详情
+
+## 1. 布局骨架
+
+在标准列表页(standard-list.md)基础上，DataTable 支持行内展开：
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  PageHeader + ActionToolbar (同标准列表页)                                 │
+│  ──┬────────────────────────────────────────────────────────────┬── │
+│     DataTable (行内展开)                                           │
+│  ☑|ID|名称|状态|标签|...|操作                                    │
+│  ▶|i-xxx|test|●运行中|🏷|...|管理|...                             │
+│    ┌─────────────────────────────────────────────────────────┐  │
+│    │ 子项1: 详情A | 详情B | 详情C                              │  │
+│    │ 子项2: 详情D | 详情E                                     │  │
+│    └─────────────────────────────────────────────────────────┘  │
+│  ▶|i-yyy|prod|●运行中|🏷|...|管理|...                             │
+│  ───────────────────────────────────────────────────────────── │
+│  BulkActionBar + Pagination (同标准列表页)                              │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## 2. 核心差异
+
+| 维度 | 标准列表 | 可展开列表 |
+|------|----------|-----------|
+| 行展开 | 不支持 | **支持** |
+| 展开触发 | — | **点击行首展开图标(▶) 或 点击行** |
+| 展开方式 | — | **行内展开，不弹出 Dialog/Sheet** |
+| 展开高度 | — | **自适应，最大高度 200px** |
+| 展开状态持久化 | — | **翻页后保持展开状态** |
+
+## 3. 行内展开交互规范
+
+| 交互 | 行为 |
+|------|------|
+| 点击展开图标(▶) | 展开/收起该行，展开图标变为 ▼ |
+| 点击行(非操作区) | 同展开图标，切换展开状态 |
+| 同时展开 | 支持多行同时展开 |
+| 展开内容 | 子数据表格 / 详情描述列表 / 关联信息 |
+| 收起所有 | 提供"收起全部"按钮(可选) |
+| 翻页行为 | 展开状态持久化，翻回原页时保持 | 待确认: 参考文档为"换页不保留" |
+
+## 4. 引用共享规则
+
+| 共享规则 | 路径 | 说明 |
+|----------|------|------|
+| 表格列元规则 | `../_shared/column-meta-rules.md` | 列元规则（显隐/拖拽/排序）
+| 产品列定义 | `products/{产品}/columns.json` | 具体列名/宽度/类型 |
+| 操作列规范 | `../_shared/action-column-spec.md` | 操作列结构、行为 |
+| 状态-操作模式 | `../_shared/state-action-pattern.md` | 状态驱动操作元规则
+| 产品状态机 | `products/{产品}/states.json` | 具体状态/操作可用性 |
+
+> DataTable(不含展开行为)、BulkActionBar、Pagination、ActionToolbar 等组件及交互行为与标准列表页一致，不再重复。
+
+## 5. 验证清单
+
+> 通用检查项见 `../../../docs/validation-workflow.md` 验证清单。此处仅列出本模式差异项。
+
+| 验证项 | 检查点 | 目标 |
+|--------|--------|------|
+| 展开图标 | ▶/▼ 切换正确 | 正确 |
+| 行内展开 | 不弹出新窗口/Dialog | 正确 |
+| 多行展开 | 支持同时展开多行 | 正确 |
+| 翻页持久化 | 翻回原页时展开状态保持 | 正确 |

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

@@ -0,0 +1,73 @@
+# 带 L2 导航列表页 (l2-sidebar)
+
+> 路由自 `../SKILL.md`
+> 布局模式: 模式D + Sidebar(TWO_COL)
+> 核心差异: 左侧 240px 分类导航 + 右侧标准列表
+
+## 1. 布局骨架
+
+在标准列表页(standard-list.md)基础上，页面采用 **TWO_COL** 布局：
+
+```
+┌──────────┬──────────────────────────────────────────────┤
+│          │  PageHeader + ActionToolbar + DataTable      │
+│  Sidebar │  + BulkActionBar + Pagination                │
+│ (240px)  │  (同标准列表页完整结构)                        │
+│          │                                              │
+│ [分类A]  │                                              │
+│ [分类B]  │                                              │
+│ [分类C]  │                                              │
+│ ──       │                                              │
+│ [子分类] │                                              │
+│ [子分类] │                                              │
+└──────────┴──────────────────────────────────────────────┘
+```
+
+## 2. 核心差异
+
+| 维度 | 标准列表 | L2 导航列表 |
+|------|----------|-------------|
+| 布局 | SINGLE_COL / TWO_COL | **TWO_COL** |
+| Sidebar | 可选 | **必需** |
+> Sidebar 收起/展开、交互规范、色彩全部引用 `rules/design-tokens.json` sidebarRules（统一规范）。
+
+## 3. Sidebar 交互规范
+
+| 交互 | 行为 |
+|------|------|
+| 点击分类 | 刷新右侧列表数据，保持当前页码 |
+| 展开/收起 | 切换子分类列表，动画过渡 |
+| 收起 Sidebar | 宽度缩至 68px，仅显示图标（详见 design-tokens.json sidebarRules.collapseBehavior） |
+| 选中态 | 灰色背景 var(--sidebar-active)（详见 design-tokens.json sidebarRules.colors.menuItem.active） |
+| 手风琴 | 打开一个分组自动关闭其他分组 |
+| 收起态 Tooltip | Hover显示节点名称 |
+| 展开持久化 | 展开/收起状态持久化 |
+| 计数徽章 | 每项右侧显示数据量（灰色 12px），数据驱动，实时刷新 |
+| 状态指示灯 | 菜单项前圆点(8px)+文字，颜色对应状态(绿/灰/蓝脉冲) |
+| 约束 | 最大 20 项 / 最大 2 级嵌套 |
+
+## 4. 引用共享规则
+
+与标准列表页共享相同的规则文件：
+
+| 共享规则 | 路径 | 说明 |
+|----------|------|------|
+| 表格列元规则 | `../_shared/column-meta-rules.md` | 列元规则（显隐/拖拽/排序）
+| 产品列定义 | `products/{产品}/columns.json` | 具体列名/宽度/类型 |
+| 操作列规范 | `../_shared/action-column-spec.md` | 操作列结构、行为 |
+| 状态-操作模式 | `../_shared/state-action-pattern.md` | 状态驱动操作元规则
+| 产品状态机 | `products/{产品}/states.json` | 具体状态/操作可用性 |
+
+> DataTable、BulkActionBar、Pagination、ActionToolbar 等组件及交互行为与标准列表页一致，不再重复。
+
+## 5. 验证清单
+
+> 通用检查项见 `../../../docs/validation-workflow.md` 验证清单。此处仅列出本模式差异项。
+
+| 验证项 | 检查点 | 目标 |
+|--------|--------|------|
+| Sidebar 规格 | 展开240px/收起68px（详见 design-tokens.json sidebarRules） | 正确 |
+| 分类选中态 | 灰色背景 var(--sidebar-active) | 正确 |
+| 分类切换 | 右侧列表刷新 | 正确 |
+| 计数徽章 | 每项右侧显示数据量（灰色12px） | 正确 |
+| 状态指示灯 | 圆点(8px)+文字，颜色对应状态 | 正确 |

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

@@ -0,0 +1,198 @@
+# 标准列表页 (standard)
+
+> 路由自 `../SKILL.md`
+> 布局模式: 模式D (复合模式)
+> 核心组件: DataTable + Pagination
+
+## 1. 布局骨架
+
+```
+┌──────────┬──────────────────────────────────────────────┤
+│          │  PageHeader                                  │
+│  Sidebar │  标题(18px/medium) [描述*] + [了解更多 12px]          │
+│          │  ─────────────────────────                   │
+│          │  ActionToolbar (单行 flex, nowrap)            │
+│          │  [创建] [批量创建]    [全部▼][输入...]🔍 [刷新]   │
+│          │  ──┬─────────────────────────────────────┬── │
+│          │     DataTable (固定列: 左选择框+ID, 右操作)    │
+│          │  ☑|ID|名称|状态|监控|标签|IP|规格|...|操作    │
+│          │  ☐|i-c7p...|test|●运行中|📊|🏷|192.168|2C2G|...│ │
+│          │  ──────────────────────────────────────── │
+│          │  BulkActionBar (内嵌表格wrapper, 选中时显示)    │
+│          │  ☑全选  [启动][停止][重启][删除]  已选2项 共8条 │
+│          │  ──────────────────────────────────────── │
+│          │  Pagination                                  │
+│          │  [‹] [1] [›]  每页显示: [10 ▼]              │
+└──────────┴──────────────────────────────────────────────┘
+```
+
+> 注: Sidebar 非必需，有 L2 导航需求时采用 TWO_COL，否则 SINGLE_COL。
+
+## 2. 必需组件（补充）
+
+| 组件 | 引用 | 层级 | 位置 | 说明 |
+|------|------|------|------|------|
+| DataTable | — | ORGANISM | center | 数据表格，支持排序/筛选/选择/固定列 |
+| BulkActionBar | — | MOLECULAR | bottom | 批量操作栏，内嵌于 DataTable 同一 wrapper 内，选中时显示 |
+
+## 3. 可选组件
+
+| 组件 | 引用 | 条件 | 说明 |
+|------|------|------|------|
+| QueryFilter | — | 筛选条件>3个时 | 高级搜索面板 |
+| ColumnConfig | — | 表格列>8列时 | 列配置弹窗，支持列显隐切换 |
+| Dialog | — | 删除/批量操作确认 | 确认弹窗 |
+| Sheet | — | 列表嵌入抽屉 | 侦滑面板 |
+| Tag | — | 标签/状态展示 | 20px 高度小标签 |
+| Badge | — | 状态徽章 | 圆形状态点 + 文字 |
+| Empty | — | 空数据 | 空状态 + 新建引导 |
+| Spinner | — | 加载中 | Loading 状态 |
+| Alert | — | 需要操作提示时 | 操作前警告提示 |
+| Sonner | — | 操作反馈 | Sonner 提示 |
+| Tooltip | — | 列标题/操作说明 | 悬浮提示 |
+| FilterTag | — | 已选筛选条件 | 筛选标签(以Tag形式展示，可单独移除) |
+
+## 4. 操作工具栏 (ActionToolbar)
+
+### 结构
+
+- **布局**: 单行 flex 布局 (`flex-wrap: nowrap`)，工具栏内部 gap = 8px
+- **左侧 `.left-actions`**: 主要操作按钮(创建等)，内部 gap = 8px
+- **SearchCombo（紧跟 .left-actions 后方）**: 作为 `.action-toolbar` 的直接子元素（**不嵌套在 .right-tools 内**），与 `.left-actions` 间距 = **20px**【硬约束】。CSS：`.action-toolbar > .search-combo { margin-left: calc(20px - var(--button-gap)); }`
+- **右侧 `.right-tools`**: 工具按钮(刷新/设置)，通过 `margin-left: auto` 推到右侧，内部间距 8px
+- **DOM 顺序**: `.left-actions` → `.search-combo` → `.right-tools`
+- **禁止**: 换行、多行布局；禁止将 SearchCombo 嵌套在 .right-tools 或 .left-actions 内
+- **Primary 按钮**: 同一区域内最多 1 个
+- **按钮数量**: 直接展示 ≤3 个，超出入 Dropdown
+
+### SearchCombo 结构
+
+- **搜索模式下拉框**: 无边框，与输入框共用外层容器边框，默认"全部"(全部/实例ID/名称/IP等维度)
+- **搜索输入框**: 无边框，与下拉框共用外层容器边框，placeholder 自动识别
+- **搜索图标**: 位于输入框内部右侧，绝对定位
+- **布局**: 外层统一边框容器，内部下拉框与输入框无边框，通过右侧分隔线区分
+
+### SearchCombo CSS 实现
+
+> 详细 CSS 规范见 `../_shared/search-combo-spec.md`（容器样式、状态、内部元素）。
+
+### 搜索与筛选交互
+
+- 搜索模式下拉框切换维度(全部/实例ID/名称/IP)
+- 输入框回车键执行搜索
+- 搜索图标点击也可执行搜索
+- 筛选条件组合为 AND 关系
+- 已选筛选项以 FilterTag 形式展示，可单独移除
+- 筛选条件清空后，FilterTag 区域隐藏(display:none)
+- 搜索框支持最近搜索记录(可选)
+
+### 筛选区展开布局（可选）
+
+当需要高级筛选时，ActionToolbar 下方可展开筛选区：
+
+```
+筛选区 (可展开, 每行最多 4 个 Select):
+  状态[Select] 地域[Select] 规格[Select] 标签[Select]
+  [搜索] [重置]
+```
+
+- 每行最多 4 个 Select（超过时换行或收入高级筛选面板）
+- 筛选条件与 FilterTag 联动，选中条件以 Tag 形式展示在表格上方
+- "重置"按钮一键清除所有筛选条件
+- 筛选无结果时：保留表头，显示"未找到匹配结果" + "清除筛选"按钮
+
+## 5. 批量操作
+
+- 触发条件：至少选中 1 行
+- 未选中时批量工具栏隐藏
+- **位置**: 选中后内嵌显示在表格底部（Pagination 上方），非独立卡片区域
+- 批量操作后执行：刷新列表 + Sonner 提示结果
+- 批量删除需 Dialog 二次确认 + 输入确认文本
+- 工具栏结构：[操作按钮组] + "已选 N 条"计数，右侧"共 M 条"
+- 异步批量操作：Sonner "批量操作已提交, 共N条", 轮询状态刷新
+- disabled 样式：`opacity: 0.45; pointer-events: none; cursor: not-allowed`
+
+## 6. 分页约定
+
+- 默认每页条数：10（业务可根据数据量调整为 5/10/20/50）
+- 可选每页条数：5 / 10 / 20 / 50（根据业务数据规模配置）
+- 翻页后保持筛选条件和滚动位置
+- 总数显示：`共 {total} 条`（非"项"）
+- 支持"前往 X 页"跳转 + 确定按钮
+
+## 7. 键盘快捷键
+
+| 快捷键 | 操作 |
+|-------|------|
+| `Enter` | 执行搜索 |
+| `Esc` | 关闭弹窗/取消选择 |
+| `Ctrl/Cmd + A` | 全选当前页 |
+| `Ctrl/Cmd + F` | 聚焦搜索框 |
+| `↑/↓` | 表格行导航(聚焦时) |
+| `Space` | 切换行选中状态 |
+
+## 8. 边界情况处理
+
+| 场景 | 处理方式 | 文案规范 | ActionBar 状态 |
+|------|----------|---------|---------------|
+| 首次使用 | Empty 组件 + 新建引导 | "暂无内容" + 创建入口链接 | 创建按钮必须可用 |
+| 加载中 | Skeleton 骨架屏 / Spinner 组件 | — | 搜索/刷新保留 |
+| 加载失败 | ErrorState + 重试按钮 | — | 刷新可用 |
+| 筛选无结果 | 保留表头 + 空状态区 | "未找到匹配结果" + "清除筛选"链接 | 创建可用, 导出禁用 |
+| 数据已清空 | Empty 组件 | "暂无数据" | 刷新可用 |
+| 权限不足 | 操作按钮隐藏或置灰 | — | 根据权限动态显隐 |
+| 分页溢出 | 重置到第 1 页 | — | — |
+
+**空状态规则：**
+- 必须有引导操作（创建/清除/帮助），不要只显示"暂无数据"无引导
+- 文案以"暂无"开头
+- 列表页空状态保留表头
+- 空状态时隐藏分页器
+
+## 9. 引用共享规则
+
+> 读取规则：元规则定义通用约束 + 产品配置定义具体列/状态。
+
+| 共享规则 | 路径 | 说明 |
+|----------|------|------|
+| 表格列元规则 | `../_shared/column-meta-rules.md` | 列定义结构、显隐规则、拖拽、排序 |
+| 产品列定义 | `products/{产品}/columns.json` | 具体列名/宽度/类型/显隐条件 |
+| 操作列规范 | `../_shared/action-column-spec.md` | 操作列结构、行为、禁用样式 |
+| 状态-操作模式 | `../_shared/state-action-pattern.md` | 状态驱动操作的元规则、异步处理、确认级别 |
+| 产品状态机 | `products/{产品}/states.json` | 具体状态名/操作可用性/确认级别 |
+
+**示例**（以 PolarDB 为例）：
+- 列定义读 `products/polar-db/columns.json`（11列：集群ID/名称/状态/数据库类型/地域/规格/节点数/存储空间/连接地址/到期时间/资源组）
+- 状态机读 `products/polar-db/states.json`（5种状态：运行中/已停止/创建中/变配中/释放中）
+
+## 10. 与 PageContainer 模式对照
+
+> 布局模式定义见 `../../../rules/layout-rules.json`
+
+标准列表页使用 **模式D（复合模式）**：
+```
+PageContainer → ContentWrapper → PageHeader + ActionToolbar + DataTable + BulkActionBar + Pagination
+```
+当不需要筛选时退化为 **模式B**：
+```
+PageContainer → ContentWrapper → PageHeader + DataTable + BulkActionBar + Pagination
+```
+
+## 11. 验证清单
+
+> 通用检查项见 `../../../docs/validation-workflow.md` 验证清单。此处仅列出标准列表模式差异项。
+
+| 验证项 | 检查点 | 目标 |
+|--------|--------|------|
+| **Card.paddingX 外侧提供** | Card 白卡容器 `padding: 0 var(--card-padding-x)` (左右 20px)；PageHeader / ActionToolbar / BulkActionBar / Pagination 的水平 padding 全部 = 0 | **必须 100% 一致**，非 Table 子组件重复设置 paddingX 即为违反 |
+| **Table 分层 padding v7.5** | 中间列 th/td paddingX = 12px（列间距 24px）；首列 padding-left = **20px**；末列 padding-right = **20px**；首列内容 X = Card 外缘 + 40；末列右缘 X = Card 右缘 - 40；唯一可接受模式：`px-3 first:pl-5 last:pr-5` | 100% |
+| 表格列 | 列数、类型、宽度、对齐、排序、固定匹配规范 | 全部匹配 |
+| 列显隐 | 条件列(监控/可用区/组织)按规则显隐 | 正确 |
+| 操作列 | 分隔线、按钮样式、disabled 样式 | 正确 |
+| 标签列 | 无标签显示"-"、最多 3 个、超出+N | 正确 |
+| SearchCombo | 容器边框、内部无边框、回车搜索 | 正确 |
+| 批量操作 | 选中≥1行显示、混合状态禁用 | 正确 |
+| 分页 | 默认 10条/页、"共N条" | 正确 |
+| Do's & Don'ts | 主按钮左侧第一位、操作列固定右侧、空数据隐藏分页、Primary≤1 | 全部遵守 |
+| 筛选无结果 | 保留表头 + "未找到匹配结果" + "清除筛选" | 正确 |
+| 三态Checkbox | 未选/半选/全选状态正确 | 正确 |

package/src/teamix-evo-design-opentrek/patterns/color-mapping.md

@@ -83,7 +83,7 @@
 
 ## 6. Sidebar / Topbar 命名空间
 
-详见 [sidebar.md §3](./sidebar.md#3-颜色映射v41-品牌化)。**不**使用主色槽（`--color-primary` 等），全部走 `--color-sidebar-*` / `--color-topbar-*`。
+详见 [sidebar-spec.md §3](../rules/sidebar-spec.md#3-颜色映射v41-品牌化)。**不**使用主色槽（`--color-primary` 等），全部走 `--color-sidebar-*` / `--color-topbar-*`。
 
 ---