@teamix-evo/skills 0.3.0 → 0.4.0

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

@@ -0,0 +1,289 @@
+# Form Page — 表单页模式
+
+> **触发**：用户描述含"新建/创建/编辑/修改/复制/填写"。
+> **核心特征**：用户输入数据 + 字段校验 + 提交。
+> **页面级别**：L2（面包屑模式 PageHeader，自动继承 Sidebar）。弹窗表单 = L0。
+
+---
+
+## 1. 子类型识别
+
+| 子类型       | 关键词               | 差异特征                                                   |
+| ------------ | -------------------- | ---------------------------------------------------------- |
+| **新建表单** | "新建"/"创建"/"新增" | 字段为空，标题"新建 XX"，保存返回列表                      |
+| **编辑表单** | "编辑"/"修改"        | 字段填充数据，标题"编辑 XX"，保存返回原页                  |
+| **复制新建** | "复制"/"克隆"        | 字段预填源数据（ID 除外），标题"复制新建 XX"，保存返回列表 |
+
+### FormPage vs Wizard 区分
+
+| 场景                       | 类型       | 判断依据                 |
+| -------------------------- | ---------- | ------------------------ |
+| 字段无顺序依赖，一次填写   | FormPage   | 单页表单                 |
+| 步骤间有顺序依赖，逐步完成 | WizardPage | 多步流程,Steps           |
+
+> Wizard 是独立页面类型，不是 FormPage 子类型。
+
+---
+
+## 2. 布局模式（三选一）
+
+### 2.1 SINGLE_COL（默认）
+
+```text
+┌────────────────────────────────────────┐
+│ PageHeader: 新建实例                   │
+│                                        │
+│ FieldGroup                             │
+│   Field [实例名称 *]                   │
+│   Field [地域            ▼]            │
+│   Field [可用区          ▼]            │
+│   Field [实例规格 *      ▼]            │
+│                                        │
+│ ─────────────────────────              │
+│ SubmitBar         [取消] [确定]         │  ← justify-end
+└────────────────────────────────────────┘
+```
+
+### 2.2 TWO_COL（多字段并排）
+
+```text
+FieldGroup
+  ┌─ 列 1 ──────┐ ┌─ 列 2 ──────┐
+  │ 用户名 *    │ │ 邮箱 *      │
+  │ 角色 *      │ │ 状态        │
+  │ 部门        │ │ 手机号      │
+  └─────────────┘ └─────────────┘
+SubmitBar  [取消] [保存]
+```
+
+### 2.3 SECTION（分区表单）
+
+```text
+Card[FieldGroup ─ 基本信息]
+  实例名称 *
+  类型 * [自研 ○ MySQL ○ PostgreSQL]
+
+Card[FieldGroup ─ 网络配置]
+  地域 *  /  VPC *  /  交换机 *
+
+Card[FieldGroup ─ 存储配置]
+  存储空间 *  /  备份策略
+
+SubmitBar  [取消] [创建]
+```
+
+**何时分区**：字段 > 10 / 业务概念分组明显 / 含可选高级配置。
+
+---
+
+## 3. 必需组件
+
+| 组件                  | 位置   | 说明                                  |
+| --------------------- | ------ | ------------------------------------- |
+| **PageHeader**        | top    | 面包屑模式(L2 页面)                   |
+| **Form / FieldGroup** | center | 表单容器,**禁止**用 div + space-y-\*  |
+| **SubmitBar**         | bottom | 提交操作栏,居右排列                   |
+
+**框架级**(自动继承):Sidebar、Breadcrumb。
+
+---
+
+## 4. SubmitBar / Footer 规则
+
+### 4.1 智能定位
+
+- Footer **从滚动区域移出**，作为 Card 的直接子元素
+- Card：`flex flex-col max-h-[calc(100vh-48px)]`
+- 内容区：`flex-1 overflow-y-auto min-h-0`
+- Footer：`flex-shrink-0 z-10 bg-card border-t`
+
+### 4.2 行为
+
+| 场景        | Card 高度                | Footer                   |
+| ----------- | ------------------------ | ------------------------ |
+| 内容 < 视口 | 自适应                   | 跟随内容自然展示         |
+| 内容 > 视口 | max-h:calc(100vh - 48px) | 固定底部，悬浮于表单上方 |
+
+### 4.3 按钮顺序（从左到右）
+
+- `[取消]` → `[上一步]`（Wizard 中）→ `[下一步 / 提交 / 保存]`
+- 主按钮始终在最右侧（Primary）
+- 容器 `justify-end`
+
+---
+
+## 5. 字段控件选型
+
+> **枚举数量阈值规则(≤7 RadioGroup / 8-30 Select / >30 Combobox)见 [components.md §3.5 输入控件](../components.md#35-输入控件--input-vs-select-vs-combobox)**。本节只列表单页专属补充字段。
+
+| 字段类型      | 组件                         | 说明                     |
+| ------------- | ---------------------------- | ------------------------ |
+| 布尔(设置)    | Switch                       | "启用 X" 类开关          |
+| 布尔(表单)    | Checkbox                     | 协议确认                 |
+| 单选(2~5 项)  | ToggleGroup                  | 类型选择(可视化优于下拉) |
+| 验证码        | InputOTP                     | 短信 / 邮箱 OTP          |
+| 范围数值      | Slider                       | 资源配比 / 阈值          |
+| 输入 + 按钮   | InputGroup                   | 复制、单位切换           |
+| 文件上传      | FileUpload                   | 单 / 多文件              |
+| 日期 / 时间   | DatePicker / DateRangePicker | —                        |
+
+---
+
+## 6. 字段校验规则
+
+### 6.1 触发时机
+
+| 场景       | 触发             |
+| ---------- | ---------------- |
+| 单字段格式 | blur（失焦）     |
+| 必填检查   | submit（提交时） |
+| 跨字段联动 | change（实时）   |
+| 后端校验   | submit 提交后    |
+
+### 6.2 视觉反馈
+
+- 错误：`data-invalid` 在 Field 上、`aria-invalid` 在控件上 → 红色边框 + FormMessage 错误描述
+- 必填：label 后置 `*` 红色标记
+- 字段说明优先 Tooltip（避免行内增加阅读负担）
+- 提交失败：聚焦第一个错误字段
+
+### 6.3 长表单分组
+
+- 单组字段 ≤ 6
+- > 10 字段必须分区或分步
+- 分区用 Card 内嵌 FieldGroup
+
+---
+
+## 7. 提交交互
+
+### 7.1 操作流
+
+| 操作             | 触发         | 前置         | 反馈                             |
+| ---------------- | ------------ | ------------ | -------------------------------- |
+| 保存             | 点[确定]     | 本地校验通过 | 校验 → 提交 → Toast「保存成功」  |
+| 保存失败         | 后端返回错误 | —            | 字段标红 + Toast 错误 + 留在表单 |
+| 取消（无未保存） | 点[取消]     | —            | 直接离开                         |
+| 取消（有未保存） | 点[取消]     | —            | Dialog 确认离开                  |
+| 返回（面包屑）   | 点击父级     | 有未保存内容 | Dialog 确认                      |
+
+### 7.2 异步提交
+
+| 类型         | UI                      | 反馈                                |
+| ------------ | ----------------------- | ----------------------------------- |
+| 同步（快速） | 按钮 disabled + Spinner | Toast 结果                          |
+| 异步（耗时） | 不阻塞                  | Toast「提交成功，后台处理中」+ 轮询 |
+
+### 7.3 操作确认分级
+
+| 级别             | 适用             |
+| ---------------- | ---------------- |
+| 一级（可逆）     | 保存（校验通过） |
+| 二级（有未保存） | 取消/离开        |
+
+---
+
+## 8. shadcn 表单组合契约
+
+> 表单**组合层面**的本地约定。视觉/全局规则参见 [boundaries.md FF1-FF4](../boundaries.md#ff1-ff4--表单专属硬约束)(色块、必填、Card 嵌套、错误文案) + [boundaries.md S2](../boundaries.md#error-s2--不用-space-x---space-y--改用-flex--gap-) (gap 替代 space-y) + [boundaries.md F8](../boundaries.md#error-f8--禁止在-dialogtitle-中加图标--scope-dialog) (DialogTitle 无图标) + [boundaries.md F9](../boundaries.md#error-f9--弹窗确定按钮禁止加-disabled-禁用态--scope-dialog) (提交按钮无 disabled)。
+
+- **FC1 表单布局**：`FieldGroup` + `Field`,**禁止** `<div>` + `space-y-*`(并见 S2)
+- **FC2 InputGroup 内子件**：`InputGroupInput` / `InputGroupTextarea`,不用原始 `Input`
+- **FC3 输入 + 按钮**：`InputGroup` + `InputGroupAddon`
+- **FC4 2~5 选项**：`ToggleGroup`,**禁止**循环 `Button` 手动 active
+- **FC5 相关选项组**：`FieldSet` + `FieldLegend`
+- **FC6 校验态**：`data-invalid` 在 `Field`、`aria-invalid` 在控件 (与 FF1 配合)
+- **反馈**：`import { toast } from "sonner"` (并见 [boundaries.md C9](../boundaries.md#warn-c9--toast-用-sonner))
+
+---
+
+## 9. 嵌套约束
+
+| 父子关系                                                                          | 状态                        |
+| --------------------------------------------------------------------------------- | --------------------------- |
+| PageContainer → ContentWrapper → Card(白卡) → PageHeader / FieldGroup / SubmitBar | ALLOW                       |
+| ContentWrapper → 业务组件（无 Card）                                              | **FORBID**                  |
+| Card → Card                                                                       | **FORBID**（白卡单例）      |
+| Card(白卡) → Card(分区)                                                           | ALLOW（分区表单内嵌）       |
+| Card(分区) → FieldGroup                                                           | ALLOW                       |
+| FieldGroup → Field                                                                | ALLOW                       |
+| Field → Input / Select / Switch / ToggleGroup / Textarea                          | ALLOW                       |
+| Field → InputGroup                                                                | ALLOW                       |
+| Card → Form                                                                       | **FORBID**（用 FieldGroup） |
+
+---
+
+## 10. 禁止项
+
+| 禁项                        | 原因                          |
+| --------------------------- | ----------------------------- |
+| DataTable 在主内容区        | 关联数据用 Dialog + DataTable |
+| Chart 在表单页              | 图表属 Dashboard              |
+| 内联 Input（不在 Field 内） | 必须 FieldGroup → Field 包装  |
+| 原始 div 表单布局           | 用 FieldGroup + Field         |
+| 单页字段 > 15 不分组        | 分区或拆 Wizard               |
+
+---
+
+## 11. 表单页特有自检
+
+- [ ] PageHeader 用面包屑模式（L2 页面）
+- [ ] 所有 Input 在 Field → FieldGroup 内(FC1)
+- [ ] data-invalid + aria-invalid 双重声明(FC6)
+- [ ] 控件按字段类型选型正确（2~5 选用 ToggleGroup，不循环 Button）
+- [ ] SubmitBar 居右 + 按钮顺序：取消 → 上一步 → 主操作
+- [ ] 长表单（> 10）分组或分区
+- [ ] 异步提交：按钮 loading + Spinner
+- [ ] 取消时未保存内容 Dialog 确认
+- [ ] 编辑模式加载用 Skeleton
+- [ ] Toast 用 sonner（C9），不用自定义全局通知
+
+---
+
+## 12. 《Teamix UI 表单设计规范》对齐 Checklist
+
+> 详细说明见 [`packages/ui/AGENTS.md` 第六节](../../../../ui/AGENTS.md#六表单族硬规则formfieldfilter-barlabelinput)。本节只列 AI 写表单时的 yes/no 自检项。
+
+### 12.1 间距(11 条硬规则,§3.1)
+
+- [ ] label → input 间距:垂直 4px / 水平 16px(由 `Field.orientation` 内置,**禁止**手写 `mt-*` / `gap-3` 覆盖)
+- [ ] error → input:**0px**(`FieldError` 内置 `-mt-1`,防止抖动)
+- [ ] description → input:4px(`FieldDescription` 默认)
+- [ ] 组内行距 20px / 组间距 32px / 详情页 12px(`FieldGroup` / `FieldSection` / `density="detail"`)
+- [ ] checkbox / radio / 文字链 横向:**16px**(`gap-4`,组件内置)
+- [ ] icon 与文字 横向:**4px**(label 内 `文字 ⓘ *`,Label 组件内置)
+
+### 12.2 必填与 a11y(§一 + §六)
+
+- [ ] `*` 后置:`<FormLabel required>` / `<FieldLabel required>`,**禁止**手写 `<span>* 邮箱</span>`
+- [ ] input 同步 `aria-required="true"`,纯视觉 `*` 不替代屏幕阅读
+- [ ] invalid 单一真值在 `<Field invalid>`,自动驱动 label 着色 + FieldError 可见 + 控件 ring,**不要**重复给控件传 `aria-invalid`
+
+### 12.3 输入域宽度(5 档,§七)
+
+- [ ] 用 `Field.inputWidth="xs|s|m|l|xl"`(104/216/328/440/552px),**禁止**手写 `w-[328px]` 或 `style={{ width: 328 }}`
+- [ ] 子控件用 `style={{ width: 'var(--field-input-width)' }}` 消费
+- [ ] horizontal 模式 label 自动 `max-width = ⅓ 输入域宽`,超长 truncate(`FieldLabel` 内置)
+
+### 12.4 响应式(5 档断点,§4.1-4.2)
+
+- [ ] 多栏筛选用 `FilterBarPanel responsiveColumns={{ base, xs, s, m, l, xl }}`,**禁止**手写媒体查询 / `lg:grid-cols-*`
+- [ ] 单栏表单 < 432 自动改上下:`<Field orientation={{ base: 'vertical', xs: 'horizontal' }}>`
+- [ ] 断点用 `useBreakpoint` + `pickByBreakpoint`(`@/hooks/use-breakpoint`),**禁止**手写 `useMediaQuery`
+
+### 12.5 按钮容器感知(§六)
+
+- [ ] 用 `FormActions container="page|page-stepper|modal|drawer"` 一次性配齐 position/align/alignWithInput
+- [ ] 决策口径:页面基础/分组 → `page` / 页面分步 → `page-stepper` / 弹窗 → `modal` / 抽屉 → `drawer`
+- [ ] **禁止**裸 `<div className="flex gap-2 justify-end">` 写底部按钮
+
+### 12.6 内容截断三件套(§八)
+
+- [ ] 横向宽度受限的字段值 / 长 label / 表格单元格用 `<Ellipsis>`,**禁止**手写 `truncate` + 独立 `<Tooltip>`
+- [ ] 多行截断走 `<Ellipsis lines={2}>`,**禁止**手写 `-webkit-line-clamp`
+
+### 12.7 RHF vs Server Actions 流派(§6.1)
+
+- [ ] 用 RHF + zod → 走 `Form / FormField / FormItem / FormLabel / FormMessage`(form 包,FormItem 内部就是 Field)
+- [ ] Server Actions / 原生 form / 简单状态 → 走 `Field / FieldGroup / FieldLabel / FieldError`(field 包)
+- [ ] **禁止**两套混用(Section / Actions 是 re-export 别名,选哪边都行,**不要交叉**)

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

@@ -0,0 +1,334 @@
+# List Page — 列表页模式
+
+> **触发**：用户描述含"列表/表格/查询/检索/卡片管理"。
+> **核心特征**：多条结构化数据 + 搜索/筛选 + 分页。
+> **页面级别**：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. 标准结构
+
+```
+┌────────────────────────────────────────────┐
+│ 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
+└────────────────────────────────────────────┘
+```
+
+---
+
+## 3. 必需组件
+
+| 组件                          | 位置    | 说明                                                        |
+| ----------------------------- | ------- | ----------------------------------------------------------- |
+| **PageHeader**                | top     | 标题模式(L1 页面);右侧主操作(如「新建」)                    |
+| **ActionToolbar**             | toolbar | 单行 flex(nowrap);左 actions + 中 SearchCombo + 右 tools    |
+| **DataTable** 或 **CardGrid** | main    | 二选一,按子类型                                             |
+| **Pagination**                | footer  | 默认 10 条/页(标准列表) / 12 条/页(卡片)                    |
+
+**框架级**(自动继承,不在 skill 内声明):Sidebar。
+
+---
+
+## 4. 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" }
+]
+```
+
+---
+
+## 5. 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`,不自动换行                        |
+
+---
+
+## 6. 操作列规范（硬约束）
+
+### 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 菜单     | 选择子操作                           |
+
+---
+
+## 7. Card 内对齐规则（硬约束 — 最容易不稳定的点）
+
+水平 padding 分层模型：
+
+- **Card.paddingX = 24px**：提供 Card 外缘 ↔ 非 Table 子组件的呼吸
+- **Table 中间列 padding = 12px**（左右 12+12=24，列间 24px）
+- **Table 首列 padding-left = 20px**（额外缩进）
+- **Table 末列 padding-right = 20px**
+
+| 组件                                                    | 水平 padding        | 起始 X         |
+| ------------------------------------------------------- | ------------------- | -------------- |
+| Card 白卡容器                                           | **24px**            | Card 外缘      |
+| PageHeader / ActionToolbar / BulkActionBar / Pagination | **0**               | Card 外缘 + 24 |
+| Table 中间列 td                                         | 12px                | —              |
+| Table 首列 td                                           | padding-left: 20px  | Card 外缘 + 44 |
+| Table 末列 td                                           | padding-right: 20px | Card 右缘 - 44 |
+
+### 禁止项
+
+- ❌ 在 PageHeader / ActionToolbar / Pagination 上重复设 paddingX（会与 Card.paddingX 叠加为 48px）
+- ❌ Table 中间列 padding 不为 12px
+- ❌ Table 首/末列 padding 不为 20px
+- ❌ 用 `px-4` `px-6` 字面量 — 用 `px-3 first:pl-5 last:pr-5`
+- ❌ 在 Card 与子组件间插入额外 paddingX 包裹层
+
+### 验证
+
+1. PageHeader / ActionToolbar / Pagination 起始 X = Card 左缘 + 24
+2. Table 首列 (checkbox) 内容 X = Card 左缘 + 44
+3. Table 相邻中间列内容间距 = 24
+
+---
+
+## 8. 状态-操作模式
+
+### 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 页,保持筛选条件
+
+---
+
+## 9. 嵌套约束
+
+| 父子关系                                                                                        | 状态                         |
+| ----------------------------------------------------------------------------------------------- | ---------------------------- |
+| PageContainer → ContentWrapper → Card(白卡容器) → PageHeader/ActionToolbar/DataTable/Pagination | ALLOW                        |
+| ContentWrapper → 业务组件（无 Card 包裹）                                                       | **FORBID**                   |
+| Card → Card                                                                                     | **FORBID**（白卡单例）       |
+| ActionToolbar → SearchCombo                                                                     | ALLOW                        |
+| CardGrid → ItemCard → CardActionBar                                                             | ALLOW                        |
+| DataTable → Pagination                                                                          | ALLOW                        |
+| DataTable → Form                                                                                | **FORBID**（用 Drawer 触发） |
+
+---
+
+## 10. 禁止项
+
+| 禁项                   | 原因                                |
+| ---------------------- | ----------------------------------- |
+| Form 直接出现在内容区  | 应通过 Dialog/Drawer/FormPage 触发  |
+| Chart 出现在标准列表   | 图表归属 Dashboard                  |
+| 内联编辑               | 编辑必须通过 Drawer/Dialog/FormPage |
+| 拖拽排序               | 表格数据为服务端排序                |
+| 无限滚动               | B2B 管理场景需精确分页              |
+| 悬浮操作栏             | 遮挡数据，可发现性差                |
+| 右键菜单               | 移动端不兼容                        |
+| `hr` / section-divider | 间距通过 padding/margin 控制        |
+
+---
+
+## 11. 列表页特有自检
+
+- [ ] PageHeader / ActionToolbar / DataTable / Pagination 嵌套结构正确
+- [ ] Card 内统一左右 padding 24px（除 Table 列）
+- [ ] 子类型组件正确（standard 用 DataTable，pure-card 用 CardGrid）
+- [ ] SearchCombo 位置正确（间距 20px）
+- [ ] 操作列水平对齐左对齐
+- [ ] 状态-操作矩阵在所有状态下正确
+- [ ] 二次确认按级别正确（启动/停止 = Dialog；删除 = 输入确认）
+- [ ] 批量操作按钮：选中 ≥1 行显示，混合状态禁用
+- [ ] 搜索：回车执行、维度切换清空、FilterTag 展示
+- [ ] 分页：保持筛选 + "共 N 条"
+- [ ] 边界：空数据 Empty + 加载 Loading + 错误 ErrorState