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

## 🚀 快速开始

### 1. 添加依赖（已完成）

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

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

### 2. 配置文件路径

在 `application.yml` 中配置：

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

### 3. 启动应用

```bash
# 编译项目（需要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命令

```bash
# 下载并转图片
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](./Word转图片功能说明.md)
2. 📖 [Word转图片API接口文档.md](./Word转图片API接口文档.md)
3. 🌐 [报告下载预览页面.html](./报告下载预览页面.html)

---

## 🎉 开始使用

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

**祝使用愉快！** 🎊