293 lines
7.8 KiB
Markdown
293 lines
7.8 KiB
Markdown
# 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：
|
||
```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，可选择执行或手动添加
|