📋 下一步操作指南

🎯 当前状态

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

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

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

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

步骤1: 检查环境

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

# 检查Maven
mvn -version

# 检查当前目录
pwd

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

步骤2: 编译项目

cd admin-server
mvn clean compile

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

步骤3: 启动应用

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

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

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

步骤4: 运行测试脚本

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

# 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 测试

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转换库在处理内存流时丢失图片

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

修改步骤:

打开文件:
bash # 使用编辑器打开 code admin-server/src/main/java/com/estate/expert/admin/controller/stat/ReportController.java
添加导入（在文件顶部）:
java import java.nio.file.Files; import java.nio.file.Path; import java.io.FileInputStream; import java.io.FileOutputStream;
替换 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);
           }
       }
   }

}
```

重新编译和测试:
```bash
cd admin-server
mvn clean compile
mvn spring-boot:run

# 重新运行测试脚本
cd ..
测试新接口.bat # 或 ./测试新接口.sh
```

📊 性能监控（可选）

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

在 downloadAsPdf 方法开始处添加:

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

在 finally 块末尾添加:

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

查看性能日志:

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

问题记录:
___________________________________________
___________________________________________

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

🎓 学习资源

项目文档

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

✅ 完成检查清单

开发阶段

[x] 代码实现完成
[x] 文档编写完成
[x] 测试脚本创建完成

测试阶段

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

部署阶段

[ ] 测试通过
[ ] 性能验证完成
[ ] 文档归档
[ ] 代码提交

📞 需要帮助？

如果遇到问题，请提供：

环境信息:
bash java -version mvn -version
错误日志:
bash tail -100 logs/application.log
测试结果:

PDF文件大小
是否能打开
图片显示情况

具体问题描述

我会继续协助您解决！

📋 下一步操作指南

🎯 当前状态

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

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

步骤1: 检查环境

步骤2: 编译项目

步骤3: 启动应用

步骤4: 运行测试脚本

步骤5: 验证结果

选项B: 快速手动测试

1. 浏览器测试

2. curl 测试

🔍 测试结果判断

场景1: PDF中有图片 ✅

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

修改步骤:

📊 性能监控（可选）

在 downloadAsPdf 方法开始处添加:

在 finally 块末尾添加:

查看性能日志:

🐛 故障排查清单

问题1: 应用启动失败

查看端口占用

查看日志

问题2: 接口404

确认接口路径

查看所有接口

问题3: 下载的PDF损坏

查看文件大小

查看文件类型

查看日志错误

📝 测试报告模板

🎓 学习资源

相关技术文档

项目文档

✅ 完成检查清单

开发阶段

测试阶段

部署阶段

📞 需要帮助？