# 后台图表业务块设计 ## 目标 在现有页面设计器和业务块体系上增加后台业务块能力，并首批提供四个仅后台可用的图表业务块： - 指标卡 - 折线图 - 柱状图 - 饼图 方案沿用现有业务块注册、布局保存、字段校验和代码生成链路，不建设第二套后台业务块系统，也不升级为通用 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`。 - 后台页面类型已经允许选择业务块页面，但页面入口当前没有向后台设计器传入业务块定义。 因此，本需求的核心不是新增一条独立链路，而是把现有链路扩展为可按使用端和块类型工作。 ## 总体架构 ```text 后台页面设计器 | | 选择 admin 图表块并配置单表聚合 DSL v front_project_page_design.layout_json | | 保存时校验表、字段、字段类型、聚合和筛选 v BusinessBlockRegistryService | | 生成 Vue/ECharts、API、Controller、Service、Mapper v BusinessBlockGenerationService | v 生成后的 Qing 后台运行页面 ``` 前后台共用业务块注册和生成基础设施，但定义通过 `surfaces` 限制可见范围，模板通过类型区分生成目标。 ## 业务块协议 2.0 ### 定义扩展 业务块定义增加以下字段： ```json { "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 中： ```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`。 ## 单表聚合 DSL ### 支持能力 - 一张数据表。 - 最多一个维度字段。 - 一个到三个指标。 - 聚合函数：`count`、`sum`、`avg`。 - 静态筛选条件。 - 日期范围预设。 - 按维度或指标排序。 - 限制返回分组数量。 ### 字段类型约束 - `count` 可用于整表或任意字段。 - `sum`、`avg` 只能用于数值字段。 - 普通维度支持文本、枚举、数字和日期时间字段。 - `timeUnit` 只能用于日期时间字段。 - 时间粒度一期支持 `day`、`week`、`month`。 - 指标别名在同一块内必须唯一。 ### 筛选运算符 一期支持： - `eq` - `ne` - `gt` - `gte` - `lt` - `lte` - `between` - `in` - `is_null` - `is_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 调整 ### 业务块定义 现有接口调整为： ```text GET /front/project/{projectId}/business-blocks?scope=admin ``` 行为： - 校验项目归属。 - `scope` 归一化为 `frontend` 或 `admin`。 - 只返回 `surfaces` 包含当前 scope 的定义。 - 前端 `listBusinessBlocks(projectId, scope)` 显式传入当前页面设计范围。 `PageDesignerView.vue` 不再通过“后台传空数组”隐藏业务块，而是传入后端过滤后的定义。 ### 页面保存 继续使用现有页面设计保存接口，不新增业务块实例表： ```text PUT /front/project/{projectId}/page-designs/{designId}?scope=admin ``` 保存时增加图表 DSL 校验。任一图表块无效时，整个页面设计保存失败，并返回块名称和具体配置项。 ### 运行时数据接口 每个生成的图表块实例提供只读接口： ```text GET /business-blocks/{instanceCode}/data ``` 响应协议： ```json { "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`。 错误消息包含业务块名称和配置项，例如： ```text 折线图“近 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 或脚本入口。