@loom-framework/core 0.1.0-alpha.83 → 0.1.0-alpha.85

package/templates/loom-skill/references/dashboard.md

@@ -1,161 +0,0 @@
-# 生成 Dashboard（数据概览页面）
-
-Dashboard 采用**两阶段**工作流：AI 设计配置 → 代码生成页面。
-
-## 阶段 1：生成 dashboard.config.json
-
-根据项目的 `loom.config.ts` 中的数据模型，站在用户角度设计 Dashboard，生成 `dashboard.config.json` 到项目根目录。
-
-**设计原则：**
-- 统计卡片放第一行（一眼看到关键数字）
-- 分布图表按业务重要性排列
-- 趋势图放最后一行（需要更多空间）
-- 每行不超过 4 个元素
-- 标题用业务语言，不用字段名
-
-### 配置 Schema
-
-```jsonc
-{
-  "name": "overview",           // 必填：Dashboard 标识（同模型命名规则）
-  "description": "数据概览",     // 可选：侧边栏展示名
-  "models": ["model_a", "model_b"],  // 必填：关联的数据模型名列表
-  "layout": [                    // 必填：布局定义，数组每项代表一行
-    {
-      "row": [                   // 每行包含一组 widget
-        {
-          "type": "stat",        // 图表类型，见下方图表类型表
-          "title": "总数",       // 业务语言标题
-          "model": "model_a",   // 数据模型名
-          "span": 6,            // 可选：Col 宽度（1-24），省略则自动均分
-          "aggregate": "count", // 可选：count|sum|avg|min|max（默认 count）
-          "field": "score",     // aggregate 非 count 时必填：数值字段名
-          "filter": { "status": "active" },  // 可选：聚合前筛选条件
-          "groupBy": "category", // 可选：分组字段
-          "interval": "month"   // 可选：date 字段分组粒度 day|week|month（默认 month）
-        }
-      ]
-    }
-  ]
-}
-```
-
-### 图表类型与数据需求
-
-#### 数值类
-
-| type | 需要 groupBy | 需要 field | 需要 interval | 生成效果 |
-|------|-------------|-----------|--------------|---------|
-| `stat` | 否 | aggregate=avg/sum 时需要 | 否 | Ant Design Statistic 数值卡片 |
-| `gauge` | 否 | 是（0-1 之间的进度值） | 否 | G2 仪表盘（进度/达标率） |
-| `liquid` | 否 | 是（0-1 之间的进度值） | 否 | G2 水波图（百分比/进度） |
-
-#### 占比类
-
-| type | 需要 groupBy | 需要 field | 需要 interval | 生成效果 |
-|------|-------------|-----------|--------------|---------|
-| `pie` | 是（enum/string 字段） | 否 | 否 | G2 饼图（分布占比） |
-| `ring` | 是（boolean/enum 字段） | 否 | 否 | G2 环形图（占比对比） |
-| `treemap` | 是（多层级字段） | 否 | 否 | G2 矩形树图（层级占比） |
-
-#### 对比类
-
-| type | 需要 groupBy | 需要 field | 需要 interval | 生成效果 |
-|------|-------------|-----------|--------------|---------|
-| `bar` | 是 | 否 | 否 | G2 条形图（横向分类对比） |
-| `stacked_bar` | 是 | 否 | 否 | G2 堆叠条形图（组成+对比） |
-| `grouped_bar` | 是 | 否 | 否 | G2 分组条形图（并列对比） |
-| `radar` | 是 | 否 | 否 | G2 雷达图（多维度对比） |
-| `funnel` | 是 | 否 | 否 | G2 漏斗图（阶段转化） |
-
-#### 趋势类
-
-| type | 需要 groupBy | 需要 field | 需要 interval | 生成效果 |
-|------|-------------|-----------|--------------|---------|
-| `line` | 是（推荐 date 字段） | 否 | 是 | G2 折线图（时间趋势） |
-| `area` | 是（推荐 date 字段） | 否 | 是 | G2 面积图（累计趋势） |
-
-#### 分布类
-
-| type | 需要 groupBy | 需要 field | 需要 interval | 生成效果 |
-|------|-------------|-----------|--------------|---------|
-| `scatter` | 是 | 否 | 否 | G2 散点图（相关性/分布） |
-| `heatmap` | 是 | 是（数值） | 否 | G2 热力图（密度/交叉分析） |
-
-## 阶段 2：执行 generate dashboard
-
-用户审查 `dashboard.config.json` 后，运行命令生成页面：
-
-```bash
-loom generate dashboard <name>
-```
-
-此命令会：
-1. 读取并校验 `dashboard.config.json`
-2. 验证引用的模型是否存在于 `loom.config.ts`
-3. 生成 Dashboard TSX 页面（含 `useData` + `useChartData` + `DashboardChart`）
-4. 自动接线 App.tsx（添加 import、navItem、switch case）
-5. 检测 `@antv/g2` 是否已安装，未安装则提示
-
-**前置依赖：** Dashboard 使用 @antv/g2 渲染图表，需在 frontend 目录安装：
-
-```bash
-cd frontend && pnpm add @antv/g2
-```
-
-## 完整配置示例
-
-以小学生错题管理平台为例：
-
-```json
-{
-  "name": "overview",
-  "description": "错题数据概览",
-  "models": ["wrong_questions", "review_plans"],
-  "layout": [
-    {
-      "row": [
-        { "type": "stat", "title": "错题总数", "model": "wrong_questions", "aggregate": "count" },
-        { "type": "stat", "title": "已掌握", "model": "wrong_questions", "aggregate": "count", "filter": { "isMastered": true } },
-        { "type": "stat", "title": "待攻克", "model": "wrong_questions", "aggregate": "count", "filter": { "isMastered": false } },
-        { "type": "gauge", "title": "掌握率", "model": "wrong_questions", "aggregate": "count", "field": "reviewCount" }
-      ]
-    },
-    {
-      "row": [
-        { "type": "pie", "title": "科目分布", "model": "wrong_questions", "groupBy": "subject", "span": 8 },
-        { "type": "bar", "title": "错误类型分布", "model": "wrong_questions", "groupBy": "errorType", "span": 8 },
-        { "type": "ring", "title": "难度分布", "model": "wrong_questions", "groupBy": "difficulty", "span": 8 }
-      ]
-    },
-    {
-      "row": [
-        { "type": "radar", "title": "各科目掌握概览", "model": "wrong_questions", "groupBy": "subject", "span": 8 },
-        { "type": "line", "title": "错题录入趋势", "model": "wrong_questions", "groupBy": "createdAt", "interval": "month", "span": 16 }
-      ]
-    }
-  ]
-}
-```
-
-## 追加自定义图表
-
-生成后的 Dashboard 页面是普通 TSX，可直接编辑追加图表：
-
-1. 使用 `useChartData` 准备数据（或自定义聚合逻辑）
-2. 使用 `/antv-g2-chart` skill 生成 G2 v5 Spec 代码
-3. 添加 `<DashboardChart spec={...} />` 组件
-
-示例——追加一个科目×年级的堆叠柱状图：
-
-```tsx
-// 在已有的 Dashboard 页面中追加
-const subjectGradeData = useChartData(wrongQuestionsList, { groupBy: 'subject' });
-
-<DashboardChart spec={{
-  type: 'interval',
-  data: subjectGradeData,
-  encode: { x: 'name', y: 'value', color: 'name' },
-  transform: [{ type: 'stackY' }],
-}} />
-```