# JSP 代理层部署指南

## 📌 概述

`metrics-proxy.jsp` 是一个 JSP 代理文件，用于处理前端到后端 C# API 的跨域请求。通过在后端调用 API，绕过浏览器的跨域限制。

## 🗂️ 文件位置

**推荐位置**: 项目 Web 根目录
```
/metrics-proxy.jsp
```

**或者 Tomcat 对应位置**:
```
$CATALINA_HOME/webapps/ROOT/metrics-proxy.jsp
```

## ⚙️ 部署步骤

### 步骤1：复制文件
将 `metrics-proxy.jsp` 复制到 Web 服务器根目录

### 步骤2：验证 Java 环境
确保安装了以下依赖：
- Java 8 或更高版本
- Tomcat 8.5 或更高版本
- org.json 库

### 步骤3：检查 JSP 引擎
验证服务器支持 JSP：
```
访问任何 .jsp 文件，检查是否能正确处理
```

### 步骤4：测试连接
在浏览器中测试：
```
http://localhost:8080/metrics-proxy.jsp?action=getLabelRate&handoverNumber=TEST&env=test
```

## 📦 依赖配置

### Maven pom.xml
```xml
<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20230227</version>
</dependency>

<!-- JSP API -->
<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.1.0</version>
    <scope>provided</scope>
</dependency>
```

### Gradle build.gradle
```gradle
dependencies {
    implementation 'org.json:json:20230227'
    providedCompile 'javax.servlet:javax.servlet-api:3.1.0'
}
```

## 🔧 配置说明

### 环境配置
JSP 自动检测环境参数：

| 环境参数 | 值 | 后端地址 |
|--------|-----|---------|
| env | local | http://localhost:5002 |
| env | test | http://172.232.21.79:5002 |
| env | production | https://lr.tooexp.com |

### 支持的操作

| Action | 方法 | 参数 | 说明 |
|--------|------|------|------|
| getLabelRate | GET | handoverNumber | 获取标签率 |
| getOrderAssessment | GET | neutralWaybillNumber | 获取订单评估 |
| getDailySummary | GET | date | 获取每日汇总 |
| getDailySummaries | GET | startDate, endDate | 获取日期范围 |
| get24HCompletionRate | GET | date | 获取24小时率 |
| getDailyCompletionRate | GET | date | 获取每日率 |
| getBatchOrderMetrics | POST | waybills | 批量查询 |
| recalculateLabelRate | POST | handoverNumber | 重新计算 |

## 🧪 测试方法

### 使用 cURL 测试
```bash
# 测试 GET 请求
curl "http://localhost:8080/metrics-proxy.jsp?action=getLabelRate&handoverNumber=HN001&env=test"

# 测试 POST 请求
curl -X POST "http://localhost:8080/metrics-proxy.jsp" \
  -H "Content-Type: application/json" \
  -d '{"action":"getBatchOrderMetrics","waybills":["LR001","LR002"],"env":"test"}'
```

### 使用 Postman 测试

1. 新建 GET 请求
2. URL: `http://localhost:8080/metrics-proxy.jsp`
3. 参数:
   - action: `getLabelRate`
   - handoverNumber: `HN001`
   - env: `test`
4. 发送请求

### 使用 JavaScript 测试
```javascript
// 测试获取标签率
fetch('metrics-proxy.jsp?action=getLabelRate&handoverNumber=HN001&env=test')
    .then(r => r.json())
    .then(data => console.log(data))
    .catch(e => console.error(e));
```

## 🛡️ CORS 配置

JSP 已配置 CORS 头：
```jsp
response.setHeader("Access-Control-Allow-Origin", "*");
response.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
response.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
```

### 限制跨域来源（生产环境建议）
修改第一行的 CORS 设置：
```jsp
response.setHeader("Access-Control-Allow-Origin", "https://yourdomain.com");
```

## 📝 日志配置

### 启用 JSP 调试日志
在 `web.xml` 中添加：
```xml
<init-param>
    <param-name>development</param-name>
    <param-value>true</param-value>
</init-param>
<init-param>
    <param-name>supressLog</param-name>
    <param-value>false</param-value>
</init-param>
```

### 查看日志
- Tomcat: `$CATALINA_HOME/logs/catalina.out`
- 应用: 取决于配置的日志框架

## 🔍 问题排查

### 问题1: 404 Not Found
```
原因: JSP 文件不存在或路径错误
解决:
1. 检查文件是否在正确位置
2. 确保服务器根目录配置正确
3. 清除浏览器缓存
```

### 问题2: 500 Internal Server Error
```
原因: JSP 执行错误
解决:
1. 查看服务器日志
2. 检查 org.json 库是否正确安装
3. 检查 Java 环本版本
```

### 问题3: org.json 导入失败
```
原因: 缺少依赖
解决:
1. 添加 org.json Maven 依赖
2. 重新构建项目
3. 清除 Tomcat 工作目录: rm -rf $CATALINA_HOME/work/*
```

### 问题4: 连接到后端 API 超时
```
原因: 后端未启动或网络不通
解决:
1. 确保后端 API 正在运行
2. 检查防火墙设置
3. 验证 URL 是否正确
4. 增加超时时间: connection.setConnectTimeout(15000)
```

### 问题5: 返回空数据
```
原因: 数据不存在或参数错误
解决:
1. 检查参数是否正确
2. 在数据库中验证数据
3. 查看后端日志
4. 使用 cURL 直接测试 API
```

## 🔐 安全加固

### 1. 输入验证（已包含基础验证）
建议增强：
```jsp
// 验证 handoverNumber 格式
if (!handoverNumber.matches("^[A-Z0-9-]+$")) {
    resultJson.put("error", "Invalid handoverNumber format");
}
```

### 2. 限制访问
在 JSP 开头添加 IP 白名单：
```jsp
String clientIP = request.getRemoteAddr();
String[] whiteList = {"127.0.0.1", "192.168.1.0"};
if (!Arrays.asList(whiteList).contains(clientIP)) {
    response.sendError(403, "Access Denied");
    return;
}
```

### 3. 请求限流
```jsp
// 添加简单的速率限制（需要使用 Redis 或其他缓存）
String key = clientIP + "_" + action;
if (hasExceededRateLimit(key)) {
    resultJson.put("error", "Rate limit exceeded");
}
```

### 4. 请求签名验证
```jsp
String signature = request.getParameter("signature");
if (!verifySignature(params, signature)) {
    resultJson.put("error", "Invalid signature");
}
```

## 📊 性能优化

### 1. 连接超时优化
```jsp
connection.setConnectTimeout(5000);   // 5 秒
connection.setReadTimeout(10000);     // 10 秒
```

### 2. 连接复用
```jsp
// 使用连接池（需要添加依赖）
HttpClientBuilder.create()
    .setConnectionManager(connManager)
    .build();
```

### 3. 缓存响应
```jsp
// 缓存 5 分钟
response.setHeader("Cache-Control", "max-age=300");
```

## 🚀 生产环境清单

- [ ] org.json 库已正确安装
- [ ] JSP 文件已部署到正确位置
- [ ] 后端 API 已配置 HTTPS
- [ ] CORS 头已限制为生产域名
- [ ] 日志记录已启用
- [ ] 输入验证已加强
- [ ] IP 白名单已配置
- [ ] 请求限流已实现
- [ ] 错误处理已完善
- [ ] 性能监控已启用

## 📞 维护建议

1. **定期检查日志** - 每天检查一次错误日志
2. **监控性能** - 记录 API 响应时间
3. **备份配置** - 保存 web.xml 和其他配置文件
4. **更新依赖** - 定期更新 org.json 库
5. **安全审计** - 定期进行安全审计

## 🎓 扩展功能

### 添加认证
```jsp
String token = request.getParameter("token");
if (!validateToken(token)) {
    resultJson.put("error", "Unauthorized");
}
```

### 添加审计日志
```jsp
auditLog.info("Action: " + action + ", User: " + userId + ", Timestamp: " + System.currentTimeMillis());
```

### 支持更多 API
```jsp
else if ("getOrderLog".equals(action)) {
    apiUrl = baseUrl + "/api/order-log/query";
}
```

---

**文档版本**: 1.0
**最后更新**: 2026-05-17
**作者**: 系统团队