# Word URL转PDF - 快速参考手册

## 🚀 快速开始（30秒）

### 1. 基本使用

```bash
curl -o report.pdf "http://localhost:8080/admin/stat/report/fuzzyReportPdfNew?wordUrl=http://example.com/report.docx"
```

### 2. 指定文件名

```bash
curl -o report.pdf "http://localhost:8080/admin/stat/report/fuzzyReportPdfNew?wordUrl=http://example.com/report.docx&fileName=项目报告"
```

### 3. JavaScript调用

```javascript
window.location.href = '/admin/stat/report/fuzzyReportPdfNew?wordUrl=' + encodeURIComponent(wordUrl);
```

---

## 📋 API接口

### 接口地址

```
GET /admin/stat/report/fuzzyReportPdfNew
```

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| wordUrl | String | 是 | Word文档URL |
| fileName | String | 否 | 文件名（不含.pdf） |

### 响应

- **Content-Type:** `application/pdf`
- **文件名:** `{fileName}.pdf` 或 `report_{timestamp}.pdf`

---

## 💡 代码示例

### JavaScript

```javascript
// 方式1：直接下载
function downloadPdf(wordUrl, fileName) {
    const url = `/admin/stat/report/fuzzyReportPdfNew?wordUrl=${encodeURIComponent(wordUrl)}`;
    window.location.href = fileName ? `${url}&fileName=${encodeURIComponent(fileName)}` : url;
}

// 方式2：使用fetch
async function downloadPdf(wordUrl, fileName) {
    const url = `/admin/stat/report/fuzzyReportPdfNew?wordUrl=${encodeURIComponent(wordUrl)}`;
    const fullUrl = fileName ? `${url}&fileName=${encodeURIComponent(fileName)}` : url;

    const response = await fetch(fullUrl);
    const blob = await response.blob();

    const downloadUrl = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = downloadUrl;
    a.download = fileName ? `${fileName}.pdf` : 'report.pdf';
    a.click();
    window.URL.revokeObjectURL(downloadUrl);
}
```

### Java

```java
import java.io.*;
import java.net.*;

public class PdfDownloader {
    public static void downloadPdf(String wordUrl, String fileName) throws IOException {
        String apiUrl = "http://localhost:8080/admin/stat/report/fuzzyReportPdfNew";
        String fullUrl = apiUrl + "?wordUrl=" + URLEncoder.encode(wordUrl, "UTF-8");

        if (fileName != null) {
            fullUrl += "&fileName=" + URLEncoder.encode(fileName, "UTF-8");
        }

        URL url = new URL(fullUrl);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();

        try (InputStream in = connection.getInputStream();
             FileOutputStream out = new FileOutputStream(fileName + ".pdf")) {
            byte[] buffer = new byte[8192];
            int bytesRead;
            while ((bytesRead = in.read(buffer)) != -1) {
                out.write(buffer, 0, bytesRead);
            }
        }
    }
}
```

### Python

```python
import requests
import urllib.parse

def download_pdf(word_url, file_name=None):
    api_url = "http://localhost:8080/admin/stat/report/fuzzyReportPdfNew"
    params = {"wordUrl": word_url}

    if file_name:
        params["fileName"] = file_name

    response = requests.get(api_url, params=params)

    if response.status_code == 200:
        output_file = f"{file_name}.pdf" if file_name else "report.pdf"
        with open(output_file, 'wb') as f:
            f.write(response.content)
        print(f"PDF下载成功: {output_file}")
    else:
        print(f"下载失败: {response.status_code}")

# 使用
download_pdf("http://example.com/report.docx", "项目报告")
```

---

## 🔧 配置参数

### 超时设置

**位置:** `ReportController.java` 第543-544行

```java
connection.setConnectTimeout(30000); // 连接超时：30秒
connection.setReadTimeout(60000);    // 读取超时：60秒
```

### User-Agent

**位置:** 第545行

```java
connection.setRequestProperty("User-Agent", "Mozilla/5.0");
```

---

## 🐛 常见问题

### Q1: 中文文件名乱码

**已解决** - 使用RFC 5987规范

### Q2: 图表丢失

**已解决** - 使用XDocReport转换

### Q3: 下载超时

**解决方案:** 增加超时时间或使用异步处理

### Q4: HTTP 403错误

**解决方案:** 检查URL是否可访问，修改User-Agent

### Q5: 无法访问内网URL

**解决方案:** 确保服务器可以访问目标URL

---

## 📊 性能参考

| 文档大小 | 预计时间 |
|---------|---------|
| 1MB | 3-5秒 |
| 5MB | 8-13秒 |
| 10MB | 15-25秒 |

---

## 🔒 安全建议

### 生产环境必须添加

1. ✅ URL白名单验证
2. ✅ 文件大小限制（建议50MB）
3. ✅ 请求频率限制
4. ✅ 认证授权（移除@IgnoreAuth）

---

## 📝 测试工具

### 命令行测试

**Windows:** `测试Word-URL转PDF.bat`
**Linux:** `测试Word-URL转PDF.sh`

### 浏览器测试

打开 `Word-URL转PDF测试页面.html`

---

## 📞 获取帮助

### 文档

- [完整使用说明](./Word-URL转PDF使用说明.md)
- [实现总结](./Word-URL转PDF实现总结.md)

### 日志

```bash
grep "从URL下载Word文档" logs/spring.log
grep "PDF转换成功" logs/spring.log
```

---

## ✅ 检查清单

部署前检查：

- [ ] 服务已启动
- [ ] Word URL可访问
- [ ] 测试基本功能
- [ ] 测试中文文件名
- [ ] 添加URL白名单（生产环境）
- [ ] 添加文件大小限制（生产环境）
- [ ] 配置监控告警

---

**版本:** v1.0.0
**更新时间:** 2026-01-24
**状态:** ✅ 可用