# 指标查询系统 - 快速开始指南

## 📋 快速检查清单

- [ ] 已将 `metrics-proxy.jsp` 部署到 Web 服务器根目录
- [ ] 已将 `metrics-dashboard.html` 放在项目根目录
- [ ] Java 环境已配置 org.json 库
- [ ] C# MetricsController 已部署并运行
- [ ] Repository 实现层已完成
- [ ] 数据库连接正常

## 🎬 三步开启仪表盘

### 第1步：访问仪表盘
在浏览器中打开：
```
http://localhost:8080/metrics-dashboard.html
```

### 第2步：选择环境
在页面顶部选择环境：
- 本地环境 (http://localhost:5002)
- 测试环境 (http://172.232.21.79:5002)
- 生产环境 (https://lr.tooexp.com)

### 第3步：执行查询
根据需要选择查询类型，输入参数，点击查询按钮。

## 🔗 集成到 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-view" type="button" role="tab">📊 指标查询</button>
</li>

<!-- 在标签内容中添加 -->
<div class="tab-pane fade" id="metrics-view" role="tabpanel">
    <iframe src="metrics-dashboard.html" 
            style="width:100%; height:1200px; border:1px solid #e2e8f0; border-radius:8px; margin-top:16px;"></iframe>
</div>
```

## 📱 功能速查表

| 功能 | 参数 | 说明 |
|------|------|------|
| 查询标签率 | 交接单号 | 获取指定交接单的标签率、订单数等 |
| 查询订单指标 | 中性面单号 | 获取订单的考核时间、完成状态等 |
| 查询每日汇总 | 日期 | 获取指定日期的所有统计指标 |
| 查询日期范围 | 开始日期、结束日期 | 获取日期范围内的每日统计 |
| 查询完成率 | 日期 | 获取24小时或每日完成率 |

## 🛠️ 常用命令

### 测试 JSP 是否正常
```bash
# 在命令行中测试
curl "http://localhost:8080/metrics-proxy.jsp?action=getLabelRate&handoverNumber=HN001&env=test"
```

### 测试后端 API 是否正常
```bash
# 测试标签率 API
curl "http://172.232.21.79:5002/api/metrics/label-rate?handoverNumber=HN001"
```

### 查看日志
```
# JSP 错误日志通常在：
$CATALINA_HOME/logs/catalina.out

# C# 应用日志位置：
/src/CONTROLLER/logs/
```

## 📊 示例数据流

```
前端 (metrics-dashboard.html)
  ↓ 发送查询请求
JSP 代理 (metrics-proxy.jsp)
  ↓ 调用后端 API
后端控制器 (MetricsController)
  ↓ 调用服务层
业务逻辑 (MetricsCalculationService)
  ↓ 调用数据层
数据库 (MySQL)
  ↑ 返回结果
业务逻辑
  ↑ 计算指标
后端控制器
  ↑ 返回 JSON
JSP 代理
  ↑ 返回响应
前端
  ↑ 渲染结果
```

## ⚠️ 常见错误及解决

### Error: metrics-proxy.jsp not found
```
解决: 检查 JSP 文件是否在 Web 服务器根目录
确保服务器支持 JSP
```

### Error: org.json not found
```
解决: 添加依赖
<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20230227</version>
</dependency>
```

### Error: Cannot connect to API
```
解决: 
1. 检查环境选择是否正确
2. 确保后端服务正在运行
3. 检查防火墙设置
4. 查看浏览器控制台的网络请求
```

### Error: No data returned
```
解决:
1. 检查输入参数是否正确
2. 确认数据库中存在相应数据
3. 查看后端日志
4. 检查数据库连接
```

## 🎯 性能优化建议

### 1. 添加缓存
在 JSP 中添加缓存机制，减少数据库查询：
```jsp
// 缓存 5 分钟
Cache.put("labelRate_" + handoverNumber, result, 300);
```

### 2. 批量查询
使用批量查询接口而不是单个查询：
```javascript
// 不推荐
for (let i = 0; i < 100; i++) {
    queryLabelRate(waybills[i]);
}

// 推荐
queryBatchMetrics(waybills);
```

### 3. 异步加载
在仪表盘中使用异步加载提高响应速度：
```javascript
Promise.all([
    queryLabelRate(...),
    queryDailySummary(...),
    query24HRate(...)
]).then(results => {
    // 并行加载，更快显示
});
```

## 🔐 安全检查清单

- [ ] JSP 中已验证所有输入参数
- [ ] 后端 API 已实现权限检查
- [ ] 生产环境使用 HTTPS
- [ ] 已设置请求频率限制
- [ ] 已添加访问日志记录
- [ ] 敏感数据已加密

## 📚 相关文档

- [完整集成指南](metrics_frontend_integration.md)
- [API 文档](../docs/API_Documentation_zh.md)
- [MetricsController 实现](../src/CONTROLLER/Controllers/MetricsController.cs)
- [业务逻辑](../src/BLL/Services/MetricsCalculationService.cs)

## 🆘 获取帮助

1. 检查 [完整集成指南](metrics_frontend_integration.md)
2. 查看后端日志文件
3. 确认 Repository 实现是否完成
4. 测试 API 端点是否正常工作

---

**最后更新**: 2026-05-17
**版本**: 1.0