@teamix-evo/skills 0.2.0 → 0.4.0

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

@@ -0,0 +1,202 @@
+# Brand — Uni-Manager 品牌画像
+
+> 视觉调性 / 文案语气 / 情感矩阵 / 正反例。
+> 价值锚：**专业 · 高效 · 可信赖** — 面向运维 / 平台管理员的"工作台"，而非营销门户。
+> 与 OpenTrek 的差异：信息密度更高、配色更冷峻、圆角更锐利、文案更"动作导向"。
+
+---
+
+## 1. 视觉风格五维（与 OpenTrek 对比）
+
+| 维度     | Uni-Manager                             | OpenTrek                         |
+| -------- | --------------------------------------- | -------------------------------- |
+| 圆角     | 锐利（`rounded-sm = 0` / `md = 2px`）   | 圆润（`md = 6px` / `lg = 12px`） |
+| 配色     | hybridcloud 蓝 B50 #0064C8 + 中性灰     | OpenTrek 主题色 + 暖灰           |
+| 信息密度 | 高（表格行高 36-40 / 字段紧凑 12-14px） | 中（行高 44-48 / 字段 14-16px）  |
+| 阴影     | 弱（透明度 0.06~0.18）                  | 中（0.10~0.25）                  |
+| 焦点反馈 | 边框加深至中性灰，**无品牌色 halo**     | 品牌色 ring                      |
+
+---
+
+## 2. 情感矩阵（0~100）
+
+| 情感   | 分值 | 主张                                 |
+| ------ | ---- | ------------------------------------ |
+| 可信赖 | 95   | 操作可逆 / 状态可见 / 错误可恢复     |
+| 高效率 | 95   | 信息密度高 / 一屏多任务 / 快捷键友好 |
+| 专业感 | 90   | 术语精确 / 不口语化 / 不情绪化       |
+| 现代感 | 70   | 锐利 + 留白 / 不堆砌装饰             |
+| 亲和力 | 45   | 中等（运维场景，亲和让位于精确）     |
+| 趣味性 | 10   | 几乎为 0 — 不用插画 / 不用拟人语气   |
+
+> 与 OpenTrek 对比：可信赖 / 高效率 + 5 分（更冷峻），亲和力 -10 分，趣味性 -10 分。
+
+---
+
+## 3. 设计哲学落地
+
+### 3.1 高密度优先
+
+- 表格行高默认 36px（OpenTrek 默认 40-44）
+- 字段标签字号 12px（`text-xs`）— 而非 OpenTrek 14px
+- DescriptionList 默认 `column: 2`，宽屏可至 4
+- Drawer 内表单字段 gap = 12px（详情页 `density="detail"`）
+
+### 3.2 一致性三件套（uni-manager 专有约束）
+
+每个页面必须满足：
+
+1. **左侧导航统一**：使用 `biz-ui/uni-manager/um-topbar` + `Sidebar` 框架；不要在业务页内重写导航
+2. **PageHeader 一致**：标题字号 `text-2xl`、面包屑紧贴标题左侧、操作按钮组统一靠右
+3. **状态语义统一**：所有"运行中 / 已停止 / 异常 / 待处理"对应 success / muted / destructive / warning，不允许业务页自创状态色
+
+详见 ADR 0030 / boundaries.md UM1-UM3。
+
+### 3.3 跨云资源可枚举
+
+- 涉及多云资源（如"阿里云 + 腾讯云 + 私有 IDC"）的列表，**必须** 用 cloud-provider Badge 标注归属
+- 资源 ID 一律 `font-mono` + 复制按钮
+- 区域 / VPC / 项目等"上下文"字段，放 ContextSwitcher（见 components.md §5.2 拼装配方）
+
+---
+
+## 4. 文案语气
+
+### 4.1 三大原则
+
+1. **精确 > 友好**：不口语化，不"宝贝/亲"，不感叹号
+2. **动词在前**：按钮文案以动词开头（"创建实例" / "释放资源" / "导出账单"）
+3. **简洁**：按钮 ≤ 5 字 / 标题 ≤ 12 字 / 错误说明 ≤ 30 字
+
+### 4.2 大小写
+
+- 中文按钮：动词 + 宾语（"创建实例"），不加标点
+- 英文按钮：Title Case（"Create Instance"），不加句号
+- 标题：中英文不混用句末标点
+
+### 4.3 文案分级
+
+| 级别      | 用途              | 长度上限 | 示例                                           |
+| --------- | ----------------- | -------- | ---------------------------------------------- |
+| 按钮      | 主操作            | 5 字     | "创建" / "释放" / "导出"                       |
+| Tag/Badge | 状态              | 4 字     | "运行中" / "已停止" / "待审批"                 |
+| 表头      | 列名              | 8 字     | "实例 ID" / "创建时间"                         |
+| 标题      | PageHeader / Card | 12 字    | "实例与镜像" / "VPC 管理"                      |
+| 帮助说明  | Tooltip           | 30 字    | "释放后实例不可恢复，已挂载磁盘将一并释放"     |
+| 空状态    | Empty.description | 40 字    | "当前组织下没有实例，新建一个开始你的资源管理" |
+
+---
+
+## 5. 危险操作专用文案模式
+
+### 5.1 模式
+
+```
+Title:    陈述句（描述后果）
+Body:     列出影响 + 不可逆性
+Confirm:  动作动词（与 Title 呼应）
+```
+
+### 5.2 示例
+
+```
+✅ 推荐
+Title:    将释放 3 个实例
+Body:     释放后实例不可恢复，已挂载的云盘将一并释放。
+          请输入实例名称 "prod-app-01" 确认。
+[Cancel]  [释放实例]
+
+❌ 避免
+Title:    确定要删除吗？
+Body:     这个操作不可恢复哦
+[取消]    [确定]
+```
+
+### 5.3 规则
+
+- 三级危险（不可逆）→ Dialog + 输入确认文本（资源名称 / "DELETE"）
+- 二级危险（影响状态）→ Dialog 二次确认
+- 一级（可逆）→ 直接执行 + Toast
+
+---
+
+## 6. 配色"应当 / 不应当"
+
+| 场景       | ✅ 应当                                            | ❌ 不应当                         |
+| ---------- | -------------------------------------------------- | --------------------------------- |
+| 主操作按钮 | `bg-primary text-primary-foreground`               | `bg-blue-600`                     |
+| 危险操作   | `variant="destructive"`                            | `bg-red-500 text-white`           |
+| 状态 Tag   | `<Badge variant="success">`                        | `<span className="bg-green-100">` |
+| 链接       | `text-primary hover:underline`                     | `text-[#0064C8]`                  |
+| 侧边栏选中 | `bg-sidebar-accent text-sidebar-accent-foreground` | `bg-blue-50 text-blue-700`        |
+
+---
+
+## 7. 视觉正反例对照
+
+### 7.1 ✅ 正例（典型 uni-manager 列表页）
+
+```tsx
+<PageContainer>
+  <PageHeader title="云实例" actions={<Button>创建实例</Button>} />
+  <Card className="rounded-md shadow-md">
+    <FilterBar>{/* 租户 / 区域 / 状态 / 关键词 */}</FilterBar>
+    <DataTable
+      rowHeight={36} // 高密度
+      columns={[
+        {
+          key: 'id',
+          title: '实例 ID',
+          render: (v) => <Mono copyable>{v}</Mono>,
+        },
+        {
+          key: 'cloud',
+          title: '所属云',
+          render: (v) => <CloudBadge provider={v} />,
+        },
+        { key: 'region', title: '区域' },
+        {
+          key: 'status',
+          title: '状态',
+          render: (v) => <Badge variant={v}>...</Badge>,
+        },
+        {
+          key: 'actions',
+          title: '操作',
+          render: (_, row) => <ActionMenu row={row} />,
+        },
+      ]}
+    />
+    <Pagination total={total} pageSize={20} />
+  </Card>
+</PageContainer>
+```
+
+### 7.2 ❌ 反例（典型 OpenTrek-style 误用）
+
+```tsx
+// ❌ 圆角太大（uni-manager 应 rounded-md = 2px，不是 lg = 4 / xl = 8）
+<Card className="rounded-xl shadow-lg p-6">
+  // ❌ 颜色硬编码
+  <h2 className="text-[#0064C8] text-2xl">云实例</h2>
+  // ❌ 表格行高过大（uni-manager 高密度应 36px，不是 56）
+  <table className="text-base">
+    <tr className="h-14">
+      // ❌ 状态用色块（违反 boundaries S8）
+      <td>
+        <span className="bg-green-100 text-green-800 px-2">运行中</span>
+      </td>
+    </tr>
+  </table>
+</Card>
+```
+
+---
+
+## 8. AI 生成自检（5 条）
+
+- [ ] 圆角是否锐利？（Card → `rounded-md`，控件 → `rounded-sm`）
+- [ ] 信息密度是否高？（表格 36-40px / 字段标签 12px）
+- [ ] 文案是否动词导向 + 简洁（按钮 ≤ 5 字 / 标题 ≤ 12 字）
+- [ ] 危险操作是否走"陈述句标题 + 动作动词按钮"
+- [ ] 没有任何颜色硬编码 / 不用 `*-500` 系列

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

@@ -0,0 +1,115 @@
+# 自检清单 · Uni-Manager
+
+> AI 生成 / 翻新页面后**必须**逐项对照本清单。规则细节看 [boundaries.md](./boundaries.md)，本文件只列"要检查什么"。
+>
+> **强制项（13）必须 100% 通过**；**建议项（7）至少 5 项通过**。
+
+---
+
+## 强制项（13）
+
+| #   | 检查点                                      | 失败示例                                                          | 通过条件                                                       | 规则            |
+| --- | ------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------- | --------------- |
+| 1   | 无硬编码色值                                | `bg-[#0064C8]` / `style={{color:'red'}}`                          | 走语义 token：`bg-primary` / `text-foreground`                 | [F1]            |
+| 2   | 状态不用原始色                              | `text-green-500` / `bg-red-100`                                   | `<Badge variant="success">` / `text-destructive`               | [S8]            |
+| 3   | 间距用 gap + 8 档刻度                       | `space-y-4` / `gap-7` / `p-2.5`                                   | `flex flex-col gap-4`；只用 1/2/3/4/5/6/8/12                   | [S2]            |
+| 4   | className 不覆盖组件颜色 / 字体             | `<Button className="bg-blue-500">`                                | `<Button variant="default">`                                   | [S1]            |
+| 5   | 复合组件结构完整                            | `<Dialog>` 缺 DialogTitle / `<Tabs>` 直接放 Trigger               | Dialog ≥ Title；Card ≥ Header+Content；Tabs 含 List；详见 C 组 | [C1-C12]        |
+| 6   | 状态 / 占位 / 分隔走专用组件                | 自定义 styled span 当 Badge / animate-pulse div                   | Badge / Skeleton / Empty / Separator / Alert / `toast()`       | [C7-C12]        |
+| 7   | 图标用 data-icon，不设尺寸类                | `<SearchIcon className="size-4 mr-2" />`                          | `<SearchIcon data-icon="inline-start" />`                      | [I1-I2]         |
+| 8   | 不手动 z-index / dark: 覆盖 / focus:ring-\* | `className="z-50"` / `focus:ring-2 ring-primary`                  | 让 scoped CSS 接管，不重复声明                                 | [S5][S7]        |
+| 9   | 条件类名用 cn()                             | `` `${active ? 'a' : 'b'}` ``                                     | `cn('base', active ? 'a' : 'b')`                               | [S6]            |
+| 10  | 危险操作二次确认（含输入资源名称）          | `<Button onClick={delete}>删除</Button>`                          | `<AlertDialog>` + 陈述句标题 + 影响列表（含云/区域）+ 输入名称 | P4 [philosophy] |
+| 11  | 可交互元素显式带手型                        | `<button onClick={...}>` 不带 `cursor-pointer`                    | `cursor-pointer` + `disabled:cursor-not-allowed`               | [ADR0023]       |
+| 12  | hover/focus 视觉反馈用 `enabled:` 前缀      | `hover:border-primary`（disabled 仍响应）                         | `enabled:hover:border-primary`                                 | [ADR0024]       |
+| 13  | 组件 Props 显式声明 + 中文 JSDoc            | `interface FooProps extends ComponentPropsWithoutRef<...>` 空透传 | 显式列出每个 prop + JSDoc                                      | [ADR0025]       |
+
+[F1]: ./boundaries.md
+[ADR0023]: ../../../../../docs/adr/0023-cursor-pointer-explicit-in-component-source.md
+[ADR0024]: ../../../../../docs/adr/0024-scoped-css-radix-state-conflict.md
+[ADR0025]: ../../../../../docs/adr/0025-component-props-explicit-declaration.md
+[S1]: ./boundaries.md
+[S2]: ./boundaries.md
+[S5]: ./boundaries.md
+[S6]: ./boundaries.md
+[S7]: ./boundaries.md
+[S8]: ./boundaries.md
+[C1-C12]: ./boundaries.md
+[C7-C12]: ./boundaries.md
+[I1-I2]: ./boundaries.md
+[philosophy]: ./philosophy.md
+
+---
+
+## 强制项（uni-manager 专有 — 一致性三件套）
+
+| #   | 检查点                                                 | 失败示例                         | 通过条件                                                                               | 规则               |
+| --- | ------------------------------------------------------ | -------------------------------- | -------------------------------------------------------------------------------------- | ------------------ |
+| UM1 | 全局 topbar 用 biz-ui 实物                             | 自建 `<header>` / `<nav>` 当顶栏 | `<UmTopbar />`（来自 `@teamix-evo/biz-ui/uni-manager`）                                | [UM1]              |
+| UM2 | PageHeader 一致（标题 24px / 面包屑紧贴 / 操作右对齐） | 自定义 h1 + flex 布局            | `<PageHeader title="..." breadcrumb={...} actions={...} />`                            | [UM2]              |
+| UM3 | 跨云资源标注 cloud-provider                            | 列表只有"实例 ID"无云厂商        | 表格必含 `cloud` 列 + `<CloudBadge provider={v} />`                                    | [UM3]              |
+| UM4 | 圆角档与组件类型匹配                                   | `<Input className="rounded-lg">` | Form 控件 `rounded-sm`（0px）/ Card `rounded-md`（2px）/ 大型 Card `rounded-lg`（4px） | [foundations §5]   |
+| UM5 | 表格行高高密度                                         | `rowHeight={56}`                 | 默认 36-40px                                                                           | [foundations §3.2] |
+
+[UM1]: ./boundaries.md#error-um1--全局-topbar-必须使用-um-topbar-实物-scope-uni-manager
+[UM2]: ./boundaries.md#error-um2--pageheader-必须保持一致性结构-scope-uni-manager
+[UM3]: ./boundaries.md#error-um3--跨云资源列表必须标注-cloud-provider-scope-uni-manager
+
+---
+
+## 建议项（7）
+
+- 💡 14. 列表页空数据有 `<Empty>` + 主操作入口（"创建第一个 X"）
+- 💡 15. 表单字段 > 6 时用 `<Card>` 分组或 Steps 分步
+- 💡 16. 按钮文案：动宾 ≤ 5 字（"创建实例"）；危险用明确名词 + 动作（"永久删除"）；不写"OK / 确认"
+- 💡 17. ID / Hash / 路径用 `font-mono` + 复制按钮
+- 💡 18. 操作 ≤ 200ms 反馈：loading / Toast / 状态变化
+- 💡 19. ContextSwitcher（租户/项目/区域）固定在 um-topbar
+- 💡 20. 详情页只读字段用 `density="detail"`（行距 12px）
+
+---
+
+## 自检报告模板
+
+```markdown
+## 自检报告 — <页面名>
+
+### 强制项（13/13 通过）✅
+
+- [x] 1. 无硬编码色值
+- [x] 2. 状态用 Badge / 语义 token
+- [x] 3. 间距用 gap + 8 档
+- [x] 4. className 不覆盖颜色
+- [x] 5. 复合组件结构完整
+- [x] 6. 专用组件
+- [x] 7. 图标 data-icon
+- [x] 8. 无 z-index / focus:ring-\*
+- [x] 9. 条件类名用 cn()
+- [x] 10. 危险操作二次确认
+- [x] 11. cursor-pointer 显式
+- [x] 12. enabled: 前缀
+- [x] 13. Props 显式声明
+
+### 一致性三件套（5/5 通过）✅
+
+- [x] UM1. UmTopbar
+- [x] UM2. PageHeader 一致
+- [x] UM3. cloud Badge
+- [x] UM4. 圆角档匹配
+- [x] UM5. 表格高密度
+
+### 建议项（5/7 通过）✅
+
+- [x] 14. 空状态
+- [x] 15. 字段分组
+- [x] 16. 按钮文案合规
+- [ ] 17. 长字符串 mono — 第 N 行 ID 未应用 font-mono
+- [x] 18. 操作反馈
+- [x] 19. ContextSwitcher
+- [ ] 20. detail density 未用
+
+### 修正建议
+
+- 第 N 行：`<span>{instance.id}</span>` → `<span className="font-mono">{instance.id}</span>` + `<CopyButton />`
+- DescriptionList 加 `density="detail"`
+```

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

@@ -0,0 +1,254 @@
+# Components — 选型决策与组合规则
+
+> **本文档只回答"用什么组件、怎么搭配"，不写具体 Props / Examples / import 路径。**
+> 组件 API、Props、示例代码通过 MCP `get_component_meta` 实时查询；可用列表通过 `list_components` / `find_components` 查询。
+
+---
+
+## 0. 组件查不到时的兜底铁律（最高优先）
+
+> **本节规则优先级高于本文件其余所有条款，违反此节即视为违反 reuse-first 原则（见 `teamix-evo-code-uni-manager/reuse-first.md`）。**
+
+### 0.1 触发场景
+
+调用 `list_components` / `find_components` 命中失败、或本文件提到的组件名（例如 `SearchCombo` / `ContextSwitcher` / `ItemCard` / `CardGrid` / `CardActionBar` / `CloudBadge`）在 `@teamix-evo/biz-ui/uni-manager` 中无实物时。
+
+### 0.2 三步处置法
+
+1. **不要自造同名组件入 `src/components/`** — 即使本文件提到该组件名，也必须先确认实物存在。
+2. **改用 `@teamix-evo/ui` 中语义近似的原子组件做最小拼装**（参见本文件 §3 决策树和 §5 拼凑配方）。
+3. **在响应中显式声明替代关系**，例如：
+
+   > `// SearchCombo 暂未实物化 → 用 Input + Select + Button 拼装`
+
+### 0.3 兜底优先序
+
+```text
+biz-ui/uni-manager 实物组件 (优先)
+  ↓ 未命中
+ui 原子组件最小拼装 (兜底)
+  ↓ 仍无法表达
+跳转 patterns/*.md 找页面级模板
+  ↓ 仍无法表达
+回报用户：缺组件 + 已尝试拼装方案
+```
+
+**永远不要**：
+
+- 在 `src/components/` 下新增与 biz-ui 同名的"私有版本"
+- 用 antd / arco / chakra 等其它库填补缺口
+- 在 skill 响应中写"假设 biz-ui 有 X"而不实查 MCP
+
+---
+
+## 1. 双层组件架构（实物归属）
+
+| 层级                                          | 来源                             | 实物清单（截至当前 variant）                                                                                                                                                                                                                                    |
+| --------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **业务扩展层（biz-ui，uni-manager variant）** | `@teamix-evo/biz-ui/uni-manager` | 当前 1 个实物：`um-topbar`（含 ContextSwitcher + Logo + 用户菜单 + 通知中心）。其余 `business/` 目录为文档草稿，**不可 import**。                                                                                                                               |
+| **ui 实现层（shadcn 原子）**                  | `@teamix-evo/ui`                 | ≈ 89 个原子/复合组件。包含 **PageHeader / Pagination / Steps / Tabs / Tooltip / DataTable / FilterBar / Combobox(=command) / AutoComplete / DatePicker / Drawer / Sheet / Dialog / AlertDialog / Card / Badge / Tag / Alert / Toast(sonner) / Form** 等高频件。 |
+
+### 1.1 选型铁律
+
+1. **优先 biz-ui/uni-manager 实物层** — 已封装变体 + 文案规范，但**注意 uni-manager 当前仅 1 个实物**。
+2. **biz-ui 无实物 → ui 实现层** — 89 个原子件覆盖绝大部分场景。
+3. **ui 仍无 → §5 拼凑配方** — 用 ui 多个原子件最小组合（不私造）。
+4. **禁止**自造同名组件（违反 reuse-first，详见 §0）。
+
+### 1.2 实时校验
+
+任何组件名引用前必须用 `find_components(name)` 验证存在性，**不要相信本文档中"组件名"的存在性默认**（biz-ui 处于持续物化中）。
+
+---
+
+## 2. 必备组件 — 每个页面都需要
+
+| 组件           | 实际归属           | 何时使用                   | 备注                                                                                   |
+| -------------- | ------------------ | -------------------------- | -------------------------------------------------------------------------------------- |
+| **um-topbar**  | biz-ui/uni-manager | **所有页面必需**（全局壳） | 含 ContextSwitcher（租户/项目/区域）+ Logo + 用户菜单 + 通知。详见 boundaries.md UM1。 |
+| **PageHeader** | ui                 | 所有页面必需               | L1 用 title 模式、L2 用 breadcrumb 模式（二选一，不并存）。详见 boundaries.md UM2。    |
+| **Sidebar**    | ui                 | TWO_COL 布局必需           | 768px 以下自动折叠为抽屉                                                               |
+| **Button**     | ui                 | 所有交互页面               | 主操作 ≤ 1 个（Primary）；次要 Secondary；危险 Destructive                             |
+
+> uni-manager 与 opentrek 的关键差异：**全局壳是 `um-topbar`**（横向顶栏 + Sidebar），而非 opentrek 的 `op-sidebar`（纵向单栏）。
+
+---
+
+## 3. 选型决策树
+
+### 3.1 反馈与确认 — Dialog vs Sheet vs Drawer vs Popover
+
+```text
+需要用户做出决定 / 阻塞主流程？
+├─ 是 → 用 Dialog
+│   ├─ 简单确认（删除/退出）→ AlertDialog
+│   └─ 复杂表单（< 8 字段）→ Dialog
+└─ 否
+    ├─ 临时编辑/筛选（侧边滑出）→ Sheet
+    ├─ 多级下探查看（侧边可叠层）→ Drawer
+    ├─ 内容预览/上下文操作（小气泡）→ Popover
+    └─ 仅展示信息（鼠标悬浮）→ Tooltip
+```
+
+**容量决策**：
+
+- 字段 ≥ 8 个 / 内容超过 1 屏 → **跳转 FormPage**（不要塞进 Dialog）
+- 字段 4~8 个 → Sheet（侧边可保留上下文）
+- 字段 ≤ 4 个 → Dialog
+- **任务层级 ≤ 3 层**（Teamix-UI 容器规范）— 超过则强制跳页
+
+### 3.2 容器选型 — 操作型 vs 展示型
+
+> 来源：Teamix-UI 容器规范（doc 10）。
+
+| 类别       | 容器                                     | 何时使用                                         |
+| ---------- | ---------------------------------------- | ------------------------------------------------ |
+| **操作型** | 全页面（FormPage）                       | 字段多 / 步骤多 / 需要持久 URL                   |
+| **操作型** | 弹窗模态（Dialog）                       | 阻塞主流程的简短确认或表单；最多 2 级，不再深入  |
+| **操作型** | 气泡（Popconfirm）                       | 二次确认（删除/解绑），轻量提示                  |
+| **展示型** | 全页面（DetailPage）                     | 完整信息查看，路由可分享                         |
+| **展示型** | 抽屉非模态（Sheet）                      | 不阻塞主流程，可保留上下文（如侧栏 Detail）      |
+| **展示型** | 抽屉模态（Drawer）                       | 多级下探查看（如资源 → 子资源 → 配置），逐层推出 |
+| **展示型** | 弹窗模态（Dialog）                       | 一次性展示重要信息                               |
+| **展示型** | 卡片（Card）                             | 同级信息分组；卡片之间间距 16px                  |
+| **展示型** | 通知反馈（Toast / Alert / Notification） | 瞬时反馈 / 页面级横幅 / 系统通知                 |
+
+### 3.3 状态展示 — Badge vs Tag vs Alert
+
+| 组件               | 用途                             | 容器                |
+| ------------------ | -------------------------------- | ------------------- |
+| **Badge**          | 状态标记（运行中/已停止/异常）   | 表格列、详情字段    |
+| **Tag**            | 业务分类（标签、关键字）         | 多个并列时使用      |
+| **Alert**          | 页面级提示（操作结果、系统通知） | 页面顶部、Form 顶部 |
+| **Toast / Sonner** | 瞬时反馈（保存成功）             | 全局浮层            |
+
+**铁律**：状态颜色用 `<Badge variant="success|warning|destructive|info">` 而非 `bg-green-100`（boundaries.md S8）。
+
+### 3.4 数据展示 — Table vs DataTable vs Card vs List
+
+```text
+数据量 ≤ 50 / 列数 ≤ 6 → Table
+数据量 > 50 / 列数 > 6 → DataTable（含虚拟滚动 + 排序 + 列控制）
+卡片化展示（含图片/丰富信息）→ Card[] + Grid 拼装
+简单单列列表 → 普通 div + map（不必造组件）
+```
+
+**列上限**：建议表格 ≤ 6 列，超过用 DataTable 的列控制。
+**uni-manager 默认行高**：36-40px（高密度），不允许 ≥ 56px。
+
+### 3.5 导航 — Tabs vs Sidebar vs Breadcrumb vs Steps vs Topbar
+
+| 场景                | 组件                                 | 归属               |
+| ------------------- | ------------------------------------ | ------------------ |
+| 全局顶部壳层        | **um-topbar**                        | biz-ui/uni-manager |
+| 详情页内子模块切换  | **Tabs**                             | ui                 |
+| 同级页面切换        | **Sidebar**                          | ui                 |
+| 父子页面层级        | **Breadcrumb**（由 PageHeader 内置） | ui                 |
+| 多步流程            | **Steps**                            | ui                 |
+| 步骤数 ≤ 3 且无依赖 | 不用 Steps，用单页 Form              | —                  |
+
+### 3.6 输入控件 — Input vs Select vs Combobox
+
+```text
+枚举值 ≤ 7 → RadioGroup（一屏可见）
+枚举值 8~30 → Select
+枚举值 > 30 / 需搜索 → Combobox（= ui command）
+多选 → MultiSelect / Checkbox
+日期 → DatePicker / DateRangePicker
+富文本 → Textarea / RichEditor
+文件 → Upload
+自动补全 → AutoComplete
+```
+
+---
+
+## 4. 复合组件结构铁律
+
+> **完整规则在 `boundaries.md` C1-C12，此处仅列高频项**
+
+| 组件       | 必备子结构                                                          | 缺失后果           |
+| ---------- | ------------------------------------------------------------------- | ------------------ |
+| **Dialog** | `DialogHeader > DialogTitle` 必须存在                               | 屏幕阅读器无法识别 |
+| **Sheet**  | `SheetHeader > SheetTitle` 必须存在                                 | 同上               |
+| **Form**   | `FormField > FormItem > FormLabel + FormControl + FormMessage` 全套 | 无错误提示渲染     |
+| **Tabs**   | `TabsTrigger` 必须在 `TabsList` 内                                  | 渲染异常           |
+| **Select** | `SelectTrigger > SelectValue` + `SelectContent > SelectItem`        | 无法触发           |
+| **Card**   | `CardHeader > CardTitle` + `CardContent`                            | 字号 / 间距错乱    |
+
+---
+
+## 5. 业务扩展层（候补）— 实物 vs 概念 + 拼凑配方
+
+> uni-manager variant 当前**只有 1 个**实物业务组件：`um-topbar`。
+> 以下表格区分"已实物化"与"概念占位（用 ui 拼装）"。
+
+### 5.1 已实物化（直接使用）
+
+| 组件          | 用途                                                              | 归属               |
+| ------------- | ----------------------------------------------------------------- | ------------------ |
+| **um-topbar** | 全局顶部壳层（ContextSwitcher + Logo + UserMenu + Notifications） | biz-ui/uni-manager |
+
+### 5.2 概念占位（按配方拼装）
+
+> 这些是 design 语义概念，**不是**可 import 的组件。出现下表名称时按"拼装配方"使用 ui 原子件。
+
+| 概念                | 拼装配方（ui 原子件）                                                                     | 触发场景                          |
+| ------------------- | ----------------------------------------------------------------------------------------- | --------------------------------- |
+| **SearchCombo**     | `Input + Select + Button` 或直接用 `filter-bar`                                           | 列表页头部筛选 + 搜索             |
+| **ContextSwitcher** | `dropdown-menu + avatar`（顶部）或 `command + popover`（带搜索） — **已内置于 um-topbar** | 多租户 / 多项目 / 多区域切换      |
+| **CloudBadge**      | `badge` + 云厂商 icon + provider 名（用 cn() 控制不同 provider 配色）                     | 多云资源列表标注 cloud-provider   |
+| **ItemCard**        | `card`（CardHeader + CardContent + CardFooter）                                           | 卡片化数据项                      |
+| **CardGrid**        | `grid` + `card[]`（Tailwind grid-cols-N + gap-4）                                         | 卡片网格列表                      |
+| **CardActionBar**   | `card` 的 Footer 内放 `button[]`（主 + 次 + 危险）                                        | 卡片底部操作区                    |
+| **BulkActionBar**   | `sheet` 底部固定 + `checkbox-group selected count` + `button[]`                           | 列表页批量操作浮动栏              |
+| **OperationLog**    | `table` + `time` 列 + `actor` 列 + `action` 列 + `target` 列                              | 任意页面"最近操作"侧栏 / Tab 内容 |
+
+**使用要求**：
+
+- 拼装时遵守 §3 决策树和 `boundaries.md` 复合结构铁律（C1-C12）。
+- 拼装代码中必须加注释 `// {Concept} 暂未实物化 → ui 原子件拼装`。
+- 严禁在 `src/components/` 下新建同名文件"沉淀"该拼装，否则违反 §0 兜底铁律。
+
+---
+
+## 6. 图标 (Icons)
+
+> **完整规则见 [`boundaries.md` I1-I4](./boundaries.md#i1-i4--图标规则)** — I1 data-icon 定位、I2 不设尺寸类、I3 作为组件对象传递、I4 按 iconLibrary 导入。
+
+仅补充组件选型相关：
+
+- **状态图标**统一选用 lucide-react 的 Check / X / AlertTriangle / Info（成功 / 失败 / 警告 / 信息）
+- **云厂商图标**走 CloudBadge 内置（不直接 import 厂商 SVG，避免商标合规问题）
+
+---
+
+## 7. 与 MCP 工具的协作
+
+```text
+当 AI 决定使用某组件后：
+  ├── 通过 list_components({ status: "stable" }) 确认组件可用
+  ├── 通过 get_component_meta("dialog") 获取：
+  │     - Props 完整签名（required / optional / default）
+  │     - 子组件层级（DialogHeader/Footer/Title/...）
+  │     - 标准用法 Example
+  │     - 常见错误（compositionPitfalls）
+  ├── 通过 find_components("filter") 模糊搜索（不确定名称时）
+  └── 通过 tokens_get() 获取最新 token 别名（颜色/间距/圆角）
+```
+
+**约束**：在 skill 中**不写**具体 import 路径与 Props 示例 —— 这些由 MCP runtime 提供。
+
+---
+
+## 8. 选型自检
+
+通用结构性规则 → 见 [checklist.md](./checklist.md)（C1-C12 / I1-I4 / UM1-UM3）。本文件特有的"选型决策"自检：
+
+- [ ] 已先用 `find_components` 验证组件存在性（不靠默认）
+- [ ] biz-ui/uni-manager 命中失败 → 改用 ui 原子件，按 §5.2 配方拼装并加注释
+- [ ] 反馈 / 确认场景按容量选 Dialog / Sheet / Drawer / Popover
+- [ ] 容器层级 ≤ 3，弹窗最多 2 级，超过则跳转全页面
+- [ ] 全局壳层使用 `um-topbar`（boundaries.md UM1）
+- [ ] 跨云资源列表必含 cloud Badge 列（boundaries.md UM3）
+- [ ] 表格 ≤ 6 列、行高 36-40px，超过列数改 DataTable + 列控制
+- [ ] 不存在的组件**绝不**自造，**绝不**写"假设有 X"

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

@@ -0,0 +1,63 @@
+# Flows — 用户旅程
+
+> **页间流转视图见 [`patterns/page-types.md §6 页间流转`](./patterns/page-types.md#6-页间流转)** — 包含后台主流转图、流转设计规则、资源生命周期、CRUD 流转速查。本文档承载"五条核心用户旅程"的编织视角（含云管平台特有的"上下文切换"）。
+
+---
+
+## 1. 五条核心旅程速查 + 设计要点
+
+### A · 资源查找与操作
+
+`Sidebar → ListPage(SearchCombo + 多云筛选) → 行内操作 → 反馈(Toast / AlertDialog → Toast) → 状态自动刷新`
+
+- 搜索框必须保留焦点
+- cloud-provider Badge 必须出现在每行
+- 危险操作的 AlertDialog 必须列出**资源标识**（含云厂商 + 区域 + ID）与**影响范围**
+
+### B · 资源创建
+
+`ListPage → FormPage(分组 + 实时校验) → 提交 → 列表(顶部)`
+
+- blur 校验单字段，submit 校验全部
+- 失败**不清空表单**，错误定位到字段
+- 长表单（> 10 字段）必须有"保存草稿"
+- 创建成功落点优先返回列表，编辑成功优先停留原页
+- 涉及跨云 / 跨区域字段时，区域选择必须先行（影响后续字段可选项）
+
+### C · 异常处理
+
+`Dashboard(StatCard) → ListPage(?status=error) → DetailPage(明细+日志) → AlertDialog 修复 → Toast`
+
+- 异常数字必须是**可点击的钻取入口**
+- LogViewer 默认定位到异常时间点 ± 5 分钟
+- 修复操作必须显示**预期影响范围**
+
+### D · 批量操作
+
+`Checkbox 选 → BulkActionBar → AlertDialog(列出受影响资源) → 进度 → Toast(成功 N / 失败 M)`
+
+- BulkActionBar 浮动在表格底部
+- AlertDialog 必须列出至少前 5 条受影响资源（含云厂商 + 区域）
+- 部分失败时，失败项显示"重试"按钮
+
+### E · 上下文切换（uni-manager 专有）
+
+`um-topbar(ContextSwitcher) → 切租户/项目/区域 → 全局确认 → 当前页面数据自动刷新`
+
+- 切换器位于 um-topbar 固定位置（左上 logo 右侧），全局可达
+- 切换跨"管理租户"维度时（影响权限范围）必须 **AlertDialog 二次确认**
+- 切换后所有列表 / 详情页数据自动刷新；URL Params 中的 tenantId/regionId 同步更新
+- 切换前如有未保存表单，弹"未保存内容将丢失"Dialog
+
+---
+
+## 2. 流转自检
+
+- [ ] 任意页面都能通过面包屑 / Esc 返回上一级
+- [ ] ListPage 的筛选条件持久化到 URL Params（含 tenantId / regionId）
+- [ ] FormPage 未保存离开有 Dialog 确认
+- [ ] 危险操作的 Dialog 列出影响范围与资源清单（含云厂商 + 区域）
+- [ ] 成功 / 失败页面都有"下一步"按钮（无死胡同）
+- [ ] 批量操作进度可见、部分失败可重试
+- [ ] 异常数字是可点击的钻取入口（Dashboard → ListPage 预筛选）
+- [ ] 上下文切换后所有页面数据自动刷新；URL 同步