Name: jeecg-onlchart
Author: jeecgboot

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"

常用系统字典编码：

| dictCode | 说明 | |----------|------| | sex | 性别（1=男，2=女） | | priority | 优先级 | | valid_status | 有效状态 | | yn | 是/否 |

方式二：字典 SQL

在 dictCode 处直接写一条 SELECT 语句，动态替换显示值。SQL 必须返回两列：value（数据库存的值）和 text（展示的文本）。

"dictCode": "SELECT id as value, name as text FROM sys_category WHERE pid = '1'"

"dictCode": "SELECT code as value, name as text FROM sys_depart ORDER BY depart_order"

注意：字典 SQL 每次渲染都会执行查询，数据量大时建议加 WHERE 条件限制范围。

Step 4: 图表类型选择

根据数据特征推荐图表类型：

| 数据场景 | 推荐 graphType | 说明 | |---------|---------------|------| | 分类对比（如男女人数） | bar | 柱状图 | | 趋势变化（如月度销售） | line | 折线图 | | 占比分布（如部门比例） | pie | 饼图 | | 趋势+对比（如月度销售对比） | line,bar | 组合图表 | | 纯数据明细 | table | 数据表格（只渲染在底部明细区，不占图表位） |

graphType 支持逗号分隔多种类型，如 "bar,pie" 会同时生成柱状图和饼图两个区域。

组合图表配置（折线+柱状同坐标系）：

graphType: "line,bar"（逗号分隔多种类型）
isCombination: "combination"（标记为组合图表）
非组合图表 isCombination 为 null 或不传

Step 5: 展示摘要并确认

必须展示以下内容，等待用户确认后再执行：

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

Step 6: 校验编码可用性（仅新增时）

用户确认后，新增图表前必须先校验 code 是否已被占用：

GET /sys/duplicate/check?tableName=onl_graphreport_head&fieldName=code&fieldVal={code}

返回结构：

{ "success": true, "result": true }   // true = 可用（未重复）
{ "success": true, "result": false }  // false = 已存在，需换一个 code

若 result 为 false，提示用户更换编码，不继续执行创建。

Python 示例：

encoded_code = urllib.parse.quote(report_code)
check = api_request(f'/sys/duplicate/check?tableName=onl_graphreport_head&fieldName=code&fieldVal={encoded_code}')
if not check.get('result'):
    print(f'图表编码 "{report_code}" 已存在，请换一个编码')
    exit(1)
print(f'编码 "{report_code}" 可用，继续创建...')

Step 7: 调用 API 创建/编辑图表

用户确认且编码校验通过后执行。

6.1 新增图表 — 请求结构

POST /online/graphreport/head/add

{
    "dbSource": "",
    "name": "统计男女比例",
    "code": "tj_user_sex",
    "displayTemplate": "tab",
    "xaxisField": "sex",
    "yaxisField": "cout",
    "dataType": "sql",
    "graphType": "bar",

jeecg-onlchart

Como adicionar

Cole no README do seu repo

Skills relacionadas

xlsx

how-it-works

weekly-digests

mem-search

Receba novas skills de Dados e Análise toda segunda