LabelChange-server/.trae/documents/implementation_plan_daily_dashboard.md

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

📋 需求确认

用户真实需求：

• ✅ 选择一个日期
• ✅ 一次查询看到所有关键指标（20+个）
• ✅ 不需要逐个模块查询
• ✅ 不需要手动计算和拼凑
• ✅ 采用 JSONP 方式（与 batch_query.html 相同）

改进前流程：

用户选择日期 → 逐个查询5个模块 → 手动汇总 → 5分钟+

改进后流程：

用户选择日期 → 点击查询 → 一屏显示所有指标 → 2-3秒

---

🎯 实现步骤

第一步：创建/更新仪表盘前端 (metrics-dashboard-summary.html)

状态：已部分完成，需补充 JSONP 实现细节和指标展示逻辑

修改内容：

1. ✅ 环境选择器
2. ✅ 日期选择器 (简化为单一输入)
3. ✅ 查询/刷新按钮
4. ❌ JSONP 请求函数 (需补充完整)
5. ❌ 响应处理函数 (需补充完整)
6. ❌ 指标显示模板 (需补充完整)

关键 JSONP 实现：

// 回调函数注册
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 安全验证 (正则表达式)

关键代码片段：

// 获取 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+ 指标
• 格式：

{
  "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. 用户友好 - 简化操作，提升体验