jeecg-onlchart
Use when user asks to create/edit Online graph charts, data visualization, or says "创建图表", "生成图表", "新建图表", "做一个图表", "online图表", "数据图表", "柱状图", "折线图", "饼图", "统计图", "可视化", "chart", "graph", "create chart", "generate chart", "bar chart", "line chart", "pie chart". Also triggers when user describes chart requirements like "做一个销售柱状图" or mentions data visualization like "用图表展示男女比例".
jeecgboot · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add jeecgboot/skills --skill jeecg-onlchartAbout this skill
name: jeecg-onlchart description: Use when user asks to create/edit Online graph charts, data visualization, or says "创建图表", "生成图表", "新建图表", "做一个图表", "online图表", "数据图表", "柱状图", "折线图", "饼图", "统计图", "可视化", "chart", "graph", "create chart", "generate chart", "bar chart", "line chart", "pie chart". Also triggers when user describes chart requirements like "做一个销售柱状图" or mentions data visualization like "用图表展示男女比例".
JeecgBoot Online 图表 AI 自动生成器
将自然语言的图表需求描述转换为 Online 图表配置,并通过 API 在 JeecgBoot 系统中自动创建/编辑图表。
重要:本 skill 处理「Online 图表」(SQL 驱动的数据可视化图表),不涉及「Online 报表」(cgreport 数据列表)或「Online 表单」(cgform)。
前置条件
用户必须提供以下信息(或由 AI 引导确认):
- API 地址:JeecgBoot 后端地址(如
https://boot3.jeecg.com/jeecgboot) - X-Access-Token:JWT 登录令牌(从浏览器 F12 获取)
如果用户未提供,提示:
请提供 JeecgBoot 后端地址和 X-Access-Token(从浏览器 F12 → Network → 任意请求的 Request Headers 中复制)。
交互流程
Step 0: 判断操作类型
| 用户意图关键词 | 操作类型 |
|---|---|
| 创建/新建/做一个/生成图表 | 新增图表 → Step 1A |
| 修改图表/改字段/换图表类型 | 编辑图表 → Step 1B |
Step 1A: 新增图表 — 解析需求
从用户描述中提取:
| 信息 | 必填 | 默认值 | 示例 |
|---|---|---|---|
| 图表编码 (code) | 是 | 自动生成 snake_case | tj_user_sex |
| 图表名称 (name) | 是 | 用户指定 | "统计男女比例" |
| SQL 语句 (cgrSql) | 是 | 从需求推导或用户提供 | select count(*) cout, sex from sys_user group by sex |
| X 轴字段 (xaxisField) | 是 | 从 SQL 推导 | sex |
| Y 轴字段 (yaxisField) | 是 | 从 SQL 推导 | cout |
| 图表类型 (graphType) | 是 | bar | bar、line、pie、line,bar |
| 展示模板 (displayTemplate) | 否 | tab | tab、single、double |
| 数据源 (dbSource) | 否 | 空(默认数据源) | second_db |
| 数据类型 (dataType) | 否 | sql | sql |
X/Y 轴推导规则:
- X 轴 (xaxisField):通常是分类/维度字段(如 sex、dept、month、category)
- Y 轴 (yaxisField):通常是度量/聚合字段(如 count、sum、avg 的结果)
Step 1B: 编辑图表 — 查询现有配置
- 用户提供图表 ID 或编码
- 通过 API 查询现有图表配置(参考 API 列表)
- 展示现有配置,根据用户需求进行修改
Step 2: 解析字段(根据 dataType 选择接口)
2A. SQL 类型 — 复用 parseSql 接口
GET /online/cgreport/head/parseSql?sql={urlEncodedSql}&dbKey={dbKey}
sql:URL 编码后的 SQL 语句dbKey:数据源编码,默认数据源可不传
返回结构:
{
"success": true,
"result": {
"fields": [
{ "fieldName": "cout", "fieldTxt": "cout", "fieldType": "String", "isShow": 1, "orderNum": 1 }
],
"params": []
}
}
注意:parseSql 返回的
isShow是数字 (0/1),但图表接口需要字符串"Y"/"N",需要转换。
2B. JSON/API 类型 — 使用 parseField 接口
POST /online/graphreport/head/parseField?type=JSON
POST /online/graphreport/head/parseField?type=API
请求体(JSON 类型传 JSON 字符串,API 类型传接口 URL):
{ "data": "[{\"month\":\"01\",\"amount\":1000}]" }
返回结构(与 parseSql 相同格式):
{
"success": true,
"result": {
"fields": [
{ "fieldName": "month", "fieldTxt": "month", "fieldType": "String", "isShow": 1 },
{ "fieldName": "amount", "fieldTxt": "amount", "fieldType": "Integer", "isShow": 1 }
],
"params": []
}
}
JSON/API 类型无需配置
dbSource,cgrSql字段存放 JSON 字符串或 API URL。
API 数据格式要求
API 接口返回的数据必须包裹在 {"data": [...]} 结构中,否则图表无法解析:
// ✓ 正确
{"data": [{"name": "一月", "value": 120}, {"name": "二月", "value": 200}]}
// ✗ 错误(裸数组,图表无法识别)
[{"name": "一月", "value": 120}]
parseField 失败时的处理
parseField?type=API 要求 JeecgBoot 服务端能访问该 URL。若服务端无法访问外网导致失败,跳过 parseField,手动构造 items(字段已知时可直接定义)。
使用 YApi Mock 创建 API 数据源
项目内置 YApi Mock 平台(https://api.jeecg.com),可快速创建 mock 接口作为 API 数据源。
使用 scripts/yapi_mock.py 脚本操作,凭证获取规则,禁止硬编码:
- 优先从当前上下文(系统提示、memory、全局配置等任意来源)中查找 YApi 邮箱和密码
- 上下文中找不到时,必须询问用户:
需要使用 YApi Mock 创建数据源,请提供登录邮箱和密码(平台地址:https://api.jeecg.com)。
yapi_mock.py内部使用http.cookiejar.CookieJar + build_opener管理会话,兼容 Python 3.6 / 3.9 / 3.12 及以上所有版本,直接调用init_yapi(email, password)即可。
import sys
sys.path.insert(0, '<skill目录>/scripts')
from yapi_mock import init_yapi, create_mock
# 凭证由 Claude 从 memory 读取后注入,不得硬编码
init_yapi(email='<email>', password='<password>')
# 创建 mock 接口并写入数据,返回完整 mock URL
mock_url = create_mock(
path='/staff', # 路径后缀,不含 basepath(/claude)
title='职员信息',
data=[
{"name": "张三", "salary": 18000},
{"name": "李四", "salary": 15000},
]
)
print(mock_url) # https://api.jeecg.com/mock/57/claude/staff
路径规则(重要):项目 basepath 为 /claude,接口路径只写后缀:
| 传入 path | 完整 mock URL |
|---|---|
/staff | https://api.jeecg.com/mock/57/claude/staff |
/line | https://api.jeecg.com/mock/57/claude/line |
Step 3: 智能字段配置
3.1 字段属性映射(图表 vs 报表的差异)
关键差异:图表字段使用 "Y"/"N" 字符串,而非数字 0/1。
| 属性 | 图表 (graphreport) | 报表 (cgreport) | 说明 |
|---|---|---|---|
| 关联头ID | graphreportHeadId | cgrheadId | 字段名不同 |
| 是否显示 | isShow: "Y"/"N" | isShow: 0/1 | 类型不同 |
| 是否合计 | isTotal: "Y"/"N" | isTotal: "0"/"1" 或 null | 类型不同 |
| 是否查询 | searchFlag: "Y"/"N" | isSearch: 0/1 | 字段名和类型都不同 |
| 查询模式 | searchMode | searchMode | 相同 |
| 字典 | dictCode | dictCode | 相同 |
| 排序 | orderNum | orderNum | 相同 |
3.2 字段显示名称 (fieldTxt)
parseSql 返回的 fieldTxt 默认等于 fieldName,AI 需要根据语义翻译为中文:
| 字段名模式 | 推导中文名 |
|---|---|
| count / cout / cnt | 数量/人数/次数 |
| sum / total / amount | 合计/总额 |
| avg / average | 平均值 |
| sex | 性别 |
| dept / department | 部门 |
| status | 状态 |
| type / category | 类型/分类 |
| month / year / date | 月份/年份/日期 |
| name / title | 名称 |
| age | 年龄 |
| salary | 薪资 |
3.3 是否显示 (isShow)
| 规则 | isShow |
|---|---|
| 所有字段(默认) | "Y"(图表通常字段不多,全部显示) |
| id / 主键字段 | "N" |
3.4 是否查询 (searchFlag) + 查询模式 (searchMode)
| 字段类型 | searchFlag | searchMode |
|---|---|---|
| 分类/维度字段 | "Y" | single |
| 日期/时间字段 | "Y" | group |
| 度量/聚合字段 | "N" | null |
3.5 是否合计 (isTotal)
| 规则 | isTotal |
|---|---|
| 度量/聚合字段 | "Y" |
| 维度/分类字段 | "N" |
3.6 字典配置 (dictCode) — 列表数据值替换显示
作用:列表(明细表格区域)中,将数据库存储的原始值替换为可读文本显示。
例:性别字段数据库存
1/2,配置字典后显示为"男"/"女"。
支持两种方式:
方式一:系统字典编码
填写系统字典的 dictCode,由系统字典表自动解析值 → 文本。
"dictCode": "sex"
Read the complete source ↗