跳到主要内容

Skills — Online报表生成

1. 功能介绍​

jeecg-onlreport 是 Claude Code 的 AI Skill，能够将自然语言需求自动转换为 JeecgBoot Online 报表，完成从 SQL 编写 → 字段解析 → 报表配置 → 创建报表 的全流程自动化。

核心能力：

  • 用自然语言描述报表需求，AI 自动生成 SQL 查询语句
  • 自动调用 parseSql 接口解析 SQL 字段
  • 智能推导字段的显示名称、查询方式、排序、字典、合计等属性
  • 自动调用 add API 创建报表
  • 支持 SQL 参数化查询（Velocity 模板语法）
  • 支持动态数据源
  • 自动生成菜单 SQL

不确定该用哪个 Skill？请查看 AI Skills 技能清单。

2. 前置条件​

使用前需要准备两个信息：

信息获取方式示例
API 地址JeecgBoot 后端服务地址https://boot3.jeecg.com/jeecgboot
X-Access-Token浏览器 F12 → Network → 任意请求的 Request HeaderseyJhbGciOiJIUzI1NiIs...

获取 Token 步骤：

  1. 登录 JeecgBoot 后台管理系统
  2. 按 F12 打开浏览器开发者工具
  3. 切换到 Network（网络）面板
  4. 点击页面上任意操作触发一个请求
  5. 点击该请求，在 Request Headers 中找到 X-Access-Token 的值并复制

3. 使用方式​

在 Claude Code 中直接用自然语言描述需求即可。以下是触发关键词：

创建报表、生成报表、新建报表、做一个报表、
online报表、SQL报表、数据报表、统计报表

4. 实战示例：创建销售统计报表​

4.1 第一步：描述需求​

直接告诉 AI 你需要什么报表：

创建一个销售统计报表，查询销售表的订单编号、客户名称、
销售金额、销售日期、状态，金额需要合计，日期支持范围查询

AI 会根据需求：

  1. 生成合适的 SQL 查询语句
  2. 调用 parseSql 接口解析字段
  3. 智能配置每个字段的属性

4.2 第二步：AI 展示配置摘要​

## Online 报表配置摘要

- 报表编码：sales_statistics
- 报表名称：销售统计报表
- 数据源：默认
- 目标环境：https://boot3.jeecg.com/jeecgboot

### SQL 语句
SELECT order_no, customer_name, amount, sale_date, status
FROM biz_sales
WHERE 1=1

### 字段配置

| 序号 | 字段名         | 显示名称 | 类型       | 显示 | 查询     | 排序 | 字典         | 合计 |
|------|---------------|---------|-----------|------|---------|------|-------------|------|
| 0    | order_no      | 订单编号 | String    | 是   | 是(模糊) | 否   | -           | -    |
| 1    | customer_name | 客户名称 | String    | 是   | 是(模糊) | 否   | -           | -    |
| 2    | amount        | 销售金额 | BigDecimal| 是   | 否      | 是   | -           | 是   |
| 3    | sale_date     | 销售日期 | Date      | 是   | 是(范围) | 是   | -           | -    |
| 4    | status        | 状态     | String    | 是   | 是(精确) | 否   | valid_status| -    |

确认以上配置？(y/n)

4.3 第三步：提供 Token 并确认​

确认配置后，提供 API 地址和 Token：

x-access-token
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxx

4.4 第四步：AI 自动执行​

AI 会依次执行以下操作：

1. 调用 parseSql API → 解析 SQL 字段 ✓
2. 调用 add API → 创建报表配置 ✓
3. 查询报表 ID → 获取 headId ✓
4. 输出菜单 SQL → 供用户选择是否执行

4.5 第五步：查看结果​

## Online 报表创建成功

- 报表编码：sales_statistics
- 报表名称：销售统计报表
- 字段数量：5 个
- 目标环境：https://boot3.jeecg.com/jeecgboot

### 菜单 SQL（可选）
INSERT INTO sys_permission(...)
VALUES ('headId', NULL, '销售统计报表', '/online/cgreport/headId', ...);

### 后续操作
1. 点击「功能测试」预览报表效果
2. 如需配置菜单，执行上方 SQL 或在后台手动添加

5. 更多使用场景​

5.1 直接提供 SQL 创建报表​

如果你已经有现成的 SQL：

创建一个online报表，SQL如下：
SELECT u.username, u.realname, d.depart_name, u.status
FROM sys_user u
LEFT JOIN sys_depart d ON u.org_code = d.org_code
WHERE 1=1

AI 会自动解析 SQL 中的字段并配置报表。

5.2 带参数的报表​

创建一个按日期范围查询的订单报表，支持按状态筛选

AI 会生成带参数的 SQL：

SELECT * FROM biz_order
WHERE 1=1
${#if($startDate != '')} AND order_date >= '$startDate' ${#end}
${#if($endDate != '')} AND order_date <= '$endDate' ${#end}
${#if($status != '')} AND status = '$status' ${#end}

5.3 多表关联报表​

创建一个用户部门统计报表，关联用户表和部门表，
显示用户名、真实姓名、部门名称、角色、状态

5.4 使用动态数据源​

创建一个报表，使用数据源 second_db，
查询外部系统的客户数据

6. 智能字段推导规则​

AI 根据字段名自动推导显示名称和配置：

6.1 字段显示名称​

字段名模式推导中文名
name / title名称/标题
code / no编码/编号
status状态
type / category类型/分类
amount / money / price金额/费用/价格
count / qty / num数量
date / time日期/时间
sex性别
age年龄
email邮箱
phone / mobile手机号

6.2 查询模式​

字段类型查询模式说明
文本类（名称/编码）like模糊查询
枚举类（状态/类型）single精确匹配
日期类（日期/时间）range范围查询
数值类（金额/数量）不查询通常不作为查询条件

6.3 字段自动隐藏规则​

以下系统字段默认隐藏（isShow=0）：

  • id — 主键
  • create_by / update_by — 创建人/更新人
  • sys_org_code — 所属部门编码
  • tenant_id — 租户 ID

7. 涉及的 API 接口​

接口方法路径说明
解析 SQLGET/online/cgreport/head/parseSql?sql={sql}&dbKey={dbKey}解析 SQL 返回字段和参数
创建报表POST/online/cgreport/head/add创建报表配置
编辑报表PUT/online/cgreport/head/editAll编辑已有报表
查询报表详情GET/online/cgreport/head/queryById?id={headId}查询报表配置
查询报表列表GET/online/cgreport/head/list?code={code}按编码搜索报表
查询报表数据GET/online/cgreport/api/getData/{code}获取报表查询结果
导出 ExcelGET/online/cgreport/api/exportManySheetXls/{reportId}导出报表数据

8. SQL 参数语法​

Online 报表使用 Velocity 模板语法实现条件查询：

-- 条件判断（参数不为空时追加条件）
${#if($paramName != '')} AND field = '$paramName' ${#end}

-- 模糊查询
${#if($keyword != '')} AND name LIKE '%$keyword%' ${#end}

-- 日期范围
${#if($startDate != '')} AND create_time >= '$startDate' ${#end}
${#if($endDate != '')} AND create_time <= '$endDate' ${#end}

前端查询时，参数通过 self_ 前缀传递：

/online/cgreport/api/getData/report_code?self_paramName=value

9. 字典配置​

Online 报表支持两种字典方式：

系统字典​

{"dictCode": "sex"}

直接使用系统字典编码，自动翻译显示。

SQL 字典​

{"dictCode": "SELECT id as value, name as text FROM sys_category"}

通过 SQL 动态查询字典数据。

10. 常见问题​

报表和 Online 表单有什么区别？​

对比项Online 报表 (cgreport)Online 表单 (cgform)
数据操作只读查询增删改查
数据来源SQL 查询语句数据库表元数据
配置方式写 SQL + 配置字段配置表结构和控件
适用场景统计报表、数据查询数据录入管理

parseSql 返回的字段类型都是 String？​

是的，parseSql 默认返回 String 类型。AI 会根据字段名语义（如 amount→BigDecimal、date→Date）自动修正字段类型。

如何支持多表关联？​

直接在 SQL 中编写 JOIN 语句即可：

SELECT u.realname, d.depart_name, r.role_name
FROM sys_user u
LEFT JOIN sys_depart d ON u.org_code = d.org_code
LEFT JOIN sys_user_role ur ON u.id = ur.user_id
LEFT JOIN sys_role r ON ur.role_id = r.id

如何实现分组合计？​

在字段配置中设置 isTotal = "1" 的字段会在表格底部显示合计值。适用于金额、数量等数值字段。

报表能导出 Excel 吗？​

可以。Online 报表内置 Excel 导出功能，支持分 sheet 导出（每 sheet 10000 条），自动处理字典翻译和合计。