JeecgBoot Online 图表 AI 自动生成器

将自然语言的图表需求描述转换为 Online 图表配置，并通过 API 在 JeecgBoot 系统中自动创建/编辑图表。

重要：本 skill 处理「Online 图表」（SQL 驱动的数据可视化图表），不涉及「Online 报表」（cgreport 数据列表）或「Online 表单」（cgform）。

前置条件

用户必须提供以下信息（或由 AI 引导确认）：

1. API 地址：JeecgBoot 后端地址（如 https://boot3.jeecg.com/jeecgboot）
2. X-Access-Token：JWT 登录令牌（从浏览器 F12 获取）

如果用户未提供，提示：

请提供 JeecgBoot 后端地址和 X-Access-Token（从浏览器 F12 → Network → 任意请求的 Request Headers 中复制）。

交互流程

Step 0: 判断操作类型

Step 1A: 新增图表 — 解析需求

从用户描述中提取：

X/Y 轴推导规则：

• X 轴 (xaxisField)：通常是分类/维度字段（如 sex、dept、month、category）
• Y 轴 (yaxisField)：通常是度量/聚合字段（如 count、sum、avg 的结果）

Step 1B: 编辑图表 — 查询现有配置

1. 用户提供图表 ID 或编码
2. 通过 API 查询现有图表配置（参考 API 列表）
3. 展示现有配置，根据用户需求进行修改

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，接口路径只写后缀：

Step 3: 智能字段配置

3.1 字段属性映射（图表 vs 报表的差异）

关键差异：图表字段使用 "Y"/"N" 字符串，而非数字 0/1。

3.2 字段显示名称 (fieldTxt)

parseSql 返回的 fieldTxt 默认等于 fieldName，AI 需要根据语义翻译为中文：

3.3 是否显示 (isShow)

3.4 是否查询 (searchFlag) + 查询模式 (searchMode)

3.5 是否合计 (isTotal)

3.6 字典配置 (dictCode) — 列表数据值替换显示

作用：列表（明细表格区域）中，将数据库存储的原始值替换为可读文本显示。

例：性别字段数据库存 1/2，配置字典后显示为"男"/"女"。

支持两种方式：

方式一：系统字典编码

填写系统字典的 dictCode，由系统字典表自动解析值 → 文本。

"dictCode": "sex"

常用系统字典编码：

方式二：字典 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,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",