Imported from Zc86-bir/novaBoot-v5.9 (.claude/skills/jimureport/SKILL.md). Install upstream with npx skills add Zc86-bir/novaBoot-v5.9 --skill jimureport. Copyright stays with the author.

积木报表 AI 生成器

不涉及「Online 报表」（cgreport）或「Online 表单」（cgform）。

一键脚本（必看，覆盖三类全场景）

写自定义 JSON / Python 之前，先看用户需求是否命中下表现成脚本，命中则直接调用，禁止重新组装 JSON 或 Python：

命中规则与禁止事项

• 关键词命中即用：用户说「生成全部图表」「全图表测试」「演示所有图表」「测试 SQL/API/JSON 三种数据集」时，第一反应就是 generate_all_reports.py，不要回头自己写 chart_entry/echarts 模板
• 3 秒能跑完：实测 ~3.1s 端到端创建。脚本启动后不要分块等待、不要发 AskUser 求确认，直接 Bash 等结果
• Mock 新建必须用唯一路径：create_mock 遇到同路径会静默覆盖已有接口数据，污染他人接口。创建新接口时必须在路径末尾追加时间戳或序号（如 /sales_20260427），只有用户明确说"修改/更新已有接口"时才可复用原路径
• saveDb 串行：脚本已改为串行调用 save_db，避免 jimu_report_db_field INSERT 并发引发 MySQL deadlock
• 新增图表类型时：在 CHARTS 列表加一行，写一个 tpl_xxx 函数即可，无需重写主流程

执行流程

第零步（必须）：Token 优先

用户消息里没有 X-Access-Token 时，立刻询问，拿到 token 后再读任何文件。等待回复期间不要预读文件——等待时间不计入 3 分钟，文件读取时间计入。

第一步（必须）：按「执行速度规范」表选最小文件集

不要先 Glob examples/，直接查下方「执行速度规范」表，按场景只读指定文件。禁止在表外额外读文件。 场景匹配优先于文件名匹配：multi-level-header.md 主要是交叉表 groupRight/dynamic，纵向分组+静态多级表头不要读它（浪费 ~30s 读不适用示例）。

读完指定文件后直接 Write JSON 配置 → 执行 CLI 命令 → 输出预览链接。两步完成，禁止多余动作。

报表链接格式（创建成功后直接输出，禁止调接口验证是否存在）：

• 设计器：http://{host}/jmreport/index/{report_id}?token={token}&tenantId=1
• 预览：http://{host}/jmreport/view/{report_id}?token={token}&tenantId=1

报表名称规则：用户明确指定名称时直接使用；未指定时 AI 自动生成名称，生成后须调 GET /jmreport/query/report/folder?pageNo=1&pageSize=10&reportType=&name={name}&token={token} 检查是否重复，有同名则追加后缀（如 _2、_20260415）。

utils 子模块速查（需确认某函数签名时，Grep 对应小文件，禁止读全量 jimureport_utils.py）：

Windows 执行环境（强制规则，违反会让用户吐槽"执行太慢"）

现象：Windows 的 Bash tool 会把 python / python -c / skill 脚本当作长命令自动 run_in_background，tool 立即返回 background ID，真正输出要等完成通知——把毫秒级调用放大到数秒，历史上多次让单报表从 1 分钟拖到 18 分钟。

规则：

• Windows（platform=win32） → 用 Bash tool 调用 powershell -Command "python xxx.py"，同步返回。
• Linux / macOS → 用 Bash tool 直接调用 python xxx.py。
• 任何平台都不用 curl：跨平台不一致，Windows Bash 下同样被后台化。

脚本执行前强制检查（4 项，缺一不可）：

1. ✅ Windows 下用 powershell -Command "python xxx.py"，不是直接 python xxx.py
2. ✅ 脚本已写入 .py 文件（禁止 python -c 内联代码）
3. ✅ 脚本第一行已加编码声明：import sys; sys.stdout.reconfigure(encoding='utf-8')（防 GBK 崩溃重试）
4. ✅ 已读过 references/pitfalls.md（任何场景都必须，防止踩已记录的坑）

Windows 正确示例：

Bash: powershell -Command "python <skill_base_dir>/scripts/xxx.py --base-url ... --token ..."

<skill_base_dir> 是本 SKILL.md 所在目录，运行时用实际路径替换，禁止写死 C:/Users/...。

Windows 错误示例（会被后台化，用户立即感知到"卡"）：

Bash: python generate_all_reports.py ...    ← 返回 "Command running in background with ID: xxx"
Bash: python -c "..."                        ← 同上
Bash: curl -X POST ...                       ← 同上

历史教训：曾因默认走 Bash + python 被用户连续吐槽"执行太慢了 / 生成这么慢"。根因是 Bash tool 在 Windows 对 python 也会后台化，不限于 curl。另一常见重试原因：脚本缺编码声明导致 UnicodeEncodeError: 'gbk' codec，加第3项检查可消除。

前置条件

用户须提供 X-Access-Token。

SQL 数据集数据源选取（用户未指定 dbSource 时必须执行）

用户未指明数据源时，先调 GET /jmreport/initDataSource（带 token header），按以下规则处理：

接口返回字段：每项包含 id（传给 db_source）和 name（展示给用户）。

脚本中直接调用（禁止在脚本里重新手写此逻辑）：

from jimureport_utils import resolve_db_source
# 用户未指定数据源时：
db_source = resolve_db_source(session)   # 自动选含「积木」的；无则抛 RuntimeError 列出清单

RuntimeError 消息已包含数据源列表，捕获后直接转告用户即可。

上下文优先：本次对话中已经通过 resolve_db_source 或用户回复确定过 db_source，后续同一会话的报表直接复用，不得重复调用 initDataSource。

API 数据集前置询问（用户未提供 API 地址时必须先问）

用户未给出 API 地址时，必须先询问：

请问接口用哪种方式创建？

• mock 接口：通过 YApi 创建 mock 接口（参见下方「YApi Mock 数据源」章节）
• 本地代码：请提供本地 JeecgBoot 项目路径，我直接把 Controller 写入项目

收到答复后的处理规则：

🚀 CLI 创建（一条命令）

python /scripts/jimureport_creator.py \
  --api-base http://BASE_URL --token TOKEN --config /path/to/config.json

配置 A：SQL 普通/分组报表

{
  "action": "create", "reportName": "报表名称", "theme": "blue",
  "datasets": [{"dbCode":"ds1","dbChName":"数据集","dbDynSql":"SELECT col1,col2 FROM t ORDER BY col1","dbSource":"","isPage":"0"}],
  "table": {"datasetCode":"ds1","title":"报表名称","columns":[
    {"field":"col1","title":"列1","width":120,"group":true},
    {"field":"col2","title":"列2","width":100,"funcname":"SUM"}
  ]}
}

columns 可选属性：group:true(分组) / funcname:"SUM"(聚合) / subtotalText:"小计"

配置 B：SQL + 图表

{
  "action":"create","reportName":"名称","layout":"chart_bottom",
  "datasets":[
    {"dbCode":"dt","dbChName":"表格","dbDynSql":"SELECT ...","isPage":"1"},
    {"dbCode":"dc","dbChName":"图表","dbDynSql":"SELECT x AS name,y AS value,'' AS type FROM ...","isPage":"0"}
  ],
  "table":{"datasetCode":"dt","title":"名称","columns":[...]},
  "chart":{"datasetCode":"dc","chartType":"bar.simple","title":"图表","width":"650","height":"380"}
}

layout: chart_bottom / chart_top / chart_right / chart_only

配置 C：JSON 数据集（dbCode 必须字符串！）

{
  "action":"create","reportName":"名称",
  "datasets":[{"dbCode":"my_data","dbChName":"数据","dbType":"3","isList":"1","isPage":"0",
    "jsonData":[{"name":"张三","age":"25"}],
    "fieldList":[["name","姓名"],["age","年龄"]]}],
  "table":{"datasetCode":"my_data","title":"名称","columns":[
    {"field":"name","title":"姓名","width":100},{"field":"age","title":"年龄","width":80}]}
}

禁止纯数字 dbCode（如 gen_code()），JSON 数据集模板引擎无法解析。

f-string 写绑定字段时必须转义花括号：f"#{{{db_code}.{field}}}" → 生成 #{db_code.field}。若写成 f"#{db_code}.{field}#" 则花括号被 Python 吃掉，变成 #db_code.field#（格式错误，末尾多 #，数据不渲染）。

配置 D：自定义 rows（复杂多级表头）

build_table_rows 无法满足时（如四级合并表头），传 customRows + customMerges 跳过自动构建：

{
  "action":"create","reportName":"名称",
  "datasets":[{"dbCode":"ds1","dbType":"3","jsonData":[...],"fieldList":[...]}],
  "table":{"datasetCode":"ds1","columns":[{"field":"f1","title":"F1","width":100}]},
  "groupField":"ds1.group_field",
  "customRows":{"1":{"cells":{"1":{"text":"标题","style":0,"merge":[0,5]}},"height":40}},
  "customMerges":["B2:G2"],
  "customStyles":[{"align":"center","font":{"size":16,"bold":true}},{"align":"center","font":{"bold":true,"color":"#FFF"},"bgcolor":"#4472C4"},{"align":"center","valign":"middle"}],
  "customCols":{"0":{"width":27},"1":{"width":100},"len":100}
}

修改已有报表

# get_report → 改 design → base_save(**design 展开，get_report 返回的 design 是安全的)
designer, design = get_report(session, report_id)
design["rows"]["3"]["cells"]["1"]["text"] = "新值"
design["chartList"] = filled_charts   # 如有图表回填，直接替换 chartList
session.request("/save", base_save(report_id, designer, **design))
# ↑ get_report 返回的 design 只含 base_save 接受的 key，**design 展开无冲突
# 注意：手动拼的 design dict 禁止 **展开，必须显式列出 rows/cols/styles/merges/chartList

⚠️ Bug 修复必须用 patch 脚本，禁止重跑创建脚本 任何情况下发现已有报表存在问题（无论是用户反馈还是 AI 自己发现），正确做法是写一个独立 patch 脚本（get_report → 改局部字段 → base_save 回写；数据集错误用 update_db），不得修改并重新执行创建脚本。重跑创建脚本会生成新 ID 的报表，原报表（含已配置的权限、分享链接、引用关系）不会被修复，且产生垃圾报表。

报表大类

积木报表分为两大类，默认为数据报表：

数据报表类型判断

单元格绑定字段名获取

写 #{dbCode.fieldName} 绑定前，不得凭 SQL 别名手写字段名。

直接用 parse_sql 返回的 fieldName（推荐，最快）：

fl = parse_sql(session, sql)
fields = [f["fieldName"] for f in fl]
# MySQL 将所有别名转小写，AS totalAmount → totalamount，直接用即可

/field/tree/{reportId} 是备用方案（需报表先 /save 存在才能调），parse_sql 已返回同样的真实字段名，无需多一次调用。

性能优化（单报表推荐模板）

单报表单数据集场景，以下 3-step 流程总 HTTP ≤ 5 次（含数据源已存在的 1 次）。实测端到端 ~0.8s。

from jimureport_utils import (
    Session, gen_id, make_designer, make_styles, base_save, report_urls,
    ensure_datasource, parse_and_save_dataset,   # ← 推荐新路径
)

session = Session(BASE_URL, TOKEN)

# ① 确保数据源存在（1-2 HTTP，已存在时只 1 次）
ds_id = ensure_datasource(
    session, name="mongodb", db_type="mongodb",
    db_url="<db_host>:27017/<db_name>",
    db_username="qqyun", db_password="qqyun188"
)

# ② 预生成 report_id（客户端，0 HTTP）
report_id = gen_id()

# ③ parse_sql + saveDb 组合（2 HTTP，report_id 允许尚不存在）
sql = f"select * from mongo.{COLLECTION}"
field_list, db_id = parse_and_save_dataset(
    session, report_id, DB_CODE, "中文名", sql,
    db_source=ds_id, is_list="1", is_page="1"
)

# ④ 构建 rows/cols/styles 后，首次 /save —— 一步创建报表 + 写入布局（1 HTTP）
designer = make_designer(report_id, REPORT_NAME)
session.request("/save", base_save(report_id, designer,
    rows=rows, cols=cols, styles=styles, merges=merges, chartList=[]))

关键原理：saveDb 接受尚不存在于服务端的 report_id（orphan），后续 /save 以此 id 首次创建报表时，数据集会正确绑定。实测验证通过。 addDataSource 返回 result: true（不返回 id），新建后必须再查一次；/initDataSource 无签名比 /getDataSourceByPage 快。

仍可用的旧路径（保留兼容）

parallel_init_and_parse 已不推荐但保留 —— 旧脚本无需修改。新脚本一律用 parse_and_save_dataset。

API 数据集快速路径（2 HTTP，实测 ~0.5s）

API 数据集无需 queryFieldBySql，字段手动定义，整个流程只需 2 次 HTTP：

from jimureport_utils import Session, gen_id, make_designer, base_save, save_db

session = Session(BASE_URL, TOKEN)

# ① 客户端生成 report_id（0 HTTP）
report_id = gen_id()

# ② saveDb：orphan report_id 合法，直接绑定（1 HTTP）
field_list = [
    {"fieldName": "f1", "fieldText": "字段1", "widgetType": "String", "orderNum": 0, "tableIndex": 0, "extJson": "", "dictCode": ""},
    # ... 其余字段
]
save_db(session, report_id, DB_CODE, "数据集名称",
        API_URL, field_list,
        db_type="1", api_url=API_URL, api_method="0",
        is_list="1", is_page="0")

# ③ /save：首次创建报表 + 完整设计一步完成（1 HTTP）
designer = make_designer(report_id, REPORT_NAME)
session.request("/save", base_save(
    report_id, designer,
    rows=rows, cols=cols, styles=styles, merges=merges, chartList=[],
    isGroup=True, groupField=f"{DB_CODE}.group_field",   # 交叉/分组报表需要
))

实测：区域省份销售额交叉报表，3 步 ~3s → 2 步 ~0.5s（2026-04-22 验证）。 适用场景：所有 API 数据集报表（交叉表、分组表、明细表均可）。

MongoDB / NoSQL 数据源特别说明

• testConnection 仅检测 TCP 连通，不验证账号密码。它返回 success 不代表凭证正确。
• 真实鉴权发生在 queryFieldBySql / 预览时。凭证错会在这两步报 Exception authenticating。
• 禁止在创建脚本里尝试多种格式（标准分离 / 连接串 / 多 authSource）的试错循环 —— 白白浪费 3-6 秒。只试用户给的一种，失败立刻报错让用户检查 MongoDB 服务端 db.getUsers()。

性能优化（多数据集 / 多报表场景）

核心原则：能并行的全部并行，消灭串行等待。

from jimureport_utils import parallel_parse_sqls, parallel_save_dbs, parallel_create_links
from concurrent.futures import ThreadPoolExecutor

# ① 并行解析所有 SQL（一轮完成）
fl_a, fl_b, fl_c = parallel_parse_sqls(session, [
    {"sql": sql_a}, {"sql": sql_b}, {"sql": sql_c},
])

# ② 并行保存所有数据集（一轮完成）
db_id_a, db_id_b, db_id_c = parallel_save_dbs(session, [
    {"report_id": rid, "db_code": "dsA", "sql": sql_a, "field_list": fl_a, ...},
    {"report_id": rid, "db_code": "dsB", "sql": sql_b, "field_list": fl_b, ...},
    {"report_id": rid, "db_code": "dsC", "sql": sql_c, "field_list": fl_c, ...},
])

# ③ 并行创建所有钻取/联动（一轮完成）
link1, link2, link3 = parallel_create_links(session, [
    {"report_id": rid, "link_name": "钻取1", "link_type": "0", ...},
    {"report_id": rid, "link_name": "钻取2", "link_type": "0", ...},
    {"report_id": rid, "link_name": "联动1", "link_type": "2", ...},
])

# ④ 多张报表最终 /save 并行
with ThreadPoolExecutor(max_workers=2) as ex:
    f1 = ex.submit(lambda: session.request("/save", base_save(rid1, d1, ...)))
    f2 = ex.submit(lambda: session.request("/save", base_save(rid2, d2, ...)))
    f1.result(); f2.result()

行列索引规则

• 全部 0-indexed，A列(col0)留空，数据从 col1(B列)开始
• merge: [extraRows, extraCols]，0=只占自身
• merges 用 Excel 记法："B2:F2"（UI行号 = code行号+1）

分组汇总

🚨 分组列开 subtotal:"groupField" 时，所有数值列必须默认 aggregate:"select" + funcname:"SUM"——否则小计/合计行的数值单元格全部空白，UI 上"显示了合计标签 + 数值列空白"是绝对不允许的折中状态。要嘛不显示合计行（分组列改 subtotal:"-1"、subtotalText:""），要嘛数值列全部默认求和。AI 不得只搬模板里"分组列带 subtotal、数值列裸 text"的写法。

funcname 聚合函数值（⚠️ 必须严格使用以下字符串，写错则不生效）

分组列 vs 聚合列属性对比

查询参数（paramList）

含查询控件时读 references/query-params.md § 0（含 SQL FreeMarker 条件、widgetType/searchMode 对照表、日期范围拆分规则）。

字段查询 vs 报表参数查询（必读规则）

核心规则：字段查询时 JimuReport 引擎自动处理过滤，SQL 保持纯净；只有使用报表参数时才在 SQL 中添加 FreeMarker WHERE 条件。两种方式不能混用。

样式规范（必读约定，无需用户提醒）

• 所有表格报表必须带 border：优先用 from jimureport_utils import make_styles 的 5 种预置样式（索引 0-4）
• col0 始终留白 30px 不加边框：标题行从 col1 开始合并（merges 写 B1:F1 不含 A 列）。make_styles() 预置样式 0-4 均含边框，col0 必须单独追加无边框样式：

  styles = make_styles()
  styles.append({"align": "center"})  # index 5：col0 专用，无边框
  # 所有行的 col0 统一用 style: 5
  "0": {"text": "", "style": 5}

• 自定义样式时 border 必须嵌套（不能 ** 展开到顶层），color（文字色）与 font 平级放 style 顶层
• ⚠️ 凡是自定义 styles 数组或修改单元格配置，必须先读 references/styling.md，不得凭经验猜属性层级（color 在顶层而非 font 内是高频踩坑点，引擎静默忽略错误写法）

完整规范 + col0 留白模板代码 → references/styling.md

图表类型速查

含图表时读 references/chart-types-quickref.md（系统名称 → chartType 对照 + series 字段取值 + 地图数据语义规则）。 完整 ECharts 配置模板 → references/chart-echarts-templates.md。

执行速度规范（3分钟内完成）

文件读取按场景取最小集，只读表中指定的文件，不得额外读其他文件：

pitfalls.md 读取规则：仅「普通表格/无分组」行要求全节读取；其他场景遇到运行时报错时，按 pitfalls.md 顶部症状索引找对应节，用 Read(offset=N, limit=40) 只读该节（不要全读，9 个节每节约 20 行）。

API 数据集 + customGroup 快速路径（用户提供了 API URL + token 时，不超过 3 步）：

1. 读 references/horizontal-grouping.md §5.3.2 拿到模板
2. 在脚本里调 parse_api(session, api_url) 获取字段名（1 次 HTTP，合并进脚本，不单独执行）
3. 替换模板中的字段名 → PowerShell 执行脚本

自定义图表脚本规范（含 SQL/API 数据集）

写自定义图表脚本前必须先确认以下规范，杜绝反复调试。

# ① BASE_URL 必须含 /jmreport
session = Session("http://host:port/jmreport", TOKEN)

# ② make_designer：首次 /save 时 report_id 传空字符串
designer = make_designer("", REPORT_NAME)
# !! 拿到 report_id 后，最终保存前必须重新构造 designer（带真实 id），否则单元格数据不会写入 !!
# designer = make_designer(report_id, REPORT_NAME)  ← 最终保存前用这个

# ③ rows 必须带 "len" key
rows = {"len": 200, "1": {"height": 25, "cells": {}}, ...}

# ④ base_save 前两个参数是位置参数，不可用关键字
resp = session.request("/save", base_save("", designer, rows=rows, cols=cols, styles=styles, merges=[], chartList=[]))

# ⑤ 首次 /save 返回的 result 是 dict，取 id
report_id = resp["result"]["id"]

# ⑥ save_db 位置参数顺序（第4个是 db_name，不是 db_ch_name）
db_id = save_db(session, report_id, "db_code", "中文名", sql_or_empty, field_list,
                db_type="1", api_url=mock_url, ...)   # API 数据集
# ⚠️ JSON数据集（db_type="3"）json_data 必须包裹 {"data":[...]}，不能传裸数组：
#    json_data=json.dumps({"data": raw_list}, ensure_ascii=False)

# ⑦ 图表回填：SQL → /qurestSql (result 是 list)；API → /qurestApi (result["data"] 是 list)
# 完整代码见 references/chart-echarts-templates.md § SQL/API 图表数据回填

# ⑧ 最终保存：get_report 返回的 design 可直接 **展开
designer2, design2 = get_report(session, report_id)
design2["chartList"] = filled_charts
session.request("/save", base_save(report_id, designer2, **design2))

已知坑点（必读）

写脚本前先 Read references/pitfalls.md，避免踩坑重试浪费时间。 写循环块报表前必须先 Read references/loopblock-grouping.md，里面有完整配置模板，禁止从头自己写。 ⚠️ API 数据集有 paramList 时，apiUrl 末尾必须加 ?paramName=${paramName}，否则联动/钻取参数传不进去。多参数用 & 连接。写完 save_db 后立即目视检查 api_url 字符串含占位符。 ⚠️ 交叉表（groupRight+dynamic）底部跟随分组扩展统计行：必须用独立静态行 + rightFollowExten:"follow" + Excel公式（如 =MAX(G6)），dynamic 单元格的 funcname 必须设为 "-1"，禁止设为 "MAX"/"MIN"/"SUM"——那不会生成跟随横向扩展的统计行。非分组维度字段（如姓名、性别）用 aggregate:"select"，不用 group()。详见 references/horizontal-grouping.md §「跟随分组扩展统计行」。

工具脚本（按需使用）

YApi Mock 数据源

报表需要 API 数据源时，使用内置 YApi 平台（https://api.jeecg.com）创建 mock 接口。 登录凭证处理流程：

1. 先检查 memory 中是否已有 YApi 凭证记录
2. 有则直接使用；没有则询问用户：

   请提供 YApi 登录账号（邮箱）和密码，用于创建 mock 接口。

3. 用户提供后，立即保存到 memory（reference 类型），下次直接读取，无需再问

import sys
sys.path.insert(0, '<skill目录>/scripts')
from yapi_mock import init_yapi, create_mock

init_yapi()  # 自动登录

mock_url = create_mock(
    path='/sales',       # 路径后缀，不含 basepath（/claude）
    title='销售数据',
    data=[
        {"month": "一月", "amount": 12000},
        {"month": "二月", "amount": 15000},
    ]
)
# mock_url = https://api.jeecg.com/mock/57/claude/sales

固定参数：project_id=57，catid=1157，basepath=/claude

路径规则：接口路径只写后缀（如 /sales），完整 URL = https://api.jeecg.com/mock/57/claude/sales

⚠️ 新建 vs 修改（严格区分，防止污染他人数据）：

create_mock() 遇到同路径会静默覆盖已有接口数据，共享项目中会破坏他人接口。默认必须用唯一路径。

分页规则：自建 mock 接口不需要分页，data 直接返回完整数组，不加 pageNo / pageSize 参数。

积木报表中使用 mock URL 作为 API 数据集时，调用 save_db(..., db_type="1", api_url=mock_url) 即可，dbCode 是自定义编码（如 sales_data），与 URL 无关。

API 数据集查询条件传参规则：见「已知坑点」章节（含代码示例）及 references/dataset-core.md § 3.2.2。

fieldList 必须带 orderNum（从 0 开始），否则数据集「排序」列为空，字段顺序不确定：

{"fieldName": "col1", "fieldText": "列1", "fieldType": "String", "orderNum": 0},
{"fieldName": "col2", "fieldText": "列2", "fieldType": "String", "orderNum": 1},

查询 AI 已创建的接口列表

init_yapi()  # 先登录，自动带上 Cookie

# 列出 project_id=57 下已创建的所有接口（需登录态）
# GET https://api.jeecg.com/api/interface/list?page=1&limit=20&project_id=57
# 返回字段：_id(接口ID), path(路径), title(名称), method, up_time
# 完整 mock URL = https://api.jeecg.com/mock/57{path}

命令行等效：python yapi_mock.py list（自动登录后分页列出所有接口）

高级 Mock 脚本（按参数动态返回不同数据）

自动判断规则（AI 必须遵守）：

⚠️ 正确 API 是 /api/plugin/advmock/save，禁止用 /api/interface/up 的 isOpen/script 字段——那个字段不生效。

from yapi_mock import init_yapi, set_advmock

init_yapi(email='...', password='...')

# 先用 create_mock / list_mocks 拿到接口 ID，再调：
set_advmock(
    iface_id='5933',   # 接口 _id（字符串）
    script=r"""
if(params.leibie=='手机'){
    mockJson = {"data": [{"name":"苹果手机","value":25500}]}
}else if(params.leibie=='电脑'){
    mockJson = {"data": [{"name":"MacBook","value":47500}]}
}else{
    mockJson = {"data": [...]}   // 兜底默认值，无参数时返回
}
""",
    enable=True,
)

脚本规则：

• 用 params.xxx 读取 URL query 参数
• 用 mockJson = {...} 赋值返回体（不是 return）
• 必须写兜底 else 分支，确保无参数时有数据
• 字段名须与积木报表数据集的 axisX/axisY（或 fieldName）完全一致

常用配置速查

冻结行列（freeze）

base_save(report_id, designer, ..., freeze="A3", freezeLineColor="red")

报表背景色（background）

# 启用背景色（在 base_save override 里传，或 patch 时改 design["background"]）
base_save(report_id, designer, ..., background={"enabled": True, "color": "#e8f5e9"})

# 禁用背景色
base_save(report_id, designer, ..., background=False)

⚠️ bgColor 写在 make_designer(**extra) 里无效；必须作为 base_save 的顶层 override 传递。 patch 已有报表时：design["background"] = {"enabled": True, "color": "#hex"} → base_save(id, designer, **design)

预览页工具条（rpbar）

btnList / childrenBtnList 存的是「显示」的按钮编号，从列表中删除编号即可隐藏，[] = 全部隐藏。 rpbar 必须是 dict 对象，不能 json.dumps()。

base_save(report_id, designer, ..., rpbar={
    "show": True, "pageSize": "",
    "btnList": [1,2,3,4,5,6,7,8,9],
    "childrenBtnList": [7.1,7.2,7.3,7.4,8.1,8.2,8.3,8.4,8.5,8.6]
})

图表 extData 必填字段

钻取/联动 linkType 对照

• 单元格触发：cell["linkIds"] = link_id + cell["display"] = "link"
• 图表触发：extData["linkIds"] = link_id（放 extData 内部，不在顶层）
• 联动必须有 linkChartId（目标图表 layer_id）；目标图表 paramList 必须设 paramValue 默认值

searchMode 映射