# 📋 下一步操作指南

## 🎯 当前状态

✅ **代码已完成**: ReportController.java 已添加新接口
✅ **文档已完成**: 6个文档文件已创建
✅ **测试脚本已完成**: Windows 和 Linux/Mac 测试脚本已就绪

⏳ **待执行**: 编译、测试、验证

---

## 🚀 立即开始测试（推荐流程）

### 选项A: 完整测试流程（推荐）

#### 步骤1: 检查环境

```bash
# 检查Java版本（需要17+）
java -version

# 检查Maven
mvn -version

# 检查当前目录
pwd
```

**预期输出**:
```
java version "17.x.x" 或更高
Apache Maven 3.x.x
当前在项目根目录
```

---

#### 步骤2: 编译项目

```bash
cd admin-server
mvn clean compile
```

**如果编译失败**:
- Java版本过低 → 升级到Java 17+
- 依赖问题 → 运行 `mvn clean install`

---

#### 步骤3: 启动应用

```bash
# 方式1: 使用Maven
mvn spring-boot:run

# 方式2: 使用jar包（如果已打包）
java -jar target/admin-server-1.0-SNAPSHOT.jar
```

**等待启动完成**，看到类似输出：
```
Started AdminServerApplication in X.XXX seconds
```

---

#### 步骤4: 运行测试脚本

**打开新的终端窗口**，运行：

```bash
# Windows
cd F:\code\estate_expert
测试新接口.bat

# Linux/Mac
cd /path/to/estate_expert
./测试新接口.sh
```

**测试脚本会自动**:
1. 下载 Word 版本报告
2. 下载旧接口 PDF
3. 下载新接口 PDF
4. 显示文件大小对比
5. 打开文件夹

---

#### 步骤5: 验证结果

打开 `test_reports` 文件夹，检查3个文件：

**文件1: 模糊评价报告.docx**
- [ ] 能正常打开
- [ ] 包含图片
- [ ] 内容完整

**文件2: 模糊评价报告_旧接口.pdf**
- [ ] 能正常打开
- [ ] 检查是否有图片
- [ ] 记录图片显示情况

**文件3: 模糊评价报告_新接口.pdf**
- [ ] 能正常打开
- [ ] **重点检查图片是否显示**
- [ ] 对比与Word版本的差异

---

### 选项B: 快速手动测试

如果不想运行测试脚本，可以手动测试：

#### 1. 浏览器测试

直接访问：
```
http://localhost:8080/admin/stat/report/fuzzyReportPdfNew?checkTaskId=1262&templateId=1
```

浏览器会自动下载PDF文件。

#### 2. curl 测试

```bash
curl -o "test.pdf" \
  "http://localhost:8080/admin/stat/report/fuzzyReportPdfNew?checkTaskId=1262&templateId=1"

# 检查文件
ls -lh test.pdf

# 打开文件
start test.pdf      # Windows
open test.pdf       # Mac
xdg-open test.pdf   # Linux
```

---

## 🔍 测试结果判断

### 场景1: PDF中有图片 ✅

**恭喜！** 新接口工作正常，无需修改。

**后续工作**:
- 可以将旧接口替换为新接口
- 或者保留两个接口供选择

---

### 场景2: PDF中没有图片 ⚠️

**原因**: PDF转换库在处理内存流时丢失图片

**解决方案**: 使用临时文件方案

#### 修改步骤:

1. **打开文件**:
   ```bash
   # 使用编辑器打开
   code admin-server/src/main/java/com/estate/expert/admin/controller/stat/ReportController.java
   ```

2. **添加导入**（在文件顶部）:
   ```java
   import java.nio.file.Files;
   import java.nio.file.Path;
   import java.io.FileInputStream;
   import java.io.FileOutputStream;
   ```

3. **替换 downloadAsPdf 方法**（第168-233行）:

   将现有的方法替换为：

   ```java
   private void downloadAsPdf(XWPFTemplate doc, HttpServletResponse response, String typeName,
                              Integer checkTaskId, Integer templateId) throws IOException {
       Path tempDocxFile = null;
       FileInputStream tempInputStream = null;
       XWPFDocument document = null;
       OutputStream out = null;
       BufferedOutputStream bos = null;

       try {
           var checkTask = checkTaskService.get(checkTaskId, true);
           var reportTemplate = reportTemplateService.get(templateId);
           BizResultCode.TASK_NOT_FOUND.check(checkTask == null);

           var docName = checkTask.getProject().getName() + "_" + reportTemplate.getName() + "_" + typeName;
           String encodedFileName = URLEncoder.encode(docName, "UTF-8");
           response.setContentType("application/pdf");
           response.setHeader("Content-disposition", "attachment;filename=\"" + encodedFileName + ".pdf\"");

           // 创建临时文件，确保Word文档完整写入磁盘
           tempDocxFile = Files.createTempFile("report_", ".docx");

           // 将Word模板写入临时文件
           try (FileOutputStream tempOutputStream = new FileOutputStream(tempDocxFile.toFile())) {
               doc.write(tempOutputStream);
               tempOutputStream.flush();
           }

           // 从临时文件读取Word文档，确保所有图片数据已完整写入
           tempInputStream = new FileInputStream(tempDocxFile.toFile());
           document = new XWPFDocument(tempInputStream);

           // 配置PDF选项
           PdfOptions options = PdfOptions.create();
           options.fontEncoding("UTF-8");

           // 转换为PDF并写入响应流
           out = response.getOutputStream();
           bos = new BufferedOutputStream(out);
           PdfConverter.getInstance().convert(document, bos, options);

           bos.flush();
           out.flush();

       } catch (Exception e) {
           log.error("Word转PDF失败", e);
           throw new IOException("Word转PDF失败: " + e.getMessage(), e);
       } finally {
           // 关闭资源
           if (document != null) {
               try {
                   document.close();
               } catch (Exception e) {
                   log.warn("关闭Word文档失败", e);
               }
           }
           if (tempInputStream != null) {
               try {
                   tempInputStream.close();
               } catch (Exception e) {
                   log.warn("关闭临时文件输入流失败", e);
               }
           }
           // 删除临时文件
           if (tempDocxFile != null) {
               try {
                   Files.deleteIfExists(tempDocxFile);
               } catch (Exception e) {
                   log.warn("删除临时文件失败: {}", tempDocxFile, e);
               }
           }
       }
   }
   ```

4. **重新编译和测试**:
   ```bash
   cd admin-server
   mvn clean compile
   mvn spring-boot:run
   
   # 重新运行测试脚本
   cd ..
   测试新接口.bat  # 或 ./测试新接口.sh
   ```

---

## 📊 性能监控（可选）

如果需要监控性能，可以添加日志：

### 在 downloadAsPdf 方法开始处添加:

```java
long startTime = System.currentTimeMillis();
log.info("开始生成PDF: checkTaskId={}, templateId={}", checkTaskId, templateId);
```

### 在 finally 块末尾添加:

```java
long endTime = System.currentTimeMillis();
log.info("PDF生成完成，耗时: {}ms", endTime - startTime);
```

### 查看性能日志:

```bash
tail -f logs/application.log | grep "PDF生成"
```

---

## 🐛 故障排查清单

### 问题1: 应用启动失败

**检查**:
```bash
# 查看端口占用
netstat -ano | findstr :8080  # Windows
lsof -i :8080                 # Linux/Mac

# 查看日志
tail -f logs/application.log
```

**解决**:
- 端口被占用 → 关闭占用进程或修改端口
- 配置错误 → 检查 application.yml

---

### 问题2: 接口404

**检查**:
```bash
# 确认接口路径
curl -I http://localhost:8080/admin/stat/report/fuzzyReportPdfNew?checkTaskId=1262&templateId=1

# 查看所有接口
curl http://localhost:8080/actuator/mappings | grep fuzzy
```

**解决**:
- 确认应用已启动
- 确认URL拼写正确
- 检查Controller是否正确加载

---

### 问题3: 下载的PDF损坏

**检查**:
```bash
# 查看文件大小
ls -lh test.pdf

# 查看文件类型
file test.pdf

# 查看日志错误
grep -i "error\|exception" logs/application.log | tail -20
```

**解决**:
- 文件大小为0 → 检查转换过程是否有异常
- 文件类型不是PDF → 检查响应头设置
- 查看详细错误日志

---

## 📝 测试报告模板

测试完成后，可以填写以下报告：

```
测试时间: ___________
测试人: ___________

环境信息:
- Java版本: ___________
- 操作系统: ___________
- 浏览器: ___________

测试结果:
[ ] Word版本下载成功
[ ] 旧接口PDF下载成功
[ ] 新接口PDF下载成功

PDF内容验证:
[ ] 文件能正常打开
[ ] 文件大小: _______ KB
[ ] 包含所有文本内容
[ ] 图片显示: [ ] 正常 [ ] 不显示 [ ] 部分显示
[ ] 中文无乱码
[ ] 表格显示正常
[ ] 图表显示正常

性能测试:
- 响应时间: _______ 秒
- 文件大小: _______ MB

问题记录:
___________________________________________
___________________________________________

结论:
[ ] 测试通过，可以使用
[ ] 需要修改（使用临时文件方案）
[ ] 其他问题: ___________
```

---

## 🎓 学习资源

### 相关技术文档

1. **Apache POI**
   - 官网: https://poi.apache.org/
   - Word处理: https://poi.apache.org/components/document/

2. **OpenSagres XDocReport**
   - GitHub: https://github.com/opensagres/xdocreport
   - PDF转换: https://github.com/opensagres/xdocreport/wiki

3. **poi-tl**
   - 官网: http://deepoove.com/poi-tl/
   - 文档: http://deepoove.com/poi-tl/#/

### 项目文档

- `README-新接口实现.md` - 完整实现总结
- `新接口使用说明.md` - 详细使用文档
- `新接口快速参考.md` - 快速参考卡片
- `快速开始.md` - 快速开始指南

---

## ✅ 完成检查清单

### 开发阶段
- [x] 代码实现完成
- [x] 文档编写完成
- [x] 测试脚本创建完成

### 测试阶段
- [ ] 环境检查完成
- [ ] 编译成功
- [ ] 应用启动成功
- [ ] 接口测试完成
- [ ] PDF内容验证完成

### 部署阶段
- [ ] 测试通过
- [ ] 性能验证完成
- [ ] 文档归档
- [ ] 代码提交

---

## 📞 需要帮助？

如果遇到问题，请提供：

1. **环境信息**:
   ```bash
   java -version
   mvn -version
   ```

2. **错误日志**:
   ```bash
   tail -100 logs/application.log
   ```

3. **测试结果**:
   - PDF文件大小
   - 是否能打开
   - 图片显示情况

4. **具体问题描述**

我会继续协助您解决！

---

**创建时间**: 2026-01-24
**版本**: v1.0
**状态**: 准备就绪，等待测试