Files

王鹏 a398dd9df0 docs: define admin home dashboard metrics

2026-07-06 12:13:54 +08:00

10 KiB

Raw Permalink Blame History

后台主页运营驾驶舱设计

目标

通用生成后台项目时，自动把后台主页从空白或默认介绍页升级为运营驾驶舱。首页首屏展示 4 个带语义图标和颜色的指标卡，下方展示趋势图和占比/分布图。方案采用 AI 蓝图驱动，生成器负责校验、兜底和渲染，不新建第二套 dashboard 组件或 SQL 生成体系。

已确认的产品方向：

后台主页采用运营驾驶舱风格。
AI 应在应用蓝图中显式描述首页指标卡和图表。
当 AI 配置不足或无效时，生成器从主业务表兜底。
图标和颜色由生成器按语义白名单映射，底层使用 Element UI 图标。
首版包含指标卡、趋势图和占比/分布图。

当前基础

项目已有可复用能力：

AppBlueprintDesign 保存角色、前台菜单、后台菜单和前台页面蓝图。
FrontendPageDesignService 会初始化 admin_home，后台主页页面码为 admin_home，路由为 /admin/home。
业务块页面使用 business-blocks-v1，生成模板为 business-blocks/page/business-block-page.vue.vm。
后台图表业务块已存在：admin_metric_chart、admin_line_chart、admin_bar_chart、admin_pie_chart。
图表块使用结构化 dataset 和 display 配置，并通过 ChartDatasetValidator、BusinessBlockGenerationService、ChartBlockRenderSupport 生成 Vue/ECharts 和后端聚合接口。

因此本功能应复用现有业务块协议和图表生成链路，只增加后台首页自动编排能力。

总体设计

新增 AdminHomeDashboardComposer，输入为：

AppBlueprintDesign.adminHomeDashboard
项目数据库表与字段元数据
业务循环计划或后台菜单上下文，用于选择主业务表兜底

输出为 admin_home.layout_json，格式仍是 business-blocks-v1。

流程：

AI 生成应用蓝图时，额外返回 adminHomeDashboard。
初始化后台页面设计时，FrontendPageDesignService.initializeAdminPageDesigns() 创建或读取 admin_home。
AdminHomeDashboardComposer 将蓝图中的指标和图表转换成业务块实例。
composer 校验表、字段、聚合、日期范围和图表类型；非法块丢弃。
有效块不足目标数量时，composer 从主业务表生成兜底块。
只有 layout_json 变化时才更新数据库，避免覆盖用户后续手动编辑。
生成项目时继续由现有 BusinessBlockGenerationService 生成前端组件、API、后端 Controller/Service/Mapper。

用户编辑保护：

如果 admin_home.layout_json 为空、不是 business-blocks-v1，或只包含 auto_admin_ 前缀的自动块，composer 可以重建后台主页。
如果已有用户手动添加的非自动块，composer 只补齐缺失的自动块，不删除或重排用户块。
如果用户删除某个自动块，后续初始化不应无限制补回；可通过 dashboard.disabledAutoBlocks 记录被用户移除的自动块 id 或 code。
自动块 id 统一使用 auto_admin_metric_ 和 auto_admin_chart_ 前缀，便于安全合并。

蓝图协议

AppBlueprintDesign 新增字段：

private AdminHomeDashboardDesign adminHomeDashboard;

建议 DTO：

AdminHomeDashboardDesign
AdminHomeMetricDesign
AdminHomeChartDesign
AdminHomeDimensionDesign
AdminHomeMetricItemDesign
AdminHomeFilterDesign
AdminHomeDateRangeDesign

AI 返回示例：

{
  "adminHomeDashboard": {
    "title": "运营总览",
    "description": "核心业务数据概览",
    "metrics": [
      {
        "code": "order_count",
        "title": "订单数",
        "tableName": "shop_order",
        "aggregate": "count",
        "field": "id",
        "filters": [],
        "dateRange": {
          "field": "create_time",
          "preset": "today"
        },
        "semantic": "order"
      }
    ],
    "charts": [
      {
        "code": "sales_trend",
        "title": "近30天销售趋势",
        "type": "line",
        "tableName": "shop_order",
        "dimension": {
          "field": "create_time",
          "timeUnit": "day"
        },
        "metrics": [
          {
            "field": "amount",
            "aggregate": "sum",
            "alias": "sales_amount",
            "label": "销售额"
          }
        ],
        "dateRange": {
          "field": "create_time",
          "preset": "last_30_days"
        },
        "semantic": "money"
      }
    ]
  }
}

规则：

metrics 目标数量为 4 个，最多采用 6 个。
charts 目标数量为 2 个，一个趋势类图表，一个结构类图表；最多采用 4 个。
所有 tableName、field、维度字段、筛选字段和日期字段必须引用真实表字段。
semantic 只用于展示映射，不参与 SQL。
允许 AI 省略 icon 和 theme，生成器统一补齐。

布局协议

后台主页仍写入 business-blocks-v1：

{
  "canvas": "business-blocks-v1",
  "dashboard": {
    "title": "运营总览",
    "source": "app_blueprint",
    "version": 1
  },
  "blocks": [
    {
      "id": "auto_admin_metric_order_count",
      "blockCode": "admin_metric_chart",
      "name": "订单数",
      "span": 3,
      "dataset": {},
      "display": {
        "title": "订单数",
        "semantic": "order",
        "icon": "el-icon-s-order",
        "theme": "green"
      }
    },
    {
      "id": "auto_admin_chart_sales_trend",
      "blockCode": "admin_line_chart",
      "name": "近30天销售趋势",
      "span": 8,
      "dataset": {},
      "display": {
        "title": "近30天销售趋势",
        "semantic": "money"
      }
    }
  ]
}

布局规则：

第一行：4 个指标卡，每个 span=3。
第二行：主趋势图 span=8，右侧分布/占比图 span=4。
第三行及以后：更多图表按 span=6 两列排列。
移动端所有块堆叠为单列。
扩展业务块页面模板，支持 span=3 和 span=8。
同步扩展业务块布局校验，允许 span 为 3、4、6、8、12。

校验与兜底

校验分三层：

引用校验：表和字段必须存在；sum、avg 字段必须是数值字段；日期范围字段必须是日期/时间字段；维度字段不能是大文本。
图表校验：复用 ChartDatasetValidator。metric 只能 1 个指标且无维度；line 和 bar 必须有维度并支持 1 到 3 个指标；pie 必须有维度且只能 1 个指标。
可恢复处理：单个块非法时丢弃该块并记录原因，不让整个后台主页失败。最终不足数量时进入兜底逻辑。

主业务表识别顺序：

优先使用业务循环计划中的核心对象或动作 owner table。
其次使用后台菜单绑定、表备注、表名打分，业务词包括 order、payment、booking、borrow、task、apply、record、product、user。
最后选字段较完整且非账号表、非关系表、非日志表的一张表。

兜底指标：

总记录数：count(id)，semantic=default
今日新增：count(id) + create_time=today，semantic=content
待处理：有状态字段时筛选 pending/waiting 等值，semantic=task
异常状态：有状态字段时筛选 rejected/cancelled/failed/disabled 等值，semantic=warning

兜底图表：

近30天新增趋势：按 create_time 的 day 分组 count(id)。
状态分布：按状态字段分组 count(id)；没有状态字段时按类型或分类字段分组。

如果兜底也无法构造合法配置，则保留业务块空态主页，并记录可诊断信息。

图标与颜色

AI 输出 semantic，生成器使用白名单映射：

money     -> el-icon-money      -> blue
order     -> el-icon-s-order    -> green
user      -> el-icon-user-solid -> cyan
task      -> el-icon-s-claim    -> orange
warning   -> el-icon-warning    -> red
inventory -> el-icon-box        -> purple
content   -> el-icon-document   -> teal
default   -> el-icon-data-line  -> gray

生成器写入 display.icon、display.theme、display.semantic。display.unit、display.prefix、display.suffix、display.precision 可由 AI 提供，缺省时保留简单数值。

模板增强

AdminChartBlock.vue.vm：

metric 类型渲染为指标卡，而不是普通图表卡。
指标卡展示图标、标题、副标题、数值和单位。
theme 控制图标背景、数字强调色和轻量边框色。
支持 unit、prefix、suffix、precision。
非 metric 图表继续使用现有 ECharts 渲染，但可复用 display.icon/theme 优化标题区。

business-block-page.vue.vm：

增加 .business-block-page__item--span-3。
增加 .business-block-page__item--span-8。

AI 提示调整

AiGenerateServiceImpl.buildAppBlueprintPrompt() 的返回 JSON 示例和约束中加入 adminHomeDashboard。

提示重点：

必须为后台首页生成运营驾驶舱配置。
指标应优先选择最能反映业务价值的 4 个核心指标。
图表应至少包含一个趋势图和一个分布/占比图。
表名和字段名应与后续数据库设计可直接创建的业务语义保持一致。
不要输出具体图标类名，输出 semantic。
不要生成 SQL、代码或菜单数据库表。

数据库生成提示也应说明：数据库设计需要包含 adminHomeDashboard 引用的表和字段，除非这些引用来自已确认蓝图中不存在的可选项。保存数据库设计后，后台主页 composer 仍以真实表结构为准。

测试

后端单元测试：

AI 返回完整 adminHomeDashboard 时，后台主页生成 4 个指标卡和 2 个图表。
AI 缺字段或字段错误时，只丢弃坏块，并使用主业务表兜底补齐。
没有 adminHomeDashboard 时，从主业务表生成默认驾驶舱。
semantic 能映射为稳定的 Element UI 图标和主题色。
span=3、span=8 能被业务块页面模板渲染。
metric 模板包含图标、主题、单位格式和数值展示。
前台首页 carousel/notice/news 自动组合不受影响。
既有后台图表业务块生成测试不回归。

建议测试类：

AdminHomeDashboardComposerTest
FrontendPageDesignServiceTest
BusinessBlockGenerationServiceTest
QingTemplateSupportTest
AiGenerateServiceImplTest

非目标

不做自由拖拽大屏。
不支持自定义 SQL。
不支持关联表聚合。
不引入新的图标库或 SVG 资产体系。
不做块级 RBAC。
不把后台图表块暴露给前台页面。

10 KiB Raw Permalink Blame History Unescape Escape