feat: конвертация бинарного .doc (Word 97-2003) в PDF (POI HWPF + FOP)

This commit is contained in:
Pjandro
2026-10-16 21:44:24 +00:00
parent 4d6cc2a795
commit 96865daef4
16 changed files with 1239 additions and 56 deletions
@@ -113,6 +113,7 @@ final class ConversionService {
}
/**
* Тело задачи воркера. Ядро принимает байты — временные файлы не нужны;
* имя влияет только на заголовок PDF (параметр {@code title}), потому
* санитизировано.
@@ -139,7 +140,7 @@ final class ConversionService {
/**
* Санитизация имени (единый источник для имени файла и Content-Disposition):
* без каталога, только буквы/цифры/пробел/ {@code . _ -}, без суффикса
* .docx; пустое после очистки → {@code document}. Кириллица разрешена —
* .docx/.doc; пустое после очистки → {@code document}. Кириллица разрешена —
* на Linux это валидное имя файла, и заголовок PDF остаётся читаемым.
*/
static String safeBaseName(String original) {
@@ -147,8 +148,11 @@ final class ConversionService {
: original.substring(Math.max(original.lastIndexOf('/'),
original.lastIndexOf('\\')) + 1);
base = base.replaceAll("[^\\p{L}\\p{N} ._-]", "");
if (base.toLowerCase(Locale.ROOT).endsWith(".docx")) {
base = base.substring(0, base.length() - ".docx".length());
String lower = base.toLowerCase(Locale.ROOT);
String suffix = lower.endsWith(".docx") ? ".docx"
: lower.endsWith(".doc") ? ".doc" : null;
if (suffix != null) {
base = base.substring(0, base.length() - suffix.length());
}
if (base.isBlank()) {
base = "document";
@@ -12,6 +12,7 @@ import org.springframework.web.bind.annotation.RestController;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.multipart.MultipartFile;
import ru.pjandro.wordpdf.ConvertOptions;
import ru.pjandro.wordpdf.WordPdfValidator;
import ru.pjandro.wordpdf.WordPdfSettings;
import ru.pjandro.wordpdf.ValidationException;
@@ -21,11 +22,12 @@ import java.util.Locale;
/**
* Единственный эндпоинт API: {@code POST /api/v1/convert} — multipart-поле
* {@code file} (.docx) → синхронный ответ байтами PDF.
* {@code file} (.docx или бинарный .doc) → синхронный ответ байтами PDF.
*
* <p>Здесь только HTTP-слой: проверка presence/расширения и формирование
* {@code Content-Disposition}; проверка содержимого (zip, размер, страницы) —
* зона {@link ConversionService#validate}. Ошибки в JSON-ответ переводит
* {@code Content-Disposition}; проверка содержимого (подпись контейнера
* zip/OLE2, размер, страницы) — зона {@link WordPdfValidator#validate(byte[], ConvertOptions)}.
* Ошибки в JSON-ответ переводит
* {@link ApiExceptionHandler}. Лимиты входа — только конфигурация сервера
* (свойства {@code wordpdf.max-bytes}/{@code wordpdf.max-pages}, env
* {@code WORDPDF_MAX_BYTES}/{@code WORDPDF_MAX_PAGES}); параметрами запроса
@@ -58,11 +60,14 @@ final class ConvertController {
this.maxPages = maxPages;
}
@Operation(summary = "Конвертировать .docx в PDF",
@Operation(summary = "Конвертировать .docx или .doc в PDF",
description = "renderCharts/renderSmartArt/errorOnCharts/errorOnSmartArt — факультативно, "
+ "по умолчанию настройки ядра; render-флаг приоритетнее error-флага. "
+ "Лимиты входа (размер/страницы) задаёт только конфигурация сервера "
+ "(свойства wordpdf.max-bytes/wordpdf.max-pages), параметрами запроса не переопределяются")
+ "(свойства wordpdf.max-bytes/wordpdf.max-pages), параметрами запроса не переопределяются. "
+ ".doc (Word 97-2003) конвертируется с деградацией вёрстки: шрифты — аналоги из бандла, "
+ "колонтитулы переносятся, диаграммы — как встроенные превью-изображения; "
+ "renderCharts/renderSmartArt/errorOn* на .doc не влияют")
@SecurityRequirement(name = OpenApiConfig.SCHEME)
@PostMapping(
path = "/api/v1/convert",
@@ -78,9 +83,10 @@ final class ConvertController {
throw new ValidationException("Файл не передан (multipart-поле «file» обязательно)");
}
String name = file.getOriginalFilename();
if (name == null || !name.toLowerCase(Locale.ROOT).endsWith(".docx")) {
if (name == null || !(name.toLowerCase(Locale.ROOT).endsWith(".docx")
|| name.toLowerCase(Locale.ROOT).endsWith(".doc"))) {
// расширение проверяется здесь: ядро с байтов его не видит
throw new ValidationException("Поддерживается только .docx (без .doc): " + name);
throw new ValidationException("Поддерживаются только .docx и .doc: " + name);
}
byte[] docxBytes;
try {
@@ -98,9 +104,15 @@ final class ConvertController {
ContentDisposition disposition = ContentDisposition.attachment()
.filename(ConversionService.safeBaseName(name) + ".pdf", StandardCharsets.UTF_8)
.build();
return ResponseEntity.ok()
ResponseEntity.BodyBuilder response = ResponseEntity.ok()
.contentType(MediaType.APPLICATION_PDF)
.header(HttpHeaders.CONTENT_DISPOSITION, disposition.toString())
.body(pdf);
.header(HttpHeaders.CONTENT_DISPOSITION, disposition.toString());
if (name.toLowerCase(Locale.ROOT).endsWith(".doc")) {
// .doc (не .docx): POI HWPF даёт дрейф вёрстки, колонтитулы —
// инъекция в FO-DOM, экзотические глифы остаются .notdef —
// клиент обязан знать о деградации (см. internal.DocToPdfRenderer).
response = response.header("X-Wordpdf-Degraded", "headers-footers-exotic-glyphs");
}
return response.body(pdf);
}
}
@@ -113,6 +113,7 @@ class ConvertControllerTest {
.andExpect(content().contentType(MediaType.APPLICATION_PDF))
.andExpect(header().string(HttpHeaders.CONTENT_DISPOSITION,
org.hamcrest.Matchers.containsString("filename*=UTF-8''ru-plain.pdf")))
.andExpect(header().doesNotExist("X-Wordpdf-Degraded"))
.andReturn();
byte[] pdf = result.getResponse().getContentAsByteArray();
assertTrue("%PDF".equals(new String(pdf, 0, 4, StandardCharsets.US_ASCII)),
@@ -326,14 +327,40 @@ class ConvertControllerTest {
@Test
void corruptNotAZip_rejected() throws Exception {
// без zip-подписи ZipInputStream молча даёт 0 записей — отсекает
// отдельная проверка magic bytes
// без подписи контейнера (zip для .docx, OLE2 для .doc) лёгкий
// счётчик страниц молчит — отсекает отдельная проверка magic bytes
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("broken.docx", "это просто текст, не архив"
.getBytes(StandardCharsets.UTF_8))))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("не zip-архив")));
org.hamcrest.Matchers.containsString("не похоже на .docx или .doc")));
}
/**
* Бинарный .doc проходит тот же эндпоинт: расширение принято, ядро
* выбирает POI-ветку по OLE2-магику, ответ несёт заголовок деградации
* X-Wordpdf-Degraded (контракт AGENTS.md); у .docx его нет.
* Регрессия — ConvertController (расширения + заголовок) +
* ConversionService#validate (магик), фикстура /samples/legacy-doc.doc
* (test-jar core).
*/
@Test
void legacyDoc_convertsToPdf() throws Exception {
MvcResult result = mockMvc.perform(multipart("/api/v1/convert")
.file(docx("testDoc.doc", bytes("/samples/legacy-doc.doc"))))
.andExpect(status().isOk())
.andExpect(content().contentType(MediaType.APPLICATION_PDF))
.andExpect(header().string(HttpHeaders.CONTENT_DISPOSITION,
org.hamcrest.Matchers.containsString("filename*=UTF-8''testDoc.pdf")))
.andExpect(header().string("X-Wordpdf-Degraded",
"headers-footers-exotic-glyphs"))
.andReturn();
byte[] pdf = result.getResponse().getContentAsByteArray();
assertTrue(new String(pdf, 0, 4, StandardCharsets.US_ASCII).equals("%PDF"),
"тело не начинается с %PDF");
String text = norm(pdfText(pdf));
assertTrue(text.contains("Нижний колонтитул"), "нет колонтитула: " + text);
}
@Test