@teamix-evo/skills 0.5.0 → 0.7.0

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

@@ -1,203 +1,268 @@
-# Detail Page — 详情页模式
+---
+name: page-rule-detail
+parent: page-rule-system
+description: >
+  详情页(PageType: DetailPage)路由规则。根据子类型识别关键词，路由到 patterns/ 目录下对应详细规则。
+  共享规则在 _shared/ 目录（PageHeader L2 面包屑强约束）。
+  包含通用属性模型、组件推荐、嵌套约束、交互补充、视觉规范同步。
+  触发：需要详情页规则、匹配详情页模板、生成详情页。
+  Version: 7.8.4
+---
+
+# 详情页路由规则
 
-> ⚠️ **Prerequisites**: 你必须已在 [generation-flow.md](../generation-flow.md) Step 2 确认页面类型为 **DetailPage**，并由 Step 3 引导到这里。
+> ⚠️ **本文件是高阶路由索引，不含布局实现细节。**
+> **生成页面时必须读取**：
+> - `../pages/detail-page/SKILL.md` — 子技能入口（子类型列表 + 属性模型）
+> - `../pages/detail-page/patterns/{subtype}.md` — 完整骨架 + DOM 结构 + CSS 约束（resource / monitor / api-doc / comparison）
+> - `../rules/page-header-spec.md` — PageHeader L2 面包屑硬约束
+>
+> 本文件仅用于：(1) 了解详情页子类型概览 (2) 快速判断属于哪个子类型
 
-> **触发**：用户描述含"详情/查看/信息/概览"。
-> **核心特征**：单条记录的只读展示 + DescriptionList + 操作按钮。
-> **页面级别**：L2（面包屑模式 PageHeader，自动继承 Sidebar）。
+## 1. 类型定义
+
+**页面类型**: DetailPage
+**核心特征**: 单条记录的只读展示 + DescriptionList + 操作按钮
+**识别条件**: 页面展示单个实体的完整信息 + 描述列表(DescriptionList) + Tab分类 + 操作按钮
 
 ---
 
-## 1. 子类型识别
+## 2. 子类型路由表
 
-| 子类型       | 关键词                   | 差异特征                                   |
-| ------------ | ------------------------ | ------------------------------------------ |
-| **标准详情** | "详情"/"基本信息"        | PageHeader + DescriptionList + 操作按钮    |
-| **资源详情** | "实例详情"/"资源"/"监控" | InfoCard + MonitorPanel + Tabs（关联资源） |
-| **概览型**   | "概览"/"总览"            | StatCard + Chart + DescriptionList         |
-| **流程型**   | "审批"/"流程"/"记录"     | Steps + Timeline + DescriptionList         |
-| **对比型**   | "对比"/"比较"            | 双栏/多栏 DescriptionList 对照             |
+| 子类型ID | 识别关键词 | 路由到 | 核心组件 |
+|----------|-----------|--------|----------|
+| resource | "实例详情"/"资源"/"详情"/"查看"/"信息" | → `patterns/resource-detail.md` | InfoCard + DescriptionList + Tabs |
+| monitor | "监控"/"指标"/"性能"/"告警"/"Metrics" | → `patterns/monitor-detail.md` | MetricCard + ChartPanel + AlertList + TimeRangeSelector |
+| api-doc | "API"/"接口"/"端点"/"文档"/"接口文档"/"模型API" | → `patterns/api-doc-detail.md` | ApiEndpoint + ParameterTable + CodeBlock |
+| comparison | "对比"/"比较"/"差异"/"版本对比" | → `patterns/comparison-detail.md` | 双栏 DescriptionList |
 
----
+### 路由判定优先级
 
-## 2. 标准结构（资源详情）
-
-```
-┌─────────────────────────────────────────────┐
-│ PageHeader（面包屑模式）                    │
-│ 实例与镜像 > 实例列表 > 实例详情 [创建镜像]│  ← Header
-│                                             │
-│ InfoCard ─ 基本信息                         │  ← 摘要区
-│ 组织 | 资源集 | 创建人 | 创建时间           │
-│                                             │
-│ InfoCard ─ 监控                             │
-│ [CPU 使用率] [内存使用率]（MonitorPanel）   │
-│                                             │
-│ Tabs                                        │  ← 分类
-│ [基本信息] [监控] [云盘] [安全组] [快照]    │
-│                                             │
-│ DescriptionList ─ 基本信息                  │  ← 主区
-│ 架构: X86       地域: cn-beijing            │
-│ 实例ID: i-xxx   状态: [Badge 运行中]        │
-│                                             │
-│ DescriptionList ─ 配置信息                  │
-│ vCPU: 2         内存: 4 GiB                 │
-└─────────────────────────────────────────────┘
-```
-
-## 简洁详情结构
-
-```
-┌─────────────────────────────────────────────┐
-│ PageHeader（面包屑模式）                    │
-│ 用户列表 > 用户详情      [编辑] [删除]      │
-│                                             │
-│ DescriptionList (column: 2)                 │
-│ 姓名: 张三       邮箱: zhangsan@example.com │
-│ 角色: 管理员     状态: [Badge 启用]         │
-│ 创建时间: 2026-01-15  更新: 2026-04-20     │
-└─────────────────────────────────────────────┘
-```
+1. 含"监控"/"指标"/"性能"/"告警"/"Metrics" → monitor
+2. 含"API"/"接口"/"端点"/"文档" → api-doc
+3. 含"对比"/"比较"/"差异" → comparison
+4. 其他详情场景 → resource（默认）
 
 ---
 
-## 3. 必需组件
+## 3. 通用属性模型
 
-| 组件                | 位置 | 说明                            |
-| ------------------- | ---- | ------------------------------- |
-| **PageHeader**      | top  | 面包屑模式(L2 页面)+ 操作按钮组 |
-| **DescriptionList** | main | 详情页核心展示组件              |
-| **DescriptionItem** | main | 描述项最小展示单元              |
+| 属性 | 值 | 说明 |
+|------|-----|------|
+| layout.type | TWO_COL / SINGLE_COL | 见 `rules/page-frame.json` layoutSelectionRules |
+| layout.frame | L2 | 详情页为 L2 级页面，自动继承 Sidebar + PageHeader 面包屑模式 |
+| responsive | 768px 侧边栏折叠为抽屉，DescriptionList 列数从 4 降为 2 |
 
-**框架级**(自动继承):Sidebar、PageHeader 由 page-frame 管控。
+> **框架组件自动继承**：Sidebar、PageHeader 由 `rules/page-frame.json` 统一管理，L2 级页面自动继承。
 
-### 可选组件
+---
 
-- **InfoCard** — 顶部摘要(组织/创建人/创建时间)
-- **Tabs** — 信息分多类(基本/监控/关联资源)
-- **MonitorPanel** — CPU/内存/网络监控(仅资源详情)
-- **Badge** — 状态指示
-- **Tooltip** — 长 ID / 截断字段悬浮
+## 4. 组件推荐
+
+### 必需组件
+
+| 组件 | 引用 | 层级 | 位置 | 说明 |
+|------|------|------|------|------|
+| PageHeader | — | ORGANISM | top | 面包屑模式 + 操作按钮组（详见 `../rules/page-header-spec.md`） |
+| DescriptionList | — | ORGANISM | center | 核心展示组件，支持 2/3/4 列布局 |
+| DescriptionItem | — | ATOMIC | center | 单个键值对单元，6 种交互模式 |
+
+### 可选组件（跨子类型通用）
+
+| 组件 | 引用 | 条件 | 说明 |
+|------|------|------|------|
+| InfoCard | — | 需展示摘要信息 | 顶部摘要卡片 |
+| CopyableText | — | ID/IP/资源名 | 可复制原子 |
+| StatusBadge | — | 资源运行态 | 带前置圆点的状态徽章 |
+| Tabs | — | 信息分多类展示 | Tab 分组 |
+| Dialog | — | 需二次确认 | 删除/释放确认 |
+| Sheet | — | 需编辑详情 | 侧滑编辑 |
+| DropdownMenu | — | 操作多项 | "更多"下拉 |
+| Tag | — | 状态/标签 | — |
+| Badge | — | 运行状态 | — |
+| Tooltip | — | 悬浮提示 | — |
+| Separator | — | 信息分组 | — |
+| Alert | — | 操作提示 | — |
+| Empty | — | 无关联数据 | — |
+| Spinner | — | 加载中 | — |
+| Sonner | — | 操作反馈 | — |
+
+### 禁止组件
+
+| 组件 | 约束 | 原因 |
+|------|------|------|
+| Form (ORGANISM) | 禁止在主内容区 | 编辑应通过 Sheet/Dialog/FormPage |
+| DataTable | 禁止在主内容区 | 关联数据通过 Tabs 子面板展示 |
+| Chart (ORGANISM) | 禁止替代 DescriptionList | 监控通过 ChartPanel，详见 patterns/monitor-detail.md |
+| PageContainer | 禁止嵌套 | 见 layout-rules.json |
+| QueryFilter | 禁止出现 | 详情页无筛选需求 |
 
 ---
 
-## 4. DescriptionItem 字段交互
-
-| 类型           | 触发       | 反馈                              |
-| -------------- | ---------- | --------------------------------- |
-| 默认展示       | —          | 只读文本，空值 `-` 占位           |
-| 可复制         | 点 📋 图标 | 图标高亮 + Toast "已复制"         |
-| 可编辑（行内） | 点 ✎ 图标  | 切换为 Input                      |
-| 链接跳转       | 点字段值   | 链接样式（VPC、安全组等关联资源） |
-| 状态展示       | —          | Badge + 语义色                    |
-| 悬浮提示       | hover      | Tooltip 完整内容（截断时）        |
+## 5. 嵌套约束（通用）
+
+| 父子关系 | 状态 | 说明 |
+|----------|------|------|
+| PageContainer → ContentWrapper | ALLOW | 右侧内容大容器（必需） |
+| ContentWrapper → Card(白卡容器) | ALLOW | 白色卡片容器（必需） |
+| Card(白卡容器) → PageHeader | ALLOW | 标准结构（面包屑模式） |
+| Card(白卡容器) → InfoCard | ALLOW | 摘要卡片 |
+| Card(白卡容器) → Tabs | ALLOW | 分类 Tab |
+| Card(白卡容器) → DescriptionList | ALLOW | 核心展示 |
+| ContentWrapper → PageHeader / DescriptionList / Tabs | FORBID | 必须经过白卡容器包裹 |
+| Card(白卡容器) → Card(白卡容器) | FORBID | 白卡容器为单例 |
+| DescriptionList → ListSection | ALLOW | 信息分组 |
+| ListSection → DescriptionItem | ALLOW | 分组详情项 |
+| Tabs → TabPane → DescriptionList | ALLOW | Tab 内展示详情 |
+| Tabs → TabPane → DataTable | ALLOW | Tab 内展示关联资源 |
+| PageHeader → ActionGroup | ALLOW | 操作按钮组 |
+| Sidebar → DescriptionList | FORBID | 描述列表不应在侧边栏 |
+
+> 子类型特有嵌套约束见对应 `patterns/*.md`。
 
 ---
 
-## 5. 操作按钮规则
+## 6. 页面交互补充（跨子类型共享）
 
-### 5.1 位置
+### DescriptionItem 字段交互
 
-- **位置 A**：PageHeader 右侧（主操作 + 更多 Dropdown）
-- **位置 B**：DescriptionItem 内（行内编辑、复制）
+| 交互类型 | 触发 | 视觉反馈 |
+|----------|------|----------|
+| 默认展示 | — | 只读文本 |
+| 可复制 | 点击复制图标 | Sonner "已复制" |
+| 可编辑 | 点击编辑图标 | 行内切换为 Input |
+| 链接跳转 | 点击字段值 | 蓝色链接 |
+| 状态展示 | — | Badge 颜色 |
+| 悬浮提示 | hover | Tooltip 完整内容 |
 
-### 5.2 操作分级
+### 操作按钮行为
 
-| 级别             | 适用            | 确认                  |
-| ---------------- | --------------- | --------------------- |
-| 一级（可逆）     | 编辑、续费/降配 | 直接执行              |
-| 二级（影响状态） | 释放、创建镜像  | Dialog 确认           |
-| 三级（不可逆）   | 删除            | Dialog + 输入确认文本 |
+| 操作 | 前置条件 | 二次确认 | 返回行为 |
+|------|---------|---------|----------|
+| 编辑 | 无 | 否 | 保存后返回详情页 |
+| 删除 | 实例已停止 | Dialog + 输入确认 | 返回列表页 |
+| 释放/创建镜像 | 实例已停止 | Dialog 确认 | 异步操作，返回列表 |
+| 续费/降配 | 运行中 | 否 | 完成后返回详情页 |
+| 返回/关闭 | 无 | 否 | 返回 ListPage |
 
-### 5.3 异步反馈
+### Tab 切换交互
 
-| 操作            | Toast        | 页面                  |
-| --------------- | ------------ | --------------------- |
-| 释放 / 创建镜像 | "操作已提交" | 轮询状态              |
-| 删除            | "删除已提交" | 返回 ListPage 并刷新  |
-| 编辑保存        | "保存成功"   | 停留详情页 + 局部刷新 |
+- 首次加载默认激活第一个 Tab
+- Tab 切换懒加载，Loading 状态展示
+- 无数据 Tab 展示 Empty
+- URL hash 同步，支持刷新保持
+- Tab 内 DataTable 含独立 Pagination
 
----
+### 边界情况处理
 
-## 6. Tab 切换交互
+| 场景 | 处理方式 |
+|------|----------|
+| 无数据 | Empty + 返回列表引导 |
+| 加载中 | Spinner 骨架屏 |
+| 加载失败 | ErrorState + 重试 |
+| 权限不足 | 操作按钮隐藏 |
+| 资源不存在 | 404 ExceptionPage |
+| 字段为空 | 展示 "-" 占位 |
+| 字段过长 | 截断 + Tooltip |
 
-| 场景       | 行为                          |
-| ---------- | ----------------------------- |
-| 首次加载   | 默认激活第一个 Tab            |
-| Tab 切换   | 懒加载数据 + Loading          |
-| 无数据 Tab | 展示 Empty                    |
-| Tab 内列表 | 含独立 Pagination             |
-| URL 同步   | 切换同步 URL hash，刷新可保持 |
+### 返回约定
+
+- 面包屑父级项可点击返回列表页
+- PageHeader 右侧关闭按钮(×)
+- 返回后列表页保持原筛选和分页
 
 ---
 
-## 7. 信息分组
+## 7. 视觉规范同步（v7.5 间距 + v7.6 表面）【硬约束】
 
-- DescriptionList 按 ListSection 分组（基本信息 / 配置信息 / 网络信息）
-- 每组可独立展开/收起（可选）
-- 分组间用 Divider 分隔
-- 每组内 DescriptionList 默认 `column: 2`，宽屏可至 4，移动端降为 1
+> 与列表页 `patterns/list-page.md` §5.1 / §5.2 形成对称。规则总源以 `rules/design-tokens.css` 为准。
 
----
+### 7.1 间距规则（v7.5 分层 padding 模型）
 
-## 8. 嵌套约束
+| 层级 | Token | 值 | 含义 |
+|------|-------|----|------|
+| PageContainer 外层 | `--page-container-padding` | **16px** | 四周 padding |
+| Card 白卡容器内 | `--card-padding-x` | **20px** | 唯一对齐源 |
+| Card 内区块垂直间距 | `--card-gap` | 16px | 各区块纵向间距 |
+| DescriptionList 内 | C26-DescriptionList | 见 component-specs.json | 行高与列宽 |
 
-| 父子关系                                                                                                                  | 状态                                                   |
-| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| PageShell(background="muted", sidebar=OpSidebar) → OpPageContainer(header=PageHeader) → InfoCard / Tabs / DescriptionList | ALLOW                                                  |
-| OpPageContainer 内大白卡 → 再嵌一层 `<Card>` 包业务组件                                                                   | **FORBID**(已内置大白卡,嵌套违反白卡单例)              |
-| InfoCard → DescriptionList / MonitorPanel                                                                                 | ALLOW(InfoCard 是局部信息卡 — 业务子区域级,非主区白卡) |
-| Tabs → TabPane → DescriptionList / DataTable                                                                              | ALLOW(关联资源用 DataTable)                            |
-| Sidebar → DescriptionList                                                                                                 | **FORBID**                                             |
-| PageHeader → Tabs                                                                                                         | WARN(Tab 应在 PageHeader 下方)                         |
+**派生约束**：
+- ContentCard 左右 padding 由 `--card-padding-x = 20px` 提供
+- 子组件（DescriptionList / InfoCard / Tabs / PageHeader）**不再重复设置左右 padding**
 
----
+### 7.2 ContentCard 表面规则（v7.6）
+
+| 属性 | **v7.6（当前）** |
+|------|----------------|
+| `border` | **`none`（去掉）** |
+| `box-shadow` | **`var(--shadow-sm)` = `0 1px 2px rgba(0,0,0,0.05)`** |
+| `border-radius` | `var(--radius-lg)` = 12px |
+| `background` | `hsl(var(--card))` |
+
+### 7.3 InfoCard surface 决议（v7.6）
+
+#### 模式 A：独立 Card 容器模式
+
+跟随主卡 ContentCard 应用 v7.6：`border: none` + `box-shadow: var(--shadow-sm)`
 
-## 9. 禁止项
+#### 模式 B：嵌入主卡内的分组区块模式
 
-| 禁项                       | 原因                                  |
-| -------------------------- | ------------------------------------- |
-| Form 直接在主内容区        | 编辑应通过 Drawer/Dialog/FormPage     |
-| DataTable 在主内容区       | 关联数据应用 Tabs 子面板              |
-| Chart 替代 DescriptionList | 图表属 Dashboard，监控用 MonitorPanel |
-| QueryFilter                | 详情页无筛选需求                      |
-| `hr` 分割线                | 用 Divider                            |
+仅使用 `padding: 16px 0` + `border-bottom: 1px solid hsl(var(--gray-line))`（功能性分组分割线）
+
+### 7.4 功能性分割线保留清单
+
+| 元素 | 边框用途 | 保留 |
+|------|----------|------|
+| `.page-header` 的 `border-bottom` | 标题区与内容区分割 | ✅ 保留 |
+| `Tabs` 容器的 `border-bottom` | TabBar 与 TabContent 分割 | ✅ 保留 |
+| `Separator` | 信息分组 | ✅ 保留 |
+| ListSection 之间横线 | 描述列表分组 | ✅ 保留 |
+| 浮层类（Dropdown/Popover/Tooltip） | 浮层与背景区分 | ✅ 保留 border + 阴影 |
+
+### 7.5 禁止项
+
+- ❌ `.card / .info-card` 中残留 `border: 1px solid hsl(var(--gray-line))`
+- ❌ 硬编码阴影 `0 1px 2px rgba(0,0,0,0.04)`；一律走 `var(--shadow-sm)`
+- ❌ `--card-padding-x` 硬编码为 24px / 16px（v7.5 起统一 20px）
+- ❌ 子组件重复设置左右 padding
 
 ---
 
-## 10. 边界情况
+## 8. 共享规则引用
 
-| 场景       | 处理                    |
-| ---------- | ----------------------- |
-| 无数据     | Empty + 返回列表引导    |
-| 加载中     | Loading 骨架屏          |
-| 加载失败   | ErrorState + 重试按钮   |
-| 权限不足   | 操作按钮隐藏，只读展示  |
-| 资源不存在 | 跳转 404 ExceptionPage  |
-| 字段为空   | 展示 "-" 占位           |
-| 字段过长   | 截断 + Tooltip 完整内容 |
+| 共享规则 | 路径 | 被引用子类型 |
+|----------|------|-------------|
+| PageHeader L1 标题 / L2 面包屑强约束 | `../rules/page-header-spec.md` | 全部 |
 
 ---
 
-## 11. 详情 → 列表返回约定
+## 规范引用
+
+- **读取路径**：见根技能 `../../SKILL.md` §4.5 三阶段读取决策树
+  - 阶段①：`page-types.json` + `business-mapping.json`
+  - 阶段②：`page-frame.json` + `layout-rules.json` + `page-flow.json`；匹配子类型后追加 `patterns/{子类型}.md`
+  - 阶段③（生成 HTML 时）：`design-tokens.json` + `design-tokens.css` + `component-specs.json` + `styling.json` + `../boundaries.md` + `../foundations.md`
 
-- 面包屑父级项点击返回 ListPage
-- PageHeader 右侧可选 × 关闭按钮
-- 返回后 ListPage 保持原筛选 + 分页
-- 详情页编辑成功后，按业务决策：
-  - 留在详情页（Toast「保存成功」+ 局部刷新）
-  - 或返回 ListPage（Toast「保存成功」+ 列表刷新）
+> `rules/design-tokens.css` 是设计 Token 唯一真相源：生成 HTML 原型时需将 :root 变量块嵌入 `<style>`；React/TSX 需确保已 `@import` 引入。
 
 ---
 
-## 12. 详情页特有自检
-
-- [ ] PageHeader 用面包屑模式（L2 页面）
-- [ ] DescriptionList 列数：默认 2，宽屏可 4，移动端 1
-- [ ] 关联资源用 Tabs 子面板（不在主区直接放 DataTable）
-- [ ] Badge 用语义色（不用原色）
-- [ ] 空字段用 "-" 占位
-- [ ] 长字段（ID/Hash）`font-mono` + 提供复制按钮
-- [ ] 操作分级正确（删除 = 输入确认）
-- [ ] Tab 切换 URL hash 同步
-- [ ] 边界状态完整：Empty / Loading / ErrorState / 权限不足 / 404
+## 验证清单 (Validation Checklist)
+
+> **通用检查项** 见 `../../docs/validation-workflow.md`。此处仅列出详情页特有检查项。
+
+| 检查项 | 检查点 | 目标 |
+|--------|--------|------|
+| 必需组件 | PageHeader、DescriptionList、DescriptionItem | 100% |
+| 嵌套约束 | PageContainer → ContentWrapper → Card → PageHeader + 内容 | 无违规 |
+| 禁止组件 | 无内联表单、DataTable 主内容区、QueryFilter | 0 个 |
+| PageHeader | 面包屑模式合规（`../rules/page-header-spec.md` 15 项） | 全部通过 |
+| ContentCard 表面 (v7.6) | 无 1px border + shadow = var(--shadow-sm) | 0 违规 |
+| InfoCard 表面 (v7.6) | 模式 A 跟随主卡；模式 B 仅 padding + border-bottom | 0 违规 |
+| Card 间距 (v7.5) | padding = 0 var(--card-padding-x) = 20px | 正确 |
+| PageContainer 间距 | padding = var(--page-container-padding) = 16px | 正确 |
+| 功能性分割线 | PageHeader / Tabs / Separator 的 border 保留 | 不被误删 |
+| 操作按钮 | 前置条件、确认方式、异步处理 | 全部正确 |
+| Tab 切换 | 懒加载、URL hash、Empty | 正确 |
+| 返回约定 | 面包屑 + 关闭按钮(×) | 正确 |
+| 边界情况 | 无数据/加载中/失败/权限/404/空值 | 正确 |