170 lines
9.2 KiB
Markdown
170 lines
9.2 KiB
Markdown
# 决策者大屏功能 - 设计文档
|
||
|
||
## 1. 功能描述
|
||
本功能模块是专为决策者和高级管理员（NEPV端）设计的全局态势感知中心。它通过一系列数据可视化图表、关键绩效指标（KPI）和地图，将系统采集和处理的海量数据，转化为直观、易于理解的宏观洞察，旨在为环保工作的战略规划和决策提供强有力的数据支持。
|
||
|
||
## 2. 涉及角色
|
||
- **主要使用者**: `决策者 (DECISION_MAKER)`
|
||
- **次要使用者**: `系统管理员 (ADMIN)` (需要访问以进行日常运营监控)
|
||
|
||
## 3. 业务规则
|
||
|
||
### 3.1 权限与数据规则
|
||
- **完全只读**: 大屏上的所有元素均为只读，不提供任何数据修改、删除或提交的入口。
|
||
- **数据聚合性**: 除非特殊说明，大屏展示的数据均为聚合后的统计结果（如区域平均值、月度总数），不暴露任何单个反馈或用户的详细隐私信息。
|
||
- **实时性**: 部分KPI指标（如"今日新增反馈"）要求准实时更新，后端需提供高效的查询接口。大部分统计图表数据可通过后台定时任务（如每小时或每日）预计算并缓存，以提升加载性能。
|
||
- **实时性与缓存**:
|
||
- **实时数据**: 关键KPI指标（如"今日新增反馈"）和实时检测数量图，应通过WebSocket或短轮询实现准实时更新。
|
||
- **缓存策略**: 大部分统计图表（如月度趋势、类型分布）的数据应由后端的定时任务（如每小时）预先计算，并存储在Redis等内存数据库中。前端请求API时，直接从缓存读取，极大提升加载速度。缓存的Key设计应包含日期和区域等维度，例如`dashboard:aqi_trend:2024-07`。
|
||
- **缓存失效**: 定时任务在生成新数据后，会覆盖旧的缓存，实现自动更新。
|
||
|
||
### 3.2 核心组件数据来源
|
||
- **KPI指标卡**: 直接查询数据库，对`feedback`和`user_account`等表进行快速COUNT或AVG聚合。
|
||
- **统计图表 (趋势图、分布图)**: 由后端的聚合服务，基于`aqi_data`和`feedback`表，按指定维度（时间、类型）进行GROUP BY计算后生成。
|
||
- **污染源热力图**: 后端聚合`feedback`表中的`grid_x`, `grid_y`坐标和`severityLevel`，生成一个包含坐标和权重的数据集，供前端渲染。数据同样需要被缓存。
|
||
- **AI年度报告**:
|
||
- 由一个年度批处理任务（Cron Job）在每年年底或次年年初自动触发。
|
||
- 该任务负责从数据库抽取全年关键统计数据，形成一份综合材料。
|
||
- 调用`deepseek-v3-250324`大模型API，将结构化的统计数据和分析要点作为Prompt，生成一份图文并茂的分析报告。
|
||
- 生成的报告（如PDF或Markdown格式）存储在文件服务器上，大屏端仅提供一个下载链接。
|
||
|
||
### 3.3 交互设计规则
|
||
- **全局筛选**: 在大屏顶部或侧边提供全局筛选控件，至少包括 **时间范围选择器**（如"近7天", "本月", "本年", 自定义范围）和 **区域选择器**（当下钻到省市级别时）。所有组件都应响应这些筛选条件的变化。
|
||
- **图表联动与下钻**:
|
||
- **联动**: 点击饼图的某个扇区（如"工业污染"），其他图表（如AQI趋势图、热力图）应能自动筛选并重新渲染，仅显示与"工业污染"相关的数据。
|
||
- **下钻**: 在地图或区域排行榜上，点击某个省份，可以下钻到该省的市级数据视图。此时，应有明显的面包屑导航提示当前所处的层级（如"全国 > 浙江省"）。
|
||
|
||
## 4. 功能实现流程
|
||
|
||
### 4.1 数据流架构
|
||
```mermaid
|
||
graph TD
|
||
subgraph "数据源 (DB)"
|
||
A[aqi_data]
|
||
B[feedback]
|
||
C[user_account]
|
||
end
|
||
|
||
subgraph "数据处理层"
|
||
D[定时聚合服务 (Cron Job)]
|
||
E[实时API服务]
|
||
F[<br><br><b>缓存 (Redis)</b><br><br>]
|
||
end
|
||
|
||
subgraph "前端大屏 (NEPV)"
|
||
G[KPI 指标卡]
|
||
H[AQI 趋势图]
|
||
I[污染类型分布图]
|
||
J[污染源热力图]
|
||
K[年度报告下载]
|
||
L[WebSocket 连接]
|
||
end
|
||
|
||
A & B & C --> D
|
||
D --> F
|
||
B & C --> E
|
||
|
||
E -- 实时查询 --> G
|
||
E -- 建立长连接 --> L
|
||
L -- 推送实时数据 --> G
|
||
|
||
F -- 读取缓存 --> H
|
||
F -- 读取缓存 --> I
|
||
F -- 读取缓存 --> J
|
||
|
||
subgraph "AI服务"
|
||
M[AI报告生成服务 (Annual Cron)]
|
||
N[大模型 API]
|
||
O[文件服务器]
|
||
end
|
||
|
||
A & B & C --> M
|
||
M --> N
|
||
N --> M
|
||
M --> O
|
||
O --> K
|
||
```
|
||
|
||
### 4.2 AI年度报告生成时序图
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Cron as "年度定时任务 (Cron Job)"
|
||
participant Service as "报告生成服务"
|
||
participant DB as "数据库"
|
||
participant LLM as "大模型API"
|
||
participant Storage as "文件服务器 (S3/MinIO)"
|
||
|
||
Cron->>Service: 触发年度报告生成任务 (e.g., for year 2024)
|
||
Service->>DB: 查询全年关键数据 (AQI, Feedback, etc.)
|
||
DB-->>Service: 返回年度统计数据
|
||
Service->>Service: 根据数据构建Prompt (包含统计表格和分析要点)
|
||
Service->>LLM: 发送请求 (POST /api/generate-report)
|
||
LLM-->>Service: 返回生成的报告内容 (Markdown/HTML)
|
||
Service->>Service: (可选) 将报告内容渲染为PDF
|
||
Service->>Storage: 上传报告文件 (e.g., report-2024.pdf)
|
||
Storage-->>Service: 返回文件URL
|
||
Service->>DB: 将报告URL存入`annual_reports`表
|
||
DB-->>Service: 存储成功
|
||
```
|
||
|
||
## 5. API 接口设计
|
||
|
||
### 5.1 KPI 指标接口
|
||
- **URL**: `GET /api/data-v/kpis`
|
||
- **查询参数**: `?timeRange=...&area=...`
|
||
- **响应**: `200 OK`, 返回 `[{ "title": "累计反馈总数", "value": 1024, "change": "+5%" }, ...]`
|
||
|
||
### 5.2 图表数据接口 (通用)
|
||
- **URL**: `GET /api/data-v/chart`
|
||
- **查询参数**: `?name=aqiTrend&timeRange=...&area=...` (name用于指定图表类型)
|
||
- **响应**: `200 OK`, 返回符合ECharts等图表库格式要求的数据结构。
|
||
|
||
### 5.3 热力图数据接口
|
||
- **URL**: `GET /api/data-v/heatmap`
|
||
- **查询参数**: `?timeRange=...&area=...`
|
||
- **响应**: `200 OK`, 返回 `[{ "lng": 120.15, "lat": 30.28, "count": 95 }, ...]`
|
||
|
||
### 5.4 实时数据推送
|
||
- **WebSocket**: `ws://your-domain/api/data-v/realtime`
|
||
- **推送消息格式**: `{ "type": "newFeedback", "data": { ... } }` or `{ "type": "kpiUpdate", "data": { ... } }`
|
||
|
||
## 6. 界面设计要求
|
||
|
||
### 6.1 整体布局与风格
|
||
- **主题**: 采用深色科技感主题（如深蓝色、暗灰色背景），以突出数据图表的色彩。
|
||
- **布局**: 基于`1920x1080`分辨率进行设计，采用栅格系统（如24列）进行灵活布局，确保在主流大屏上不变形。
|
||
- **组件**: 所有可视化组件（Widgets）以卡片形式组织，每个卡片都有清晰的标题。
|
||
- **交互性**: 所有图表在鼠标悬浮时应显示详细的Tooltip提示。支持点击事件，用于图表间的联动和下钻。
|
||
- **技术选型**: 推荐使用成熟的图表库，如`ECharts`或`AntV`，来实现高质量的可视化效果。
|
||
|
||
### 6.2 核心可视化组件详解
|
||
|
||
- **顶部 - KPI指标行 & 全局筛选器**:
|
||
- 在屏幕顶端横向排列4-6个核心指标卡。
|
||
- 指标行旁边或下方设置全局筛选器，包括时间范围和区域选择。
|
||
- 每个卡片包含一个醒目的图标、一个加粗的巨大数值、和一个清晰的指标名称（如"累计反馈总数"、"当前活跃网格员"、"本月平均AQI"）。
|
||
|
||
- **中部 - 可交互的污染源热力图**:
|
||
- **需求**: 在地图上查看可视化污染源热力图。
|
||
- **呈现形式**: 占据屏幕最大面积的核心组件。在二维网格地图上，根据各网格内高严重等级反馈的数量和权重，用不同的颜色（如从蓝色到红色）渲染，形成热力效果。地图应支持基本的缩放和拖拽操作。
|
||
|
||
- **图表组件 - 左侧面板**:
|
||
- **空气质量超标趋势图 (折线图)**:
|
||
- **需求**: 查看过去12个月的空气质量超标趋势。
|
||
- **呈现形式**: X轴为过去12个月份，Y轴为超标天数或超标事件次数。用平滑的曲线展示AQI超标趋势，并可提供与去年同期的对比线。
|
||
- **总AQI及分项污染物超标统计 (柱形图)**:
|
||
- **需求**: 查看总AQI及各分项污染物浓度超标的累计统计。
|
||
- **呈现形式**: X轴为污染物类型（总AQI, PM2.5, O3, NO2, SO2等），Y轴为本年度累计超标次数。每个污染物为一根柱子，清晰对比。
|
||
|
||
- **图表组件 - 右侧面板**:
|
||
- **AQI级别分布图 (饼图)**:
|
||
- **需求**: 查看AQI级别分布。
|
||
- **呈现形式**: 标准饼图，将AQI数据按标准（优、良、轻度污染、中度污染、重度污染、严重污染）划分，展示各级别占比。
|
||
- **各省市网格覆盖率 (饼图)**:
|
||
- **需求**: 查看各省市的网格覆盖率。
|
||
- **呈现形式**: 饼图展示已覆盖与未覆盖网格的**总体比例**。为获得更佳体验，可提供下钻功能或辅以排行榜/地图着色展示各省市详情。
|
||
- **实时空气质量检测数量 (实时折线图)**:
|
||
- **需求**: 查看实时的空气质量检测数量统计。
|
||
- **呈现形式**: X轴为过去24小时，Y轴为该时段内完成的AQI检测数，线条实时或准实时更新。
|
||
- **AI年度报告下载**:
|
||
- 一个简洁的卡片，包含报告年份，和一个醒目的"下载报告"按钮。 |