yidaima/RuoYi-Vue/docs/superpowers/specs/2026-07-06-admin-home-dashboard-metrics-design.md

# 后台主页运营驾驶舱设计

## 目标

通用生成后台项目时，自动把后台主页从空白或默认介绍页升级为运营驾驶舱。首页首屏展示 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。
- 不把后台图表块暴露给前台页面。