jimubi-dashboard

# JeecgBoot 仪表盘 AI 自动生成器 将自然语言的仪表盘需求转换为 drag page 配置，并通过 API 自动创建。 > **本 skill 专门处理仪表盘（default）模式**：网格布局（24列栅格），亮色主题，带卡片头，适用于日常数据看板。 > 大屏请使用 `jimubi-bigscreen` skill。 ## ⚠️ 强制规则：所有仪表盘相关操作必须优先通过本 skill 处理（无任何例外） **触发范围**：凡涉及仪表盘的任何操作，包括但不限于： - 创建/删除/修改仪表盘页面 - 添加/编辑/删除组件 - 数据集（SQL/API/文件/WebSocket）的创建与绑定 - 数据源的创建、编辑、测试（包括修改用户名、密码、连接参数等） - 模板复制、页面配置修改 - 组件联动、钻取、外部链接 **禁止行为**： - 未调用本 skill，直接读 memory 找凭据自行执行 - 未调用本 skill，自己探索 API 路径后直接调用 - 以"操作太简单不需要 skill"为由跳过 - **用 curl/bash/Agent 子代理探测仪表盘 API 端点**（正确做法：先调用本 skill，再在 skill 上下文内执行） **正确执行顺序**： 1. 用户提出仪表盘相关需求 2. **第一步必须调用本 skill**（`Skill jimubi-dashboard`） 3. 在 skill 上下文中读取凭据、选择脚本、执行操作 ## 按需加载指南 本 skill 采用分层加载：核心规则始终在上下文中，专题文档按需读取。 | 场景 | 读取文件 | |------|---------| | 需要示例/演示数据（用户未提供数据源）| `references/api-dataset-examples.md`（92条公开 mock API，按行业分类，直接用 `dataset_ops.py create-api` 创建） | | 创建/绑定/修改数据集（SQL/API/文件）| `references/dataset-guide.md`（**仅自定义脚本时需要**；使用预置脚本时**无需读取**） | | **多文件数据集（FILES）+ 图表** | 直接用 `files_ops.py create-bind`（**无需 Write 脚本**） | | 创建 WebSocket 数据集 | `references/dataset-guide.md`「创建 WebSocket 数据集」章节 | | **创建 JSON 数据集 + 图表** | 无需读文档；规则已内联：`dataType:'json'`，数据放 `querySql`（**禁止放 content**），无需 dbSource/queryFieldBySql，直接 `_request POST /add` + `batch-add --specs` 绑定 | | **多图表+联动批量生成**（≥2个图表且需要联动） | 直接用 `multi_chart_linkage.py` | | 从模板复制创建仪表盘 | 直接用 `template_ops.py copy` | | 模板复制遇到问题时 | `references/template-copy-guide.md` | | 地图组件（JAreaMap 等）| `references/map-guide.md` + 静态数据用 `references/map-static-data.md` | | 创建数据源 + SQL数据集 + 图表 | `datasource_ops.py create` 创建数据源 → `dataset_ops.py create-sql` 创建数据集 → `comp_ops.py batch-add --specs` 绑定图表（在每个 spec 的 `"config"` 中传入 `dataType:2/dataSetId/dataMapping` 即可，视觉配置由 `default_configs.json` 自动提供）。**仅当 SQL 含 FreeMarker / 需要 queryFieldBySql 回写时，才需写全流程自定义脚本。** | | 自写 Java API 接口 + API 数据集 + 批量图表 | 参考 `references/pitfalls.md`「完整工作流：自写API接口」章节 | | **YApi Mock 系统 + API 数据集** | 直接用 `yapi_ops.py create-mock`（固定项目：**proj_id=57，catid=1157，basepath=/claude**） | | 签名接口 / 数据源管理 / NoSQL 数据源 | `references/signing-datasource-guide.md` | | 组件联动 / 钻取 | 直接用 `linkage_ops.py` | | 组件外部链接跳转 | 直接用 `link_ops.py` | | 字典翻译（jimu_dict） | `references/dict-guide.md` | | 修改页面配置（背景色/背景图/风格/组件主题）| `references/page-config-guide.md`（**仪表盘无水印功能**，水印仅大屏专有） | | 遇到奇怪问题时查阅 | `references/pitfalls.md` | | 组件样式配置路径 | `references/bi-comp-option-config.md`（**仅当 skill.md 中未列出目标组件时才读取**；JStatsSummary/JCapsuleChart/JGauge/JProgress/JScrollBoard/JNumber 已内联在「常用组件配置路径速查」章节） | | 完整组件类型清单 | `references/bi-component-types.md`（已内联在「图表查询与推荐」章节，一般无需再读取） | | 新增组件默认尺寸/数据/option | `references/core-configs/component-defaults.md` | | Online表单/设计器表单生成图表（dataType:4）| `references/online-design-form-chart-guide.md` | | **bi_utils 初始化 / 字段访问规则** | 已内联在「bi_utils 使用规则（强制）」章节，**无需读取外部文件** | | **comp_ops.py 参数与数据绑定格式** | 已内联在「快捷操作：comp_ops.py」章节，**无需读取外部文件** | | **linkage_ops.py 联动/钻取命令** | 已内联在「快捷操作：linkage_ops.py」章节，**无需读取外部文件** | | **link_ops.py 外部链接 + 自定义JS** | 已内联在「快捷操作：link_ops.py」章节，**无需读取外部文件** | | 踩坑速查 | 已内联在「核心踩坑速查」章节（~45条），**优先查此处**；极端复杂场景再读 `references/pitfalls.md` | | 图库（图标/图片）管理 | 已内联在「图库管理」章节，**无需读取外部文件** | ## SQL数据集创建标准流程（强制） > **触发条件**：用户说"使用SQL数据集"、"增加SQL数据集"、"统计 xxx 表"、"生成图表"等涉及 SQL 数据集的任何场景，必须严格按以下四步执行，**不得跳过第1步**。 ### 第1步：确认数据源（必须询问，禁止擅自选择，无任何例外） > ⚠️ **无论使用任何方式创建 SQL 数据集，都必须先询问数据源，禁止直接执行。** **执行步骤（强制）：** 1. 先运行以下命令列出所有可用数据源 2. 向用户展示列表，询问"请问使用哪个数据源？" 3. 等待用户选择后，用选定的数据源 ID 继续执行 ```bash SKILL_REFS="$HOME/.claude/skills/jimubi-dashboard/references" PYTHONIOENCODING=utf-8 PYTHONPATH="$SKILL_REFS:$SKILL_REFS/scripts" py "$SKILL_REFS/scripts/datasource_ops.py" list "<api_base>" "TOKEN" ``` ### 第2步：根据业务场景自行编写SQL - 用户指定数据源后，根据用户描述的业务场景，自行设计并编写合适的 SQL 语句 - **🚨 comp_ops.py add/batch-add 不支持 `--create-sql`/`--sql-file`/`--ds-name`/`--db-source`**，这些参数不存在，使用会报 `unrecognized arguments` - **推荐方式（普通SQL，无 FreeMarker 动态条件）**：`dataset_ops.py create-sql` 创建数据集，再用 `comp_ops.py batch-add --specs` 绑定图表；每个 spec 的 `"config"` 字段只需传 `dataType/dataSetId/dataMapping` 等数据绑定字段，视觉配置自动从 `default_configs.json` 取 - **全流程自定义脚本（仅限以下场景）**：SQL 含 FreeMarker 动态参数（`<#if>`/`${}`）、需要 queryFieldBySql 自动回写字段、或需要在同一脚本内串联复杂逻辑时，才用 Write 工具写入 Python 脚本执行（详见下方"全流程自定义脚本模板"章节） - **⚠️ "singleFile" 是文件数据集的 dataType 值**（`dataType: 'singleFile'`，上传 Excel/CSV），与 SQL 数据集脚本模式无关，禁止把 SQL 场景的自定义脚本称为"singleFile 脚本" ### 第3步：创建SQL数据集 - 分组必须使用 **"示例数据集"**（`dataset_ops.py create-sql` 已内置 `--group "示例数据集"` 默认值） ```bash SKILL_REFS="$HOME/.claude/skills/jimubi-dashboard/references" PYTHONIOENCODING=utf-8 PYTHONPATH="$SKILL_REFS:$SKILL_REFS/scripts" py "$SKILL_REFS/scripts/dataset_ops.py" create-sql $API_BASE $TOKEN \ --name "数据集名称" --db-source "数据源ID" \ --sql "SELECT name, value FROM table GROUP BY name" \ --fields "name:String,value:Integer" ``` - 数据集创建完成后，**必须执行查询解析验证**确认数据正常返回 ### 第4步：后续绑定操作（按需） - 询问用户是否需要将数据集绑定到图表组件 - 如需要，优先使用 `dataset_ops.py create-sql` + `comp_ops.py batch-add --specs` 组合；仅当场景复杂（FreeMarker/需字段回写）时才写全流程自定义脚本 --- ## 执行效率规则（强制） ### 简单操作直接执行，禁止多余探索 **对所有仪表盘操作，必须跳过以下步骤直接执行：** - 禁止启动 Explore 子代理去探索源码 - 禁止启动子代理去读 data.ts 默认配置（skill 文档已包含完整信息） - 禁止读取 template-copy-guide.md（template_ops.py copy 已实现全部流程） - 禁止使用预置脚本时读取 dataset-guide.md（`dataset_ops.py`/`comp_ops.py --dataset-name` 已封装全部逻辑） - 禁止执行预置脚本前先 `--help` 查看用法（skill 文档已包含完整参数说明） - 禁止展示设计摘要等待确认（除非用户明确要求确认） **耗时目标：** | 操作类型 | 目标耗时 | 做法 | |---------|---------|------| | 单组件增/删/改/查 | ≤30s | comp_ops.py 一条命令（SKILL_REFS + 全路径执行，1轮完成） | | 数据集 + 单组件 | ≤60s | singleFile 脚本（7步完整流程：/add → queryFieldBySql → /edit → getAllChartData → config → append → save_page） | | 复合操作（数据集 + 多组件） | ≤60s | 并行 Bash 调用 | | 模板复制创建仪表盘 | ≤60s | template_ops.py copy | | 多图表+联动（≥2图+联动） | ≤10s | `multi_chart_linkage.py` 单脚本 | ### 反模式检查清单（出现任何一条就说明在浪费时间） - **🚨 用 `py -c` 或 `ls` 探索已知信息**（default_configs.json 的路径、可用键名、组件类型等在 skill.md 和 map-guide.md 中已完整列出，禁止用探索命令去"验证"，直接写脚本执行。探索命令还会引入 `$HOME` Unix 路径格式问题导致 `FileNotFoundError`。） - **🚨 添加≥2个组件时用单独的 `add` 并行执行**（并行导致乐观锁冲突丢失组件！必须用 `batch-add --specs '[...]'` 一次保存） - **🚨 `add` 命令后 chartData 为 `[]`**（comp_ops.py 已从 default_configs.json 加载完整默认数据，出现空数据说明 default_configs.json 未被复制到工作目录） - **🚨 静态 chartData 禁止使用 comp_ops.py 兜底数据**（default_configs.json 为空时 comp_ops.py 回落到内置占位数据：JBar→A/B/C/D/E、JStackBar→收入/支出，这些是虚构数据。必须从前端源码 `data.ts`（位于 `packages/dragEngine/components/jeecgComponents/data.ts`）中读取各组件 `compConfig.chartData` 的真实值，通过每个 spec 加 `"config":{"chartData":[...]}` 字段，或 singleFile 脚本中调用 `comp_ops._build_comp_config(comp_type, title, {"chartData": json.dumps(real_data)})` 覆盖） - **⚠️ 创建 SQL 数据集时跳过询问数据源直接执行**（无论使用哪种脚本，执行前必须先 `datasource_ops.py list` 列出数据源，询问用户） - **⚠️ 用户已给出 API 地址时先用 `--dataset-name` 探测或先添加静态组件**（直接 `dataset_ops.py create-api` → `comp_ops.py add --dataset-name`，2 轮完成） - **⚠️ singleFile 全流程脚本第4步（add_component）前漏写 query_page + 缓存 template**（漏掉两行缓存代码时，`save_page` 将仪表盘**所有已有组件永久清空**） - **⚠️ singleFile 场景将"建数据集脚本"和"添加图表脚本"拆成两个**（必须一个脚本完成全部流程） - **⚠️ singleFile 场景用 `comp_ops.py --dataset-name` 绑定图表**（按字段数组顺序自动映射，导致图表显示错误数据） - **⚠️ 执行 `py script.py` 时不加 `PYTHONIOENCODING=utf-8`**（Windows 默认 GBK 编码，中文必定乱码） - **⚠️ 自定义脚本用 `cp bi_utils.py` 而非 `sys.path.insert`**（cp 路径硬编码，换机器失效，且需要清理。**必须用 `sys.path.insert(0, os.path.join(os.path.expanduser('~'), '.claude', 'skills', 'jimubi-dashboard', 'references'))`**） - **⚠️ 预置脚本用 `py comp_ops.py` 短名调用**（PYTHONPATH 只解决 `import bi_utils`，不解决脚本文件查找！`py comp_ops.py` 在当前目录找脚本，必然报"No such file"。**必须用全路径**：`SKILL_REFS="$HOME/.claude/skills/jimubi-dashboard/references"; PYTHONIOENCODING=utf-8 PYTHONPATH="$SKILL_REFS:$SKILL_REFS/scripts" py "$SKILL_REFS/scripts/comp_ops.py" ...`） - **🚨 create_page 后紧接 save_page**（create_page 内部已保存一次，updateCount 变为1；随即 save_page 携带 updateCount=0 触发乐观锁报"仪表盘内容不是最新"。**save_page 只在添加/修改组件后调用**） - **⚠️ Write 脚本时写占位符 TOKEN/API_BASE 再单独 Edit 更新**（凭据已在上下文中，必须 Write 时直接填入最终值） - **⚠️ 多图表+联动场景逐个调用 comp_ops.py + linkage_ops.py**（用 `multi_chart_linkage.py` 单脚本，节省约80%耗时） - **⚠️ 直接调用 bi_utils.add_xxx() + save_page() 添加组件到已有页面**（会覆盖已有组件！必须先 query_page + 缓存 template） - **⚠️ 写自定义脚本用 bash heredoc 而非 Write 工具**（heredoc 含单引号必报错） - **⚠️ 脚本中用拼音/英文替代中文字段名、组件名**（如把"基础柱形图"写成 `JiChu-ZhuXingTu`，用户无法识别） - **⚠️ 用户未指定数据来源时擅自使用公开 mock API**（必须先执行 Step 0.1 询问数据来源） - **⚠️ 批量绑定数据集时 dataMapping.filed 写成字段名**（`filed` 是语义槽位标签"维度"/"数值"/"分组"，`mapping` 才是字段名） - **⚠️ dataMapping 按数组索引顺序映射而非语义映射**（必须按语义显式指定：单系列 `[{维度→name},{数值→value}]`，多系列 `[{分组→type},{维度→name},{数值→value}]`） - **⚠️ 仪表盘 size 字段用栅格单位**（`config.size.width/height` 必须是像素：`width = w×75, height = h×11`） --- ## 仪表盘特征 - **布局**：24 列栅格，坐标和尺寸单位为**栅格单位**（如 x=0, y=0, w=6, h=17） - **背景色**：支持，字段 `backgroundColor`（`DragEngineDef.vue` 第68行） - **背景图**：支持，字段 `backgroundImage` - **风格（style）**：支持 `transparent`/`light`/`dark`/`default`（`DragEngineDef.vue` 第50行） - **组件主题（theme）**：支持 `default`/`gray`/`green`/`red`/`blue`/`dark`（`DragEngineDef.vue` 第58行） - **水印**：❌ 不支持（水印仅大屏专有，仪表盘无此功能） - **卡片头**：图表组件的 `card.title` 应留空（标题由 ECharts `option.title` 显示），避免标题重复 - **颜色体系**：白底 `#FFFFFF`、深灰标题 `#464646`、浅灰轴标签 `#909198`、浅灰网格 `#F3F3F3` ## 仪表盘栅格布局规则 | 组件类型 | 推荐 w | 推荐 h | 说明 | |---------|--------|--------|------| | JNumber | 6 | 17 | 数字卡片，4 个一行正好 24 列 | | JGrowCard/JSimpleCard | 6-8 | 17-22 | 统计增长卡片 | | JLine/JBar/JSmoothLine | 12-14 | 28-35 | 图表，通常半宽或更宽 | | JPie/JRing/JRose | 10-12 | 28-35 | 饼图/环形图 | | JHorizontalBar | 12 | 28-35 | 横向柱状图 | | JCommonTable | 12 | 30-40 | 数据表格 | | JList | 12 | 30-40 | 数据列表 | | JGauge | 6-8 | 25-30 | 仪表盘表盘 | | JProgress/JCustomProgress | 8-12 | 20-28 | 进度条/进度图 | **布局原则：** - 总宽度 24 列，组件 w 之和不要超过 24 - 第一行通常放 4 个 JNumber（w=6×4=24） - 第二行放图表组合（如 JLine w=14 + JPie w=10 = 24） - 第三行放表格/排行等 ## 前置条件 用户必须提供： 1. **API 地址**：JeecgBoot 后端地址（如 `https://api3.boot.jeecg.com`） 2. **X-Access-Token**：JWT 登录令牌（从浏览器 F12 获取） --- ## 交互流程 ### Step 0: 解析用户需求 | 信息 | 默认值 | 示例 | |------|--------|------| | 页面名称 | 用户指定 | "运营数据看板" | | 主题 | default | default | | 组件列表 | 从描述中解析 | 用户总数(数字)、增长趋势(折线)、来源分布(饼图) | ### Step 0.1: 数据来源确认（强制，用户未明确指定时必须询问） **触发条件：** 用户没有明确说明数据来自哪里（没有给出接口地址、没有指定数据集、没有说用 SQL/mock/自己写代码），则**必须先问用户以下两个问题，不得擅自假设或跳过**： > **问题一：接口来源** > 使用 **mock 系统** 还是 **自己编写代码**？ > - **mock 系统**：请提供 mock 服务地址 + 账号密码（如 YApi） > - **自己编写代码**：请提供代码存放路径（Java Controller 文件全路径） > > **问题二：接口需要实现什么业务需求？** > 描述各组件要展示的数据内容 **可跳过询问、直接执行的情况：** - 用户已明确说"使用 mock 系统"并提供了地址和账号 - 用户已明确说"写接口"并提供了文件路径 - 用户指定了已有数据集名称或 SQL 数据源 - 任务不涉及数据集创建（如纯样式修改、组件位移、删除等） ### Step 0.5: 模板匹配（优先使用模板布局） **生成整个仪表盘时，必须先匹配模板，复用已有布局。** 这是最优先的步骤，能确保生成的仪表盘布局专业、美观。 **模板目录**：`references/templates/default/`（29 个仪表盘模板 JSON） **匹配流程：** 1. **根据用户需求关键词搜索模板**：将用户描述的行业/场景与模板名称进行语义匹配 | 用户需求关键词 | 推荐模板 |