259 lines
7.2 KiB
Markdown
259 lines
7.2 KiB
Markdown
# 一键日期查询完整指标仪表盘 - 实现计划
|
||
|
||
## 📋 需求确认
|
||
|
||
**用户真实需求**：
|
||
- ✅ 选择**一个日期**
|
||
- ✅ **一次查询**看到所有关键指标（20+个）
|
||
- ✅ 不需要逐个模块查询
|
||
- ✅ 不需要手动计算和拼凑
|
||
- ✅ 采用 JSONP 方式（与 batch_query.html 相同）
|
||
|
||
**改进前流程**：
|
||
```
|
||
用户选择日期 → 逐个查询5个模块 → 手动汇总 → 5分钟+
|
||
```
|
||
|
||
**改进后流程**：
|
||
```
|
||
用户选择日期 → 点击查询 → 一屏显示所有指标 → 2-3秒
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 实现步骤
|
||
|
||
### 第一步：创建/更新仪表盘前端 (metrics-dashboard-summary.html)
|
||
**状态**：已部分完成，需补充 JSONP 实现细节和指标展示逻辑
|
||
|
||
**修改内容**：
|
||
1. ✅ 环境选择器
|
||
2. ✅ 日期选择器 (简化为单一输入)
|
||
3. ✅ 查询/刷新按钮
|
||
4. ❌ JSONP 请求函数 (需补充完整)
|
||
5. ❌ 响应处理函数 (需补充完整)
|
||
6. ❌ 指标显示模板 (需补充完整)
|
||
|
||
**关键 JSONP 实现**：
|
||
```javascript
|
||
// 回调函数注册
|
||
window['dashboardCallback_' + timestamp] = function(response) {
|
||
// 处理响应
|
||
}
|
||
|
||
// 构建 JSONP URL
|
||
url = "metrics-proxy.jsp?action=getDailyDashboard&date=2026-05-17&callback=dashboardCallback_xxx&env=test"
|
||
|
||
// 通过 script 标签加载
|
||
const script = document.createElement('script');
|
||
script.src = url;
|
||
document.head.appendChild(script);
|
||
```
|
||
|
||
**指标显示结构**：
|
||
```
|
||
├─ 核心指标 (3个大卡片)：当天新增、应换单数、已完成
|
||
├─ 完成率指标 (2个卡片)：当日完成率、24小时完成率
|
||
├─ 分时段统计 (表格)：16点前/后对比
|
||
└─ 详细指标 (信息卡片)：STOP数、标签推送、扫描数等
|
||
```
|
||
|
||
**文件路径**：`d:\EPproject\LabelReplaceServer\metrics-dashboard-summary.html`
|
||
|
||
---
|
||
|
||
### 第二步：更新 JSP 代理 (metrics-proxy.jsp)
|
||
**状态**：已存在，需新增 getDailyDashboard 操作和 JSONP 支持
|
||
|
||
**修改内容**：
|
||
1. 获取 callback 参数
|
||
2. 判断返回格式 (JSON vs JSONP)
|
||
3. 新增 `getDailyDashboard` 操作分支
|
||
4. JSONP 响应包装 (callback + 数据)
|
||
5. Callback 安全验证 (正则表达式)
|
||
|
||
**关键代码片段**：
|
||
```jsp
|
||
// 获取 callback 参数
|
||
String callback = request.getParameter("callback");
|
||
String format = request.getParameter("format");
|
||
if (format == null) {
|
||
format = (callback != null && !callback.isEmpty()) ? "jsonp" : "json";
|
||
}
|
||
|
||
// 新增操作
|
||
else if ("getDailyDashboard".equals(action)) {
|
||
apiUrl = baseUrl + "/api/metrics/daily-dashboard?date=" + URLEncoder.encode(date, "UTF-8");
|
||
}
|
||
|
||
// JSONP 返回处理
|
||
if ("jsonp".equals(format) && callback != null && !callback.isEmpty()) {
|
||
if (callback.matches("^[a-zA-Z_$][a-zA-Z0-9_$]*$")) {
|
||
out.print(callback + "(" + resultJson.toString() + ");");
|
||
} else {
|
||
out.print("jsonp_error({\"error\": \"Invalid callback name\"});");
|
||
}
|
||
} else {
|
||
out.print(resultJson.toString());
|
||
}
|
||
```
|
||
|
||
**文件路径**：`d:\EPproject\LabelReplaceServer\metrics-proxy.jsp`
|
||
|
||
---
|
||
|
||
### 第三步：后端 API 支持 (可选但推荐)
|
||
**状态**：需新增或验证
|
||
|
||
**修改内容**：
|
||
1. 验证 `/api/metrics/daily-dashboard` 端点是否存在
|
||
2. 如不存在，在 MetricsController 中新增此端点
|
||
3. 后端调用 MetricsCalculationService 的方法聚合数据
|
||
|
||
**API 规格**：
|
||
- **端点**：`GET /api/metrics/daily-dashboard?date=2026-05-17`
|
||
- **返回**：完整汇总 JSON 包含所有 20+ 指标
|
||
- **格式**：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"date": "2026-05-17",
|
||
"summary": {
|
||
"dailyNewReplaceCount": 150,
|
||
"dailyShouldReplaceCount": 150,
|
||
"dailySuccessCount": 145,
|
||
"dailyCompletionRate": "96.67%",
|
||
"rate24Hour": "96.67%"
|
||
},
|
||
"breakdown": {
|
||
"beforeNoon": {"arrived": 80, "passed": 78, "rate": "97.50%"},
|
||
"afternoon": {"arrived": 70, "passed": 67, "rate": "95.71%"}
|
||
},
|
||
"details": {
|
||
"cumulativeTotal": 500,
|
||
"dailyStop": 25,
|
||
"dailyLabelPush": 160,
|
||
"dailyScanCount": 200,
|
||
"dailyFailure": 5
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**文件路径**：
|
||
- `d:\EPproject\LabelReplaceServer\src\CONTROLLER\Controllers\MetricsController.cs`
|
||
- `d:\EPproject\LabelReplaceServer\src\BLL\Services\MetricsCalculationService.cs`
|
||
|
||
---
|
||
|
||
## 🔄 JSONP 工作流
|
||
|
||
### 前端流程
|
||
```
|
||
1. 用户选择日期 (e.g., 2026-05-17)
|
||
2. 点击"查询"按钮
|
||
3. 生成唯一回调名称：dashboardCallback_1234567890
|
||
4. 注册 window 全局函数：window['dashboardCallback_1234567890'] = function(data) {...}
|
||
5. 创建 <script> 标签，src = "metrics-proxy.jsp?action=getDailyDashboard&date=...&callback=dashboardCallback_1234567890&env=test"
|
||
6. 浏览器加载脚本，后端返回：dashboardCallback_1234567890({data...})
|
||
7. 浏览器执行回调，展示数据
|
||
```
|
||
|
||
### 后端流程 (JSP)
|
||
```
|
||
1. 接收 callback 参数
|
||
2. 判断格式为 JSONP
|
||
3. 调用后端 API：/api/metrics/daily-dashboard?date=xxx
|
||
4. 获取 JSON 响应
|
||
5. 包装成 JSONP 格式：callback_name({json_data})
|
||
6. 返回给浏览器
|
||
7. 浏览器执行回调函数
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 指标展示优先级
|
||
|
||
### 一级显示 (核心指标卡片)
|
||
- 当天新增换单数
|
||
- 当天应该换单数
|
||
- 当日换单完成数
|
||
|
||
### 二级显示 (完成率卡片)
|
||
- 当日完成率
|
||
- 24小时完成率
|
||
|
||
### 三级显示 (分时段表格)
|
||
- 16点前：到仓数、完成数、完成率
|
||
- 16点后：到仓数、完成数、完成率
|
||
|
||
### 四级显示 (详细指标卡片)
|
||
- 当日STOP数
|
||
- 当日标签推送数
|
||
- 当日扫描数
|
||
- 当日失败数
|
||
- 累计积压数
|
||
|
||
---
|
||
|
||
## 🎨 UI 样式要点
|
||
|
||
**颜色编码**（与 batch_query.html 保持一致）：
|
||
- 🟢 绿色：完成率 ≥ 95%
|
||
- 🟡 黄色：完成率 85%-95%
|
||
- 🔴 红色：完成率 < 85%
|
||
|
||
**响应式设计**：
|
||
- PC 端：全屏展示，多列布局
|
||
- 移动端：单列展示，堆叠卡片
|
||
|
||
---
|
||
|
||
## ✅ 验收标准
|
||
|
||
- ✅ 用户选择日期后，一次 JSONP 调用获取所有指标
|
||
- ✅ 所有 20+ 个指标在一个仪表盘页面展示
|
||
- ✅ 无需多个模块查询，无需手动计算
|
||
- ✅ JSONP 请求成功，callback 正确执行
|
||
- ✅ 错误处理完善 (超时、网络错误等)
|
||
- ✅ 支持环境切换 (本地、测试、生产)
|
||
- ✅ 支持数据刷新按钮
|
||
|
||
---
|
||
|
||
## 📅 实现优先级
|
||
|
||
| 优先级 | 任务 | 文件 |
|
||
|--------|------|------|
|
||
| **高** | 完成仪表盘前端 JSONP 实现 | metrics-dashboard-summary.html |
|
||
| **高** | 更新 JSP 代理支持 getDailyDashboard | metrics-proxy.jsp |
|
||
| **中** | 后端 API 端点新增/验证 | MetricsController.cs |
|
||
| **低** | 集成到导航菜单 (可选) | batch_query.html / 其他 |
|
||
|
||
---
|
||
|
||
## 🔗 相关文件参考
|
||
|
||
### 已有参考
|
||
- `batch_query.html` - JSONP 实现参考
|
||
- `metrics-dashboard-summary.html` - 前端仪表盘框架
|
||
- `metrics-proxy.jsp` - 后端代理框架
|
||
- `metrics_dashboard_improvement_plan.md` - 需求分析文档
|
||
|
||
### 需要新增/修改
|
||
- `metrics-dashboard-summary.html` - 补充完整 JSONP 和显示逻辑
|
||
- `metrics-proxy.jsp` - 新增 getDailyDashboard 操作
|
||
- `MetricsController.cs` - 新增 daily-dashboard 端点
|
||
|
||
---
|
||
|
||
## 💡 关键要点
|
||
|
||
1. **JSONP 方式** - 与现有 batch_query.html 保持一致
|
||
2. **一次查询** - 前端单一 API 调用，获取所有指标
|
||
3. **数据聚合** - JSP 代理调用后端聚合 API
|
||
4. **展示完整** - 一屏显示所有关键指标，分层展示
|
||
5. **用户友好** - 简化操作，提升体验
|
||
|