From a398dd9df0769b52ffbafd95eb9f1a2a815a53bd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E9=B9=8F?= <wangpengv@yonyou.com>
Date: Mon, 6 Jul 2026 12:13:54 +0800
Subject: [PATCH] docs: define admin home dashboard metrics

---
 ...-06-admin-home-dashboard-metrics-design.md | 284 ++++++++++++++++++
 1 file changed, 284 insertions(+)
 create mode 100644 RuoYi-Vue/docs/superpowers/specs/2026-07-06-admin-home-dashboard-metrics-design.md

diff --git a/RuoYi-Vue/docs/superpowers/specs/2026-07-06-admin-home-dashboard-metrics-design.md b/RuoYi-Vue/docs/superpowers/specs/2026-07-06-admin-home-dashboard-metrics-design.md
new file mode 100644
index 0000000..819da30
--- /dev/null
+++ b/RuoYi-Vue/docs/superpowers/specs/2026-07-06-admin-home-dashboard-metrics-design.md
@@ -0,0 +1,284 @@
+# 后台主页运营驾驶舱设计
+
+## 目标
+
+通用生成后台项目时，自动把后台主页从空白或默认介绍页升级为运营驾驶舱。首页首屏展示 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`。
+
+流程：
+
+1. AI 生成应用蓝图时，额外返回 `adminHomeDashboard`。
+2. 初始化后台页面设计时，`FrontendPageDesignService.initializeAdminPageDesigns()` 创建或读取 `admin_home`。
+3. `AdminHomeDashboardComposer` 将蓝图中的指标和图表转换成业务块实例。
+4. composer 校验表、字段、聚合、日期范围和图表类型；非法块丢弃。
+5. 有效块不足目标数量时，composer 从主业务表生成兜底块。
+6. 只有 `layout_json` 变化时才更新数据库，避免覆盖用户后续手动编辑。
+7. 生成项目时继续由现有 `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` 新增字段：
+
+```java
+private AdminHomeDashboardDesign adminHomeDashboard;
+```
+
+建议 DTO：
+
+- `AdminHomeDashboardDesign`
+- `AdminHomeMetricDesign`
+- `AdminHomeChartDesign`
+- `AdminHomeDimensionDesign`
+- `AdminHomeMetricItemDesign`
+- `AdminHomeFilterDesign`
+- `AdminHomeDateRangeDesign`
+
+AI 返回示例：
+
+```json
+{
+  "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`：
+
+```json
+{
+  "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`。
+
+## 校验与兜底
+
+校验分三层：
+
+1. 引用校验：表和字段必须存在；`sum`、`avg` 字段必须是数值字段；日期范围字段必须是日期/时间字段；维度字段不能是大文本。
+2. 图表校验：复用 `ChartDatasetValidator`。`metric` 只能 1 个指标且无维度；`line` 和 `bar` 必须有维度并支持 1 到 3 个指标；`pie` 必须有维度且只能 1 个指标。
+3. 可恢复处理：单个块非法时丢弃该块并记录原因，不让整个后台主页失败。最终不足数量时进入兜底逻辑。
+
+主业务表识别顺序：
+
+1. 优先使用业务循环计划中的核心对象或动作 owner table。
+2. 其次使用后台菜单绑定、表备注、表名打分，业务词包括 `order`、`payment`、`booking`、`borrow`、`task`、`apply`、`record`、`product`、`user`。
+3. 最后选字段较完整且非账号表、非关系表、非日志表的一张表。
+
+兜底指标：
+
+- 总记录数：`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`，生成器使用白名单映射：
+
+```text
+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。
+- 不把后台图表块暴露给前台页面。