# Word转图片功能 - API接口文档

## 接口概览

| 接口名称 | 接口路径 | 方法 | 说明 |
|---------|---------|------|------|
| 模糊评价报告下载 | `/admin/stat/report/fuzzyReport` | GET | 下载Word报告，可选转图片 |
| 获取报告图片列表 | `/admin/stat/report/getReportImages` | GET | 获取已转换的图片文件列表 |
| 检查转换状态 | `/admin/stat/report/checkConversionStatus` | GET | 检查文件转换状态 |

---

## 1. 模糊评价报告下载（支持转图片）

### 接口信息

- **接口路径：** `/admin/stat/report/fuzzyReport`
- **请求方法：** `GET`
- **接口说明：** 下载模糊评价报告Word文档，可选择同时转换为图片保存到服务器

### 请求参数

| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| checkTaskId | Integer | 是 | 检查任务ID | 1 |
| templateId | Integer | 是 | 报告模板ID | 1 |
| uuid | String | 否 | 文件唯一标识，传入则保存文件并转换为图片 | abc123 |

### 响应说明

- **Content-Type：** `application/octet-stream`
- **响应体：** Word文档二进制流
- **文件名：** `项目名_模板名_模糊评价.docx`（URL编码）

### 服务器端行为

**当 uuid 参数为空或不传时：**
- 仅返回Word文档供用户下载
- 不保存文件到服务器
- 不进行图片转换

**当 uuid 参数有值时：**
1. 返回Word文档供用户下载
2. 保存Word文档到服务器：`F:\file\estate\reports\{uuid}.docx`
3. 后台转换Word为图片：`F:\file\estate\reports\images\{uuid}_page_N.png`

### 请求示例

#### 示例1：仅下载（不保存）

```bash
curl -o report.docx "http://localhost:8080/admin/stat/report/fuzzyReport?checkTaskId=1&templateId=1"
```

#### 示例2：下载并转图片

```bash
curl -o report.docx "http://localhost:8080/admin/stat/report/fuzzyReport?checkTaskId=1&templateId=1&uuid=abc123"
```

#### 示例3：JavaScript调用

```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}`;

// 稍后查询图片列表
setTimeout(() => {
    fetch(`/admin/stat/report/getReportImages?uuid=${uuid}`)
        .then(res => res.json())
        .then(data => console.log('图片列表:', data));
}, 5000); // 等待5秒让转换完成
```

---

## 2. 获取报告图片列表

### 接口信息

- **接口路径：** `/admin/stat/report/getReportImages`
- **请求方法：** `GET`
- **接口说明：** 根据UUID获取已转换的图片文件列表

### 请求参数

| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| uuid | String | 是 | 文件唯一标识 | abc123 |

### 响应格式

```json
{
    "code": 0,
    "message": "success",
    "data": [
        "abc123_page_1.png",
        "abc123_page_2.png",
        "abc123_page_3.png"
    ]
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码，0表示成功 |
| message | String | 响应消息 |
| data | Array<String> | 图片文件名列表，按页码排序 |

### 请求示例

```bash
curl "http://localhost:8080/admin/stat/report/getReportImages?uuid=abc123"
```

### JavaScript示例

```javascript
async function getReportImages(uuid) {
    const response = await fetch(`/admin/stat/report/getReportImages?uuid=${uuid}`);
    const result = await response.json();

    if (result.code === 0) {
        console.log('图片列表:', result.data);
        // 构建完整URL
        const imageUrls = result.data.map(filename =>
            `/files/reports/images/${filename}`
        );
        return imageUrls;
    } else {
        console.error('获取图片列表失败:', result.message);
        return [];
    }
}

// 使用示例
getReportImages('abc123').then(urls => {
    urls.forEach((url, index) => {
        console.log(`第${index + 1}页: ${url}`);
    });
});
```

---

## 3. 检查转换状态

### 接口信息

- **接口路径：** `/admin/stat/report/checkConversionStatus`
- **请求方法：** `GET`
- **接口说明：** 检查Word文档转换为图片的状态

### 请求参数

| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| uuid | String | 是 | 文件唯一标识 | abc123 |

### 响应格式

```json
{
    "code": 0,
    "message": "success",
    "data": {
        "uuid": "abc123",
        "wordFileExists": true,
        "imageCount": 3,
        "conversionCompleted": true
    }
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码，0表示成功 |
| message | String | 响应消息 |
| data | Object | 转换状态对象 |
| data.uuid | String | 文件唯一标识 |
| data.wordFileExists | Boolean | Word文件是否存在 |
| data.imageCount | Integer | 已转换的图片数量 |
| data.conversionCompleted | Boolean | 转换是否完成（imageCount > 0） |

### 请求示例

```bash
curl "http://localhost:8080/admin/stat/report/checkConversionStatus?uuid=abc123"
```

### JavaScript示例

```javascript
async function checkConversionStatus(uuid) {
    const response = await fetch(`/admin/stat/report/checkConversionStatus?uuid=${uuid}`);
    const result = await response.json();

    if (result.code === 0) {
        const status = result.data;
        console.log(`UUID: ${status.uuid}`);
        console.log(`Word文件存在: ${status.wordFileExists}`);
        console.log(`图片数量: ${status.imageCount}`);
        console.log(`转换完成: ${status.conversionCompleted}`);
        return status;
    } else {
        console.error('检查状态失败:', result.message);
        return null;
    }
}

// 轮询检查转换状态
async function waitForConversion(uuid, maxAttempts = 10, interval = 2000) {
    for (let i = 0; i < maxAttempts; i++) {
        const status = await checkConversionStatus(uuid);

        if (status && status.conversionCompleted) {
            console.log('转换完成！');
            return status;
        }

        console.log(`等待转换完成... (${i + 1}/${maxAttempts})`);
        await new Promise(resolve => setTimeout(resolve, interval));
    }

    console.error('转换超时');
    return null;
}

// 使用示例
waitForConversion('abc123').then(status => {
    if (status) {
        console.log(`成功转换${status.imageCount}张图片`);
    }
});
```

---

## 完整使用流程示例

### 场景：下载报告并获取图片

```javascript
// 1. 生成UUID
const uuid = generateUUID(); // 或使用 crypto.randomUUID()

// 2. 下载报告（同时触发转换）
downloadReport(uuid);

// 3. 等待转换完成
const status = await waitForConversion(uuid);

// 4. 获取图片列表
if (status && status.conversionCompleted) {
    const images = await getReportImages(uuid);
    displayImages(images);
}

// 辅助函数
function generateUUID() {
    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
        const r = Math.random() * 16 | 0;
        const v = c === 'x' ? r : (r & 0x3 | 0x8);
        return v.toString(16);
    });
}

function downloadReport(uuid) {
    const url = `/admin/stat/report/fuzzyReport?checkTaskId=1&templateId=1&uuid=${uuid}`;
    window.location.href = url;
}

async function waitForConversion(uuid, maxAttempts = 10, interval = 2000) {
    for (let i = 0; i < maxAttempts; i++) {
        const response = await fetch(`/admin/stat/report/checkConversionStatus?uuid=${uuid}`);
        const result = await response.json();

        if (result.code === 0 && result.data.conversionCompleted) {
            return result.data;
        }

        await new Promise(resolve => setTimeout(resolve, interval));
    }
    return null;
}

async function getReportImages(uuid) {
    const response = await fetch(`/admin/stat/report/getReportImages?uuid=${uuid}`);
    const result = await response.json();
    return result.code === 0 ? result.data : [];
}

function displayImages(imageFiles) {
    const container = document.getElementById('image-container');
    imageFiles.forEach(filename => {
        const img = document.createElement('img');
        img.src = `/files/reports/images/${filename}`;
        img.alt = filename;
        container.appendChild(img);
    });
}
```

---

## 错误码说明

| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 0 | 成功 | - |
| 非0 | 失败 | 查看message字段获取详细错误信息 |

### 常见错误

**1. 任务不存在**
```json
{
    "code": 1001,
    "message": "任务不存在"
}
```
**解决方案：** 检查checkTaskId是否正确

**2. 文件不存在**
```json
{
    "code": 0,
    "message": "success",
    "data": []
}
```
**解决方案：**
- 检查uuid是否正确
- 确认是否已调用下载接口并传入uuid参数
- 等待转换完成（通常需要几秒钟）

**3. 转换失败**
- 查看服务器日志，搜索关键词："Word转图片失败"
- 检查服务器磁盘空间
- 检查系统字体是否完整

---

## 性能说明

### 转换时间

| 文档页数 | 预计转换时间 | 图片大小（300 DPI） |
|---------|-------------|-------------------|
| 1-5页 | 2-5秒 | 约500KB/页 |
| 6-10页 | 5-10秒 | 约500KB/页 |
| 11-20页 | 10-20秒 | 约500KB/页 |

### 并发限制

- 建议同时转换任务数：≤ 5个
- 超过限制可能导致服务器响应变慢

### 存储空间

- Word文档：约100-500KB/文档
- PNG图片：约500KB/页（300 DPI）
- 建议定期清理旧文件

---

## 安全说明

### 访问控制

- 所有接口已添加 `@IgnoreAuth` 注解，无需认证
- 生产环境建议添加认证机制

### UUID安全

- UUID应由客户端生成，确保唯一性
- 避免使用可预测的UUID（如连续数字）
- 建议使用标准UUID格式

### 文件访问

- 图片文件存储在服务器本地
- 需要配置静态资源映射才能通过HTTP访问
- 建议添加访问权限控制

---

## 配置静态资源访问

### Spring Boot配置

```java
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Value("${file.upload.dir}")
    private String uploadDir;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 映射图片访问路径
        registry.addResourceHandler("/files/reports/images/**")
                .addResourceLocations("file:" + uploadDir + "/reports/images/");
    }
}
```

### 访问示例

```
http://localhost:8080/files/reports/images/abc123_page_1.png
```

---

## 附录

### UUID生成方法

**Java:**
```java
String uuid = UUID.randomUUID().toString().replace("-", "");
```

**JavaScript:**
```javascript
const uuid = crypto.randomUUID().replace(/-/g, '');
```

**Python:**
```python
import uuid
uuid_str = str(uuid.uuid4()).replace('-', '')
```

### 图片预览HTML示例

```html
<!DOCTYPE html>
<html>
<head>
    <title>报告预览</title>
    <style>
        .image-container {
            max-width: 800px;
            margin: 0 auto;
        }
        .page-image {
            width: 100%;
            margin-bottom: 20px;
            box-shadow: 0 2px 8px rgba(0,0,0,0.1);
        }
    </style>
</head>
<body>
    <div class="image-container" id="images"></div>

    <script>
        const uuid = 'abc123'; // 替换为实际UUID

        fetch(`/admin/stat/report/getReportImages?uuid=${uuid}`)
            .then(res => res.json())
            .then(result => {
                if (result.code === 0) {
                    const container = document.getElementById('images');
                    result.data.forEach((filename, index) => {
                        const img = document.createElement('img');
                        img.src = `/files/reports/images/${filename}`;
                        img.className = 'page-image';
                        img.alt = `第${index + 1}页`;
                        container.appendChild(img);
                    });
                }
            });
    </script>
</body>
</html>
```