@teamix-evo/skills 0.5.0 → 0.6.0

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

@@ -0,0 +1,362 @@
+---
+name: page-rule-form
+parent: page-rule-system
+description: >
+  表单页(PageType: FormPage)模版规则。包含表单页类型定义、子类型识别、属性模型、
+  标准布局骨架、组件推荐规则及约束、页面交互补充。基于 @teamix-evo/ui 表单规范构建。
+  触发：需要表单页规则、匹配表单页模板、生成表单页。
+  Version: 7.0
+---
+
+# 表单页技能
+
+## 1. 页面类型定义
+
+**页面类型**: FormPage
+**核心特征**: 用户输入数据 + 字段校验 + 提交
+**识别条件**: 页面包含输入控件（Input/Select/Switch等）+ 校验规则 + 提交/取消按钮
+
+## 2. 页面子类型识别规则
+
+| 子类型 | 识别关键词 | 差异特征 |
+|--------|-----------|----------|
+| 新建表单 | "新建"/"创建"/"新增" | 所有字段为空，标题"新建 XX"，保存成功返回列表 |
+| 编辑表单 | "编辑"/"修改" | 所有字段填充数据，标题"编辑 XX"，保存后返回原页面 |
+| 复制新建 | "复制"/"克隆" | 字段预填源数据（ID除外），标题"复制新建 XX"，保存后返回列表 |
+
+### FormPage vs WizardPage 区分
+
+| 场景 | 页面类型 | 核心组件 | 判断依据 |
+|------|---------|---------|---------|
+| 单页表单（所有字段同时可见） | FormPage | Form, FieldGroup, SubmitBar | 字段无顺序依赖，一次性填写提交 |
+| 分步流程（多个有序步骤） | WizardPage | Steps (C27), StepForm, NavigationBar | 步骤间有顺序依赖，需逐步完成 |
+
+> **注意**：WizardPage 是独立的页面类型，不是 FormPage 的子类型。如需设计分步表单，请参考：
+> - 页面类型定义：`rules/page-types.json` → WizardPage
+> - 组件规范：`rules/component-specs.json` → C27-Steps
+> - 示例实现：`page-rule-examples/wizard-form-page.html`
+
+## 3. 页面属性模型
+
+| 属性 | 值 | 说明 |
+|------|-----|------|
+| layout.type | SINGLE_COL / GRID | 简单表单 SINGLE_COL，多列表单 GRID |
+| layout.frame | L2 | 表单页为 L2 级页面，自动继承 Sidebar（含Logo+产品名），PageHeader 使用面包屑基础组件模式 |
+| responsive | Desktop: 单列/多列, Tablet: 单列, Mobile: 不推荐 |
+| form.layout | SINGLE_COL(默认), TWO_COL(多字段), SECTION(分区) |
+| submit.position | bottom | flex 布局，所有行动点居右排列（justify-content: flex-end），按钮从左到右顺序：取消 → 上一步（如有）→ 下一步/提交 |
+
+> **框架组件自动继承**：Sidebar、Breadcrumb 由 `rules/page-frame.json` 统一管理，L2 级页面自动包含。弹窗表单（Dialog/FormPage）为 L0 级，无框架组件。
+
+## 4. 标准布局骨架
+
+### 模式：单列表单（SINGLE_COL）
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  ┌─ Card(白卡容器) ──────────────────────────────────┐  │
+│  │  PageHeader (面包屑模式)
+│  │   新建实例                                │  │
+│  │  Form (SINGLE_COL)                                   │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  │ 实例名称 *                                  │   │  │
+│  │  │ ┌───────────────────────────────────────┐   │   │  │
+│  │  │ │ 请输入实例名称                         │   │   │  │
+│  │  │ └───────────────────────────────────────┘   │   │  │
+│  │  └─────────────────────────────────────────────┘   │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  │ 地域                                        │   │  │
+│  │  │ ┌───────────────────────────────────────┐   │   │  │
+│  │  │ │ 华东 1(杭州)                     ▼   │   │   │  │
+│  │  │ └───────────────────────────────────────┘   │   │  │
+│  │  └─────────────────────────────────────────────┘   │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  │ 可用区                                      │   │  │
+│  │  │ ┌───────────────────────────────────────┐   │   │  │
+│  │  │ │ 杭州 可用区 G                    ▼   │   │   │  │
+│  │  │ └───────────────────────────────────────┘   │   │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  实例规格 *                                      │   │  │
+│  │  ┌─────────────────────────────────────────┐    │   │  │
+│  │  │ ecs.c6.large                        ▼  │    │   │  │
+│  │  └─────────────────────────────────────────┘    │   │  │
+│  │  └─────────────────────────────────────────────┘   │  │
+│  │  ┌─────────────────────────────────────────────┐   │  │
+│  │  监控 *                                          │   │  │
+│  │  ┌─────────────────────────────────────────┐    │   │  │
+│  │  │ ○ 开通                                    │    │   │  │
+│  │  └─────────────────────────────────────────┘    │   │  │
+│  │  └─────────────────────────────────────────────┘   │  │
+│  │  ─────────────────────────                           │  │
+│  │  SubmitBar (底部操作栏, 居右)                           │  │
+│  │                            [取消] [确定]              │  │
+│  └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 模式：两列表单（TWO_COL）
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  ┌─ Card(白卡容器) ──────────────────────────────────┐  │
+│  │  PageHeader (面包屑模式)
+│  │   编辑用户                                │  │
+│  │  Form (TWO_COL)                                     │  │
+│  │  ┌────── 列 1 ──────┐ ┌────── 列 2 ──────┐         │  │
+│  │  │ 用户名 *          │ │ 邮箱 *            │         │  │
+│  │  │ [_______________]│ │ [_______________] │         │  │
+│  │  │ 角色 *           │ │ 状态              │         │  │
+│  │  │ [选择 ▼]         │ │ [● 启用 ○ 禁用]   │         │  │
+│  │  │ 部门             │ │ 手机号码          │         │  │
+│  │  │ [选择 ▼]         │ │ [_______________] │         │  │
+│  │  └──────────────────┘ └──────────────────┘         │  │
+│  │  ─────────────────────────                           │  │
+│  │  SubmitBar (居右)                                      │  │
+│  │                            [取消] [保存]             │  │
+│  └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 模式：分区表单（SECTION）
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  ┌─ Card(白卡容器) ──────────────────────────────────┐  │
+│  │  PageHeader (面包屑模式)
+│  │   创建数据库                              │  │
+│  │  Form (SECTION)                                     │  │
+│  │  ┌─── 基本信息 ───────────────────────────────┐    │  │
+│  │  │ 实例名称 *                                 │    │  │
+│  │  │ ┌──────────────────────────────────────┐  │    │  │
+│  │  │ │ 请输入实例名称                       │  │    │  │
+│  │  │ └──────────────────────────────────────┘  │    │  │
+│  │  │ 类型 *                                    │    │  │
+│  │  │ [自研 ○ MySQL ○ PostgreSQL ○ Redis]       │    │  │
+│  │  └───────────────────────────────────────────┘    │  │
+│  │  ┌─── 网络配置 ───────────────────────────────┐    │  │
+│  │  │ 地域 *                                     │    │  │
+│  │  │ [选择 ▼]                                   │    │  │
+│  │  │ VPC *                                      │    │  │
+│  │  │ [选择 ▼]                                   │    │  │
+│  │  │ 交换机 *                                   │    │  │
+│  │  │ [选择 ▼]                                   │    │  │
+│  │  └───────────────────────────────────────────┘    │  │
+│  │  ┌─── 存储配置 ───────────────────────────────┐    │  │
+│  │  │ 存储空间 *                                 │    │  │
+│  │  │ [ 100 ] GB                                 │    │  │
+│  │  │ 备份策略                                   │    │  │
+│  │  │ [● 自动 ○ 手动]                            │    │  │
+│  │  └───────────────────────────────────────────┘    │  │
+│  │  ─────────────────────────                          │  │
+│  │  SubmitBar (居右)                                     │  │
+│  │                            [取消] [创建]            │  │
+│  └───────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+### SubmitBar / Footer 定位规则
+
+表单页（FormPage）的 SubmitBar 采用 **智能定位** 策略：
+
+**布局结构**：
+- Footer（SubmitBar）从滚动区域（card-scrollable）中 **移出**，作为 Card 的 **直接子元素**
+- Card 使用 `display: flex; flex-direction: column`
+- card-scrollable 使用 `flex: 1 1 auto; overflow-y: auto; min-height: 0`
+- Footer 使用 `flex-shrink: 0` 固定高度
+
+**行为定义**：
+| 场景 | Card 高度 | Footer 位置 | 内容区 |
+|------|----------|------------|--------|
+| 浏览器高度 ≥ 内容总高度 | 内容自适应（不拉伸） | 跟随表单内容自然展示 | 无滚动 |
+| 浏览器高度 < 内容总高度 | `max-height: calc(100vh - 2 × page-container-padding)` | 固定在 Card 底部，悬浮于表单上方 | 内容区滚动 |
+
+**CSS 模板**：
+```css
+.card { display: flex; flex-direction: column; max-height: calc(100vh - 48px); }
+.card-scrollable { flex: 1 1 auto; overflow-y: auto; min-height: 0; }
+.settings-footer { flex-shrink: 0; z-index: 10; background: hsl(var(--card)); border-top: 1px solid hsl(var(--gray-line)); }
+```
+
+**参考**：与 Dialog/Sheet Footer 的固定底部策略一致（component-specs.json C18/C19）。
+
+### Settings Section 样式规范
+
+| 属性 | 值 | 说明 |
+|------|-----|------|
+| Section padding | `var(--card-gap) 0` (16px 0) | 上下内边距 |
+| Section 间分割线 | `border-top: 1px solid hsl(var(--gray-line))` | 仅 Section 之间有分割线 |
+| Section 标题字号 | 16px | — |
+| Section 标题字重 | 600 (semibold) | — |
+| Section 标题颜色 | `hsl(var(--gray-title))` | — |
+| Section 标题下间距 | 12px (--gap-lg) | margin-bottom |
+| Section 描述字号 | 13px (--font-size-sm) | — |
+| Section 描述颜色 | `hsl(var(--gray-secondary))` | — |
+| Section 描述下间距 | 20px (--gap-xl) | margin-bottom，距第一个 form-row |
+
+## 5. 组件推荐规则及约束
+
+### 必需组件
+
+| 组件 | 引用 | 层级 | 位置 | 说明 |
+|------|------|------|------|------|
+| PageHeader | — | ORGANISM | top | 页面标题（如"新建实例"） |
+| Form | FieldGroup | ORGANISM | center | 表单容器，替代 div + space-y-* |
+| SubmitBar | — | ORGANISM | bottom | 提交操作栏，底部固定 |
+
+> **框架级组件**（自动继承，无需在此声明）：Sidebar、Breadcrumb 由 `rules/page-frame.json` 统一管理，L2 级页面自动包含。弹窗表单（Dialog 内）为 L0 级，无框架组件。
+
+### 可选组件
+
+| 组件 | 引用 | 条件 | 说明 |
+|------|------|------|------|
+| Select | Select | 下拉选择字段 | 地域、类型等预定义选项 |
+| Combobox | Combobox | 可搜索下拉 | 数据量大的选项 |
+| Switch | Switch | 布尔字段(设置) | 监控、备份等开关 |
+| Checkbox | Checkbox | 布尔字段(表单) | 协议确认等 |
+| RadioGroup | RadioGroup | 单选(少量) | 类型选择 |
+| ToggleGroup | ToggleGroup | 2-5 选项切换 | 替代 Button 循环 |
+| InputOTP | InputOTP | 验证码输入 | 短信/邮箱验证 |
+| Textarea | Textarea | 多行文本 | 描述、备注 |
+| Slider | Slider | 范围选择 | 数值范围调节 |
+| Dialog | Dialog | 删除/二次确认 | 取消时弹窗确认 |
+| Badge | Badge | 状态标识 | 字段状态标记 |
+| Tooltip | Tooltip | 字段说明 | 复杂字段悬浮提示 |
+| Alert | Alert | 操作提示 | 危险操作预警 |
+| Sonner | Sonner | 操作反馈 | 保存成功/失败 |
+| Separator | Separator | 分区之间 | 替代 hr |
+| Skeleton | Skeleton | 加载时 | 编辑模式加载数据时 |
+
+### 禁止组件
+
+| 组件 | 约束 | 原因 |
+|------|------|------|
+| DataTable | 禁止出现在表单页主内容区 | 如需选择关联数据，用 Dialog + DataTable |
+| Chart | 禁止出现在表单页 | 图表属于 Dashboard |
+| PageContainer | 禁止嵌套 | 见 `rules/layout-rules.json` |
+| ListPage | 禁止嵌套 | 表单页是页面级组件 |
+| 内联 Input | 禁止不在 Field 内 | 所有 Input 必须在 FieldGroup → Field 内(F1) |
+| 原始 div 表单布局 | 禁止 | 用 FieldGroup + Field 替代(F1) |
+
+### 嵌套约束
+
+| 父子关系 | 状态 | 说明 |
+|----------|------|------|
+| PageContainer → ContentWrapper | ALLOW | 右侧内容大容器（必需） |
+| ContentWrapper → Card(白卡容器) | ALLOW | 白色卡片容器，包裹所有业务内容（必需） |
+| Card(白卡容器) → Breadcrumb | ALLOW | 标准结构 |
+| Card(白卡容器) → PageHeader | ALLOW | 标准结构 |
+| Card(白卡容器) → FieldGroup | ALLOW | 表单容器 |
+| Card(白卡容器) → SubmitBar | ALLOW | 底部提交栏 |
+| ContentWrapper → PageHeader / Breadcrumb / FieldGroup / SubmitBar | FORBID | 业务组件必须经过白卡容器包裹 |
+| Card(白卡容器) → Card(白卡容器) | FORBID | 白卡容器为单例，禁止嵌套 |
+| FieldGroup → Field | ALLOW | 表单字段 |
+| Field → Input/Select/Switch | ALLOW | 表单控件 |
+| Field → ToggleGroup | ALLOW | 选项组控件 |
+| Field → Textarea | ALLOW | 多行文本 |
+| Card(白卡容器) → Card(分区) | ALLOW | 分区表单（内部卡片） |
+| Card(分区) → FieldGroup | ALLOW | 分区内表单 |
+| Card(白卡容器) → Dialog | WARN | 取消确认弹窗由全局状态管理 |
+| Card(白卡容器) → Form | FORBID | Form 应在 FieldGroup 层级 |
+| Field → InputGroup | ALLOW | 输入框组（验证码等场景） |
+
+## 6. 页面交互补充
+
+### 6.1 字段校验
+
+| 场景 | 触发 | 视觉反馈 | shadcn 规范 |
+|------|------|----------|-------------|
+| 必填字段为空 | 失焦/提交 | 红色边框 + 错误提示 | data-invalid on Field, aria-invalid on Input(F6) |
+| 格式错误 | 失焦/提交 | 红色边框 + 错误描述 | data-invalid + FieldDescription 展示错误(F6) |
+| 后端校验失败 | 提交后 | 字段标红 + 错误提示 | data-invalid on Field(F6) |
+
+### 6.2 控件选型
+
+| 字段场景 | shadcn 组件 | 规范引用 |
+|---------|-------------|---------|
+| 文本输入 | Input | F1 |
+| 下拉选择 | Select | C1(Group 嵌套) |
+| 可搜索下拉 | Combobox | — |
+| 布尔开关(设置) | Switch | F1 |
+| 复选框(表单) | Checkbox | F1,F5 |
+| 单选(2-5项) | ToggleGroup | F4 |
+| 单选(>7项) | RadioGroup | F1,F5 |
+| 验证码 | InputOTP | — |
+| 多行文本 | Textarea | F2 |
+| 范围选择 | Slider | — |
+| 输入框+按钮 | InputGroup | F2,F3 |
+
+### 6.3 提交交互
+
+| 操作 | 触发 | 前置条件 | 二次确认 | 目标页面/组件 | 返回行为 |
+|------|------|---------|---------|-------------|----------|
+| 保存/提交 | 点击"确定"按钮 | 本地校验通过 | 否 | 校验 → 提交 → 成功 | 新建返回列表, 编辑返回原页, Sonner "保存成功"(C9) |
+| 保存失败 | 提交返回错误 | — | — | — | 字段标红(F6) + Sonner 错误(C9), 留在表单页，聚焦第一个错误字段 |
+| 取消 | 点击"取消"按钮 | 有未保存内容 | 是 (Dialog 确认) | Dialog 确认(有未保存内容) | 确认后离开, 无未保存内容直接离开 |
+| 返回 | 点击 Breadcrumb 返回 | 有未保存内容 | 是 (Dialog 确认) | 返回 ListPage | 保持筛选+分页状态 |
+
+### 异步提交处理
+
+| 场景 | 提交后行为 | 反馈方式 |
+|------|-----------|---------|
+| 同步提交(快速) | 阻塞UI, 显示 Spinner | SubmitBar 按钮 disabled + `<Spinner data-icon="inline-start" />` |
+| 异步提交(耗时) | 不阻塞UI, 后台处理 | Sonner "提交成功, 后台处理中" + 轮询状态 |
+
+### 操作确认规范
+
+> 三级确认定义见 `rules/page-flow.json` operationConfirmationLevels。
+
+| 确认级别 | 适用操作 |
+|---------|---------|
+| 一级 (可逆) | 保存/提交(本地校验通过时) |
+| 二级 (有未保存内容) | 取消/离开 |
+
+### 6.4 shadcn 关键交互约定
+
+- **表单布局**: 用 `FieldGroup` + `Field`，不用 `div` + `space-y-*`(F1)
+- **字段校验**: `data-invalid` 在 `Field` 上，`aria-invalid` 在控件上(F6)
+- **禁用状态**: `data-disabled` 在 `Field` 上，`disabled` 在控件上(F6)
+- **2-5 选项**: 用 `ToggleGroup`，不用循环 `Button` 手动 active 状态(F4)
+- **相关选项组**: 用 `FieldSet` + `FieldLegend`(F5)
+- **InputGroup**: 内部用 `InputGroupInput`/`InputGroupTextarea`，不用原始 `Input`(F2)
+- **按钮在 input 内**: 用 `InputGroup` + `InputGroupAddon`(F3)
+- **Sonner 反馈**: `import { toast } from "sonner"`(C9)
+
+### 6.5 与 PageContainer 模式对照
+
+> 布局模式定义见 `rules/layout-rules.json`
+
+表单页使用 **模式A（直接内容）或模式B（Card 分组）**：
+```
+模式A: PageContainer → ContentWrapper → Breadcrumb + PageHeader + FieldGroup + SubmitBar
+模式B: PageContainer → ContentWrapper → Breadcrumb + PageHeader + Card[FieldGroup] + SubmitBar
+```
+分区表单使用 **模式B 扩展**：
+```
+PageContainer → ContentWrapper → Breadcrumb + PageHeader + Card[FieldGroup] + Separator + Card[FieldGroup] + SubmitBar
+```
+
+## 规范引用
+
+- **读取路径**：见根技能 `../../SKILL.md` §4.5 三阶段读取决策树
+  - 阶段①：`page-types.json` + `business-mapping.json`
+  - 阶段②：`page-frame.json` + `layout-rules.json` + `page-flow.json`
+  - 阶段③（生成 HTML 时）：`design-tokens.json` + `design-tokens.css` + `styling.json` + `../../boundaries.md` + `../../foundations.md`（表单布局精确规格见 `../../patterns/form-page.md` §8）
+
+> `rules/design-tokens.css` 是设计 Token 的唯一真相源（:root 变量定义）：生成 HTML 原型时需将 :root 变量块嵌入页面 `<style>` 标签；生成 React/TSX 需确保项目已通过 `@import` 引入该 CSS 文件。
+
+## 7. 验证清单 (Validation Checklist)
+
+> **通用检查项**（布局分区/颜色Token/间距/字体/尺寸/禁用样式/异步操作/空数据/加载中）见根技能 `../../docs/validation-workflow.md` 验证清单。此处仅列出表单页特有检查项。
+
+| 检查项 | 检查点 | 目标 |
+|--------|--------|------|
+| 必需组件 | PageHeader、Form(FieldGroup)、SubmitBar | 100% |
+| 嵌套约束 | PageContainer → ContentWrapper → Breadcrumb + PageHeader + FieldGroup + SubmitBar | 无违规嵌套 |
+| 禁止组件 | 无 DataTable、Chart、内联 Input(不在 Field 内)、原始 div 布局 | 0 个 |
+| 表单布局 | 所有 Input 在 Field → FieldGroup 内(F1) | 正确 |
+| 字段校验 | 必填为空/格式错误/后端校验, data-invalid 正确 | 全部正确 |
+| 控件选型 | 每种字段场景使用正确 shadcn 组件 | 正确 |
+| 提交交互 | 前置条件、确认方式、异步处理 | 正确 |
+| 取消确认 | 未保存内容时 Dialog确认 | 正确 |
+| 按钮 loading | SubmitBar 按钮 disabled + Spinner(C4) | 正确 |
+| 分区表单 | Card 分组、Separator 分隔 | 正确 |

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

@@ -0,0 +1,286 @@
+---
+name: page-rule-list
+parent: page-rule-system
+description: >
+  列表页(PageType: ListPage)路由规则。根据子类型识别关键词，路由到 patterns/ 目录下对应详细规则。
+  共享规则在 _shared/ 目录（表格列元规则 / 操作列规范 / 状态-操作模式）。
+  产品配置在 products/{产品}/ 目录（列定义 / 状态机 / 业务映射）。
+  三层参数化架构（v7.0）：元规则（固化）+ 产品配置（灵活）+ 模式细节。
+  触发：需要列表页规则、匹配列表页模板、生成列表页。
+  Version: 7.8.4
+---
+
+# 列表页路由规则
+
+## 1. 类型定义
+
+**页面类型**: ListPage
+**核心特征**: 多条结构化数据的展示、筛选和操作入口
+**识别条件**: 页面包含数据表格（DataTable）或卡片网格（CardGrid）+ 搜索/筛选 + 分页
+
+---
+
+## 2. 子类型路由表
+
+| 子类型ID | 识别关键词 | 路由到 | 布局模式 | 核心组件 |
+|----------|-----------|--------|----------|----------|
+| standard | "列表"/"表格"/"查询" | → `patterns/standard-list.md` | 模式D | DataTable + Pagination |
+| l2-sidebar | "分类"/"分组"/"左侧树" | → `patterns/l2-sidebar-list.md` | 模式D + Sidebar | Sidebar(240px) + DataTable |
+| expandable | "展开"/"子项"/"详情" | → `patterns/expandable-list.md` | 模式D | DataTable(行内展开) |
+| drawer | "弹窗列表"/"选择器" | → `patterns/drawer-list.md` | 模式D (Sheet内) | DataTable ⊂ Sheet |
+| **pure-card** | "纯卡片"/"卡片管理"/"智能体列表" | → `patterns/card-list.md` | 模式A-CARD | CardGrid + ItemCard + CardActionBar |
+| **standard-card** | "卡片列表"/"分类卡片"/"资源卡片" | → `patterns/card-list.md` | 模式D-CARD (TWO_COL) | Sidebar + CardGrid + ItemCard + CardActionBar |
+| **view-toggle** | "视图切换"/"列表卡片切换" | → `patterns/card-list.md` | 模式D + ViewToggle | ViewToggle + CardGrid/DataTable + ItemCard(tile) |
+| advanced-filter | "高级筛选"/"更多条件" | → `patterns/advanced-filter-list.md` | 模式D+ | AdvancedFilterPanel + DataTable |
+
+> **v7.2 合并**：原 `pure-card-list.md` / `standard-card-list.md` / `view-toggle-list.md` 三个 patterns 合并为单一 `patterns/card-list.md`，子类型差异在其 §1 差异矩阵中区分。
+
+### 路由判定优先级
+
+1. 含"纯卡片"/"卡片管理"关键词 → pure-card
+2. 含"卡片列表"/"分类卡片"/"资源卡片"关键词 → standard-card
+3. 含"视图切换"/"列表卡片"关键词 → view-toggle
+4. 含"高级筛选"关键词 → advanced-filter
+5. 含"展开"/"子项"关键词 → expandable
+6. 含"分类"/"分组"/"左侧树"关键词 → l2-sidebar
+7. 含"弹窗列表"/"选择器"关键词 → drawer
+8. 其他列表场景 → standard（默认）
+
+---
+
+## 3. 通用属性模型
+
+| 属性 | 值 | 说明 |
+|------|-----|------|
+| layout.type | TWO_COL / SINGLE_COL | 见 `rules/page-frame.json` layoutSelectionRules |
+| layout.frame | L1 | 列表页为 L1 级页面，自动继承 Sidebar（含Logo+产品名）。无面包屑。 |
+| responsive | Desktop ≥1200px(完整), Tablet 768-1199px(横滚), Mobile <768px(不推荐) |
+| pagination.default | 标准列表 10 条/页, 纯卡片 12 条/页 |
+
+> **框架组件自动继承**：Sidebar 的存在性由 `rules/page-frame.json` 统一管理，子技能只定义内容区组件。L1 级页面自动包含：Sidebar（顶部Logo+产品名），无面包屑。
+
+---
+
+## 4. 组件推荐
+
+### 必需组件
+
+| 组件 | 引用 | 层级 | 位置 | 说明 |
+|------|------|------|------|------|
+| PageHeader | — | ORGANISM | top | 页面标题(18px/medium)，默认无描述 |
+| ActionToolbar | — | ORGANISM | top | 操作工具栏，单行 flex(flex-wrap:nowrap)，左侧创建按钮 + 右侧搜索工具 |
+| Pagination | — | MOLECULAR | bottom | 分页控件 |
+
+> **框架级组件**（自动继承，无需在此声明）：Sidebar 由 `rules/page-frame.json` 统一管理，L1 级页面自动包含。
+> 注：DataTable 为 standard/l2/expandable/drawer/view-toggle 的必需组件；CardGrid 为 standard-card/pure-card/view-toggle 的必需组件。
+
+### 禁止组件
+
+| 组件 | 约束 | 原因 |
+|------|------|------|
+| Form(ORGANISM) | 禁止直接出现在内容区 | 表单应通过 Dialog/Sheet/FormPage 触发 |
+| Chart(ORGANISM) | 禁止出现在标准列表页 | 图表属于 Dashboard |
+| PageContainer | 禁止嵌套 | 见 `rules/layout-rules.json` |
+| 内联编辑 | 禁止 | 编辑应通过 Sheet/Dialog/FormPage |
+| 拖拽排序 | 禁止 | 表格数据为服务端排序 |
+| 无限滚动 | 禁止 | B2B 管理场景需精确分页 |
+| 悬浮操作栏 | 禁止 | 遮挡数据，可发现性差 |
+| 右键菜单 | 禁止 | 可发现性差，移动端不兼容 |
+| hr/section-divider | 禁止 | 组件间距通过 padding/margin 控制，禁止用分割线分隔 PageHeader/ActionToolbar/DataTable
+---
+
+## 5.1 Card 内左右对齐【稳定规则 / 硬约束】
+
+> **这是列表页生成中最容易不稳定的点，必须严格遵守：**
+
+水平 padding 采用**分层模型 v7.5**，职责严格划分：
+
+- **Card.paddingX (20px)** → 提供 Card 外侧边缘 ↔ **非 Table 子组件** (PageHeader / ActionToolbar / BulkActionBar / Pagination) 外缘的外侧呼吸
+- **Table td.paddingX (12px)** → 仅提供中间列与列之间的内部呼吸（相邻 td 12+12=24）
+- **Table 首末列 padding-left/right = 20px** → 表格作为密集数据区，额外享有 20px 视觉缩进
+
+> 注意：Table 首列内容 X = Card 外缘 + 40px，与 PageHeader / ActionToolbar / Pagination 起始线**不对齐**（这是设计预期）。
+
+Card 白卡容器：`padding: 0 var(--card-padding-x)` （上下 0 / 左右 20px）。注意：`--card-padding-x` (20px) 独立于 `--page-container-padding` (16px)，后者为 PageContainer 外层间距。
+
+| 组件 | 水平 padding | 起始线 X 坐标 | 说明 |
+|------|---------------|-----------------|------|
+| Card 白卡容器 | **20px** | Card 外缘 | `padding: 0 var(--card-padding-x)`【外侧呼吸提供者】 |
+| PageHeader | **0** | Card 外缘 + 20 | 外侧呼吸由 Card.paddingX 提供 |
+| ActionToolbar | **0** | Card 外缘 + 20 | 外侧呼吸由 Card.paddingX 提供 |
+| **Table th / td 中间列** | **12px** | — | 仅提供列间内部呼吸（列间距 24px） |
+| **Table th / td 首列** | `padding-left: 20px` | **Card 外缘 + 40** | 表格额外享有 20px 缩进 |
+| **Table th / td 末列** | `padding-right: 20px` | 末缘 = Card 右缘 - 40 | 同上 |
+| BulkActionBar | **0** | Card 外缘 + 20 | 外侧呼吸由 Card.paddingX 提供 |
+| Pagination | **0** | Card 外缘 + 20 | 外侧呼吸由 Card.paddingX 提供 |
+
+### 参考 CSS
+
+```css
+.data-table thead th,
+.data-table tbody td { padding: 12px 12px; }
+.data-table thead th:first-child,
+.data-table tbody td:first-child { padding-left: 20px; }
+.data-table thead th:last-child,
+.data-table tbody td:last-child { padding-right: 20px; }
+```
+
+### 禁止项
+
+- ❌ 禁止在非 Table 子组件 (PageHeader / ActionToolbar / BulkActionBar / Pagination) 重复设置 paddingX（会与 Card.paddingX 叠加为 40px）
+- ❌ 禁止 Table 中间列 td paddingX 不为 12px（列间距不为 24px，与设计不一致）
+- ❌ 禁止 Table 首列 padding-left 为非 20 值（0 / 12 / 16 / 24 都不适用）
+- ❌ 禁止 Table 末列 padding-right 为非 20 值（同上）
+- ❌ 禁止使用 `px-4` / `px-6` 等字面量。Tailwind 唯一可接受模式：`px-3 first:pl-5 last:pr-5`（20px = pl-5 / pr-5）
+- ❌ 禁止在 Card 与子组件之间插入额外的 paddingX 包裹层（如为 `.card-scrollable` 加 paddingX）
+
+### 验证方法
+
+生成后逐项验证：
+
+1. PageHeader 标题左边缘 X = ActionToolbar 首个控件 X = Pagination 左侧起始 X = **Card 左边缘 + 20px**
+2. Table 首列 (checkbox) 内容左边缘 X = **Card 左边缘 + 40px**（20 + 20）
+3. Table 末列内容右边缘 X = **Card 右边缘 - 40px**
+4. Table 相邻两个中间列内容间距 = **24px**（例如「ID」列右边缘 ↔ 「状态」列左边缘）
+
+任一不一致即为违反。
+
+### 视觉预期
+
+- thead 背景、tbody tr `border-bottom`、BulkActionBar 背景、Pagination `border-top` **不延伸到 Card 左右边缘**（Card 左右各保留 20px 白边）
+- 表格首末列内容在此基础上进一步缩进 20px，总体与 Card 边缘保持 40px 距离
+- 这是设计预期行为；表格作为密集数据区，额外的首末列缩进为文本提供更舒适的阅读呼吸
+
+> Token 定义：`rules/design-tokens.json` · `componentSpacing.Card.padding` + `componentSpacing.DataTable.firstLastCellRule` + `componentSpacing.DataTable.horizontalAlignmentRule`
+> 组件详细规范：`rules/component-specs.json` · `C17-Table.horizontalPaddingRule`
+
+---
+
+## 5.2 ContentCard 表面规则 v7.6【硬约束】
+
+内容区大卡片容器（ContentCard 作为白卡容器使用时）表面规则：
+
+| 属性 | v7.5 及之前 | **v7.6（当前）** |
+|------|-------------|----------------|
+| `border` | `1px solid hsl(var(--gray-line))` | **`none`（去掉）** |
+| `box-shadow` | `0 1px 2px rgba(0,0,0,0.04)` 或 `shadow-card` | **`var(--shadow-sm)` = `0 1px 2px rgba(0,0,0,0.05)`** |
+| `border-radius` | `var(--radius-lg)` = 12px | 保持不变 |
+| `background` | `hsl(var(--card))` | 保持不变 |
+
+### 参考 CSS
+
+```css
+.card,
+.card-wrapper {
+  background: hsl(var(--card));
+  border-radius: var(--radius-lg);
+  /* v7.6：去掉 1px border，使用最弱阴影 */
+  box-shadow: var(--shadow-sm);
+  overflow: hidden;
+}
+```
+
+### 禁止项
+
+- ❌ 禁止 `border: 1px solid hsl(var(--gray-line))`（v7.6 去线框后不再需要）
+- ❌ 禁止硬编码 `box-shadow: 0 1px 2px rgba(0,0,0,0.04)`（一律走 `var(--shadow-sm)`）
+- ❌ 禁止使用 `shadow-DEFAULT` / `shadow-md` 等更强阴影（会造成表面过重）
+- ❌ 禁止同时使用 `border` + `shadow`（v7.6 为二选一关系，仅保留 `shadow`）
+
+### 不适用场景（依然使用 border）
+
+- 浮层类：Dropdown / Popover / Select content / Tooltip
+- 业务卡片列表项 (item-card / GenericCard)
+- shadcn 默认 Card（未作为内容区白卡容器使用时）
+
+> Token 定义：`rules/design-tokens.json` · `componentSpacing.Card.surface`
+> 组件规格：`rules/component-specs.json` · `C7-Card.contentCardOverride`
+
+---
+
+## 5. 嵌套约束
+
+| 父子关系 | 状态 | 说明 |
+|----------|------|------|
+| PageContainer → ContentWrapper | ALLOW | 右侧内容大容器（必需） |
+| ContentWrapper → Card(白卡容器) | ALLOW | 白色卡片容器，包裹所有业务内容（必需） |
+| Card(白卡容器) → PageHeader | ALLOW | 标准结构 |
+| Card(白卡容器) → ActionToolbar | ALLOW | 操作工具栏 |
+| Card(白卡容器) → DataTable | ALLOW | 核心组件 |
+| Card(白卡容器) → CardGrid | ALLOW | 卡片列表 |
+| Card(白卡容器) → ViewToggle | ALLOW | 视图切换 |
+| Card(白卡容器) → AdvancedFilterPanel | ALLOW | 高级筛选面板 |
+| Card(白卡容器) → Pagination | ALLOW | 分页控件 |
+| ContentWrapper → PageHeader / ActionToolbar / DataTable / CardGrid / Pagination | FORBID | 业务组件必须经过白卡容器包裹 |
+| Card(白卡容器) → Card(白卡容器) | FORBID | 白卡容器为单例，禁止嵌套 |
+| ActionToolbar → SearchCombo | ALLOW | 搜索组合 |
+| CardGrid → ItemCard | ALLOW | 业务卡片（v7.3 起详见 `patterns/card-list.md` §9.1） |
+| ItemCard → CardActionBar | ALLOW | 卡片操作栏，三态：hover-slidebar / hover-fade / always-visible（v7.3 详见 `patterns/card-list.md` §9.3） |
+| DataTable → Pagination | ALLOW | 分页控件 |
+| DataTable → Dialog | WARN | 确认弹窗由全局状态管理 |
+| DataTable → Form | FORBID | 表格内不应直接嵌套完整表单 |
+| Sidebar → DescriptionList | FORBID | 描述列表不应嵌套在侧边栏 |
+
+---
+
+## 6. 共享规则引用
+
+以下规范为多个子类型共用，提取到 `_shared/` 目录：
+
+| 共享规则 | 路径 | 被引用子类型 |
+|----------|------|-------------|
+| 表格列元规则 | `_shared/column-meta-rules.md` | standard, l2-sidebar, expandable, drawer, view-toggle（列表视图） |
+| 操作列规范 | `_shared/action-column-spec.md` | standard, l2-sidebar, expandable, drawer, view-toggle（列表视图） |
+| 状态-操作模式 | `_shared/state-action-pattern.md` | standard, l2-sidebar, expandable, drawer, pure-card, standard-card, view-toggle |
+| 业务卡片三件套规格（v7.3 下沉） | `patterns/card-list.md` §9（ItemCard/CardGrid/CardActionBar 完整规格） | pure-card, standard-card, view-toggle（均路由到 patterns/card-list.md） |
+
+子类型文件按需要引用对应共享文件。
+
+## 7. 产品配置引用
+
+> 具体列定义、状态机、业务场景按产品隔离，存放在 `products/{产品}/` 目录。
+> AI 读取时需根据目标产品加载对应配置文件。
+
+| 产品类型 | 列定义 | 状态机 | 业务映射 |
+|----------|--------|--------|---------|
+| ECS | `products/ecs/columns.json` | `products/ecs/states.json` | `products/ecs/mapping.json` |
+| PolarDB | `products/polar-db/columns.json` | `products/polar-db/states.json` | `products/polar-db/mapping.json` |
+| Cloud-Catalog | `products/cloud-catalog/columns.json` | `products/cloud-catalog/states.json` | — |
+| AI Gateway | `products/ai-gateway/columns.json` | `products/ai-gateway/states.json` | `products/ai-gateway/mapping.json` + `cards.json`（v7.2 新增，卡片视图 slot 绑定） |
+
+**读取规则**：
+1. 根技能确定页面类型 → Phase ①
+2. 子技能匹配子类型 → Phase ②
+3. 根据目标产品加载 `products/{产品}/` 下对应配置文件 → Phase ②.5
+4. 元规则（列应该有显隐规则/拖拽/排序） + 产品配置（具体列名/宽度/状态） → Phase ③ 生成 HTML
+
+---
+
+## 规范引用
+
+- **读取路径**：见根技能 `../../SKILL.md` §4.5 四阶段读取决策树
+  - 阶段①：`page-types.json` + `business-mapping.json`
+  - 阶段②：`page-frame.json` + `layout-rules.json` + `page-flow.json` + `_shared/search-combo-spec.md`；卡片子类型 (pure-card / standard-card / view-toggle) 追加读取 `patterns/card-list.md`（v7.3 起为三件套唯一规范来源）
+  - 阶段②.5：`products/{产品}/columns.json` + `states.json`（v6.2 新增）
+  - 阶段③（生成 HTML 时）：`design-tokens.json` + `design-tokens.css` + `styling.json` + `../../boundaries.md` + `../../foundations.md`
+
+> `rules/design-tokens.css` 是设计 Token 的唯一真相源（:root 变量定义）：生成 HTML 原型时需将 :root 变量块嵌入页面 `<style>` 标签；生成 React/TSX 需确保项目已通过 `@import` 引入该 CSS 文件。
+
+---
+
+## 验证清单 (Validation Checklist)
+
+> **通用检查项**（布局分区/颜色Token/间距/字体/尺寸/禁用样式/异步操作/空数据/加载中）见根技能 `../../docs/validation-workflow.md` 验证清单。此处仅列出列表页特有检查项。
+
+| 检查项 | 检查点 | 目标 |
+|--------|--------|------|
+| 嵌套结构 | PageContainer → ContentWrapper → Card(白卡容器) → PageHeader/ActionToolbar/DataTable/Pagination | 100% |
+| Card 内统一左右内边距 | PageHeader/ActionToolbar/DataTable/Pagination 在 Card 内左右 padding 均为 24px | 100% |
+| 必需组件 | PageHeader、ActionToolbar、Pagination + 子类型组件（DataTable/CardGrid） | 100% |
+| 禁止组件 | 无内联编辑、拖拽排序、无限滚动、悬浮操作栏、右键菜单 | 0 个 |
+| 子类型组件 | 按子类型路由到正确组件（DataTable 或 CardGrid） | 正确 |
+| 操作可用性 | 状态-操作矩阵匹配 | 所有状态正确 |
+| 二次确认 | 启动/停止/重启 Dialog确认，删除需输入确认 | 正确 |
+| 批量操作 | 选中≥1行显示、混合状态禁用、异步处理 | 正确 |
+| 搜索交互 | 回车执行、下拉切换维度、FilterTag 展示 | 正确 |
+| 分页 | 默认条数、保持筛选、"共N条" | 正确 |