jimubi-bigscreen

# JeecgBoot 大屏 AI 自动生成器 > 本 skill 处理大屏（bigScreen）。仪表盘（看板）请用 `jimubi-dashboard` skill。 ## ⚠️ 核心强制规则（9条） 1. 所有大屏操作必须通过本 skill（禁止未调用 skill 直接读 memory 凭据自行执行） 2. **入口即分叉**：按场景决策树选路径，禁止默认走 spec_builder。spec_builder 仅用于"整屏生成（含组件）"场景。禁止逐组件拼 Python 脚本 3. 🚨 删除/重写/清空前必须询问用户确认（除非用户明确说"删除/去掉/移除/清空/清除"） 4. 🚨 编写 SQL 前必须 SHOW TABLES 确认表名（onl_drag_page ≠ jimu_drag_page） 5. `dataMapping.filed` 拼写：少一个 d（不是 field） 6. Windows：用 `py` 不是 `python`；所有脚本加 `PYTHONIOENCODING=utf-8` 7. 🚨 **用户未指定数据来源时必须先问**（纯静态布局/纯装饰除外）。可选项：静态 mock / YApi 接口 / SQL 数据集 / Excel-CSV 文件 / 存储过程 / 自写 Java API / **BI 直连 Online 表/设计器表单/Online 报表（`dataType=4`）**。⚠️ 用户说"用某 Online 表 / cgform / jeecg 表 / Online 报表 / desform 作为数据源"时**优先 BI 模式**而非 SQL 数据集（详见 `references/bi-mode-online.md`）。禁止默认编造静态数据 8. **真相源优先级（写组件配置 / 数据集绑定都遵循）**： - **数据集绑定字段映射** → `references/data-binding-mapping.md`（唯一真相源，描述冲突以此为准；按 §0 检测算法对照 `defaults/<CompType>.json` 判定 A/B/无映射 三型，别猜） - **组件 option 字段名（passthrough 自定义组件 JScrollList / JScrollBoard / JScrollTable / JText / JCurrentTime / JStatsSummary / JDragDecoration / JDragBorder / JFlashList / JRectangle / JLiquid / JSemiGauge / JCustomProgress / JListProgress 等，非穷举）**，按以下四级顺序查，找到即止： - ① `references/scripts/defaults/<CompType>.json`（初始加载真相源，`--schema <CompType> --full` 调取） - ② `references/<comp>-option-config.md`（组件专项文档） - ③ `references/bi-comp-option-config.md`（兜底） - ④ **以上三级仍找不到 → 说明该字段是 UI 运行时动态写入的**（不在 defaults 里）。正确做法：在页面上手动操作一次该属性，再 `query_page` 观察实际写入了哪些字段，以观察结果为准。典型案例：`JRing` 的环形尺寸，defaults 只有 `series[0].radius`（百分比），但 UI 实际写的是 `option.outRadius` / `option.innerRadius`（像素整数），不查 ④ 直接写百分比字段会被 Vue 渲染器忽略（实测 2026-04-28） - 错字段不报错只会被默认值覆盖（看似"有效"实则无效）。禁止按 Vue/React/Bootstrap 习惯拍脑袋写 `bgColor`/`fontColor`/`borderColor`——实际可能是 `backgroundColor`/`alternateBackgroundColor`/`BGC` 等平台自定义名 - ECharts 标准字段（`series[*].itemStyle.color` / `xAxis.axisLabel.color` 等）可凭记忆写，不受此规则限制 9. **配色禁止 AI 自编色值**——用户说"复古/商务/科技/红涨绿跌"等命名色板，必走 `style_ops.py set-palette --name <名称>`（或 spec 顶层 `palette`）。查色值用 `style_ops.py list-palettes`，不调 API 不耗 token 10. 🚨 **用户已指定风格/配色/背景时，立即执行，禁止内部反复推翻**——用户说"浅色/深色/科技感/复古风/XX 风格"，选一个合理实现方案后直接执行，不得多轮权衡"技术上是否可行"。平台默认深色主题不是拒绝浅色的理由，遇到技术限制先执行再调整。post-creation 颜色调整必须合并批量：`style_ops.py` 多个子命令尽量串联为 1-2 次调用（`set-axis-color` + `set-title-color` + `set-grid-color` 可各自独立，但禁止因犹豫在 spec 生成后串行执行 6+ 次单独 HTTP 操作） ## ⚡ 写/改任何组件 option 字段前——强制预检（不可跳过） 在编写任何组件 config 脚本、`comp_ops.py edit --set`、或手写 Python patch 之前，**必须先确认字段名，不允许凭 ECharts 文档或经验直接写**。按以下优先级判断： | 情况 | 做什么 | |------|--------| | 当前上下文已有该组件 config（刚 query_page / dump 过） | **直接看它**，从中确认字段名和现有结构 | | Config 中没有目标字段、或字段名不确定 | **查 `bi-comp-option-config.md`** 对应 CompType section（平台缩写字段如 `legend.t` 只在这里，defaults JSON 里没有） | | 从零建组件、需要确认初始字段结构 | 先查 `defaults/<CompType>.json`（`--schema <CompType> --full`），再查 `bi-comp-option-config.md` 补充 | | 以上三处均无 | 在 UI 手动操作一次，`query_page` 观察实际写入字段，以观察结果为准 | **找到即止，立即执行，禁止从多个来源重复确认同一字段**。任一来源确认字段名后直接跑命令，不再查第二个来源。`comp_ops.py edit` 的 `true/false/数字` 自动类型转换是固定行为，无需每次验证源码。 **错字段不报错不报 warning，只会被默认值静默覆盖**（典型案例：`option.legend.top` 无效，正确字段是 `option.legend.t`；`option.outRadius/innerRadius` 与 `series[0].radius` 同理）。 --- ## 大屏平台默认值 - 分辨率 1920×1080（后端默认，spec_builder 不写）| style bigScreen | designType 100 - 主题 dark（spec_builder L797）| 背景 `/img/bg/bg4.png` 深空星空（spec_builder L798）| 图层 bg/border 透明 `#FFFFFF00` - bg4 色板（spec_builder 内置）：主标题 `#f0c040`，副标题 `#00d4ff`，数值 `#d4e8ff`，轴 `#8ab8d0`，分割线 `#1a3a5a55` - A股红涨绿跌：`#ff4d4f` / `#52c41a` --- ## 入口判断（先做这一步） **1. 新建 vs 已有大屏？** | 用户语境 | 走哪 | |---------|------| | 含 page_id / 提到"当前大屏 / 刚才那个屏 / 这个大屏" | **C 组件操作**（已有屏） | | 说"做一个 / 创建 / 新建 / 设计 XX 大屏" | **B 整屏生成**（新建） | | 仅说"删除 / 改名 / 换背景 / 克隆" | **A 页面级** | | 仅说"换数据源 / 绑数据集 / 接 SQL/API" | **D 数据绑定** | | 模糊（"帮我做大屏"，无 page_id 也无具体诉求） | **必须先问用户**：新建还是修改已有？数据来源？组件清单？ | **2. 模糊需求兜底（用户没指定组件、数据、布局）** 禁止默认 spec_builder 编造一通。优先动作： - 问 1-2 个关键问题（业务主题 / 大致 5-8 个图想看什么 / 数据从哪来） - 或者直接命中 B-Step1 模板时，向用户确认"我用 XX 模板复制后再改" **3. 高频意图 → 脚本/组件 速查** | 用户说 | 路径 | |-------|------| | "排行 / TOP N / 排名" | 组件首选 `JScrollRankingBoard`，动画版 `JDynamicBar` | | "KPI / 核心数字 / 大数字" | **≥3 个一组并排（二选一，按数据项数决定）**：① `JStatsSummary` — label/value/unit + 环比/同比对比 + 涨跌箭头，文档化驾驶舱风格，**需要展示同/环比对比、或项数不能整除 24（如 5/7/9-11 项）时首选**；② `JColorBlock` — 每项独立色块背景（每条数据自带 `backgroundColor`），可语义化配色（红/橙=警示、绿=正向、蓝/青=中性），**视觉冲击/状态可视化场景首选**——**🚨 强约束：源码 colorBlock.vue:122-124 用 Antd 24 栅格 `span = ceil(24/lineNum)` 渲染，数据项数必须 = `lineNum` 且能整除 24，KPI 行实用项数仅 {2, 3, 4, 6, 8}（4-6 最饱满）；5/7/9-11/13-23 项会折行错位（5 项变 4+1、7 项变 6+1）→ 改用 JStatsSummary**。单个突出大数字 → `JCountTo`（翻牌动画）/ `JNumber`（静态）。⛔ 禁止 N 个 JNumber/JCountTo 横排凑 KPI 行 | | "完成率 / 达标率" | `JGauge`（指针）/ `JLiquid`（液位）/ `JRingProgress`（环形），value 是 **0-100** 整数 | | "占比 / 比例 / 分布" | `JPie` / `JRing` / `JRose` | | "趋势 / 走势 / 时序" | `JLine` / `JSmoothLine` / `JArea` | | "对比 / 多组数据" | `JBar` / `JMultipleBar` / `JStackBar` | | "转化 / 漏斗" | `JFunnel` | | "地图 / 区域 / 飞线 / 热力" | `JAreaMap` / `JFlyLineMap` / `JHeatMap` | | "装饰 / 好看点" | `JDragDecoration`（12 套预设，禁止与 JDragBorder 混） | | "边框 / 框一下" | `JDragBorder`（13 套预设，选哪种看 `references/border-style-guide.md`） | | "标题 / 文字 / 标语" | `JText` | | "时钟 / 实时时间" | `JCurrentTime` | | "日历" | `JPermanentCalendar` | | "换配色 / 复古 / 商务 / 科技色" | `style_ops.py set-palette --name <名称>` | | "联动 / 点饼图筛柱图" | `linkage_ops.py`（已有屏加联动） | | "新建多图带联动" | `multi_chart_linkage.py`（一次建多图+联动） | | "弹窗 / Modal" | `references/popup-guide.md` | | "外链 / 跳转 / 自定义 JS" | `link_ops.py` | | "克隆 / 备份 / 恢复" | `backup_ops.py` | | "看现在有哪些组件" | `comp_ops.py list` | | "通用组件 / 自由写 ECharts JS / customOption / 写个 JS option 串 / 桑基/树图/自定义图" | **`JCommon`**（菜单"通用组件"） — 写 `config.customOption`（**JS 字符串**，须 `option = {...}; return option;` 结尾），可写 function 等动态逻辑。spec_builder 不会自动写此字段，需 spec 建壳后用 bi_utils patch | | "自定义组件 / 自定义 echarts / 直接写 echarts JSON" | **`JCustomEchart`**（菜单"自定义组件"） — 写 `config.definitionOption`（**JSON 对象**，纯静态，不能含 function）。spec_builder 不会自动写此字段，需 spec 建壳后用 bi_utils patch | | "用 Online 表 / cgform / jeecg 表 / Online 报表 / desform 作为数据源" | **BI 模式 (`dataType=4`)** — 见 `references/bi-mode-online.md`，禁止默认套 SQL 数据集 | > ⚠️ **JCommon ≠ ECharts 内置组件（JBar/JLine/JPie 等）**。"通用组件"是平台菜单分类，专指 JCommon；用户说"通用组件"时**默认指 JCommon**，禁止误映射到 builtin handler 图表。区别看 `references/data-binding-mapping.md` §3。 --- ## ⭐ 模糊需求 → 快速好看大屏 SOP（核心） > **目标**：用户没指定组件/布局/数据时，AI 也能 1 次往返产出"快 + 好看 + 不丑"的大屏。 ### 速度铁律（HTTP 越少越快） | 优先级 | 路径 | HTTP 次数 | 适用 | |-------|------|-----------|------| | 🥇 最快 | `template_ops.py copy --replace` | **1** | B-Step1 模板触发词命中 | | 🥈 次快 | `spec_builder.py` 单次生成全部组件 | **1** | 模板未命中 / 自定义布局 | | ⛔ 禁止 | 循环 `comp_ops.py add` 逐个加 | N | 任何"建多个组件"的场景都禁止 | **潜规则**：spec_builder 一个 spec 写 N 个组件 = 1 次 HTTP；逐个 add 一个组件 1 次 HTTP。建 8 个图，前者 1 次，后者 8 次，速度差 ~6-8 倍。 ### 组件挑选原则：5 维结构（用户没指定组件时按这个组） > 不靠行业专属清单，靠**通用结构**——每张大屏从下面 5-7 维选 4-6 项即可，AI 据用户业务描述映射到具体组件。 | 维度 | 用途 | 候选组件（按"高频意图→组件"速查决定具体选哪个） | |------|------|------------------------------------------------| | **KPI 数字** | 顶部 KPI 行 ≥3 项 → **`JStatsSummary`**（带环比/同比对比卡，任意项数）/ **`JColorBlock`**（每项独立色块、可语义化配色，**仅项数 ∈ {2,3,4,6,8} 才视觉饱满**——24 栅格约束，详见上方"高频意图"速查）二选一；单大数字 → `JCountTo` / `JNumber` | — | | **趋势** | 时间维度变化 | JLine / JArea / JSmoothLine / JStepLine | | **对比** | 多类目/多组对比 | JBar / JStackBar / JMultipleBar / JMixLineBar | | **占比** | 部分/整体 | JPie / JRing / JRose / JFunnel | | **排行** | TOP N | JScrollRankingBoard / JDynamicBar / JBubbleRank | | **地理**（可选） | 业务含地理属性 | JAreaMap / JFlyLineMap / JBubbleMap / JHeatMap | | **明细/告警**（可选） | 列表/动态信息 | JScrollList / JScrollBoard / JScrollTable / JFlashList | **挑选流程**： 1. 读用户描述，提取"想看的指标关键词" 2. 用上方"高频意图→组件"速查表把每个指标映射到具体组件类型 3. 缺维度（如完全没说时间/对比）就**反问**而非自己脑补 4. 行业模板若 B-Step1 命中，**优先 copy 模板**再按需替换组件，比从 0 拼快 ### 布局规则（按画布等比例算，不写死坐标） > 画布尺寸由用户决定（默认 1920×1080；竖屏 1080×1920；4K 等比例放大）。AI 按下面比例规则算坐标，**不要硬背像素**。 **通用比例**（让"不丑"的最小约束）： - 边距（画布外沿到组件） ≥ 短边 × 4% - 组件间距 ≥ 短边 × 1.5%–2% - 标题区高度 ≈ 短边 × 5%–7% - 所有 x/y/w/h 对齐到 10 或 20 的倍数（防像素错位） - 检查：组件不重叠（前一个 x+w + 间距 ≤ 后一个 x）、不贴边、不留大块孤儿空白 **三种推荐布局形态**（描述结构，不锁坐标）： | 形态 | 结构 | 适合 | |------|------|------| | **A 顶 KPI 行 + 主图网格** | 顶部 1 行 4-5 个 KPI；下方 2-3 行 × 3 列主图网格 | 最通用驾驶舱 | | **B 左侧栏 + 中央大图 + 右侧栏** | 两侧各 2-3 个小图；中央 1 大图占 ~50% 宽 | 突出核心趋势/地图 | | **C 四角 KPI + 中央大图** | 中央大图占主视觉；四角各 1 个 KPI | 监控/指挥中心 | **默认搭配**：主题 `dark` + 平台命名色板（用户说"复古/商务/科技"等走 `style_ops.py set-palette`）。 ### 演示数据量原则（AI 编 mock 时必读） > **总则**：用户没给真实数据让 AI 编演示数据时，**数据条数尽可能多**。默认值偏少（多数 5-7 条），照抄会让大屏空旷且滚动/分页/排行类组件不触发动效。 | 组件类型 | 推荐演示数据量 | 触发条件 | |---------|---------------|---------| | **滚动类**（JScrollList / JScrollTable / JScrollBoard / JFlashCloud / JCardScroll） | ≥ 可视行数 × 1.5（按容器 h / 行高估算可视行数） | 数据 ≤ 可视时不滚 | | **排行类**（JScrollRankingBoard / JDynamicBar / JCapsuleChart / JBubbleRank / JFlashList） | 取上限 — JBubbleRank 5 / JFlashList 4 / **JScrollRankingBoard：data_count ≥ rowNum+3**（rowNum=floor(h/40)，≈ 10 时 h≈400；h=195 时 rowNum=4） | **data_count > rowNum 才滚动**；两者相等全部展示完毕→不滚动 | | **类目对比**（JBar / JStackBar / JLine / JArea） | ≥ 8-12 类目（柱图）/ ≥ 12-24 时间点（折线） | 太少视觉空 | | **占比类**（JPie / JRing / JRose / JFunnel） | 5-8 项（占比类反而忌过多） | — | | **KPI / 单值类**（JNumber / JCountTo / JGauge / JLiquid） | 1 个值，数据量与该规则无关 | — | | **地图类**（JAreaMap / JFlyLineMap / JBubbleMap / JHeatMap） | 全国铺满（≥ 25 省份）或 ≥ 30 飞线/热点 | 稀疏会显假 | | **明细/告警**（JList / JCommonTable / JDevHistory） | ≥ 10-15 行 | 撑满容器才耐看 | **自检 checklist**： - 滚动组件保存后回查 `数据行数 vs (h / row.height + marginBottom)` 比值，低于 1.5 倍直接补数据 - spec_builder 默认 chartData 多数是 5-7 条，**禁止照抄默认 chartData 当成"演示数据已够"** - 真实接口/数据集到位后此规则失效（取真实数据，量由业务定） ### AI 模糊需求处理 SOP（按顺序走） 1. **B-Step1 行业模板命中？** - 是 → `template_ops.py copy` → 与用户确认改文案/数据 → 完成 - 否 → 进入 2 2. **5 维结构 + 高频意图速查 = 选 4-6 个组件**，按形态 A 默认排版 → `spec_builder.py` 单次生成 → 给用户预览 3. **数据来源未指定** → 必须先问（强制规则 #7）；用户允许 mock 时首选静态 mock 让效果最快出，后续再换真实数据集 --- ## 场景决策树（入口即分叉，直达最短路径） > 先判断操作类型，再判断子场景，**不要默认走 spec_builder**。 --- ### A. 页面级操作 | 场景 | 脚本 | 备注 | |------|------|------| | **创建空白大屏** | 直接调 `bi_utils.create_page()`（见下方模板） | 禁止用 spec_builder；`page_ops.py` 无 create 子命令 | | 删除大屏 | `page_ops.py delete` | 必须先确认 | | 重命名/换背景/加水印 | `page_ops.py` | 读 `references/page-config-guide.md` | | 标记/取消模板 | `page_ops.py set-template --flag 0\|1` | 单字段改 `izTemplate`，最小 payload | | 克隆/导出/导入/对比 | `backup_ops.py`（子命令：`clone` / `export` / `import` / `diff`） | | **创建空白大屏标准调用：** ```bash cd <skill目录> && python3 - <<'EOF' import sys, time; sys.path.insert(0, 'references') import bi_utils t0 = time.time()