Word转图片功能 - 快速开始指南

🚀 快速开始

1. 添加依赖（已完成）

在 admin-server/pom.xml 中已添加：

<!-- PDF to Image conversion -->
<dependency>
    <groupId>org.apache.pdfbox</groupId>
    <artifactId>pdfbox</artifactId>
    <version>2.0.29</version>
</dependency>

2. 配置文件路径

在 application.yml 中配置：

file:
  upload:
    dir: F:\file\estate  # Windows
    # dir: /data/uploads  # Linux

3. 启动应用

# 编译项目（需要Java 17）
mvn clean package -DskipTests

# 启动应用
java -jar admin-server/target/admin-server-1.0-SNAPSHOT.jar

4. 测试功能

方式1：使用测试脚本

Windows:
bash 测试Word转图片.bat

Linux:
bash chmod +x 测试Word转图片.sh ./测试Word转图片.sh

方式2：使用浏览器

打开 报告下载预览页面.html，按照页面提示操作。

方式3：使用curl命令

# 下载并转图片
curl -o report.docx "http://localhost:8080/admin/stat/report/fuzzyReport?checkTaskId=1&templateId=1&uuid=test123"

# 查询图片列表
curl "http://localhost:8080/admin/stat/report/getReportImages?uuid=test123"

# 检查转换状态
curl "http://localhost:8080/admin/stat/report/checkConversionStatus?uuid=test123"

📁 文件结构

F:\file\estate\reports\
├── test123.docx                    # Word原文件
└── images\
    ├── test123_page_1.png         # 第1页图片
    ├── test123_page_2.png         # 第2页图片
    └── test123_page_N.png         # 第N页图片

🔧 核心功能

1. 下载Word报告（可选转图片）

接口： GET /admin/stat/report/fuzzyReport

参数：
- checkTaskId (必填): 检查任务ID
- templateId (必填): 报告模板ID
- uuid (可选): 文件唯一标识，传入则保存并转图片

示例：
```javascript
// 仅下载
window.location.href = '/admin/stat/report/fuzzyReport?checkTaskId=1&templateId=1';

// 下载并转图片
const uuid = generateUUID();
window.location.href = /admin/stat/report/fuzzyReport?checkTaskId=1&templateId=1&uuid=${uuid};
```

2. 获取图片列表

接口： GET /admin/stat/report/getReportImages

示例：
javascript fetch('/admin/stat/report/getReportImages?uuid=test123') .then(res => res.json()) .then(result => { if (result.code === 0) { result.data.forEach(filename => { console.log(`/files/reports/images/${filename}`); }); } });

3. 检查转换状态

接口： GET /admin/stat/report/checkConversionStatus

示例：
``javascript async function waitForConversion(uuid) { for (let i = 0; i < 10; i++) { const res = await fetch(/admin/stat/report/checkConversionStatus?uuid=${uuid}`);
const result = await res.json();

    if (result.code === 0 && result.data.conversionCompleted) {
        console.log(`转换完成！共${result.data.imageCount}张图片`);
        return result.data;
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
}

}
```

🐛 常见问题

Q1: 转换失败，日志显示字体错误

原因： 系统缺少中文字体

解决方案：

Windows:
- 确保 C:\Windows\Fonts 目录有中文字体（如微软雅黑）

Linux:
bash sudo apt-get install fonts-wqy-zenhei fonts-wqy-microhei

Q2: 图片模糊不清晰

原因： DPI设置过低

解决方案： 修改DPI参数（在ReportController.java第456行）
java // 从 150 改为 300 BufferedImage image = pdfRenderer.renderImageWithDPI(i, 300, ImageType.RGB);

Q3: 转换速度慢

原因： 同步处理阻塞主线程

解决方案： 使用异步处理

Q4: 图片无法访问

原因： 静态资源映射未配置

解决方案： 检查 WebMvcConfig.java 配置是否正确

📝 更新日志

v1.0.0 (2026-01-24)
- ✅ 实现Word转图片基础功能
- ✅ 支持多页文档转换
- ✅ 300 DPI高清输出
- ✅ 完善的异常处理和日志记录
- ✅ 新增图片列表查询接口
- ✅ 新增转换状态检查接口
- ✅ 静态资源访问配置

📞 技术支持

如有问题，请查看：
1. 📖 Word转图片功能说明.md
2. 📖 Word转图片API接口文档.md
3. 🌐 报告下载预览页面.html

🎉 开始使用

✅ 确认依赖已添加
✅ 配置文件路径
✅ 启动应用
✅ 打开测试页面或运行测试脚本
✅ 开始使用！

祝使用愉快！ 🎊