# 一键日期查询完整指标仪表盘 - 实现计划

## 📋 需求确认

**用户真实需求**：
- ✅ 选择**一个日期**
- ✅ **一次查询**看到所有关键指标（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. **用户友好** - 简化操作，提升体验