Skills — Online图表生成

1. 功能介绍

jeecg-onlchart 是 Claude Code 的 AI Skill，能够将自然语言需求自动转换为 JeecgBoot Online 图表，完成从 SQL 编写 → 字段解析 → X/Y 轴推导 → 图表配置 → 创建图表 的全流程自动化。

核心能力：

用自然语言描述图表需求，AI 自动生成 SQL 查询语句
智能推导 X/Y 轴字段：维度字段→X 轴，度量字段→Y 轴
根据数据特征自动推荐图表类型（柱状图、折线图、饼图、组合图表）
自动调用 parseSql 接口解析 SQL 字段
智能推导字段的中文名称、字典配置、查询方式、合计等属性
自动调用 API 创建/编辑图表
支持组合图表（折线+柱状同时展示）
支持 SQL 参数化查询（Velocity 模板语法）
支持动态数据源
自动生成菜单 SQL

不确定该用哪个 Skill？请查看 AI Skills 技能清单。下载地址：https://github.com/jeecgboot/skills

2. 前置条件

使用前需要准备两个信息：

信息	获取方式	示例
API 地址	JeecgBoot 后端服务地址	`https://boot3.jeecg.com/jeecgboot`
X-Access-Token	浏览器 F12 → Network → 任意请求的 Request Headers	`eyJhbGciOiJIUzI1NiIs...`

获取 Token 步骤：

登录 JeecgBoot 后台管理系统
按 F12 打开浏览器开发者工具
切换到 Network（网络）面板
点击页面上任意操作触发一个请求
点击该请求，在 Request Headers 中找到 X-Access-Token 的值并复制

3. 使用方式

在 Claude Code 中直接用自然语言描述需求即可。以下是触发关键词：

创建图表、生成图表、新建图表、做一个图表、
online图表、数据图表、柱状图、折线图、饼图、
统计图、可视化、chart、graph

4. 实战示例：创建用户性别统计图表

4.1 第一步：描述需求

直接告诉 AI 你需要什么图表：

创建一个柱状图，统计系统用户的男女比例

AI 会根据需求：

自动推导 SQL 查询语句
调用 parseSql 接口解析字段
智能识别 X 轴（sex 性别）和 Y 轴（count 人数）
推荐图表类型（柱状图）

4.2 第二步：AI 展示配置摘要

## Online 图表配置摘要

- 图表编码：tj_user_sex
- 图表名称：统计男女比例
- 图表类型：bar（柱状图）
- X 轴字段：sex（性别）
- Y 轴字段：cout（人数）
- 数据源：默认
- 目标环境：https://boot3.jeecg.com/jeecgboot

### SQL 语句
select count(*) cout, sex from sys_user group by sex

### 字段配置

| 序号 | 字段名 | 显示名称 | 类型   | 显示 | 查询 | 字典 | 合计 |
|------|--------|---------|--------|------|------|------|------|
| 0    | cout   | 人数    | String | Y    | N    | -    | Y    |
| 1    | sex    | 性别    | String | Y    | N    | sex  | N    |

确认以上配置？(y/n)

4.3 第三步：提供 Token 并确认

确认配置后，提供 API 地址和 Token：

x-access-token
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxx

4.4 第四步：AI 自动执行

AI 会依次执行以下操作：

调用 parseSql API → 解析 SQL 字段 ✓
调用 add API → 创建图表配置 ✓
查询图表 ID → 获取 headId ✓
输出菜单 SQL → 供用户选择是否执行

4.5 第五步：查看结果

## Online 图表创建成功

- 图表编码：tj_user_sex
- 图表名称：统计男女比例
- 图表类型：bar（柱状图）
- X 轴：sex（性别）
- Y 轴：cout（人数）
- 目标环境：https://boot3.jeecg.com/jeecgboot

### 菜单 SQL（可选）
INSERT INTO sys_permission(...)
VALUES ('headId', NULL, '统计男女比例', '/online/graphreport/headId', ...);

### 后续操作
1. 打开 JeecgBoot 后台 → Online图表
2. 找到该图表，点击「功能测试」预览效果
3. 如需配置菜单，执行上方 SQL 或在后台手动添加

5. 更多使用场景

5.1 直接提供 SQL 创建图表

如果你已经有现成的 SQL：

创建一个图表，SQL如下：
select DATE_FORMAT(create_time,'%Y-%m') month, count(*) cnt
from sys_user group by month
用折线图展示

AI 会自动解析 SQL 中的字段，识别 X 轴（month）和 Y 轴（cnt），并设置图表类型为折线图。

5.2 饼图展示占比分布

用饼图展示系统用户的性别分布

AI 识别"饼图"关键词，设置 graphType: "pie"，自动推导 SQL 和 X/Y 轴字段。

5.3 组合图表（折线+柱状）

做一个月度销售分析，同时显示折线图和柱状图

AI 自动设置：

graphType: "line,bar"
isCombination: "combination"

在同一坐标系中同时展示折线和柱状图。

5.4 带查询参数的图表

创建一个柱状图统计各部门人数，支持按状态筛选

AI 生成带 Velocity 参数的 SQL：

select count(*) cnt, dept from sys_user
where 1=1
${#if($status != '')} AND status = '$status' ${#end}
group by dept

5.5 使用动态数据源

用 second_db 数据源做一个销售统计图表

AI 设置 dbSource: "second_db"，从指定数据源查询数据。

5.6 修改已有图表

修改图表 tj_user_sex，把图表类型改成饼图

AI 先查询现有图表配置，再进行修改，使用 edit API 更新。

6. 支持的图表类型

图表类型	graphType 值	适用场景	数据特征
柱状图	`bar`	分类对比	如男女人数、部门对比
折线图	`line`	趋势变化	如月度销售、访问量趋势
饼图	`pie`	占比分布	如部门比例、状态分布
组合图表	`line,bar`	趋势+对比	同时展示折线和柱状

AI 会根据数据特征自动推荐最合适的图表类型：

数据场景识别：
├── 分类对比（如男女人数） → 柱状图 bar
├── 趋势变化（如月度销售） → 折线图 line
├── 占比分布（如部门比例） → 饼图 pie
└── 多维分析（趋势+对比） → 组合图表 line,bar

7. 智能字段推导规则

7.1 X/Y 轴自动推导

字段特征	推导为	说明
分类/维度字段（sex、dept、month、category）	X 轴	图表的分类维度
度量/聚合字段（count、sum、avg 的结果）	Y 轴	图表的数值度量

7.2 字段显示名称

AI 自动将英文字段名翻译为中文：

字段名模式	推导中文名
count / cout / cnt	数量/人数
sum / total / amount	合计/总额
avg / average	平均值
sex	性别
dept / department	部门
status	状态
type / category	类型/分类
month / year / date	月份/年份/日期
name / title	名称

7.3 字典自动关联

字段名	关联字典
sex	`sex`（性别）
status	`valid_status`（有效状态）
priority	`priority`（优先级）

也支持 SQL 字典：

{"dictCode": "SELECT id as value, name as text FROM sys_category"}

7.4 查询与合计配置

字段类型	查询 (searchFlag)	查询模式	合计 (isTotal)
分类/维度字段	Y	`single`	N
日期/时间字段	Y	`range`	N
度量/聚合字段	N	-	Y

8. 涉及的 API 接口

接口	方法	路径	说明
解析 SQL	GET	`/online/cgreport/head/parseSql?sql={sql}&dbKey={dbKey}`	复用报表接口解析 SQL 字段
创建图表	POST	`/online/graphreport/head/add`	创建图表配置
编辑图表	PUT	`/online/graphreport/head/edit`	修改已有图表
查询图表列表	GET	`/online/graphreport/head/list?code={code}`	按编码搜索图表
查询图表详情	GET	`/online/graphreport/head/queryById?id={headId}`	按 ID 查询图表

9. 高级配置

9.1 Y 轴标签 (yaxisText)

自定义 Y 轴显示文字：

创建图表并设置 Y 轴标签为"人数（单位：人）"

9.2 扩展 JS (extendJs)

通过自定义 JS 扩展图表行为：

创建图表，加一段扩展 JS：option.tooltip = {trigger: 'axis'};

9.3 SQL 参数语法

Online 图表使用 Velocity 模板语法实现条件查询：

-- 条件判断（参数不为空时追加条件）
${#if($status != '')} AND status = '$status' ${#end}

-- 日期范围
${#if($startDate != '')} AND create_time >= '$startDate' ${#end}

对应的参数配置：

[
  {"paramName": "status", "paramTxt": "状态", "paramValue": "", "orderNum": 1}
]

10. 常见问题

Online 图表和 Online 报表有什么区别？

对比项	Online 图表 (graphreport)	Online 报表 (cgreport)
数据展示	可视化图表（柱状/折线/饼图）	数据表格列表
数据来源	SQL 查询语句	SQL 查询语句
X/Y 轴	✅ 需要配置	❌ 不涉及
适用场景	数据可视化、趋势分析、占比展示	数据查询、统计列表、数据导出

支持哪些图表类型？

目前支持 4 种：柱状图（bar）、折线图（line）、饼图（pie）、组合图表（line,bar）。组合图表可以在同一坐标系中同时展示折线和柱状。

parseSql 返回的字段类型都是 String？

是的，parseSql 默认返回 String 类型。AI 会根据字段名语义自动修正字段类型。

图表创建后如何预览？

在 JeecgBoot 后台 → Online 图表列表中，找到对应图表，点击「功能测试」即可预览效果。

add 和 edit 接口的字段差异？

这是一个容易踩坑的地方：

add 时：items 中关联 ID 字段名为 cgrheadId（值为 null）
edit 时：items 中关联 ID 字段名为 graphreportHeadId（值为 headId）
add 时：查询字段用 isSearch
edit 时：查询字段用 searchFlag（"Y"/"N"）

AI 会自动处理这些差异，用户无需关心。

1. 功能介绍​

2. 前置条件​

3. 使用方式​

4. 实战示例：创建用户性别统计图表​

4.1 第一步：描述需求​

4.2 第二步：AI 展示配置摘要​

4.3 第三步：提供 Token 并确认​

4.4 第四步：AI 自动执行​

4.5 第五步：查看结果​

5. 更多使用场景​

5.1 直接提供 SQL 创建图表​

5.2 饼图展示占比分布​

5.3 组合图表（折线+柱状）​

5.4 带查询参数的图表​

5.5 使用动态数据源​

5.6 修改已有图表​

6. 支持的图表类型​

7. 智能字段推导规则​

7.1 X/Y 轴自动推导​

7.2 字段显示名称​

7.3 字典自动关联​

7.4 查询与合计配置​

8. 涉及的 API 接口​

9. 高级配置​

9.1 Y 轴标签 (yaxisText)​

9.2 扩展 JS (extendJs)​

9.3 SQL 参数语法​

10. 常见问题​

Online 图表和 Online 报表有什么区别？​

支持哪些图表类型？​

parseSql 返回的字段类型都是 String？​

图表创建后如何预览？​

add 和 edit 接口的字段差异？​