@teamix-evo/skills 0.3.0 → 0.5.0

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

@@ -0,0 +1,367 @@
+# List Page — 列表页模式
+
+> ⚠️ **Prerequisites**: 你必须已在 [generation-flow.md](../generation-flow.md) Step 2 确认页面类型为 **ListPage**，并由 Step 3 引导到这里。
+
+> **触发**：用户描述含"列表/表格/查询/检索/卡片管理"。
+> **核心特征**：多条结构化数据 + 搜索/筛选 + 分页。
+> **页面级别**：L1（标题模式 PageHeader，自动继承 Sidebar）。
+
+---
+
+## 1. 子类型路由
+
+| 子类型              | 关键词                           | 布局                          | 核心组件                            |
+| ------------------- | -------------------------------- | ----------------------------- | ----------------------------------- |
+| **standard**        | "列表"/"表格"/"查询"             | TWO_COL                       | DataTable + Pagination              |
+| **l2-sidebar**      | "分类"/"分组"/"左侧树"           | TWO_COL + 内部 Sidebar(240px) | Sidebar + DataTable                 |
+| **expandable**      | "展开"/"子项"/"详情行"           | TWO_COL                       | DataTable（行内展开）               |
+| **drawer**          | "弹窗列表"/"选择器"              | Drawer 内                     | DataTable ⊂ Drawer                  |
+| **pure-card**       | "纯卡片"/"卡片管理"/"智能体列表" | SINGLE_COL                    | CardGrid + ItemCard + CardActionBar |
+| **standard-card**   | "卡片列表"/"分类卡片"/"资源卡片" | TWO_COL                       | Sidebar + CardGrid + ItemCard       |
+| **view-toggle**     | "视图切换"/"列表卡片切换"        | TWO_COL + ViewToggle          | ViewToggle + DataTable/CardGrid     |
+| **advanced-filter** | "高级筛选"/"更多条件"            | TWO_COL                       | AdvancedFilterPanel + DataTable     |
+
+### 路由优先级
+
+1. "纯卡片"/"卡片管理" → pure-card
+2. "卡片列表"/"分类卡片"/"资源卡片" → standard-card
+3. "视图切换"/"列表卡片" → view-toggle
+4. "高级筛选" → advanced-filter
+5. "展开"/"子项" → expandable
+6. "分类"/"分组"/"左侧树" → l2-sidebar
+7. "弹窗列表"/"选择器" → drawer
+8. 默认 → standard
+
+---
+
+## 2. Template 组件拼装
+
+> 源自 `packages/create/variants/opentrek/src/templates/list-page.tsx`
+
+```tsx
+<PageShell background="muted" sidebar={<OpSidebar />}>
+  <OpPageContainer header={<PageHeader title="..." actions={...} />}>
+    {/* children: 以下组件由消费方自由组合 */}
+    <ActionToolbar ... />
+    <DataTable ... />   {/* 或 CardGrid */}
+    <Pagination ... />
+  </OpPageContainer>
+</PageShell>
+```
+
+| Slot         | 注入内容                                          | 来源                               |
+| ------------ | ------------------------------------------------- | ---------------------------------- |
+| `sidebar`    | OpSidebar（左导）                                 | `@/components/business/op-sidebar` |
+| `pageHeader` | PageHeader 整块（title + Tabs + Toolbar 组合）    | `@/components/ui/page-header`      |
+| `children`   | ActionToolbar + DataTable / CardGrid + Pagination | 消费方自组合                       |
+
+**壳层特征**：
+
+- PageShell `background="muted"` → 灰底主区
+- OpPageContainer → 内嵌**无边框大白卡**（`bg-card rounded-2xl p-6`）
+- 业务组件直接作为 children，**不要再包 `<Card>`**（白卡单例）
+
+---
+
+## 3. 标准结构（设计线框）
+
+```
+┌────────────────────────────────────────────┐
+│ PageHeader: 标题模式              [新建]   │  ← Header zone
+├────────────────────────────────────────────┤
+│ ActionToolbar: 🔍 搜索 [筛选▼] [刷新]      │  ← Toolbar zone
+├────────────────────────────────────────────┤
+│ ▢ ID         │ 状态  │ 创建时间  │ 操作  │  ← Main zone
+│ ▢ ORD-001234 │ 进行中│ 2026-05-13│ ⋯    │
+│ ▢ ORD-001235 │ 已完成│ 2026-05-12│ ⋯    │
+├────────────────────────────────────────────┤
+│ [已选 2 项] 批量审批 / 批量导出 / 批量删除  │  ← BulkActionBar (按需)
+├────────────────────────────────────────────┤
+│        ←  1 / 24 →  [50/页 ▼]   共 1200条 │  ← Footer zone
+└────────────────────────────────────────────┘
+```
+
+---
+
+## 4. 必需组件
+
+| 组件                          | 位置    | 说明                                                     |
+| ----------------------------- | ------- | -------------------------------------------------------- |
+| **PageHeader**                | top     | 标题模式(L1 页面);右侧主操作(如「新建」)                 |
+| **ActionToolbar**             | toolbar | 单行 flex(nowrap);左 actions + 中 SearchCombo + 右 tools |
+| **DataTable** 或 **CardGrid** | main    | 二选一,按子类型                                          |
+| **Pagination**                | footer  | 默认 10 条/页(标准列表) / 12 条/页(卡片)                 |
+
+**框架级**(自动继承,不在 skill 内声明):Sidebar。
+
+---
+
+## 5. SearchCombo 规范
+
+> ListPage 顶部搜索 + 筛选的标准复合组件。**禁止**用 Input + Select 散件拼装。
+
+### 4.1 在 ActionToolbar 中的位置（硬约束）
+
+- SearchCombo 是 ActionToolbar 的**直接子元素**，位于 `.left-actions` 之后、`.right-tools` 之前
+- 与 `.left-actions` 间距 = **20px**
+
+### 4.2 结构
+
+```
+[ 维度Select | 分隔线 | 搜索Input | 搜索Button(图标) ]
+```
+
+- 容器统一 border + radius 6px + height 32px + min-width 200px
+- 内部元素无独立边框
+
+### 4.3 交互规则
+
+| 触发                      | 行为                             |
+| ------------------------- | -------------------------------- |
+| 切换维度                  | input.value 清空 → input.focus() |
+| 输入框回车 / 点击搜索按钮 | 执行搜索 → 重置到第 1 页         |
+| 输入框 hover 显示 ×       | 清空输入 → 维度切回"全部"        |
+| 输入框为空时点搜索        | 清除当前条件 → 重置分页          |
+
+### 4.4 FilterTag 展示
+
+- 已应用的搜索条件以 FilterTag 形式展示
+- 单条 Tag 含 `label: value ×`
+- 多条提供「清空全部」链接
+
+### 4.5 搜索维度配置示例
+
+> 维度按业务上下文动态配置;默认含「全部」。
+
+```json
+// 默认维度
+[
+  { "label": "全部", "value": "all" },
+  { "label": "名称", "value": "name" },
+  { "label": "ID", "value": "id" }
+]
+
+// ECS 实例列表示例
+[
+  { "label": "全部", "value": "all" },
+  { "label": "实例 ID/名称", "value": "instance" },
+  { "label": "IP", "value": "ip" },
+  { "label": "标签", "value": "tag" }
+]
+```
+
+---
+
+## 6. DataTable 规则（核心）
+
+### 5.1 列元规则（每列必备）
+
+| 规则     | 说明                                  |
+| -------- | ------------------------------------- |
+| 唯一 ID  | 用于列宽 / 显隐持久化                 |
+| 显隐规则 | "始终显示" 或 "条件显示" + 触发条件   |
+| 宽度定义 | 固定 px / 百分比 / minmax             |
+| 对齐方式 | left（默认）/ center / right          |
+| 排序能力 | 是否支持服务端排序                    |
+| 固定方向 | left（前缀列）/ right（操作列）/ none |
+| 字体     | ID/IP/Hash 等机器列用 `font-mono`     |
+
+### 5.2 列固定
+
+- 左固定：Checkbox(48px) + ID/名称（20%）
+- 右固定：操作列（140px）
+- 固定列与滚动列交界处 `box-shadow: 1px 0 0 var(--border)`
+- 固定列 `z-index: 10`，滚动列 `z-index: 1`
+
+### 5.3 行高
+
+- 单行内容：56px
+- 多行内容（如规格列）：72px+
+
+### 5.4 选择框三态
+
+| 状态   | 视觉             | 触发            |
+| ------ | ---------------- | --------------- |
+| 未选 ☐ | 默认             | —               |
+| 半选 ☐̲ | 当前页有部分选中 | 自动计算        |
+| 全选 ☑ | 当前页全选       | 点表头 checkbox |
+
+### 5.5 行选择交互
+
+- Checkbox：切换当前行
+- 行点击（非操作区）：跳转 DetailPage
+- Shift+点击：范围选中
+- Ctrl/Cmd+点击：切换单行
+- 选中样式：背景 `bg-accent`（与 Checkbox 选中态一致）
+
+### 5.6 列宽拖拽
+
+- 拖拽手柄置于列头右边界,宽 2px,`cursor: col-resize`
+- 仅对 `visibility: always` 的列允许拖拽
+- 最小宽度取列定义的 `minWidth`(无定义时默认 100px,状态/监控类窄列 80px)
+- 最大宽度不超过表格宽度的 50%
+- 拖拽过程对 `document.body` 加 `cursor: col-resize` + `user-select: none`,防鼠标越界丢失光标
+- 拖拽结束写入 `localStorage`(key 命名 `columnWidths:{产品ID}`);初始化时读取恢复
+- 列配置弹窗提供「恢复默认列宽」按钮,清 localStorage 后刷新
+
+### 5.7 列排序
+
+- 表头右侧 `⇅` 图标(`text-tertiary`、12px)
+- 升序 `↑` / 降序 `↓` 用 `primary` 色
+- 点击循环:默认 → 升序 → 降序 → 默认
+- 排序状态持久化到 `localStorage`
+
+### 5.8 文字换行
+
+| 列类型  | 处理                                               |
+| ------- | -------------------------------------------------- |
+| ID / IP | `font-mono` + `word-break: break-all` + `truncate` |
+| 规格    | 多行展示,不截断                                    |
+| 标签    | 最多 3 个 + `+N`,不自动换行                        |
+
+---
+
+## 7. 操作列规范（硬约束）
+
+### 6.1 结构
+
+操作列 = 主操作 + 分隔线 + 次要操作 + 分隔线 + 状态操作 + 分隔线 + 更多
+
+| 元素                | 样式     | 禁用                             |
+| ------------------- | -------- | -------------------------------- |
+| 主操作（管理/查看） | 链接样式 | —                                |
+| `\|` 分隔线         | —        | —                                |
+| 次要操作            | 文字按钮 | `opacity-45 pointer-events-none` |
+| 状态操作            | 下拉按钮 | 同上                             |
+| "..." 更多          | Dropdown | —                                |
+
+### 6.2 水平对齐（硬约束）
+
+- `text-align: left`，**表头与表体均需显式声明**
+- 表头「操作」左边缘 X = 表体「详情」链接左边缘 X
+- ❌ 禁止操作列内容居中
+- ❌ 禁止只在 `.col-action` 上设 text-align（部分浏览器会被覆盖）
+
+### 6.3 操作列行为映射
+
+| 操作      | 触发     | 前置       | 二次确认        | 目标              | 返回行为                             |
+| --------- | -------- | ---------- | --------------- | ----------------- | ------------------------------------ |
+| 查看/管理 | 点链接   | —          | 否              | DetailPage        | 返回列表保持筛选+分页                |
+| 编辑      | 点按钮   | —          | 否              | FormPage / Drawer | 保存成功返回列表 + Toast「保存成功」 |
+| 删除      | 点按钮   | 资源已停止 | 是(三级 Dialog) | Dialog 确认       | 确认后刷新 + Toast「删除成功」       |
+| 更多      | Dropdown | —          | 按操作分级      | Dropdown 菜单     | 选择子操作                           |
+
+---
+
+## 8. 主区对齐规则(硬约束 — 最容易不稳定的点)
+
+opentrek 主区由 `OpPageContainer` 提供 — 外层 `py-5 pr-5`(无左 padding,sidebar 自带 20px 间隙) + 内嵌**无边框白底大 Card**(`bg-card rounded-2xl p-6`)承载 PageHeader / ActionToolbar / DataTable / Pagination。水平 padding 分层模型:
+
+- **OpPageContainer 外层**:`py-5 pr-5`(灰底主区 ↔ 白卡的间隙;左侧贴 sidebar 不留 padding)
+- **OpPageContainer 内白卡 padding = 24px**(`p-6`):提供白卡内缘 ↔ 非 Table 子组件的呼吸 — **由容器统一管,不要在 PageHeader / Toolbar 上再加 paddingX**
+- **Table 中间列 padding = 12px**(左右 12+12=24,列间 24px)
+- **Table 首列 padding-left = 20px**(额外缩进让 checkbox 与白卡内缘有呼吸)
+- **Table 末列 padding-right = 20px**
+
+| 组件                                                    | 水平 padding        | 起始 X              |
+| ------------------------------------------------------- | ------------------- | ------------------- |
+| OpPageContainer 外层                                    | `pr-5`(右 20,左 0)  | PageShell main 外缘 |
+| OpPageContainer 内白卡                                  | **24px**(`p-6`)     | 白卡内缘            |
+| PageHeader / ActionToolbar / BulkActionBar / Pagination | **0**               | 白卡内缘 + 24       |
+| Table 中间列 td                                         | 12px                | —                   |
+| Table 首列 td                                           | padding-left: 20px  | 白卡内缘 + 44       |
+| Table 末列 td                                           | padding-right: 20px | 白卡右内缘 - 44     |
+
+### 禁止项
+
+- ❌ 在 OpPageContainer 主区再叠一层 `<Card>` — 容器已经内置大白卡,嵌套违反白卡单例
+- ❌ 在 PageHeader / ActionToolbar / Pagination 上重复设 paddingX(会与 OpPageContainer 内白卡的 `p-6` 叠加为 48px)
+- ❌ Table 中间列 padding 不为 12px
+- ❌ Table 首/末列 padding 不为 20px
+- ❌ 用 `px-4` `px-6` 字面量直接套子组件 — 用 `px-3 first:pl-5 last:pr-5` 让 Table 自己分配
+- ❌ 在 OpPageContainer 内白卡与子组件间插入额外 paddingX 包裹层
+
+### 验证
+
+1. PageHeader / ActionToolbar / Pagination 起始 X = OpPageContainer 内白卡左内缘 + 24
+2. Table 首列(checkbox)内容 X = OpPageContainer 内白卡左内缘 + 44
+3. Table 相邻中间列内容间距 = 24
+
+---
+
+## 9. 状态-操作模式
+
+### 8.1 元规则
+
+- 每个状态必须定义操作可用性矩阵
+- 禁用样式统一 `opacity-45 pointer-events-none`
+- 混合状态时批量按钮禁用，hover 提示原因
+- 异步操作必须有 Toast + 列表刷新机制
+
+### 8.2 操作确认分级
+
+| 级别                 | 适用                 | 确认方式              |
+| -------------------- | -------------------- | --------------------- |
+| **一级**（可逆）     | 查看、编辑、远程连接 | 直接执行              |
+| **二级**（影响状态） | 启动、停止、重启     | Dialog 确认           |
+| **三级**（不可逆）   | 删除                 | Dialog + 输入确认文本 |
+
+### 8.3 异步反馈
+
+| 操作     | Toast 文案                | 列表         |
+| -------- | ------------------------- | ------------ |
+| 状态变更 | "操作已提交"              | 轮询状态     |
+| 删除     | "删除已提交"              | 移除行或刷新 |
+| 批量     | "批量操作已提交，共 N 条" | 轮询         |
+
+### 8.4 页面间导航交互
+
+- **操作列「查看/管理」** → DetailPage(页面跳转);面包屑返回,保持筛选+分页
+- **操作列「编辑」** → FormPage 或 Drawer(跳转/侧滑);保存/取消返回列表,保存附 Toast
+- **创建操作** → FormPage(页面跳转);创建成功/取消返回列表
+- **搜索执行** → 当前列表(数据刷新);重置到第 1 页
+- **筛选条件变更** → 当前列表(数据刷新);重置到第 1 页,保持筛选条件
+
+---
+
+## 10. 嵌套约束
+
+| 父子关系                                                                                                                       | 状态                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| PageShell(background="muted", sidebar=OpSidebar) → OpPageContainer(header=PageHeader) → ActionToolbar / DataTable / Pagination | ALLOW                                                                   |
+| OpPageContainer 内大白卡 → 再嵌一层 `<Card>` 包业务组件                                                                        | **FORBID**(OpPageContainer 已内置大白卡,嵌套违反白卡单例)               |
+| ActionToolbar → SearchCombo                                                                                                    | ALLOW                                                                   |
+| CardGrid → ItemCard → CardActionBar                                                                                            | ALLOW(卡片网格内每个 ItemCard 是局部小卡 — 业务子区域级,非主区白卡嵌套) |
+| DataTable → Pagination                                                                                                         | ALLOW                                                                   |
+| DataTable → Form                                                                                                               | **FORBID**(用 Drawer 触发)                                              |
+
+---
+
+## 11. 禁止项
+
+| 禁项                   | 原因                                |
+| ---------------------- | ----------------------------------- |
+| Form 直接出现在内容区  | 应通过 Dialog/Drawer/FormPage 触发  |
+| Chart 出现在标准列表   | 图表归属 Dashboard                  |
+| 内联编辑               | 编辑必须通过 Drawer/Dialog/FormPage |
+| 拖拽排序               | 表格数据为服务端排序                |
+| 无限滚动               | B2B 管理场景需精确分页              |
+| 悬浮操作栏             | 遮挡数据，可发现性差                |
+| 右键菜单               | 移动端不兼容                        |
+| `hr` / section-divider | 间距通过 padding/margin 控制        |
+
+---
+
+## 12. 列表页特有自检
+
+- [ ] PageHeader / ActionToolbar / DataTable / Pagination 嵌套结构正确
+- [ ] Card 内统一左右 padding 24px（除 Table 列）
+- [ ] 子类型组件正确（standard 用 DataTable，pure-card 用 CardGrid）
+- [ ] SearchCombo 位置正确（间距 20px）
+- [ ] 操作列水平对齐左对齐
+- [ ] 状态-操作矩阵在所有状态下正确
+- [ ] 二次确认按级别正确（启动/停止 = Dialog；删除 = 输入确认）
+- [ ] 批量操作按钮：选中 ≥1 行显示，混合状态禁用
+- [ ] 搜索：回车执行、维度切换清空、FilterTag 展示
+- [ ] 分页：保持筛选 + "共 N 条"
+- [ ] 边界：空数据 Empty + 加载 Loading + 错误 ErrorState

package/src/teamix-evo-design-opentrek/patterns/page-types.md

@@ -0,0 +1,159 @@
+# Page Types — 5 种标准页面类型
+
+> ⚠️ **Prerequisites**: 你必须由 [generation-flow.md](../generation-flow.md) Step 2 引导到这里。若未完成 Step 1（需求确认），请先返回。
+
+> AI 生成页面前**必须先识别页面类型**，再选择对应模式。本文档是 generation-flow.md Step 2 的核心输入。
+
+---
+
+## 1. 类型概览
+
+| 类型             | 用途                           | 核心组件                                        | 子文件                    |
+| ---------------- | ------------------------------ | ----------------------------------------------- | ------------------------- |
+| **ListPage**     | 资源集合的查询、筛选、批量操作 | DataTable / CardGrid + SearchCombo + Pagination | `list-page.md`            |
+| **DetailPage**   | 单个资源的完整信息展示         | Tabs + DescriptionList + ActionToolbar          | `detail-page.md`          |
+| **FormPage**     | 资源的创建 / 编辑              | Form(FieldGroup + Field) + SubmitBar            | `form-page.md`            |
+| **Dashboard**    | 数据概览与监控                 | StatCard + Chart + Timeline                     | `dashboard.md`            |
+| **Dialog/Sheet** | 二次确认、快速操作             | AlertDialog / Dialog / Sheet                    | （见 components.md §3.1） |
+
+---
+
+## 2. 识别决策树
+
+```text
+用户描述包含什么？
+├─ "列表"/"表格"/"查询"/"检索"/"卡片管理" → ListPage
+├─ "详情"/"查看"/"信息"/"概览" → DetailPage
+├─ "新建"/"创建"/"编辑"/"修改"/"复制" → FormPage
+├─ "仪表盘"/"概览大屏"/"监控"/"统计" → Dashboard
+├─ "确认"/"删除二次确认"/"快速重命名" → Dialog
+└─ 不确定 → 优先 ListPage（最通用入口）
+```
+
+**优先级裁决**：
+
+- 出现"批量操作" → ListPage（即使页面看起来像 Dashboard）
+- 出现"步骤"/"分步" → FormPage（Wizard 变体）
+- 出现"对比" → DetailPage（对比型）
+
+---
+
+## 3. 页面级别 (L1 / L2 / L0)
+
+| 级别   | 适用类型             | PageHeader 模式           | Sidebar  |
+| ------ | -------------------- | ------------------------- | -------- |
+| **L0** | Dialog / Sheet 内部  | 无 PageHeader             | 无       |
+| **L1** | ListPage、Dashboard  | title 模式（仅标题）      | 自动继承 |
+| **L2** | DetailPage、FormPage | breadcrumb 模式（含路径） | 自动继承 |
+
+**框架自动继承**：L1 / L2 页面**不需要在 skill 中显式声明** Sidebar 与 PageHeader — 由 page-frame 统一管理。
+
+---
+
+## 4. Zone Map（区域命名约定）
+
+| Zone            | 位置          | 用途                                             |
+| --------------- | ------------- | ------------------------------------------------ |
+| **header**      | 顶部          | PageHeader（标题或面包屑 + 主操作）              |
+| **toolbar**     | header 下     | ActionToolbar（搜索 + 筛选 + 视图切换）          |
+| **main**        | 中部主体      | 主要内容区（DataTable / Form / DescriptionList） |
+| **bulk-action** | main 浮于底部 | BulkActionBar（仅 ListPage 选中行时）            |
+| **footer**      | 底部固定      | Pagination 或 SubmitBar                          |
+| **sidebar**     | 左侧          | 全局导航（框架级，自动继承）                     |
+| **aside**       | 右侧          | 侧边详情 / AI 面板（按 variant 启用）            |
+
+**默认壳层结构**：`Sidebar(左) + Header(顶) + Main(中)` — 三栏布局是基线。
+
+---
+
+## 5. Dashboard
+
+> **完整规范见 [`dashboard.md`](./dashboard.md)** — 标准结构 + 设计要点(关键指标字号、StatCard 数量、chart-\* 色彩消费顺序)。
+
+---
+
+## 6. 页间流转
+
+> 单页内部规则在 §1-§5,本节是**跨页流转**视角。完整的"四条核心用户旅程"(A 资源查找 / B 创建 / C 异常 / D 批量)见 [`flows.md`](../flows.md)。
+
+### 6.1 后台主流转图
+
+```text
+              ┌─────────────────┐
+              │  全局导航 / 首页 │
+              └────────┬────────┘
+                       │ 选择模块
+                       ▼
+┌──────────┐ 创建 ┌──────────┐ 查看  ┌────────────┐
+│ FormPage │◄────│ ListPage │──────►│ DetailPage │
+└────┬─────┘     └─────┬────┘       └─────┬──────┘
+     │ 成功            │                   │
+     └────────────────►│◄──────────────────┘
+                       │ 编辑                返回
+                       ▼
+              ┌──────────────┐
+              │   FormPage   │
+              └──────────────┘
+
+   Dashboard ──下钻──► ListPage(预筛选)
+```
+
+> AI 副驾驶(命令面板 / 对话主面板 / 告警诊断 / 操作编排 / 知识问答 / 拓扑感知)属于**变体专属**流转,不在中性基线内。
+
+### 6.2 流转设计规则
+
+1. **导航深度 ≤ 4 层** — 超过即是信息架构问题
+2. **每层都有返回路径** — 面包屑 / 返回按钮 / Esc 快捷键
+3. **主导航始终可见** — 仅"全屏编辑 / 大屏展示"模式可隐藏
+4. **状态保持** — 列表筛选条件、表单未提交内容必须保留
+5. **快捷路径** — 高频操作建议提供 `Cmd+K` 入口
+6. **不创建死胡同** — 任何成功 / 失败页面都必须有"下一步"按钮
+
+### 6.3 资源生命周期
+
+| 阶段 | 发现     | 创建     | 配置       | 监控      | 变更     | 删除     |
+| ---- | -------- | -------- | ---------- | --------- | -------- | -------- |
+| 页面 | ListPage | FormPage | DetailPage | Dashboard | FormPage | Dialog   |
+| 动作 | 搜索定位 | 填写表单 | 查看明细   | 处置异常  | 编辑提交 | 二次确认 |
+
+> "资源" 泛指业务对象(订单 / 用户 / 商品 / 任务 / 工单 / 文档…)。
+
+### 6.4 CRUD 流转速查
+
+| 意图     | 关键词         | 目标页                  | 完成后         |
+| -------- | -------------- | ----------------------- | -------------- |
+| 查看列表 | 列表/查询/检索 | ListPage                | —              |
+| 查看详情 | 详情/查看/信息 | DetailPage              | 可返回列表     |
+| 新建     | 新建/创建/新增 | FormPage(新建)          | 保存后返回列表 |
+| 编辑     | 编辑/修改      | FormPage(编辑)或 Drawer | 保存后返回原页 |
+| 删除     | 删除/移除      | Dialog(输入确认)        | 确认后刷新列表 |
+| 复制     | 复制/克隆      | FormPage(复制新建)      | 保存后返回列表 |
+
+---
+
+## 7. 通用结构铁律（所有页面类型共享）
+
+1. **`<PageShell background="muted" sidebar={<OpSidebar/>}> → <OpPageContainer header={<PageHeader/>}> → 业务组件`**
+   - PageShell 来自 `@/components/ui/page-shell`(三明治壳;opentrek 主区背景用 `muted` 灰底,无 header slot)
+   - OpPageContainer 来自 `@/components/business/op-page-container`(padding `py-5 pr-5`,**内置无边框大白卡** `bg-card rounded-2xl`)
+   - PageHeader 来自 `@/components/ui/page-header`(本身无 padding,由 OpPageContainer 内白卡统一管)
+   - 业务组件(ListCard 网格 / DataTable / Form 等)直接作为 OpPageContainer children,**不要再手动包 `<Card>`** — 容器已经是白卡
+2. **主区白卡单例** — OpPageContainer 已内置 `bg-card rounded-2xl` 大白卡,主区内**不要再手写 `<Card>`** 包整个 PageHeader / DataTable / Form / FieldGroup(嵌套违反白卡单例)。卡片网格内的 ItemCard / 表单分区的子 Card 是局部容器,不算"嵌套主区白卡"
+3. **页头不可重复** — 子页面禁止自建 header，PageHeader 由框架管控
+4. **不在内容区直接放 Form 整体** — 必须用 FieldGroup + Field（详见 boundaries.md C7）
+5. **不在 ListPage / DetailPage 内嵌 Chart 整体** — 图表归属 Dashboard
+6. **不在 FormPage / DetailPage 内嵌 DataTable 整体** — 关联数据通过 Tabs / Drawer 组织
+
+---
+
+## 8. 类型选择自检
+
+完成识别后必须能回答：
+
+- [ ] 这是 L0 / L1 / L2 哪一级？
+- [ ] PageHeader 用 title 还是 breadcrumb 模式？
+- [ ] Main 区核心组件是什么？（DataTable / DescriptionList / FieldGroup）
+- [ ] 是否需要 toolbar / bulk-action / footer Zone？
+- [ ] 错位风险：是否在不该出现的页面类型里出现了 Form / DataTable / Chart？
+
+类型识别错误 = 后续所有约束都错位。**错则回到 Step 1 重判。**

package/src/teamix-evo-design-opentrek/patterns/sidebar.md

@@ -0,0 +1,122 @@
+# Sidebar Pattern — OpenTrek 侧边栏统一规范
+
+> ⚠️ **Prerequisites**: 你必须已在 [generation-flow.md](../generation-flow.md) Step 3 确认布局包含侧边栏，或由翻新/验证路径引导到这里。
+
+> AI 生成或翻新页面时必须引用本规则。所有色值与尺寸通过 token 引用，禁止硬编码。Token 真值见 `tokens/tokens.theme.css`。
+
+---
+
+## 1. 宽度与定位
+
+| 状态   | Token                       | 业务含义                        |
+| ------ | --------------------------- | ------------------------------- |
+| 展开态 | `--layout-sidebar-width`    | 侧边栏展开宽度                  |
+| 收起态 | `--sidebar-collapsed-width` | 仅图标，居中对齐于中轴线        |
+| 顶部条 | `--topbar-height`           | 与 Sidebar 顶部对齐，区分品牌区 |
+
+**布局规则**：
+
+- Sidebar 走 `position: fixed; top: 0; left: 0; bottom: 0; z-index: 100`
+- 主内容区通过 `margin-left: var(--layout-sidebar-width)` 补偿
+- **禁止**：把 Sidebar + 主内容区放进一个 flex 容器（不可预期的滚动行为）
+
+---
+
+## 2. 结构变体（2 选 1，按信息架构层级）
+
+### 2.1 三级结构（默认）
+
+适用：信息架构需要 3 层归类（顶层业务域 / 中层主导航 / 底层细分）。
+
+```
+aside.sidebar
+├─ div.sidebar-header        ← 品牌区
+├─ div.sidebar-content       ← 滚动容器
+│  ├─ div.sidebar-group-label  ← 分组标题（可重复）
+│  ├─ ul.sidebar-menu
+│  │  └─ li > a.sidebar-menu-item
+│  └─ ul.sidebar-sub-menu      ← 主菜单展开后显示
+│     └─ li > a.sidebar-menu-item
+├─ div.sidebar-divider
+└─ div.sidebar-footer
+```
+
+### 2.2 二级结构（v4.1 新增）
+
+适用：主菜单项语义对等，无需分组标题归类。
+
+- **禁止** `div.sidebar-group-label`
+- 所有主菜单项放进同一个 `ul.sidebar-menu`
+- 子菜单项与主菜单项**文字 x 坐标对齐**（同列），层级关系由展开箭头 + 字号 + 背景色表现，**不**通过左缩进
+- 子菜单项不带 `.item-icon`，只有文字
+
+### 2.3 选型决策
+
+| 信息架构层级深度 | 选用       |
+| ---------------- | ---------- |
+| 3 层归类         | threeLevel |
+| 2 层归类         | twoLevel   |
+
+> 与菜单项**个数无关**，只看信息架构。
+
+---
+
+## 3. 颜色映射（v4.1 品牌化）
+
+| 槽位                                | 用途                                        |
+| ----------------------------------- | ------------------------------------------- |
+| `--color-sidebar`                   | 侧边栏背景                                  |
+| `--color-sidebar-foreground`        | 默认文字                                    |
+| `--color-sidebar-active`            | 选中项背景（v4.1 走灰色，区别 hover）       |
+| `--color-sidebar-active-foreground` | 选中项文字（OpenTrek 蓝）                   |
+| `--color-sidebar-hover`             | hover 态背景                                |
+| `--color-sidebar-title`             | sidebar-group-label 文字                    |
+| `--color-sidebar-item-muted`        | 二级文字 / 次要项                           |
+| `--color-sidebar-primary`           | 品牌强调（`#0055EE`）— 高亮 logo / 选中态等 |
+| `--color-sidebar-border`            | 分隔线                                      |
+| `--color-sidebar-ring`              | 焦点圈                                      |
+
+**禁止**：
+
+- 直接用 `bg-blue-600` / `text-gray-500` 这类原始 Tailwind 色
+- 在 sidebar 内消费 `--color-primary` / `--color-foreground`（应走 sidebar 命名空间）
+
+---
+
+## 4. 收起态行为
+
+- 宽度 `--sidebar-collapsed-width`，`overflow: visible`（支持 flyout 浮层溢出）
+- 滚动能力下移到 `.sidebar-content`（`overflow-y: auto; overflow-x: hidden`）
+- 仅显示图标，隐藏所有文字（label / group title / count / expand-icon）
+- 选中态用 `--color-sidebar-active` 灰色背景，**不**显示左侧高亮条
+- 过渡走 `width var(--duration-normal) var(--easing-ease)`
+- 菜单项 40×40px，`border-radius: var(--radius-md)`，`li { display: flex; justify-content: center }` 保证居中于中轴线
+
+---
+
+## 5. Footer / Header 槽位
+
+| 槽位             | 内容                                                  |
+| ---------------- | ----------------------------------------------------- |
+| sidebar-header   | 展开态：品牌 logo；收起态：方形 logo +hover 展开 icon |
+| sidebar-avatar   | 用户头像                                              |
+| sidebar-username | 用户名（收起态隐藏）                                  |
+| sidebar-more     | 更多操作触发器                                        |
+
+---
+
+## 6. 禁止清单（硬约束）
+
+- [ERROR] 扁平化结构（直接 `<a>` 挂在 `nav`/`div` 下，无 `ul > li` 包裹）
+- [ERROR] Sidebar 整体使用 flex 布局（必须 `fixed` 定位）
+- [ERROR] 省略 `sidebar-content` 滚动容器
+- [ERROR] twoLevel 变体出现 `sidebar-group-label`
+- [ERROR] 无子菜单的菜单项出现 expand-icon 或 `data-toggle`（expand-icon 仅出现在有 `sidebar-sub-menu` 的主菜单项）
+- [WARN] 在 sidebar 里直接消费 `--color-primary`（应走 `--color-sidebar-primary`）
+- [WARN] 二级结构子菜单文字起点低于主菜单文字 x（隐藏层级关系）
+
+---
+
+## 7. 引用关系
+
+本规则是 OpenTrek sidebar 的 **single source of truth**。其他 skill 文件（page-frame / common-components / 子技能）须 `$ref` 本文件，禁止重复定义或冲突覆写。