215 lines
5.8 KiB
Markdown
215 lines
5.8 KiB
Markdown
# 指标查询系统 - 前后端集成指南
|
||
|
||
## 📌 概述
|
||
|
||
为了解决跨域问题，实现了一套完整的指标查询系统，包括：
|
||
- **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 文档
|
||
- 前端仪表盘使用指南
|