Skills — 积木报表自动生成

1. 功能介绍

jimureport 是 Claude Code 的 AI Skill，能够将自然语言的报表需求描述或截图转换为积木报表配置，并通过 API 在 JeecgBoot 系统中自动创建/编辑报表。

核心能力：

支持按照截图原样生成报表：提供报表截图/图片，AI 自动识别表格布局、字段和样式，还原生成对应报表
可视化 Excel 设计器风格，支持自由布局、合并单元格、多 Sheet
数据绑定：#{数据集编码.字段名} 模板语法
支持数据填报（submitForm）
精细打印控制：纸张大小、边距、方向
CSS/JS/Python 增强能力
与 Online 报表（cgreport）互补：积木报表侧重复杂布局，Online 报表侧重快速配置

不确定该用哪个 Skill？请查看 AI Skills 技能清单。下载地址：https://github.com/jeecgboot/skills

2. 与 Online 报表的区别

特性	积木报表 (jimureport)	Online 报表 (cgreport)
设计方式	可视化 Excel 设计器	配置式（字段列表）
布局能力	自由布局、合并单元格、多sheet	固定表格列
数据绑定	`#{数据集编码.字段名}`	自动列映射
填报功能	支持（submitForm=1）	不支持
打印配置	精细控制（纸张/边距/方向）	基础打印
增强能力	CSS/JS/Python 增强	无

3. 前置条件

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

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

4. 使用方式

在 Claude Code 中直接用自然语言描述报表需求，或提供报表截图即可。以下是触发关键词：

创建积木报表、积木报表、jmreport、做一个可视化报表、
Excel报表、数据填报、积木设计器、
create jimureport、visual report

5. 交互流程

5.1 操作类型判断

用户意图关键词	操作类型
创建/新建/做一个积木报表	新增报表
修改积木报表/改字段/加数据集/加查询条件	编辑报表（需要报表ID）

5.2 新增报表完整流程

save (空报表)     →  先创建空报表，获取报表ID
queryFieldBySql   →  解析SQL，获取字段列表
saveDb            →  保存数据集（含字段映射、分页配置），关联报表ID
save (完整设计)   →  jsonStr内容放请求体顶层，保存完整报表设计

5.3 编辑报表流程

GET /jmreport/field/tree/{reportId} → 获取所有数据集
GET /jmreport/loadDbData/{dbId}?reportId={reportId} → 获取数据集详情
POST /jmreport/saveDb（传 id = 更新） → 更新 SQL / 参数
GET /jmreport/get/{reportId} → 获取当前 jsonStr
修改 jsonStr 后，POST /jmreport/save → 保存报表设计

6. 接口签名机制

部分接口需要在 Header 中携带 X-Sign 和 X-TIMESTAMP。

需要签名的接口： queryFieldBySql、executeSelectApi、loadTableData、testConnection、download/image、dictCodeSearch、getDataSourceByPage、getDataSourceById

不需要签名的接口： save、saveDb、get/{id}、field/tree/{reportId}、loadDbData/{dbId}

签名算法

收集所有请求参数
所有值转为字符串
按 key 字母升序排序
转为紧凑 JSON 字符串（无空格）
拼接密钥: jsonStr + "dd05f1c54d63749eda95f9fa6d49v442a"
MD5 并转大写

默认签名密钥： dd05f1c54d63749eda95f9fa6d49v442a（注意第29位是字母 v 不是数字 4）时间戳有效期：5 分钟。

7. jsonStr 核心设计

jsonStr 是积木报表的核心设计数据，定义了 Excel 风格的布局。

7.1 行列数据 (rows)

行和列的索引从 1 开始：

{
    "rows": {
        "1": {
            "cells": {
                "1": { "text": "ID", "style": 4 },
                "2": { "text": "名称", "style": 4 }
            },
            "height": 34
        },
        "2": {
            "cells": {
                "1": { "text": "#{ds.id}", "style": 2 },
                "2": { "text": "#{ds.name}", "style": 2 }
            }
        },
        "len": 200
    }
}

第1行：表头行（通常用 style 4，蓝底白字）
第2行：数据绑定行（#{数据集编码.字段名} 语法）

7.2 数据绑定语法

语法	说明	示例
`#{dbCode.fieldName}`	普通字段绑定	`#{sales.amount}`
`=SUM(#{dbCode.fieldName})`	聚合函数	`=SUM(#{sales.amount})`
`=COUNT(#{dbCode.fieldName})`	计数	`=COUNT(#{sales.id})`

7.3 样式 (styles)

通过索引在 cells 中引用：

索引	效果	用途
0	边框	基础单元格
1	边框+居中	文本居中
2	边框+居中+垂直居中	数据行
3	边框+居中+垂直居中+蓝底	表头（无白字）
4	边框+居中+垂直居中+蓝底白字	表头（推荐）

7.4 单元格合并 (merges)

"merges": ["B1:F1"]

格式为 Excel 风格的范围表示。

7.5 打印配置 (printConfig)

属性	说明	可选值
paper	纸张大小	"A4", "A3", "B5", "letter"
width/height	纸张宽高(mm)	A4: 210×297
layout	方向	"portrait"(纵向), "landscape"(横向)
marginX/marginY	边距(mm)	默认10

8. 保存接口格式

POST /jmreport/save

save_data = {
    # 只有 designerObj 是字符串
    "designerObj": json.dumps(designer_obj, ensure_ascii=False),
    # 其他所有字段保持原始对象/数组
    "name": "sheet1",
    "rows": rows_data,          # dict
    "cols": cols_data,           # dict
    "styles": styles_list,       # list
    "merges": merges_list,       # list
    "chartList": chart_list,     # list
    # ...
    "sheetId": "default",
    "sheetName": "默认Sheet",
    "sheetOrder": "0"
}

关键：只有 designerObj 用 json.dumps() 转字符串，其他所有字段保持原始 Python 对象。

9. 高级功能

9.1 分组报表（纵向分组）

当用户要求"按XX分组"时，使用分组语法：

三个必须项：

jsonStr 顶层添加 "isGroup": true 和 "groupField": "数据集编码.分组字段名"
save 请求体中也传这两个字段
分组列使用 #{db.group(field)} 语法

分组单元格属性：

属性	值	说明
`text`	`#{dbCode.group(fieldName)}`	分组绑定，相同值自动合并
`aggregate`	`"group"`	标记为分组聚合列
`subtotal`	`"groupField"`	启用小计/合计行
`funcname`	`"-1"` / `"SUM"` / `"COUNT"` / `"AVG"`	聚合函数
`subtotalText`	`"合计"` / `"小计"`	小计行文本

注意：

SQL 必须按分组字段 ORDER BY
数据集 isPage 设为 "0"（不分页）
支持多级分组

9.2 SQL 参数化与动态条件

-- 基础参数
SELECT * FROM demo WHERE name like '%${name}%'

-- FreeMarker动态条件
select * from demo where 1=1
<#if isNotEmpty(name)> and name = '${name}'</#if>

9.3 查询配置

izOpenQueryBar：是否展开查询栏
izDefaultQuery：是否自动查询
支持文本、下拉单选/多选、范围、模糊、下拉树等控件

9.4 CSS/JS/Python 增强

通过 designerObj 的 cssStr、jsStr、pyStr 字段传入增强代码。

9.5 多 Sheet

设置 isMultiSheet 为 1，通过 sheets 字段管理多个 sheet 页。

9.6 填报模式

设置 submitForm 为 1，启用数据填报功能。

10. 图表与数据表格布局

chart_bottom 布局（表格在上，图表在下）

图表虚拟单元格需放在数据展开区域之后
图表开始行 = 数据绑定行 + pageSize + gap
虚拟单元格只需 1行（不是多行）

合并单元格行号

合并单元格使用 UI 行号（从1开始），公式：ui_row = code_row + 1

11. 智能字段配置

字段显示名称推导

字段名模式	推导中文名
name / title	名称/标题
code / no	编码/编号
status	状态
amount / money / price	金额/费用/价格
count / qty / num	数量
date / time	日期/时间
create_by / update_by	创建人/更新人

是否在报表中显示

规则	是否显示
业务字段（默认）	显示
id / 主键字段	通常隐藏
create_by / update_by	通常隐藏
sys_org_code / tenant_id	隐藏

12. 与其他 Skill 的区别

Skill	产出物	适用场景
`jimureport`	积木报表（可视化Excel设计器）	复杂布局报表、合并单元格、打印、填报
`jeecg-onlreport`	Online 报表（SQL 驱动列表）	简单数据查询报表
`jeecg-onlform`	Online 表单（元数据CRUD）	数据录入管理
`jeecg-desform`	设计器表单 JSON	数据采集、审批表单
`jeecg-codegen`	Java + Vue3 代码 + SQL	自定义业务逻辑模块

13. 常见问题

问题	解决方案
Token 过期（401）	重新获取 X-Access-Token
`code:1001` 签名验证失败	接口需要签名，添加 X-Sign 和 X-TIMESTAMP
`签名校验失败，参数有误！`	检查参数排序、JSON无空格格式、密钥
SQL 解析失败	检查 SQL 语法和表名
数据集编码重复	换一个 dbCode
jsonStr 格式错误	检查 JSON 转义，designerObj 是字符串，其他保持原始对象
中文乱码	使用 Python（不要用 curl）
表格和图表间距过大	图表从 data_binding_row + pageSize + gap 开始
标题重复	合并单元格使用 UI 行号
滚动条不显示	设置 area = False 或在图表底部添加分页符行

1. 功能介绍​

2. 与 Online 报表的区别​

3. 前置条件​

4. 使用方式​

5. 交互流程​

5.1 操作类型判断​

5.2 新增报表完整流程​

5.3 编辑报表流程​

6. 接口签名机制​

签名算法​

7. jsonStr 核心设计​

7.1 行列数据 (rows)​

7.2 数据绑定语法​

7.3 样式 (styles)​

7.4 单元格合并 (merges)​

7.5 打印配置 (printConfig)​

8. 保存接口格式​

9. 高级功能​

9.1 分组报表（纵向分组）​

9.2 SQL 参数化与动态条件​

9.3 查询配置​

9.4 CSS/JS/Python 增强​

9.5 多 Sheet​

9.6 填报模式​

10. 图表与数据表格布局​

chart_bottom 布局（表格在上，图表在下）​

合并单元格行号​

11. 智能字段配置​

字段显示名称推导​

是否在报表中显示​

12. 与其他 Skill 的区别​

13. 常见问题​