qhmes/.trae/skills/jeecg-onlchart/docs/skill-usage-guide.md

JeecgBoot Online 图表 AI 自动生成 — Skills 使用指南

通过 Claude Code 以自然语言描述图表需求，AI 自动生成 SQL、推导 X/Y 轴字段、配置图表类型，并调用 API 在 JeecgBoot 系统中创建/编辑 Online 图表。 无需手动写 SQL 或逐一配置字段，AI 从需求描述到可预览图表一步到位。

与传统方式的区别

• 无需手写 SQL：描述业务需求，AI 自动推导 SQL 语句和字段配置
• 智能推导 X/Y 轴：AI 根据 SQL 字段语义自动识别维度字段（X 轴）和度量字段（Y 轴）
• 自动选择图表类型：根据数据特征推荐最适合的图表类型（柱状图、折线图、饼图等）
• 字段中文名翻译：自动将 SQL 字段名翻译为中文显示名称
• 字典自动匹配：识别常见字段（如 sex、status）并关联系统字典

---

前置准备

使用前需准备两样东西：

信息	获取方式	示例
后端地址	运维/开发提供	https://boot3.jeecg.com/jeecgboot
X-Access-Token	浏览器 F12 → Network → 任意请求 Headers	eyJhbGciOiJIUzI1NiJ9...

---

触发方式

在 Claude Code 对话中，用自然语言描述你要创建的图表，包含以下任意关键词即可自动触发：

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

---

实战案例：用户性别统计图表

以下是一个完整的图表创建过程，展示了 skill 的实际使用方式。

第一步：描述需求

用户输入：

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

AI 交互过程：

1. AI 询问后端地址和 Token
2. 用户提供凭据后，AI 自动推导 SQL 和字段配置，展示摘要：

## 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)

3. 用户确认 y 后，AI 自动调用 API 创建图表
4. 返回结果：

## Online 图表创建成功

- 图表编码：tj_user_sex
- 图表名称：统计男女比例
- 图表类型：bar（柱状图）

### 后续操作
1. 打开 JeecgBoot 后台 → Online图表
2. 找到该图表，点击「功能测试」预览效果

---

第二步：修改图表类型

用户输入：

把刚才的图表改成折线+柱状组合图

AI 交互过程：

1. AI 基于已有图表信息，展示修改摘要（标注变更项）：

### 变更内容
- 图表类型：bar → line,bar（组合图表）
- 新增标记：isCombination = combination

2. 用户确认后，AI 调用 edit API 更新图表

---

示例用法

1. 一句话描述（最简方式）

做一个柱状图，统计各部门的人数

AI 会自动推导 SQL：select count(*) cnt, depart_name from sys_depart group by depart_name

2. 指定图表类型

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

AI 识别 "饼图" → graphType: "pie"

3. 指定 SQL

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

4. 组合图表

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

AI 自动设置 graphType: "line,bar" + isCombination: "combination"

5. 带查询参数的图表

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

AI 生成带 Velocity 参数的 SQL：

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

6. 指定数据源

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

AI 设置 dbSource: "second_db"

---

支持的图表类型

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

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

• 分类对比场景 → 柱状图
• 时间趋势场景 → 折线图
• 占比分布场景 → 饼图
• 多维分析场景 → 组合图表

---

智能字段推导

AI 根据 SQL 字段语义自动推导配置：

X/Y 轴推导

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

字段中文名翻译

字段名	自动翻译
count / cout / cnt	数量/人数
sum / total / amount	合计/总额
avg / average	平均值
sex	性别
dept / department	部门
month / year / date	月份/年份/日期

字典自动关联

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

---

修改已有图表

如果要修改已创建的图表：

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

给图表 tj_user_sex 的 Y 轴加上标签文字"人数（单位：人）"

需要提供图表 ID 或编码。AI 会先查询现有配置，再进行修改。

---

高级功能

Y 轴标签

创建图表并设置 Y 轴标签为"销售额（万元）"

扩展 JS

通过自定义 JS 扩展图表行为，适合高级用户：

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

动态数据源

查询非默认数据源的数据：

用 report_db 数据源创建统计图表

---

与其他 Skill 的区别

Skill	产出物	适用场景
jeecg-onlchart	Online 图表配置（SQL 驱动，数据可视化）	柱状图、折线图、饼图等数据可视化
jeecg-onlreport	Online 报表配置（SQL 驱动，数据列表）	数据查询报表、统计列表
jeecg-onlform	Online 表单配置（元数据驱动，CRUD）	数据录入管理表单
jeecg-codegen	Java + Vue3 代码 + SQL	需要自定义业务逻辑的模块
jeecg-desform	设计器表单 JSON	数据采集、审批表单
jeecg-bpmn	Flowable BPMN 2.0 XML	审批流程、工作流

选择建议：

• 需要数据可视化（图表） → jeecg-onlchart
• 需要数据查询列表 → jeecg-onlreport
• 需要简单 CRUD 表单 → jeecg-onlform
• 需要自定义业务逻辑 → jeecg-codegen
• 需要数据采集/审批表单 → jeecg-desform
• 需要审批流程 → jeecg-bpmn

---

注意事项

1. Token 有效期：JWT Token 有过期时间，过期后需重新从浏览器获取
2. 图表编码唯一：同一系统中 code 不能重复，如已存在需改名或使用编辑功能
3. SQL 安全：不要在 SQL 中使用 DROP/DELETE/UPDATE 等危险语句
4. 同一会话内可连续修改：AI 会记住当前图表的 ID 和编码，无需重复提供
5. 创建后可在后台微调：AI 创建的图表可以在 Online 图表编辑页面中继续调整
6. 菜单配置可选：创建成功后 AI 会提供菜单 SQL，可选择执行或手动添加