@teamix-evo/skills 0.2.0 → 0.4.0

package/src/teamix-evo-design-uni-manager/foundations.md

@@ -0,0 +1,258 @@
+# Foundations — Uni-Manager 视觉地基
+
+> 排版 / 色彩 / 间距 / 圆角 / 阴影 / 动效 在 Uni-Manager 下的系统化使用规范。
+> 价值锚：**hybridcloud 锐利风 · 高密度信息可读性 · token-first**。
+> 真值源：`@teamix-evo/tokens/variants/uni-manager/theme.css`（Tailwind v4 `@theme` + `[data-theme='uni-manager']` scoped CSS）。
+
+---
+
+## 0. AI 实操路径（先做这步）
+
+写任何视觉之前先调 MCP `tokens_list`（group=uni-manager）拿当前真值，**不要凭记忆**：
+
+| 拿到结果 → 该做什么                  | 工具                                                      |
+| ------------------------------------ | --------------------------------------------------------- |
+| 列出可用语义槽 + 真值                | `tokens_list({ group: "uni-manager" })`                   |
+| 查某个槽位（如 `--shadow-md`）的值   | `tokens_list({ group: "uni-manager", filter: "shadow" })` |
+| 校验生成代码是否使用了未声明的 token | `validate_tokens(code)`（规划中）                         |
+
+> 圆角、阴影、字号是 uni-manager 与 opentrek 差异最大的三类 token。**禁止**直接套 opentrek 经验值。
+
+---
+
+## 1. Token 优先级铁律
+
+```
+Tailwind 语义类(bg-card / text-foreground)   ← 首选
+   ↓ 不够用时
+CSS 变量(var(--color-success))               ← 次选
+   ↓ 不够用时（罕见）
+hardcoded 数值                                ← 仅限 token 真空地带，且需评审
+```
+
+- **禁止** 直接 `text-blue-600` / `bg-[#0064C8]` / `style={{ color: '#0064C8' }}`（违反 boundaries.md F1 / S1 / S8）
+- **允许** 间距 / 尺寸的 Tailwind 数字类（`p-4` / `gap-3`），它们已在 `theme.css` 中校准
+- 一切色彩走 5 类语义槽：Surface / Text / Action / Boundary / Feedback（见 §4）
+
+---
+
+## 2. 排版（Typography）
+
+### 2.1 字号 9 档（覆盖 Tailwind v4 默认）
+
+| Tailwind         | px  | 用途                                  | 来源           |
+| ---------------- | --- | ------------------------------------- | -------------- |
+| `text-xxs`       | 10  | 角标、密集表格副信息（罕用）          | 辅助档         |
+| `text-xs`        | 12  | 字段标签、表格副字段、Caption         | cd body.1      |
+| `text-sm`        | 14  | 默认正文 / 表格主字段 / Form 输入文字 | cd body.2      |
+| `text-base`      | 16  | 强调正文 / Card 副标题                | cd subhead     |
+| `text-lg`        | 18  | Card 标题 / 弹窗主标题                | cd title       |
+| `text-xl`        | 20  | 区块标题 / DescriptionList 分组标题   | cd headline    |
+| `text-2xl`       | 24  | 页面 PageHeader.title                 | cd display.1   |
+| `text-3xl`       | 28  | 大数据展示 / Dashboard 数值卡         | cd display.2 ✱ |
+| `text-display-3` | 32  | 超大档（运营 / 营销 banner，罕用）    | cd display.3   |
+| `text-4xl`       | 36  | 营销超大档                            | 备用           |
+
+> ✱ uni-manager 把 Tailwind v4 默认 `text-3xl=30px` 覆盖为 28px，与 cd hybridcloud display.2 对齐；其余档与 Tailwind v4 默认一致。
+
+### 2.2 字重（4 档）
+
+| Tailwind        | weight | 用途                         |
+| --------------- | ------ | ---------------------------- |
+| `font-normal`   | 400    | 正文 / 表格单元格            |
+| `font-medium`   | 500    | 标签 / 次级标题 / 数据强调   |
+| `font-semibold` | 600    | 主标题 / Card / Page Title   |
+| `font-bold`     | 700    | 仅 Dashboard 大数据 / 营销头 |
+
+### 2.3 行高
+
+- 正文统一 `leading-relaxed`（≈ 1.5×）— Teamix-UI 规范明示行高 1.5×
+- 数据卡片大数字 `leading-none` 让数值贴底
+- 超长正文 ≥ 3 行 `leading-7` 提升阅读节奏
+
+---
+
+## 3. 间距（Spacing）— 8 档刻度
+
+### 3.1 8 档间距锚点（Teamix-UI 规范）
+
+| 档位 | px  | Tailwind          | 用途                             |
+| ---- | --- | ----------------- | -------------------------------- |
+| XXS  | 4   | `p-1` / `gap-1`   | 图标-文字、错误信息内 padding    |
+| XS   | 8   | `p-2` / `gap-2`   | 紧凑分组内、Toolbar 内按钮间     |
+| S    | 12  | `p-3` / `gap-3`   | 详情页字段行距、紧凑表格行内     |
+| M    | 16  | `p-4` / `gap-4`   | 默认间距（最常用）               |
+| L    | 20  | `p-5` / `gap-5`   | Form 字段间距 / 区块间留白       |
+| XL   | 24  | `p-6` / `gap-6`   | 页面 margin / Card padding       |
+| XXL  | 32  | `p-8` / `gap-8`   | Form 分区间距 / 大区块间隔       |
+| XXXL | 48  | `p-12` / `gap-12` | 页面级超大留白（启动页 / Empty） |
+
+> **铁律**：8 档之外的间距值（如 `p-2.5` = 10px / `gap-7` = 28px）原则上 **禁止使用**，违反 Teamix-UI 规范。例外：`p-1.5` = 6px 仅用于 Icon Button 内边距（已在组件源码内置）。
+
+### 3.2 信息密度 3 档（来自 doc 04）
+
+| 密度 | 行间距 / 区间距 | 适用                     |
+| ---- | --------------- | ------------------------ |
+| 高   | 32 / 48         | Dashboard / 运营首页     |
+| 中   | 16 / 24         | 列表页 / 详情页（默认）  |
+| 低   | 8 / 12          | 紧凑表格 / Drawer 内表单 |
+
+### 3.3 Form 间距三档（hardcode token，禁手写）
+
+| Token                              | 值   | 自动应用于                      |
+| ---------------------------------- | ---- | ------------------------------- |
+| `--spacing-form-label-to-input`    | 4px  | `<FieldLabel>` → 控件           |
+| `--spacing-form-error-to-input`    | 0px  | `<FieldError>` → 控件（防抖动） |
+| `--spacing-form-help-to-input`     | 4px  | `<FieldDescription>` → 控件     |
+| `--spacing-form-item-gap`          | 20px | FieldGroup 组内行距             |
+| `--spacing-form-section-gap`       | 32px | FieldSection 组间距             |
+| `--spacing-form-section-title-gap` | 20px | FieldSection 标题 → 第一字段    |
+
+详情页只读字段 `density="detail"` → 行距 12px（doc 16）。
+
+### 3.4 栅格（Layout）
+
+- **24 列栅格 · margin 24 · gutter 16**（Teamix-UI 规范）
+- 4 档断点：`base / xs / s / m / l / xl` → 1280 / 1440 / 1920（Teamix-UI doc 03）
+- 推荐：`max-w-screen-2xl mx-auto` + 内层 `grid grid-cols-24 gap-4`
+
+---
+
+## 4. 色彩（Color）— 5 类语义槽
+
+### 4.1 Brand（uni-manager 锚点）
+
+| 角色            | Token                        | 真值           | 用途                                |
+| --------------- | ---------------------------- | -------------- | ----------------------------------- |
+| primary         | `--color-primary`            | #0064C8（B50） | 主按钮 / 链接 / 选中态              |
+| primary-fg      | `--color-primary-foreground` | #ffffff        | primary 上的文字                    |
+| sidebar         | `--color-sidebar`            | #ffffff        | 侧边栏背景（白底，opentrek 是深色） |
+| sidebar-primary | `--color-sidebar-primary`    | #0064C8        | 侧边栏选中条                        |
+
+### 4.2 Surface
+
+`bg-background` / `bg-card` / `bg-popover` / `bg-muted` / `bg-secondary`。
+**禁止** 直接 `bg-white` / `bg-gray-50`。
+
+### 4.3 Text
+
+`text-foreground` / `text-muted-foreground` / `text-primary` / `text-destructive`。
+**禁止** 直接 `text-gray-700` / `text-zinc-500`。
+
+### 4.4 Boundary
+
+`border` / `border-input` / `border-border` / `ring-ring`。
+
+> **uni-manager 特例**：`--color-ring: transparent` — focus 不显示品牌色 halo，而是通过 `border-color` 加深到 `--color-input-focus: #aaaaaa`（cd hybridcloud 风格）。AI 生成时 **不需要** 主动写 `focus:ring-*`，theme.css scoped CSS 会自动接管。
+
+### 4.5 Feedback（语义状态色）
+
+| 语义        | Token                         | 用途                        |
+| ----------- | ----------------------------- | --------------------------- |
+| success     | `--color-success` #23B066     | 成功状态、运行中            |
+| warning     | `--color-warning` #F98E1A     | 警告、待处理                |
+| destructive | `--color-destructive` #E84738 | 错误、删除、不可逆操作      |
+| info        | `--color-info` #0064C8        | 信息提示（与 primary 同色） |
+
+每个语义都附 `*-foreground` / `*-subtle`（弱底色） / `*-border`（弱边框）三件套。
+
+### 4.6 Chart（5 色 + 取色规则）
+
+`--color-chart-1` ~ `--color-chart-5` 已预设。多于 5 系列：用 `chart-1..5` 顺序循环 + 透明度变化，**禁止** 自创第 6 色。
+
+### 4.7 告警色阶（doc 01 P1-P7）
+
+按严重等级 P1（最严重）~ P7（最轻）使用，不混用功能色：
+
+| 等级  | 用途            | Token / Tailwind 别名（待补） |
+| ----- | --------------- | ----------------------------- |
+| P1    | 紧急 / 不可恢复 | destructive                   |
+| P2-P3 | 严重 / 高优     | destructive + warning 渐变    |
+| P4-P5 | 一般 / 中优     | warning                       |
+| P6-P7 | 低优 / 提示性   | info                          |
+
+> P 级映射到具体 token 在 ADR 0030 中定稿；当前阶段 AI 生成可暂用 destructive / warning / info 三档替代。
+
+---
+
+## 5. 圆角（Radius）— uni-manager 锐利风
+
+> uni-manager 的 **核心视觉差异**：相比 opentrek 圆润（base 16px），uni-manager 走 cd hybridcloud 锐利风（base 4px / `radius-sm = 0px`）。
+
+| Tailwind       | 真值   | 用途                                                |
+| -------------- | ------ | --------------------------------------------------- |
+| `rounded-none` | 0      | 表格行 / 全屏 banner                                |
+| `rounded-sm`   | 0px    | ✱ 输入控件 / 表格 / Tag 边角（uni-manager 默认）    |
+| `rounded-md`   | 2px    | ✱ 按钮 / Card 默认 / Dialog（与 OpenTrek 6px 不同） |
+| `rounded-lg`   | 4px    | ✱ Card 强调 / Drawer / 弹层                         |
+| `rounded-xl`   | 8px    | ✱ 大型 Card / 营销卡                                |
+| `rounded-2xl`  | 12px   | ✱ 营销 / 大屏数据卡                                 |
+| `rounded-full` | 9999px | Avatar / Badge dot / 圆形按钮                       |
+
+> ✱ 标注的档位与 Tailwind v4 默认不同，由 `theme.css` 显式声明覆盖。
+> **AI 生成铁律**：表单控件、表格、Tag 一律 `rounded-sm`（即 0px 直角）；常规 Card 用 `rounded-md`（2px）；不要套用 opentrek 的 `rounded-lg`（曾是 12px，现在 uni-manager 下是 4px）。
+
+### 5.1 组件级圆角 alias
+
+| Token             | 真值 | 用途                               |
+| ----------------- | ---- | ---------------------------------- |
+| `--radius-dialog` | 2px  | Dialog / Sheet 圆角（cd corner-1） |
+| `--radius-tag`    | 4px  | Tag 圆角（cd corner-2）            |
+
+---
+
+## 6. 阴影（Shadow）— hybridcloud 4 级
+
+> uni-manager 阴影从 cd hybridcloud `shadow.1/2/3.down` 直接投影，**显著弱于** OpenTrek。
+
+| Tailwind               | 真值                            | 来源                | 用途                         |
+| ---------------------- | ------------------------------- | ------------------- | ---------------------------- |
+| `shadow-none`          | none                            | —                   | 默认（Form 控件、表格行）    |
+| `shadow-2xs`/`xs`/`sm` | 0 1px 2px rgba(0,0,0,0.04~0.05) | base                | 微弱浮起（罕用）             |
+| `shadow-md`            | 0 3px 8px rgba(0,0,0,0.06)      | hybridcloud S1.down | Card / Form hover            |
+| `shadow-lg`            | 0 3px 8px rgba(0,0,0,0.18)      | hybridcloud S2.down | Dropdown / Popover / Tooltip |
+| `shadow-xl`            | 0 6px 24px rgba(0,0,0,0.10)     | hybridcloud S3.down | Sheet / Drawer / Dialog      |
+| `shadow-2xl`           | 0 12px 48px rgba(0,0,0,0.20)    | 顶层模态            | AlertDialog / 全屏 modal     |
+
+### 6.1 圆角 × 阴影对应表（不可乱配）
+
+| 容器         | radius                               | shadow                            | 备注                 |
+| ------------ | ------------------------------------ | --------------------------------- | -------------------- |
+| 表单输入     | `rounded-sm`                         | `shadow-none` (hover `shadow-md`) | scoped CSS 自动接管  |
+| 表格行       | `rounded-none`                       | `shadow-none`                     | —                    |
+| Card         | `rounded-md`                         | `shadow-md`                       | hybridcloud 默认浮起 |
+| Dropdown     | `rounded-md`                         | `shadow-lg`                       | —                    |
+| Sheet/Drawer | `rounded-lg`                         | `shadow-xl`                       | 大尺寸弹层           |
+| Dialog       | `rounded-md`(`--radius-dialog: 2px`) | `shadow-xl`                       | cd hybridcloud 锐利  |
+
+### 6.2 Form 控件特殊行为
+
+uni-manager `theme.css` 内置的 scoped CSS 会自动让带 `border-input` 的 input/select/textarea：
+
+- 默认 `box-shadow: none`
+- hover → `var(--shadow-form-hover)` (= shadow-md)
+- focus → `border-color: #aaaaaa` + `var(--shadow-form-hover)`，**不显示** ring
+
+AI 生成时 **不要** 写 `focus:ring-2 focus:ring-primary`，否则与 scoped CSS 冲突。
+
+---
+
+## 7. 动效（Motion）
+
+| 时长           | 用途                         |
+| -------------- | ---------------------------- |
+| `duration-75`  | 微交互（hover 色变）         |
+| `duration-150` | 默认（按钮 / 输入态）        |
+| `duration-200` | 中等（折叠 / 展开）          |
+| `duration-300` | 较慢（Drawer / Dialog 进出） |
+
+缓动统一 `ease-out`（进场）/ `ease-in`（退场）。**禁止** 自定义 `cubic-bezier(...)` 字面量。
+
+---
+
+## 8. AI 自检（4 条）
+
+- [ ] 没有任何 hardcode 色值 / 任意尺寸 / 任意圆角
+- [ ] 圆角档与"组件类型"匹配（Form 控件 → `rounded-sm` / Card → `rounded-md`）
+- [ ] 阴影档与"圆角档"匹配（见 §6.1）
+- [ ] Form 控件没有手动 `focus:ring-*`（让 scoped CSS 接管）

package/src/teamix-evo-design-uni-manager/generation-flow.md

@@ -0,0 +1,194 @@
+# 生成 / 翻新 / 验证流程
+
+> AI 在执行页面级任务时，按本文件的门控顺序执行。每一步都有明确的输入输出，跳步会导致结果不可控。
+
+---
+
+## 1. 生成路径（六步门控）
+
+适用关键词：**"生成 / 创建 / 新建 / 设计一个 / 做一个 / 起一个控制台"**。
+
+```
+Step 1 需求确认 → Step 2 类型识别 → Step 3 子类型 + 布局
+                                            ↓
+Step 6 自检    ← Step 5 视觉填充  ← Step 4 组件挑选
+```
+
+### Step 1 · 最小 quorum + 默认值
+
+**只有两个信息缺一不可**（最小 quorum，缺则反问）：
+
+- [ ] **页面类型**：ListPage / DetailPage / FormPage / Dashboard / Console / Dialog（缺则按 Step 2 决策树推断）
+- [ ] **资源实体**：要操作的对象是什么（实例 / VPC / 租户 / 工单 / ……）
+
+**其他信息全部走默认值，先生成再细化**：
+
+| 维度     | 默认                                                | 何时升级                               |
+| -------- | --------------------------------------------------- | -------------------------------------- |
+| 业务领域 | 云资源管理                                          | 用户明确说"工作流 / 报表 / 审计"等     |
+| 用户角色 | 平台管理员                                          | 涉及合规 / 审批 / 租户管理员等敏感角色 |
+| 核心动作 | CRUD（增 / 删 / 改 / 查 + 列表）                    | 明确出现"批量 / 审批 / 导出 / 监控"    |
+| 入口路径 | 从同名菜单进入，无外部跳转                          | 明确说"从 X 跳到 Y"                    |
+| 子类型   | ListPage→standard / FormPage→single-page / 其余各 1 | 用户提到 wizard / drawer / tabbed 等   |
+| 多云感知 | 默认显示 cloud-provider Badge 列                    | 单云场景明确不需要时去除               |
+
+**反问触发条件**（只有以下情况反问）：
+
+1. 页面类型与资源实体均无法从需求中推断
+2. 用户描述与默认值明显冲突（如"我要做一个数据看板"但又说"列表"）
+
+**输出**：页面类型 + 资源实体 + 一句话场景假设（"假设是平台管理员的实例 CRUD 列表，多云资源默认显示 cloud Badge，如有偏差请指正"）。
+
+### Step 2 · 页面类型识别
+
+根据 [patterns/page-types.md](./patterns/page-types.md) §决策树匹配类型：
+
+```
+页面内容是什么？
+├─ 多条结构化数据 → ListPage
+├─ 单个记录详情 → DetailPage
+├─ 用户输入数据 → FormPage
+├─ 数据可视化/统计 → Dashboard
+├─ 控制台首页 / 多模块入口 → Console Home（Dashboard 子类）
+└─ 二次确认 / 快速操作 → Dialog/Sheet
+```
+
+**输出**：页面类型 ID（`ListPage` / `DetailPage` / `Console` / ...）。
+
+### Step 3 · 子类型识别 + 布局选择
+
+读对应 `patterns/{type}-page.md`：
+
+- 列表页：`standard / pure-card / drawer / expandable / l2-sidebar / advanced-filter`
+- 详情页：`tabbed / single-section / resource-detail`
+- 表单页：`single-page / wizard / drawer-form`
+- Dashboard：`overview / console-home / monitor-detail`
+
+**输出**：子类型 ID + 区域骨架（参照 [patterns/page-types.md](./patterns/page-types.md) §Zone Map）。
+
+### Step 4 · 组件挑选
+
+读 [components.md](./components.md) §选型决策树：
+
+1. 优先使用 `@teamix-evo/ui` 注册表中的稳定组件
+2. 通过 MCP `list_components(status: "stable")` 查可用列表
+3. 通过 MCP `get_component_meta(id)` 查具体 Props/Examples
+4. 复合场景按 [components.md](./components.md) §5.2 拼装配方装配（SearchCombo / ContextSwitcher / CardGrid 等概念占位）
+5. um-topbar / um-side-nav 等实物业务组件位于 `@teamix-evo/biz-ui/uni-manager/*`
+
+**输出**：组件清单 + 每个组件的关键 Props。
+
+### Step 5 · 视觉填充（Token 绑定）
+
+读 [foundations.md](./foundations.md)，所有色彩、间距、字号、圆角、阴影、动效**必须**使用 Token：
+
+| 维度 | Token 入口                                                                   |
+| ---- | ---------------------------------------------------------------------------- |
+| 色彩 | `bg-primary` / `text-foreground` / `border-border` / `text-muted-foreground` |
+| 间距 | 8 档刻度（`gap-1/2/3/4/5/6/8/12`），对应 4/8/12/16/20/24/32/48               |
+| 字号 | `text-xs` / `text-sm` / `text-base` / `text-lg` / `text-2xl` / `text-3xl`    |
+| 圆角 | `rounded-sm`(0) / `rounded-md`(2px) / `rounded-lg`(4px) — 锐利风             |
+| 阴影 | `shadow-md` / `shadow-lg` / `shadow-xl` — 弱浮起                             |
+| 动效 | `duration-150` / `duration-300` / `transition-colors`                        |
+
+**禁止**：硬编码 hex 色值、`#xxx` rgb()、内联 `style={{ ... }}`、`text-emerald-600` 等原始色。
+
+**输出**：含 Token 引用的可执行代码 / HTML。
+
+### Step 6 · 自检
+
+对照 [checklist.md](./checklist.md) 12+ 项逐项验证：
+
+- 通过 → 输出最终代码
+- 不通过 → 回到对应失败项的步骤修正后重新自检
+
+**输出**：合规代码 + 自检报告。
+
+---
+
+## 2. 翻新路径
+
+适用关键词：**"改造 / 升级 / 翻新 / 对齐规范 / 重新生成"**。
+
+```
+1. 读取目标页面源码
+2. 扫描违规项（按 boundaries.md F1-F10 + S1-S8 + UM1-UM3）
+3. 生成 old → new 替换清单
+   - 硬编码色值 → CSS Token 变量
+   - space-y-* → flex + gap-*
+   - w-N h-N (等值) → size-N
+   - 自定义 dark: 覆盖 → 语义 token
+   - rounded-lg/xl 在 Form/Table 控件 → rounded-sm
+   - 自建 topbar / sidebar → 用 biz-ui/uni-manager/um-topbar
+4. 对照 components.md 检查组件选型是否合理
+5. 应用替换 + 输出变更报告
+```
+
+**输出**：翻新后代码 + 变更报告（每项替换的 old → new + 引用的规则 ID）。
+
+---
+
+## 3. 验证路径
+
+适用关键词：**"检查 / 验证 / 评估 / 是否符合规范"**。
+
+```
+1. 读取目标页面源码
+2. 逐条对照 boundaries.md
+   - F1-F10（禁止项）
+   - FF1-FF4（表单）
+   - S1-S8（样式规则）
+   - C1-C12（组件结构规则）
+   - I1-I4（图标）
+   - UM1-UM3（专有云一致性）
+3. 对照 checklist.md 12+ 项自检
+4. 输出验证报告
+```
+
+**报告格式**：
+
+```markdown
+## 验证报告
+
+### ❌ 违规项（N）
+
+- F1 第 12 行：硬编码 `#0064C8` → 应改为 `text-primary`
+- S2 第 23 行：使用 `space-y-4` → 应改为 `flex flex-col gap-4`
+- UM1 第 5 行：自建 topbar → 应使用 `<UmTopbar />`
+
+### ⚠️ 建议项（M）
+
+- ...
+
+### ✅ 合规项（K）
+
+- ...
+```
+
+---
+
+## 4. 子任务退出条件
+
+| 任务类型 | 何时停止生成                      |
+| -------- | --------------------------------- |
+| 生成     | Step 6 自检全部通过               |
+| 翻新     | 替换清单为空 + 重新对照无违规     |
+| 验证     | 报告完整列出所有违规项 + 修复建议 |
+
+---
+
+## 5. 与 code-uni-manager skill 的协作
+
+页面级任务通常**两个 skill 同时触发**。Design skill 决定"长什么样"，Code skill 决定"怎么落地"：
+
+| 决策点                   | 由谁主导                                                                                  |
+| ------------------------ | ----------------------------------------------------------------------------------------- |
+| 页面骨架 / Zone 划分     | design                                                                                    |
+| 组件选型                 | design                                                                                    |
+| Token 绑定 / 视觉规则    | design                                                                                    |
+| 文件放置位置             | code（[file-structure.md](../teamix-evo-code-uni-manager/file-structure.md)）             |
+| import 路径 / reuse 策略 | code（[reuse-first.md](../teamix-evo-code-uni-manager/reuse-first.md)）                   |
+| API / services 层        | code（[api-layering.md](../teamix-evo-code-uni-manager/api-layering.md)）                 |
+| 表单实现细节             | code（[forms-and-validation.md](../teamix-evo-code-uni-manager/forms-and-validation.md)） |
+
+冲突时按 ADR 0018 AI 上下文路由约定：design 决定"做什么"，code 决定"怎么做"。

package/src/teamix-evo-design-uni-manager/patterns/dashboard.md

@@ -0,0 +1,95 @@
+# Dashboard — 控制台首页 / 数据概览页
+
+> AI 实操路径：Step 2（页面类型识别）判定为 Dashboard 后，本文档接管。
+>
+> uni-manager 中 Dashboard **同时承担"控制台 Home"** 角色（资源总览 / 待办 / 跨云态势），是用户登录后第一屏。
+
+---
+
+## 1. 子类型识别
+
+| 子类型           | 关键词                             | 差异特征                                                      |
+| ---------------- | ---------------------------------- | ------------------------------------------------------------- |
+| **Console Home** | "控制台首页"/"工作台"/"我的工作台" | 资源总览 + 待办 + 快捷入口 + 资产分布（uni-manager 默认入口） |
+| **资源概览**     | "资源概览"/"资产分布"              | StatCard + 多云资产分布图 + 区域 Top N                        |
+| **业务概览**     | "业务概览"/"运营总览"              | StatCard + Chart + Timeline                                   |
+| **监控概览**     | "监控大屏"/"健康度"                | 全屏 Chart Grid + 实时刷新                                    |
+
+**默认裁决**：用户描述含"管理控制台/Console/工作台"且未指明子类型 → **Console Home**。
+
+---
+
+## 2. 标准结构（Console Home）
+
+```text
+┌──────────────────────────────────────────────────────────────┐
+│ um-topbar：[logo] 租户切换▼ 区域▼ ··· 用户▼              │  ← 框架级
+├──────────────────────────────────────────────────────────────┤
+│ PageHeader：工作台 · 您好 张三              [今日 ▼] [刷新]  │
+├──────────────────────────────────────────────────────────────┤
+│ ┌────────┐┌────────┐┌────────┐┌────────┐                     │
+│ │总资源  ││待处理  ││今日告警││工单    │  ← StatCards (4×1)  │
+│ │ 1,024  ││   12   ││    3   ││   5    │                     │
+│ └────────┘└────────┘└────────┘└────────┘                     │
+├──────────────────────────────────────────────────────────────┤
+│ ┌─────────────────────────┐ ┌────────────────────────────┐   │
+│ │ 多云资产分布             │ │ 待办 / 待审批              │   │
+│ │ [饼图：阿里云/AWS/私有云]│ │ [Timeline]                 │   │
+│ │                          │ │                            │   │
+│ └─────────────────────────┘ └────────────────────────────┘   │
+├──────────────────────────────────────────────────────────────┤
+│ 快捷入口（最常用 8 个产品）                                  │
+│ [ECS] [RDS] [SLB] [VPC] [OSS] [ACK] [监控] [运维]            │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. 标准结构（业务概览 / 监控概览）
+
+```text
+┌────────────────────────────────────────────┐
+│ PageHeader: 概览        [今日 ▼] [刷新]    │
+├────────────────────────────────────────────┤
+│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐        │
+│ │实例数│ │待办数│ │告警数│ │健康度│  ← StatCards
+│ │ 1024 │ │  3   │ │  12  │ │ 98%  │        │
+│ └──────┘ └──────┘ └──────┘ └──────┘        │
+├────────────────────────────────────────────┤
+│ 业务趋势                   最近异常         │
+│ [Chart 折线图]            [Timeline]        │
+└────────────────────────────────────────────┘
+```
+
+---
+
+## 4. 设计要点
+
+- 关键指标用 `text-3xl font-bold`，与上一周期对比用 `+/-` 配 `chart-*` 色
+- 时间范围切换持久化到 URL params（`?range=today`）
+- 图表色彩按 `chart-1` `chart-2` `chart-3` ... 顺序消费，**禁止**任意 hex
+- StatCard 数量：4（1×4）/ 6（2×3）/ 8（2×4）；超过 8 改用 ListPage
+- 不要在 Dashboard 内放可编辑表单 — 跳转 FormPage
+- **Console Home 的 StatCard 数字必须可点击下钻** —— 跳转预筛选 ListPage（如「待处理 12」→ 工单列表 status=pending）
+- 跨云资产分布图必须使用 cloud Badge 同款色板（与 brand.md §3.3 跨云语义统一）
+
+---
+
+## 5. Console Home 专属约束（uni-manager）
+
+- [ ] 顶部框架必须使用 `um-topbar`（含租户切换 / 区域切换），不可自建 header（UM1）
+- [ ] StatCard 必须有"对比指标"（环比 / 同比），裸数字无意义
+- [ ] 跨云资产分布必须显式标注云厂商（CloudBadge 或饼图扇区 label）
+- [ ] 待办 / 待审批 Timeline 每条必须有"前往处理"链接，不创建死胡同
+- [ ] 快捷入口数量 ≤ 8，超出走"全部产品"二级页
+
+---
+
+## 6. 自检
+
+- [ ] 类型选对：是 Console Home / 资源概览 / 业务概览 / 监控概览？
+- [ ] StatCard 数字可下钻
+- [ ] 时间范围 URL 同步
+- [ ] 图表色用 `chart-*`，无 hex
+- [ ] um-topbar 在位（Console Home 必须）
+- [ ] 跨云分布有 CloudBadge 标注