# 指标查询系统 - 前后端集成指南

## 📌 概述

为了解决跨域问题，实现了一套完整的指标查询系统，包括：
- **JSP 代理层** (`metrics-proxy.jsp`) - 后端代理调用 C# API
- **前端仪表盘** (`metrics-dashboard.html`) - 可视化展示界面

## 📁 文件说明

### 1. metrics-proxy.jsp
位置: 项目根目录

**作用**: 作为中间层代理，调用 C# 后端的 MetricsController API

**支持的操作**:
- `getLabelRate` - 获取交接单标签率
- `getOrderAssessment` - 获取订单考核指标
- `getDailySummary` - 获取每日汇总
- `getDailySummaries` - 获取日期范围汇总
- `get24HCompletionRate` - 获取24小时完成率
- `getDailyCompletionRate` - 获取每日完成率
- `getBatchOrderMetrics` - 批量获取订单指标 (POST)
- `recalculateLabelRate` - 重新计算标签率 (POST)

**请求示例**:
```javascript
// GET 请求示例
fetch('metrics-proxy.jsp?action=getLabelRate&handoverNumber=HN001&env=test')

// POST 请求示例
fetch('metrics-proxy.jsp', {
    method: 'POST',
    body: JSON.stringify({
        action: 'getBatchOrderMetrics',
        waybills: ['LR001', 'LR002'],
        env: 'test'
    })
})
```

### 2. metrics-dashboard.html
位置: 项目根目录

**作用**: 前端可视化仪表盘，提供友好的用户界面

**功能模块**:
1. 🏷️ **交接单标签率查询** - 输入交接单号查询标签率
2. 📋 **订单考核指标查询** - 输入中性面单号查询考核信息
3. 📊 **每日汇总统计** - 选择日期查询该天的完整统计
4. 📈 **日期范围统计** - 查询某个时间段的所有统计数据
5. ⚡ **完成率统计** - 查询24小时完成率和每日完成率

## 🚀 使用步骤

### 步骤1: 部署 JSP 文件

1. 将 `metrics-proxy.jsp` 放在项目根目录或 Web 服务器的根目录
2. 确保 Java 环境已配置（需要 `org.json` 库）

### 步骤2: 配置依赖

如果使用 JSP，需要在 pom.xml 中添加依赖（如果使用 Maven）：
```xml
<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20230227</version>
</dependency>
```

### 步骤3: 集成到 batch_query.html

在 batch_query.html 的标签页中添加新的标签：
```html
<li class="nav-item" role="presentation">
    <button class="nav-link" id="metrics-tab" data-bs-toggle="tab" data-bs-target="#metrics" type="button" role="tab">📊 指标查询</button>
</li>
```

在内容区添加 iframe：
```html
<div class="tab-pane fade" id="metrics" role="tabpanel">
    <iframe src="metrics-dashboard.html" style="width:100%; height:800px; border:none; border-radius:8px;"></iframe>
</div>
```

### 步骤4: 打开仪表盘

在浏览器中访问：
```
http://your-domain/metrics-dashboard.html
```

## 🔧 环境配置

仪表盘支持三种环境：
- **本地环境**: http://localhost:5002
- **测试环境**: http://172.232.21.79:5002 (默认)
- **生产环境**: https://lr.tooexp.com

在仪表盘中的"环境选择"下拉菜单切换环境。

## 📊 API 端点说明

### 1. 获取标签率
```
GET /metrics-proxy.jsp?action=getLabelRate&handoverNumber=HN001&env=test

响应:
{
  "success": true,
  "data": {
    "handoverNumber": "HN001",
    "totalOrderCount": 100,
    "labeledOrderCount": 90,
    "labelRate": 0.9,
    "firstScanTime": "2026-05-17T10:30:00"
  }
}
```

### 2. 获取订单评估
```
GET /metrics-proxy.jsp?action=getOrderAssessment&neutralWaybillNumber=LR001&env=test

响应:
{
  "success": true,
  "data": {
    "neutralWaybillNumber": "LR001",
    "labelRate": 0.85,
    "assessmentTime": "2026-05-18T16:00:00",
    "completedOnTime": true,
    "handoverNumber": "HN001"
  }
}
```

### 3. 获取每日汇总
```
GET /metrics-proxy.jsp?action=getDailySummary&date=2026-05-17&env=test

响应:
{
  "success": true,
  "data": {
    "date": "2026-05-17",
    "dailyNewReplaceCount": 150,
    "dailySuccessCount": 145,
    "dailyShouldReplaceCount": 150,
    "dailyCompletionRate": "96.67%",
    "dailyScanCount": 200,
    "dailyStopCount": 25,
    "dailyLabelPushCount": 160
  }
}
```

## 🎯 关键特性

✅ **跨域处理** - 通过 JSP 代理层解决跨域问题
✅ **多环境支持** - 支持本地、测试、生产环境切换
✅ **实时查询** - 直接调用后端 API 获取最新数据
✅ **友好界面** - 现代化的卡片式设计
✅ **完整指标** - 覆盖所有业务指标
✅ **错误处理** - 完善的错误提示和异常处理

## 🔍 排查问题

### 问题1: JSP 404 错误
**原因**: JSP 文件未正确部署
**解决**: 确保 metrics-proxy.jsp 在 Web 服务器的正确目录

### 问题2: 跨域仍然发生
**原因**: JSP 配置不完整
**解决**: 检查 JSP 中的 CORS 头设置是否正确

### 问题3: 无法调用 API
**原因**: 环境配置错误或后端服务未启动
**解决**: 检查环境选择，确保后端服务正在运行

### 问题4: 数据为空
**原因**: 查询的数据不存在或参数错误
**解决**: 确认参数正确，检查数据库是否有相应数据

## 📝 集成建议

1. **性能优化**：如果查询量大，可在 JSP 中添加缓存机制
2. **权限控制**：在 JSP 中添加身份验证逻辑
3. **日志记录**：记录所有代理请求以便调试
4. **错误日志**：添加更详细的错误日志记录

## 🔐 安全建议

1. **输入验证**：JSP 中已添加基本验证，但建议加强
2. **速率限制**：防止 DDoS 攻击，添加请求限流
3. **授权检查**：在生产环境中添加授权验证
4. **HTTPS 使用**：生产环境必须使用 HTTPS

## 📞 技术支持

如有问题，请检查：
1. 后端 MetricsController 是否正确部署
2. Repository 实现层是否完成
3. 数据库连接是否正常
4. 日志文件中是否有错误信息

## 🎓 学习资源

- JSP 代理模式文档
- 跨域解决方案对比
- MetricsController API 文档
- 前端仪表盘使用指南