@loom-framework/core 0.1.0-alpha.80 → 0.1.0-alpha.82

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loom-framework/core",
-  "version": "0.1.0-alpha.80",
+  "version": "0.1.0-alpha.82",
   "description": "Loom framework - DataAdapter, Capability Generator, config system, backend server, CLI",
   "type": "module",
   "main": "./dist/index.js",

package/templates/loom-skill/SKILL.md

@@ -41,7 +41,7 @@ npx -p @loom-framework/core loom init <name> --description <desc> --adapter <fil
 loom generate page <Name> --model <model-name>
 ```
 
-此命令自动生成：CRUD 页面（含 AI 按钮）、App.tsx 路由接线、后端 API、应用 Skill。数据实体立即可通过 `loom data` CLI 和 AI 对话使用。
+此命令自动生成：CRUD 页面（含 AI 按钮）、App.tsx 路由接线、后端 API、应用 Skill。模型立即可通过 `loom data` CLI 和 AI 对话使用。
 
 ### 4. 补充应用 Skill 描述（必须）
 
@@ -66,7 +66,7 @@ loom dev
 
 ### 迭代：修改配置 → 重新生成
 
-编辑 `loom.config.ts`（添加/修改数据实体或 AI 按钮）→ 重新执行步骤 3。
+编辑 `loom.config.ts`（添加/修改模型或 AI 按钮）→ 重新执行步骤 3。
 
 ### 可选：添加更多 Skill
 
@@ -82,6 +82,7 @@ loom dev
 | `loom dev` | 启动开发环境（`--skip-generate` `--backend-only` `--frontend-only`） |
 | `loom build` | 生产构建 |
 | `loom generate page <name> --model <model>` | 生成 CRUD 页面 + 应用 Skill（含 aiButtons 则自动集成） |
+| `loom generate dashboard <name>` | 从 dashboard.config.json 生成 Dashboard 数据概览页面 |
 | `loom generate capabilities` | 仅重新生成应用 Skill 的 `references/models.md` |
 | `loom generate skill <name>` | 生成自定义 Skill 脚手架 |
 
@@ -119,12 +120,24 @@ export default defineConfig({
     id: 'analyze',            // 带变量的示例
     label: '分析',
     prompt: '分析{{questionContent}}，错误答案：{{wrongAnswer}}',
-    placement: 'wrong_questions',  // 可选：限制按钮只出现在指定数据实体的页面，逗号分隔多个实体名；省略则出现在所有页面
+    placement: 'wrong_questions',  // 可选：限制按钮只出现在指定模型页面，逗号分隔多个模型名；省略则出现在所有页面
   }],
 });
 ```
 
-高级配置（`ai.claudeCode`、`server`、各数据实体的 `adapters`、`indexes`）见 `references/data-model.md`。
+高级配置（`ai.claudeCode`、`server`、按模型 `adapters`、`indexes`）见 `references/data-model.md`。
+
+### 可选：生成 Dashboard（数据概览页面）
+
+Dashboard 采用**两阶段**工作流：AI 生成 `dashboard.config.json` → 用户审查后执行 `loom generate dashboard <name>` 生成页面。
+
+```bash
+# 阶段 1：AI 生成配置（详见 references/dashboard.md）
+# 阶段 2：
+loom generate dashboard <name>
+```
+
+详细的配置 Schema、图表类型说明和示例见 **references/dashboard.md**。
 
 ## API 路由格式
 

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

@@ -0,0 +1,161 @@
+# 生成 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' }],
+}} />
+```