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