qhmes/.trae/skills/jimureport/SKILL.md

---
name: jimureport
description: "Use when user asks to create/edit JiMu reports (积木报表), visual Excel-style reports, or says \"创建积木报表\", \"积木报表\", \"jmreport\", \"做一个可视化报表\", \"Excel报表\", \"数据填报\", \"积木设计器\", \"create jimureport\", \"visual report\". Also triggers when user describes report requirements involving Excel-like layouts, data binding with"
---

# JeecgBoot 积木报表 (JiMu Report) AI 自动生成器

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

> **重要：本 skill 处理「积木报表」（可视化 Excel 风格报表设计器），不涉及「Online 报表」（SQL 驱动的 cgreport）或「Online 表单」（cgform）。**

## 与 Online 报表的区别

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

## 前置条件

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

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

如果用户未提供，提示：
> 请提供 JeecgBoot 后端地址和 X-Access-Token（从浏览器 F12 → Network → 任意请求的 Request Headers 中复制）。

## 接口签名机制

部分接口标记了 `@JimuSignature` 注解，调用时必须在 Header 中携带 `X-Sign` 和 `X-TIMESTAMP`，否则返回 `code: 1001` 签名校验失败。

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

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

### 签名算法

```
1. 收集所有请求参数（URL query + POST body）
2. 所有值转为字符串（数字→str, 布尔→"true"/"false", 对象→JSON字符串）
3. 按 key 字母升序排序
4. 转为紧凑 JSON 字符串（无空格）: json.dumps(sorted_dict, separators=(',', ':'))
5. 拼接密钥: jsonStr + "dd05f1c54d63749eda95f9fa6d49v442a"
6. MD5 并转大写: hashlib.md5(拼接结果.encode()).hexdigest().upper()
```

> **默认签名密钥：** `dd05f1c54d63749eda95f9fa6d49v442a`（注意第29位是字母 `v` 不是数字 `4`）
> 可通过 `jeecg.signatureSecret` 配置覆盖。
> **时间戳有效期：5 分钟。**

详细文档见 `references/signature.md`。

更多参考文档：
- `references/template-analysis.md` - 模板报表分析（46个模板结构、displayConfig条码、循环报表）
- `references/components.md` - 组件配置（图表、图片、条码、二维码）
- `references/chart-templates.md` - 图表模板与ECharts配置
- `references/chart-config.md` - 图表配置详解

## 交互流程

### Step 0: 判断操作类型

| 用户意图关键词 | 操作类型 |
|---------------|---------|
| 创建/新建/做一个积木报表 | **新增报表** → Step 1 |
| 修改积木报表/改字段/加数据集/加查询条件 | **编辑报表** → 需要报表ID，走编辑流程 |

**编辑报表流程：**
1. `GET /jmreport/field/tree/{reportId}` → 获取所有数据集的 `dbCode` 和 `dbId`
2. `GET /jmreport/loadDbData/{dbId}?reportId={reportId}` → 获取数据集详情（含 fieldList）
3. `POST /jmreport/saveDb`（**传 id = 更新**，不传 id = 新增）→ 更新 SQL / 参数
4. `GET /jmreport/get/{reportId}` → 获取当前 jsonStr
5. 修改 jsonStr 内容后，`POST /jmreport/save` → 保存报表设计

详见 `references/dataset-skills.md` 中的"查询已有数据集"章节。

### Step 1: 解析需求

从用户描述中提取：

| 信息 | 默认值 | 示例 |
|------|--------|------|
| 报表名称 (name) | 用户指定 | "销售统计报表" |
| SQL 语句 | 从需求推导或用户提供 | `SELECT ... FROM ...` |
| 数据源 (dbSource) | 空（默认数据源） | `second_db` |
| 是否分页 (isPage) | "1" | "0"=不分页 |
| 是否填报 (submitForm) | 0 | 1=填报模式 |

### Step 2: 调用 SQL 解析接口获取字段

**POST** `/jmreport/queryFieldBySql`

```json
{
    "sql": "select * from demo",
    "dbSource": "",
    "type": "0"
}
```

**返回结构：**
```json
{
    "success": true,
    "result": {
        "paramList": [],
        "fieldList": [
            {
                "fieldName": "id",
                "fieldText": "id",
                "widgetType": "String",
                "orderNum": 1
            }
        ]
    }
}
```

### Step 3: 调用数据集保存接口

**POST** `/jmreport/saveDb`

```json
{
    "izSharedSource": 0,
    "jimuReportId": "报表ID",
    "dbCode": "数据集编码",
    "dbChName": "数据集中文名",
    "dbType": "0",
    "dbSource": "",
    "jsonData": "",
    "apiConvert": "",
    "isList": "1",
    "isPage": "1",
    "dbDynSql": "SQL语句",
    "fieldList": [],
    "paramList": []
}
```

**关键字段说明：**

| 字段 | 说明 | 示例 |
|------|------|------|
| `jimuReportId` | 关联的报表ID | `"1193766682428530688"` |
| `dbCode` | 数据集编码，在jsonStr中通过 `#{dbCode.fieldName}` 引用 | `"sales"` |
| `dbChName` | 数据集中文名称 | `"销售数据"` |
| `dbType` | 数据源类型："0"=SQL, "1"=API, "2"=JavaBean, "3"=JSON, "4"=共享, "5"=多文件, "6"=单文件 | `"0"` |
| `dbSource` | 数据源标识，空=默认 | `""` |
| `isList` | "1"=列表数据 | `"1"` |
| `isPage` | "1"=分页 | `"1"` |
| `dbDynSql` | SQL语句 | `"select * from demo"` |

**fieldList 每个字段的结构：**
```json
{
    "fieldName": "id",
    "fieldText": "id",
    "widgetType": "String",
    "orderNum": 0,
    "tableIndex": 0,
    "extJson": "",
    "dictCode": ""
}
```

### Step 4: 构造报表 jsonStr

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

#### 4.1 jsonStr 完整结构

```json
{
    "loopBlockList": [],
    "querySetting": {
        "izOpenQueryBar": false,
        "izDefaultQuery": true
    },
    "recordSubTableOrCollection": { "group": [], "record": [], "range": [] },
    "printConfig": {
        "paper": "A4",
        "width": 210,
        "height": 297,
        "definition": 1,
        "isBackend": false,
        "marginX": 10,
        "marginY": 10,
        "layout": "portrait",
        "printCallBackUrl": ""
    },
    "hidden": { "rows": [], "cols": [], "conditions": { "rows": {}, "cols": {} } },
    "queryFormSetting": { "useQueryForm": false, "dbKey": "", "idField": "" },
    "dbexps": [],
    "dicts": [],
    "fillFormToolbar": {
        "show": true,
        "btnList": ["save","subTable_add","verify","subTable_del","print","close","first","prev","next","paging","total","last","exportPDF","exportExcel","exportWord"]
    },
    "freeze": "A1",
    "dataRectWidth": 700,
    "isViewContentHorizontalCenter": false,
    "autofilter": {},
    "validations": [],
    "cols": { "len": 100 },
    "area": { "sri": 0, "sci": 0, "eri": 0, "eci": 0, "width": 100, "height": 25 },
    "pyGroupEngine": false,
    "submitHandlers": [],
    "hiddenCells": [],
    "zonedEditionList": [],
    "rows": {
        "1": {
            "cells": {
                "1": { "text": "表头1", "style": 4 },
                "2": { "text": "表头2", "style": 4 }
            },
            "height": 34
        },
        "2": {
            "cells": {    "name": "sheet1",

                "1": { "text": "#{数据集编码.字段1}", "style": 2 },
                "2": { "text": "#{数据集编码.字段2}", "style": 2 }
            }
        },
        "len": 200
    },
    "rpbar": { "show": true, "pageSize": "", "btnList": [] },
    "fixedPrintHeadRows": [],
    "fixedPrintTailRows": [],
    "displayConfig": {},
    "fillFormInfo": { "layout": { "direction": "horizontal", "width": 200, "height": 45 } },
    "background": false,
    "styles": [],
    "fillFormStyle": "default",
    "freezeLineColor": "rgb(185, 185, 185)",
    "merges": []
}
```

#### 4.2 行列数据 (rows)

行和列的索引从 **1** 开始（0行通常为空）。

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

- **第1行**：表头行（通常用 style 4，蓝底白字）
- **第2行**：数据绑定行（用 `#{数据集编码.字段名}` 语法）
- `height`：行高（像素）
- `len`：总行数（默认200）

#### 4.3 数据绑定语法

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

#### 4.4 样式 (styles)

样式数组，通过索引在 cells 中引用：

```json
"styles": [
    {
        "border": { "bottom": ["thin","#000"], "top": ["thin","#000"], "left": ["thin","#000"], "right": ["thin","#000"] }
    },
    {
        "border": { "bottom": ["thin","#000"], "top": ["thin","#000"], "left": ["thin","#000"], "right": ["thin","#000"] },
        "align": "center"
    },
    {
        "border": { "bottom": ["thin","#000"], "top": ["thin","#000"], "left": ["thin","#000"], "right": ["thin","#000"] },
        "align": "center",
        "valign": "middle"
    },
    {
        "border": { "bottom": ["thin","#000"], "top": ["thin","#000"], "left": ["thin","#000"], "right": ["thin","#000"] },
        "align": "center",
        "valign": "middle",
        "bgcolor": "#01b0f1"
    },
    {
        "border": { "bottom": ["thin","#000"], "top": ["thin","#000"], "left": ["thin","#000"], "right": ["thin","#000"] },
        "align": "center",
        "valign": "middle",
        "bgcolor": "#01b0f1",
        "color": "#ffffff"
    }
]
```

**常用样式索引：**

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

#### 4.5 单元格合并 (merges)

```json
"merges": [
    "B1:F1"
]
```
格式为 Excel 风格的范围表示，如 `B1:F1` 表示合并 B1 到 F1。

#### 4.6 打印配置 (printConfig)

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

#### 4.7 查询条件 (querySetting)

```json
"querySetting": {
    "izOpenQueryBar": true,
    "izDefaultQuery": true
}
```

- `izOpenQueryBar`: 是否显示查询栏
- `izDefaultQuery`: 是否默认查询

### Step 5: 调用报表保存接口

**POST** `/jmreport/save`

> **关键格式要求：**
> 1. `designerObj` 是 **JSON 字符串**（不是对象）
> 2. 所有 jsonStr 字段（`rows`、`cols`、`styles`、`merges`、`chartList` 等）都放在请求体**顶层**，每个值都是 **JSON 字符串**（不是对象）
> 3. 必须包含 `sheetId`、`sheetName`、`sheetOrder` 字段
> 4. 后端 `saveReport` 逻辑：`json.remove("designerObj")` 后，剩余的顶层 JSON 直接作为 jsonStr 存入数据库

**请求体结构（只有 designerObj 是字符串，其他都是原始对象）：**

```json
{
    "designerObj": "{\"id\":\"报表ID\",\"name\":\"报表名称\",\"type\":\"0\",\"template\":0,\"delFlag\":0,\"submitForm\":0,\"reportName\":\"报表名称\"}",
    "name": "sheet1",
    "freeze": "A1",
    "freezeLineColor": "rgb(185, 185, 185)",
    "rows": {"1": {"cells": {"1": {"text": "表头", "style": 4}}, "height": 34}, "len": 200},
    "cols": {"len": 100},
    "styles": [],
    "merges": [],
    "validations": [],
    "autofilter": {},
    "dbexps": [],
    "dicts": [],
    "loopBlockList": [],
    "zonedEditionList": [],
    "fixedPrintHeadRows": [],
    "fixedPrintTailRows": [],
    "rpbar": {"show": true, "pageSize": "", "btnList": []},
    "fillFormToolbar": {"show": true, "btnList": ["save","subTable_add","verify","subTable_del","print","close","first","prev","next","paging","total","last","exportPDF","exportExcel","exportWord"]},
    "hiddenCells": [],
    "hidden": {"rows": [], "cols": [], "conditions": {"rows": {}, "cols": {}}},
    "fillFormInfo": {"layout": {"direction": "horizontal", "width": 200, "height": 45}},
    "recordSubTableOrCollection": {"group": [], "record": [], "range": []},
    "displayConfig": {},
    "printConfig": {"paper": "A4", "width": 210, "height": 297, "definition": 1, "isBackend": false, "marginX": 10, "marginY": 10, "layout": "portrait", "printCallBackUrl": ""},
    "querySetting": {"izOpenQueryBar": false, "izDefaultQuery": true},
    "queryFormSetting": {"useQueryForm": false, "dbKey": "", "idField": ""},
    "area": {"sri": 0, "sci": 0, "eri": 0, "eci": 0, "width": 100, "height": 25},
    "submitHandlers": [],
    "chartList": [],
    "background": false,
    "dataRectWidth": 700,
    "excel_config_id": "报表ID",
    "pyGroupEngine": false,
    "isViewContentHorizontalCenter": false,
    "fillFormStyle": "default",
    "sheetId": "default",
    "sheetName": "默认Sheet",
    "sheetOrder": "0"
}
```

**Python 构造示例：**

```python
save_data = {
    # 只有 designerObj 是字符串
    "designerObj": json.dumps(designer_obj, ensure_ascii=False),
    # 其他所有字段都是原始对象/数组，不要 json.dumps
    "name": "sheet1",
    "freeze": "A1",
    "freezeLineColor": "rgb(185, 185, 185)",
    "rows": rows_data,          # dict, 不是字符串
    "cols": cols_data,           # dict
    "styles": styles_list,       # list
    "merges": merges_list,       # list
    "chartList": chart_list,     # list
    "loopBlockList": [],         # list
    "querySetting": {"izOpenQueryBar": False, "izDefaultQuery": True},  # dict
    # ... 其他配置字段同理
    "sheetId": "default",
    "sheetName": "默认Sheet",
    "sheetOrder": "0",
    "background": False,         # 布尔值
    "dataRectWidth": 700,        # 数字
    "excel_config_id": report_id,
    "pyGroupEngine": False,
    "isViewContentHorizontalCenter": False,
    "fillFormStyle": "default"
}
```

> **关键：只有 `designerObj` 用 `json.dumps()` 转字符串，其他所有字段（`rows`、`cols`、`styles`、`merges`、`chartList`、`loopBlockList` 等）都保持原始 Python 对象。如果把它们也 json.dumps 转成字符串，会导致双重序列化，前端解析报错。**

**designerObj 关键字段（JSON 字符串内的对象结构）：**

| 字段 | 说明 | 必填 |
|------|------|------|
| `id` | 报表唯一ID | 是 |
| `code` | 报表编码（如时间戳格式） | 是 |
| `name` / `reportName` | 报表名称 | 是 |
| `type` | 报表分类，默认 `"0"` | 是 |
| `template` | 是否为模板（0否） | 是 |
| `cssStr` | CSS增强代码 | 否 |
| `jsStr` | JS增强代码 | 否 |
| `pyStr` | Python增强代码 | 否 |
| `tenantId` | 租户ID | 否 |
| `submitForm` | 是否填报（0否，1是） | 否 |

**注意事项：**
- **只有 `designerObj` 是字符串**（`json.dumps(obj)`），其他所有字段保持原始对象/数组
- `rows`、`cols`、`styles`、`chartList`、`loopBlockList` 等都是 **原始对象/数组**，禁止 json.dumps
- `background`、`pyGroupEngine`、`isViewContentHorizontalCenter` 是布尔值 `False`
- `dataRectWidth` 是数字（如 `700`）
- 必须传 `sheetId: "default"`、`sheetName: "默认Sheet"`、`sheetOrder: "0"`

### Step 6: 展示摘要并确认

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

```
## 积木报表配置摘要

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

### 数据集配置
| 编码 | 名称 | SQL | 分页 |
|------|------|-----|------|
| sales | 销售数据 | SELECT id, name, amount FROM biz_sales | 是 |

### 表头设计
| 列 | 表头文本 | 数据绑定 |
|----|---------|---------|
| B | ID | #{sales.id} |
| C | 名称 | #{sales.name} |
| D | 金额 | #{sales.amount} |

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

### Step 7: 使用 Python 调用 API

**重要限制：**
1. **Windows 环境下 curl 发送中文/长 JSON 会出错**，必须使用 Python
2. **禁止使用 `python3 -c "..."` 内联方式**
3. **必须先用 Write 工具写入 `.py` 临时文件，再用 Bash 执行，最后删除临时文件**

**完整 Python 脚本模板：**

```python
import urllib.request
import json
import time
import random
import ssl
import hashlib

API_BASE = '{用户提供的后端地址}'
TOKEN = '{用户提供的 X-Access-Token}'
SIGNATURE_SECRET = 'dd05f1c54d63749eda95f9fa6d49v442a'

ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE

# 需要签名的接口列表
SIGNED_ENDPOINTS = [
    '/jmreport/queryFieldBySql',
    '/jmreport/executeSelectApi',
    '/jmreport/loadTableData',
    '/jmreport/testConnection',
    '/jmreport/download/image',
    '/jmreport/dictCodeSearch',
    '/jmreport/getDataSourceByPage',
    '/jmreport/getDataSourceById',
]

def compute_sign(params_dict):
    """计算积木报表接口签名"""
    str_params = {}
    for k, v in params_dict.items():
        if v is None:
            continue
        if isinstance(v, bool):
            str_params[k] = str(v).lower()
        elif isinstance(v, (int, float)):
            str_params[k] = str(v)
        elif isinstance(v, (dict, list)):
            str_params[k] = json.dumps(v, ensure_ascii=False, separators=(',', ':'))
        else:
            str_params[k] = str(v)
    sorted_params = dict(sorted(str_params.items()))
    params_json = json.dumps(sorted_params, ensure_ascii=False, separators=(',', ':'))
    sign_str = params_json + SIGNATURE_SECRET
    return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()

def api_request(path, data=None, method=None):
    url = f'{API_BASE}{path}'
    headers = {
        'X-Access-Token': TOKEN,
        'Content-Type': 'application/json; charset=UTF-8'
    }
    # 自动判断是否需要签名
    need_sign = any(path.rstrip('/').endswith(ep.rstrip('/')) for ep in SIGNED_ENDPOINTS)
    if need_sign:
        sign_params = data if data else {}
        headers['X-TIMESTAMP'] = str(int(time.time() * 1000))
        headers['X-Sign'] = compute_sign(sign_params)
    if data is not None:
        json_data = json.dumps(data, ensure_ascii=False).encode('utf-8')
        req = urllib.request.Request(url, data=json_data, headers=headers, method=method or 'POST')
    else:
        req = urllib.request.Request(url, headers=headers, method=method or 'GET')
    resp = urllib.request.urlopen(req, context=ctx)
    return json.loads(resp.read().decode('utf-8'))

def gen_id():
    return str(int(time.time() * 1000) * 1000000 + random.randint(100000, 999999))

# ====== Step 1: 解析SQL获取字段 ======
parse_result = api_request('/jmreport/queryFieldBySql', {
    "sql": "select * from demo",
    "dbSource": "",
    "type": "0"
})
print('SQL解析结果:', json.dumps(parse_result, ensure_ascii=False, indent=2))

# ====== Step 2: 保存数据集 ======
db_data = {
    "izSharedSource": 0,
    "jimuReportId": "报表ID",
    "dbCode": "demo",
    "dbChName": "示例数据",
    "dbType": "0",
    "dbSource": "",
    "jsonData": "",
    "apiConvert": "",
    "isList": "1",
    "isPage": "1",
    "dbDynSql": "select * from demo",
    "fieldList": parse_result['result']['fieldList'],
    "paramList": []
}
db_result = api_request('/jmreport/saveDb', db_data)
print('数据集保存结果:', json.dumps(db_result, ensure_ascii=False, indent=2))

# ====== Step 3: 构造请求体并保存报表 ======
# 关键: designerObj 是字符串, 所有 jsonStr 字段也是字符串
# 后端逻辑: json.remove("designerObj") 后, 剩余的顶层字段就是 jsonStr

designer_obj = {
    "id": report_id, "name": "报表名称", "type": "0",
    "template": 0, "delFlag": 0, "viewCount": 0, "updateCount": 0,
    "submitForm": 0, "reportName": "报表名称"
}

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

styles_list = [
    {"border": {"bottom": ["thin", "#000"], "top": ["thin", "#000"], "left": ["thin", "#000"], "right": ["thin", "#000"]}},
    {"border": {"bottom": ["thin", "#000"], "top": ["thin", "#000"], "left": ["thin", "#000"], "right": ["thin", "#000"]}, "align": "center"},
    {"border": {"bottom": ["thin", "#000"], "top": ["thin", "#000"], "left": ["thin", "#000"], "right": ["thin", "#000"]}, "align": "center", "valign": "middle"},
    {"border": {"bottom": ["thin", "#000"], "top": ["thin", "#000"], "left": ["thin", "#000"], "right": ["thin", "#000"]}, "align": "center", "valign": "middle", "bgcolor": "#01b0f1"},
    {"border": {"bottom": ["thin", "#000"], "top": ["thin", "#000"], "left": ["thin", "#000"], "right": ["thin", "#000"]}, "align": "center", "valign": "middle", "bgcolor": "#01b0f1", "color": "#ffffff"}
]

# 所有对象/数组字段用 json.dumps 转为字符串
save_data = {
    "designerObj": json.dumps(designer_obj, ensure_ascii=False),
    "name": "sheet1",
    "freeze": "A1",
    "freezeLineColor": "rgb(185, 185, 185)",
    "rows": json.dumps(rows_data, ensure_ascii=False),
    "cols": json.dumps({"len": 100}, ensure_ascii=False),
    "styles": json.dumps(styles_list, ensure_ascii=False),
    "merges": json.dumps([], ensure_ascii=False),
    "validations": "[]",
    "autofilter": "{}",
    "dbexps": "[]",
    "dicts": "[]",
    "loopBlockList": "[]",
    "zonedEditionList": "[]",
    "fixedPrintHeadRows": "[]",
    "fixedPrintTailRows": "[]",
    "hiddenCells": "[]",
    "submitHandlers": "[]",
    "rpbar": json.dumps({"show": True, "pageSize": "", "btnList": []}, ensure_ascii=False),
    "fillFormToolbar": json.dumps({"show": True, "btnList": ["save", "subTable_add", "verify", "subTable_del", "print", "close", "first", "prev", "next", "paging", "total", "last", "exportPDF", "exportExcel", "exportWord"]}, ensure_ascii=False),
    "hidden": json.dumps({"rows": [], "cols": [], "conditions": {"rows": {}, "cols": {}}}, ensure_ascii=False),
    "fillFormInfo": json.dumps({"layout": {"direction": "horizontal", "width": 200, "height": 45}}, ensure_ascii=False),
    "recordSubTableOrCollection": json.dumps({"group": [], "record": [], "range": []}, ensure_ascii=False),
    "displayConfig": "{}",
    "printConfig": json.dumps({"paper": "A4", "width": 210, "height": 297, "definition": 1, "isBackend": False, "marginX": 10, "marginY": 10, "layout": "portrait", "printCallBackUrl": ""}, ensure_ascii=False),
    "querySetting": json.dumps({"izOpenQueryBar": False, "izDefaultQuery": True}, ensure_ascii=False),
    "queryFormSetting": json.dumps({"useQueryForm": False, "dbKey": "", "idField": ""}, ensure_ascii=False),
    "area": json.dumps({"sri": 0, "sci": 0, "eri": 0, "eci": 0, "width": 100, "height": 25}, ensure_ascii=False),
    "chartList": "[]",
    "background": "false",
    "dataRectWidth": "700",
    "excel_config_id": report_id,
    "pyGroupEngine": "false",
    "isViewContentHorizontalCenter": "false",
    "fillFormStyle": "default",
    "sheetId": "default",
    "sheetName": "默认Sheet",
    "sheetOrder": "0"
}
save_result = api_request('/jmreport/save', save_data)
print('报表保存结果:', json.dumps(save_result, ensure_ascii=False, indent=2))
```

## 典型工作流总结

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

**关键注意事项：**
- Step 1 创建空报表时，`save` 接口首次调用会返回 `isRefresh: true`，此时报表已创建
- Step 4 的 `save` 请求体格式：`designerObj`（元数据）+ jsonStr 内容（rows/cols/styles 等）放在**同一层级**
- 禁止将 jsonStr 嵌套在 `designerObj.jsonStr` 字符串中，否则后端会清空 rows 数据
- `designerObj.type` 默认值为 `"0"`，不要传分类名称字符串（如 "demo"）

## 智能字段配置

### 字段显示名称推导

| 字段名模式 | 推导中文名 |
|-----------|-----------|
| id | ID/主键 |
| name / title | 名称/标题 |
| code / no | 编码/编号 |
| status | 状态 |
| amount / money / price / salary | 金额/费用/价格/薪资 |
| count / qty / num / age | 数量/年龄 |
| date / time / birthday | 日期/时间/生日 |
| create_by / update_by | 创建人/更新人 |
| create_time / update_time | 创建时间/更新时间 |
| sex | 性别 |
| email | 邮箱 |
| phone / mobile / tel | 电话/手机号 |
| content / remark | 内容/备注 |
| sys_org_code | 组织编码 |
| tenant_id | 租户ID |

### 是否在报表中显示

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

## 高级功能

### SQL 参数化与动态条件

积木报表支持在SQL中使用参数和FreeMarker动态条件：

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

-- FreeMarker动态条件（参数为空时自动跳过）
select * from demo where 1=1
<#if isNotEmpty(name)> and name = '${name}'</#if>
<#if isNotEmpty(age)> and age = '${age}'</#if>

-- IN查询（v1.6.2+）
select * from demo where sex in(${DaoFormat.in('${sex}')})
select * from demo where age in(${DaoFormat.inNumber('${age}')})
```

### 查询配置

报表支持丰富的查询控件（文本、下拉单选/多选、范围、模糊、下拉树），详见 `references/query-config.md`。

关键配置点：
- **querySetting**：`izOpenQueryBar`(展开查询栏) / `izDefaultQuery`(自动查询)
- **控件默认值**：静态值 / `=dateStr('yyyy-MM-dd')` / `#{sysUserCode}`
- **JS增强**：级联下拉 `updateSelectOptions()` / 监听变化 `onSearchFormChange()`
- **参数优先级**：查询条件值 > URL参数 > 默认值

### 分组报表（纵向分组）

当用户要求"分组报表"、"按XX分组"、"按XX统计"时，必须使用分组语法，**不要**用普通的汇总SQL+明细SQL拆分方式。

#### 核心配置（3个必须项）

1. **jsonStr 顶层**添加分组标记：
```json
{
    "isGroup": true,
    "groupField": "数据集编码.分组字段名"
}
```

2. **save 请求体**中也要传这两个字段（与 rows/cols 同级）：
```python
save_data = {
    ...
    "isGroup": True,
    "groupField": "users.sex_name",
    ...
}
```

3. **分组列单元格**使用 `#{db.group(field)}` 语法，并配置聚合属性：
```json
{
    "text": "#{users.group(sex_name)}",
    "aggregate": "group",
    "subtotal": "groupField",
    "funcname": "-1",
    "subtotalText": "合计"
}
```

#### 分组单元格属性

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

#### 多级分组

从左到右为高到低级别，每级用不同的 `subtotalText` 区分：
- 一级分组（如起始站）：`subtotalText: "合计"` — 一级分组切换时显示
- 二级分组（如终止站）：`subtotalText: "小计"` — 二级分组切换时显示
- `groupField` 始终指向**一级（最高级）分组字段**

**多级分组示例（按起始站+终止站分组）：**
```json
// save 请求体
{
    "isGroup": true,
    "groupField": "jp.kaishi",  // 指向一级分组字段
    ...
}

// 数据绑定行 cells
"1": {
    "text": "#{jp.group(kaishi)}",    // 一级分组
    "aggregate": "group",
    "subtotal": "groupField",
    "funcname": "-1",
    "subtotalText": "合计"
},
"2": {
    "text": "#{jp.group(jieshu)}",    // 二级分组
    "aggregate": "group",
    "subtotal": "groupField",
    "funcname": "-1",
    "subtotalText": "小计"
},
"3": {"text": "#{jp.bnum}"},          // 普通字段
```

#### 分组报表布局示例

```
第1行: 标题（合并单元格）
第2行: 表头（起始站 | 终止站 | 班次号 | 发车时间 | ...）
第3行: 数据绑定行（#{db.group(kaishi)} | #{db.group(jieshu)} | #{db.bnum} | ...）
```

预览效果：
```
┌────────┬────────┬────────┬──────────┐
│ 起始站  │ 终止站  │ 班次号  │ 发车时间  │
├────────┼────────┼────────┼──────────┤
│        │        │ K7725  │ 21:13    │
│        │ 邯郸   ├────────┼──────────┤
│ 北京西  │        │        小计       │
│        ├────────┼────────┼──────────┤
│        │ 深圳   │ G101   │ 06:44    │
│        │        │        小计       │
├────────┼────────┼────────┼──────────┤
│        │        │        合计       │
└────────┴────────┴────────┴──────────┘
```

#### 注意事项
- SQL 中必须按分组字段 `ORDER BY`，确保相同值相邻（多级分组时按一级、二级顺序排序）
- 数据集 `isPage` 设为 `"0"`（不分页），否则分组合并可能不完整
- `pyGroupEngine` 保持 `false`（标准分组不需要 Python 引擎）
- 列数较多时（>6列），考虑将 `printConfig.layout` 设为 `"landscape"`（横向打印）
- 完整示例见 `examples/vertical-group-subtotal-example.md`

#### 数据探查

`queryFieldBySql` 只返回字段元数据，不返回实际数据行。当需要了解数据内容以判断分组字段时：
- 优先通过 **pymysql 连接本地数据库**查看实际数据（`SELECT DISTINCT`、`GROUP BY` 等）
- 本地数据库名通常为 `jeecgboot3`（可通过 `SHOW DATABASES LIKE '%jeecg%'` 确认）
- 查看数据后再确定哪些字段适合作为分组依据

### CSS/JS/Python 增强

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

### 多 Sheet

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

### 填报模式

设置 `submitForm` 为 1，启用数据填报功能，允许用户在报表中录入数据。

## 错误处理

| 错误 | 解决方案 |
|------|---------|
| Token 过期（401/认证失败） | 提示用户重新获取 X-Access-Token |
| `code:1001` 签名验证失败 | 接口需要签名，需在 Header 添加 X-Sign 和 X-TIMESTAMP，详见签名机制章节 |
| `签名验证失败:X-TIMESTAMP已过期` | 客户端与服务器时间差超过5分钟，检查系统时间 |
| `签名校验失败，参数有误！` | 签名计算不匹配，检查参数排序、JSON无空格格式、密钥是否正确 |
| SQL 解析失败 | 检查 SQL 语法是否正确，表是否存在 |
| 数据集编码重复 | 换一个 dbCode |
| jsonStr 格式错误 | 检查 JSON 字符串转义是否正确 |
| 中文乱码 | 确认使用 Python urllib（不要用 curl） |

## 与其他 Skill 的区别

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

## 图表与数据表格布局实战经验

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

**核心问题：** 积木报表的数据绑定行在预览时会展开显示多页数据，导致图表位置被推后。

**解决方案：**
1. 图表虚拟单元格需要放在数据展开区域之后
2. 图表开始行 = 数据绑定行 + pageSize + gap
3. 示例：数据绑定行=3, pageSize=10, gap=1 → 图表从第14行开始

```python
# 布局计算公式
page_size = config.get('pageSize', 10)
gap = config.get('gap', 1)  # 默认1行间距，负值可减少间距
data_binding_row = 3  # 标题行(1) + 表头行(2) + 数据绑定行(3)
chart_start = data_binding_row + page_size + gap  # 14
```

### 虚拟单元格行数

**关键发现：** 图表的 `virtualCellRange` 只需要 **1行**（不是多行）。

错误做法（早期版本）：
```python
row_count = (chart_height // 25) + 2  # 300px高度 = 14行
```

正确做法：
```python
row_count = 1  # 只用1行作为锚点，图表大小由width/height控制
```

设计器保存后的实际结构：
- 图表虚拟单元格只有1行
- 图表位置由 `chartList[].row` 和 `chartList[].width/height` 决定

### area 和 dataRectWidth 设置

为确保预览正确显示，需要设置正确的 `area` 和 `dataRectWidth`：

```python
# 计算列宽总和
total_width = sum(col.get('width', 100) for col in cols.values() if isinstance(col, dict))

# area 定义内容边界（告诉前端报表的实际范围）
# 注意：设计器保存后会重新计算 area，建议在图表底部添加2-3行空行来确保滚动正常
area = {
    "sri": 1,           # 起始行（UI行号）
    "sci": 1,           # 起始列
    "eri": chart_start, # 结束行（图表开始的行）
    "eci": col_count,   # 结束列
    "width": total_width,
    "height": title_h + header_h + (chart_start - 3) * row_h + chart_h
}
```

**滚动问题的解决方案（已自动化）：**

脚本已自动处理滚动条问题，无需手动操作：

1. 设置 `area = False`，让系统自动计算滚动高度
2. 在图表底部自动添加分页符行（位置 = chart_start + pageSize + 3）

```python
# 在图表下方添加分页符行（使用空格避免显示"1"）
pagination_row = chart_start + pageSize + 3
all_rows[str(pagination_row)] = {"cells": {"1": {"text": "   "}}}
```

这样系统就能正确识别滚动区域，滚动条自动正常工作。

### 合并单元格行号

**重要：** 合并单元格使用 **UI 行号**（不是代码行号）。

- 代码行号从 0 开始（但 rows 中的 key 从 "1" 开始）
- UI 行号从 1 开始
- 公式：`ui_row = code_row + 1`

示例：
```python
# 标题在代码第1行，合并 C1:H1
ui_row = 1 + 1  # = 2
merges.append(f"C{ui_row}:H{ui_row}")  # "C2:H2"
```

### 预览地址带 Token

报表预览地址需要携带 token 参数：

```
https://api3.boot.jeecg.com/jmreport/view/{report_id}?token={X-Access-Token}
```

### 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 表格和图表间距过大 | 图表虚拟单元格放在了数据展开区域内 | 图表从 `data_binding_row + pageSize + gap` 开始 |
| 图表与数据重叠 | 虚拟单元格行数过多 | 虚拟单元格只用1行 |
| 设计器与预览效果不一致 | area 设置不正确 | 设置正确的 area.sri/eri |
| 滚动条不显示 | area 范围计算错误 | 确保 area.eri 等于图表实际开始的行 |
| 间距仍偏大 | gap 默认值过大 | 将 gap 改为负值（如 -5）可以减少间距 |
| 滚动幅度太小 | 内容总高度不够 | 在图表底部添加2-3行空行或分页符，增加总高度 |