15 KiB
后台图表业务块设计
目标
在现有页面设计器和业务块体系上增加后台业务块能力，并首批提供四个仅后台可用的图表业务块：
- 指标卡
- 折线图
- 柱状图
- 饼图
方案沿用现有业务块注册、布局保存、字段校验和代码生成链路，不建设第二套后台业务块系统，也不升级为通用 BI 或自由大屏设计器。
已确认的产品边界
- 采用统一业务块协议扩展方案。
- 图表业务块一期仅用于后台页面。
- 数据源仅支持单表聚合。
- 支持维度、计数、求和、平均值和固定筛选条件。
- 不支持关联表、自定义 SQL、公式脚本、运行时数据源切换和任意 ECharts JSON。
- 首批只实现指标卡、折线图、柱状图和饼图。
- 布局继续使用现有业务块页面和普通页面嵌入区，不增加自由栅格编辑器。
- 每个块只提供整行、半行、三分之一三种宽度。
当前基础
项目已有以下可复用能力：
FrontendPageDesigner.vue同时支持前台和后台页面设计模式。- 页面布局保存在
front_project_page_design.layout_json。 - 业务块定义位于
business-blocks/*/block.json。 BusinessBlockRegistryService负责定义加载、表字段校验和布局校验。BusinessBlockGenerationService按业务块实例生成前端组件、API 和后端文件。business-blocks-v1支持业务块页面，普通页面支持embeddedBlocks.top和embeddedBlocks.bottom。- 后台页面类型已经允许选择业务块页面，但页面入口当前没有向后台设计器传入业务块定义。
因此，本需求的核心不是新增一条独立链路，而是把现有链路扩展为可按使用端和块类型工作。
总体架构
后台页面设计器
|
| 选择 admin 图表块并配置单表聚合 DSL
v
front_project_page_design.layout_json
|
| 保存时校验表、字段、字段类型、聚合和筛选
v
BusinessBlockRegistryService
|
| 生成 Vue/ECharts、API、Controller、Service、Mapper
v
BusinessBlockGenerationService
|
v
生成后的 Qing 后台运行页面
前后台共用业务块注册和生成基础设施，但定义通过 surfaces 限制可见范围，模板通过类型区分生成目标。
业务块协议 2.0
定义扩展
业务块定义增加以下字段：
{
"code": "admin_line_chart",
"name": "折线图",
"category": "数据图表",
"kind": "chart",
"surfaces": ["admin"],
"placements": ["embedded", "page"],
"chartType": "line",
"datasetSchema": "single-table-aggregate-v1",
"version": 2,
"defaultSpan": 12,
"templates": []
}
字段含义：
kind：块类型。已有业务块归一化为business，图表块为chart。surfaces：适用端，支持frontend、admin。placements：允许放置到普通页面嵌入区或业务块页面。chartType：metric、line、bar、pie。datasetSchema：图表使用的数据配置协议。defaultSpan：默认宽度，取值为12、6、4。
兼容规则：
- 老定义缺少
kind时按business处理。 - 老定义缺少
surfaces时按["frontend"]处理。 - 老定义的单值
placement归一化为placements数组。 - 老页面和老业务块实例不要求迁移。
实例扩展
图表块实例保存在现有页面布局 JSON 中：
{
"id": "admin_line_chart_001",
"blockCode": "admin_line_chart",
"name": "近 30 天销售趋势",
"span": 12,
"dataset": {
"schema": "single-table-aggregate-v1",
"table": "shop_order",
"dimension": {
"field": "create_time",
"timeUnit": "day"
},
"metrics": [
{
"field": "amount",
"aggregate": "sum",
"alias": "salesAmount",
"label": "销售额"
}
],
"filters": [
{
"field": "status",
"operator": "eq",
"value": "PAID"
}
],
"dateRange": {
"field": "create_time",
"preset": "last_30_days"
},
"sort": {
"by": "dimension",
"order": "asc"
},
"limit": 100
},
"display": {
"showTitle": true,
"showLegend": true,
"smooth": true,
"numberFormat": "decimal",
"emptyText": "暂无数据"
}
}
现有 config 字段继续服务于购物车、公告、轮播等老业务块。图表使用结构化的 dataset 和 display，避免把嵌套配置塞入 Map<String, String>。
单表聚合 DSL
支持能力
- 一张数据表。
- 最多一个维度字段。
- 一个到三个指标。
- 聚合函数：
count、sum、avg。 - 静态筛选条件。
- 日期范围预设。
- 按维度或指标排序。
- 限制返回分组数量。
字段类型约束
count可用于整表或任意字段。sum、avg只能用于数值字段。- 普通维度支持文本、枚举、数字和日期时间字段。
timeUnit只能用于日期时间字段。- 时间粒度一期支持
day、week、month。 - 指标别名在同一块内必须唯一。
筛选运算符
一期支持：
eqnegtgteltltebetweeninis_nullis_not_null
筛选值必须与字段类型兼容。单个块最多配置十个筛选条件。
日期范围
一期提供以下预设：
- 今天
- 最近 7 天
- 最近 30 天
- 本月
- 本年
- 固定起止日期
日期预设在生成后的服务端计算，避免依赖浏览器时间拼接 SQL。
数量限制
- 全局最大分组数为 500。
- 折线图默认 100 个分组。
- 柱状图默认 20 个分组。
- 饼图默认 10 个分组，最大 20 个。
- 指标卡不返回维度分组。
四种图表块
指标卡
- 不要求维度。
- 只允许一个指标。
- 支持前缀、后缀、小数位、标题和辅助说明。
- 一期不计算同比、环比；辅助说明为静态文案。
折线图
- 必须配置一个维度。
- 支持一个到三个指标。
- 时间维度可配置日、周、月粒度。
- 展示配置支持平滑曲线、面积填充和图例。
柱状图
- 必须配置一个维度。
- 支持一个到三个指标。
- 展示配置支持横向、纵向、堆叠和 Top N。
饼图
- 必须配置一个分类维度。
- 只允许一个指标。
- 展示配置支持实心、环形、标签和“其他”分组。
页面设计器
素材面板
后台模式请求 scope=admin 的业务块定义，只展示 surfaces 包含 admin 的定义。
图表块归入“数据图表”分类：
- 指标卡
- 折线图
- 柱状图
- 饼图
前台模式不显示这四个块。现有前台业务块也不会因为本需求自动出现在后台素材池。
放置方式
图表块支持：
- 普通后台页面顶部业务块区。
- 普通后台页面底部业务块区。
- 后台业务块页面。
块实例支持拖拽排序和三档宽度：
span=12：整行。span=6：半行。span=4：三分之一。
画布使用 12 列 CSS Grid 自动换行，不提供任意坐标、任意缩放和断点级布局编辑。
属性面板
选中图表块后，右侧分为三个页签。
“数据”页签：
- 标题
- 数据表
- 维度字段
- 时间粒度
- 指标字段
- 聚合方式
- 筛选条件
- 日期范围
- 排序
- Top N 或分组上限
“展示”页签：
- 图例
- 颜色主题
- 数值格式
- 图表类型特有选项
- 空数据文案
“权限”页签：
- 显示“继承所在后台页面”。
- 一期不允许单个块覆盖页面权限。
- 当前生成目标若只有后台登录保护，则块继承该登录保护；本需求不额外建设块级 RBAC。
预览
设计器内的即时预览使用稳定的样例数据，只验证图形、标题、图例、格式和布局。
配置变化后 400 毫秒防抖刷新当前块。真实数据库结果在保存并生成运行预览后验证。本期不增加设计器直接执行聚合 SQL 的接口。
这样可以避免设计阶段访问未初始化的数据源，也减少预览查询对数据库的压力。
API 调整
业务块定义
现有接口调整为：
GET /front/project/{projectId}/business-blocks?scope=admin
行为：
- 校验项目归属。
scope归一化为frontend或admin。- 只返回
surfaces包含当前 scope 的定义。 - 前端
listBusinessBlocks(projectId, scope)显式传入当前页面设计范围。
PageDesignerView.vue 不再通过“后台传空数组”隐藏业务块，而是传入后端过滤后的定义。
页面保存
继续使用现有页面设计保存接口，不新增业务块实例表：
PUT /front/project/{projectId}/page-designs/{designId}?scope=admin
保存时增加图表 DSL 校验。任一图表块无效时，整个页面设计保存失败，并返回块名称和具体配置项。
运行时数据接口
每个生成的图表块实例提供只读接口：
GET /business-blocks/{instanceCode}/data
响应协议：
{
"dimensions": [
{
"key": "2026-06-01",
"label": "06-01"
}
],
"series": [
{
"key": "salesAmount",
"name": "销售额",
"values": [12800.5]
}
],
"summary": {
"value": 86420,
"count": 328
}
}
指标卡读取 summary；折线图和柱状图读取 dimensions 与 series；饼图把维度和第一组指标映射为分类占比。
后端校验
BusinessBlockRegistryService 增加以下职责：
- 按
surface过滤定义。 - 归一化协议 1.0 和 2.0 定义。
- 校验图表块只能出现在后台页面。
- 校验数据表存在于项目数据库设计。
- 校验维度、指标、筛选和日期字段存在。
- 校验聚合函数与字段类型匹配。
- 校验图表类型需要的维度和指标数量。
- 校验运算符、筛选值、排序字段和 limit。
- 校验
span只能为12、6、4。
错误消息包含业务块名称和配置项，例如：
折线图“近 30 天销售趋势”的指标字段 amount 不是数值类型，不能使用 SUM
代码生成
前端
生成项目增加 ECharts 依赖，并提供共享图表工具：
- 图表初始化与销毁。
- 窗口尺寸变化时 resize。
- 统一加载、空数据和错误状态。
- 统一主题颜色与数值格式。
每个图表块仍按现有业务块模式生成独立 Vue 组件和 API 文件。该方式会增加文件数量，但与当前生成机制一致，实例隔离清楚，也便于预览单个生成文件。
后端
每个实例生成只读的 Controller、Service 和 Mapper 文件。
生成 SQL 规则：
- 表名和字段名只能来自已校验的项目数据库元数据。
- 聚合函数只能来自固定枚举。
- MySQL 时间维度使用固定的
DATE_FORMAT模板。 - 筛选值通过 MyBatis 参数绑定。
- 排序只能引用生成后的维度或指标别名。
- 不接受客户端传入表名、字段名、SQL 片段、聚合函数或排序表达式。
生成的接口位于后台认证保护范围内，并继承所在页面当前具备的后台访问边界。
权限与安全
- 图表块不能放入前台页面。
- 块不拥有独立权限，继承后台页面和后台登录态。
- 设计器保存前做元数据白名单校验。
- 生成阶段再次校验，防止绕过页面保存直接生成。
- 运行时只接受生成代码中预定义的查询，不接受动态查询结构。
- 最大分组数和筛选数量受限。
- 空值和数值聚合使用安全的默认处理，避免前端出现
NaN。
块级 RBAC、部门数据权限和用户可编辑筛选器不属于一期。后续若项目增加稳定的页面权限模型，再由图表块继承该模型，不单独发明另一套权限协议。
错误处理
设计时
- 必填配置缺失时在右侧表单直接标红。
- 字段被删除或类型发生变化时，页面标记为“需要修复”。
- 无效页面不能保存，也不能生成预览。
- 错误定位到具体块和具体字段。
运行时
- 空结果展示块级空状态。
- 当前接口失败时只让当前块显示错误和重试按钮。
- 一个图表块失败不影响同页其他块。
- 组件卸载时销毁 ECharts 实例和 resize 监听。
数据库与兼容性
- 不新增数据库表。
- 不修改
front_project_page_design表结构。 - 新配置继续存入
layout_json。 - 老页面布局保持原样可读。
- 老业务块定义通过归一化逻辑继续工作。
- 前台业务块生成结果不因本需求改变。
测试
前端
- 后台页面能获取并展示四个图表块。
- 前台页面不展示后台图表块。
- 拖入、选择、删除、排序和宽度切换正确更新布局 JSON。
- 图表配置面板按图表类型显示正确字段。
- 类型不匹配和必填缺失显示块级错误。
- 样例数据预览支持加载、空数据和错误状态。
- 旧业务块页面和普通页面嵌入块行为不回归。
后端
- 业务块定义能按 scope 过滤。
- 老定义能被正确归一化。
- 表、字段、字段类型、聚合、筛选、时间粒度、排序和 limit 校验完整。
- 后台图表块不能保存到前台页面。
- 无效布局不能进入代码生成。
生成器
- 四种图表生成正确的 Vue、API、Controller、Service 和 Mapper。
- 生成项目包含 ECharts 依赖。
- SQL 只包含白名单标识符和固定函数。
- 筛选值使用参数绑定。
- 统一响应能被四种组件正确消费。
- 多块页面按
span正确排列。 - 单块接口失败不会影响其他组件。
分阶段落地
第一阶段：协议和可见范围
- 扩展业务块定义 DTO。
- 增加定义归一化和 scope 过滤。
- 修改业务块列表 API 和后台设计器传参。
- 保证旧定义与旧页面测试通过。
第二阶段：图表设计器
- 增加图表块实例模型和单表聚合 DSL。
- 增加专用图表配置面板。
- 增加三档宽度和 12 列布局。
- 增加样例数据即时预览。
第三阶段：校验和代码生成
- 完成 DSL 后端校验。
- 增加 ECharts 共享运行组件。
- 增加四个图表块定义和生成模板。
- 生成只读聚合接口。
第四阶段：验证和发布
- 前后端自动化测试。
- 使用包含数值、枚举、日期字段的订单表做运行预览。
- 验证前台业务块、后台 CRUD 页面和老项目兼容性。
- 文档中说明一期限制和后续扩展边界。
后续扩展
协议稳定后可以逐项增加：
- 表格统计块。
- 排行榜块。
- 待办列表块。
- 审核工作台块。
- 页面级公共筛选器。
- 关联表数据集。
这些能力不进入本期，也不预留可执行 SQL 或脚本入口。