新增JeecgBoot BPM流程自动生成器，包含流程创建、修改及审批人配置功能，支持自然语言描述转化为BPMN XML，并通过API与JeecgBoot系统交互。
This commit is contained in:
geht
292
.trae/skills/jeecg-onlchart/docs/skill-usage-guide.md
Normal file
292
.trae/skills/jeecg-onlchart/docs/skill-usage-guide.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# 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，可选择执行或手动添加
|
||||
Reference in New Issue
Block a user