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

This commit is contained in:
Pjandro
2026-10-16 21:44:24 +00:00
parent e925242948
commit d72bf295ee
15 changed files with 1217 additions and 40 deletions
@@ -117,11 +117,13 @@ final class ConversionService {
* из конфигурации сервера: свойства {@code wordpdf.max-bytes}/
* {@code wordpdf.max-pages}, дефолт — константы ядра).
*
* <p>Проверка zip-подписи отдельным шагом обязательна:
* <p>Проверка подписи контейнера отдельным шагом обязательна:
* {@code ZipInputStream.getNextEntry()} на не-zip-потоке возвращает
* {@code null} молча, и {@link WordPdfValidator#checkPageCountLightweight(byte[])}
* такой вход не отверг бы (0 страниц). Регрессия —
* ConvertControllerTest#corruptNotAZip_rejected.</p>
* ConvertControllerTest#corruptNotAZip_rejected. Бинарный .doc — не zip,
* а OLE2 (CFB): для него свой магик и свой счётчик страниц
* ({@link WordPdfValidator#checkDocPageCountLightweight(byte[], int)}).</p>
*/
void validate(byte[] docxBytes, ConvertOptions options) {
try {
@@ -129,17 +131,31 @@ final class ConversionService {
} catch (ConversionException e) {
throw new ValidationException(e.getMessage(), e);
}
if (docxBytes.length < 4 || docxBytes[0] != 'P' || docxBytes[1] != 'K'
|| (docxBytes[2] & 0xFF) != 0x03 || (docxBytes[3] & 0xFF) != 0x04) {
throw new ValidationException("Содержимое не похоже на .docx (не zip-архив)");
boolean zip = docxBytes.length >= 4 && docxBytes[0] == 'P' && docxBytes[1] == 'K'
&& (docxBytes[2] & 0xFF) == 0x03 && (docxBytes[3] & 0xFF) == 0x04;
if (!zip && !isOle2(docxBytes)) {
throw new ValidationException("Содержимое не похоже на .docx или .doc");
}
try {
WordPdfValidator.checkPageCountLightweight(docxBytes, options.maxPages());
if (zip) {
WordPdfValidator.checkPageCountLightweight(docxBytes, options.maxPages());
} else {
WordPdfValidator.checkDocPageCountLightweight(docxBytes, options.maxPages());
}
} catch (ConversionException e) {
throw new ValidationException(e.getMessage(), e);
}
}
/** Магик OLE2 (CFB): {@code D0 CF 11 E0 A1 B1 1A E1} — контейнер .doc. */
private static boolean isOle2(byte[] bytes) {
return bytes.length >= 8
&& (bytes[0] & 0xFF) == 0xD0 && (bytes[1] & 0xFF) == 0xCF
&& (bytes[2] & 0xFF) == 0x11 && (bytes[3] & 0xFF) == 0xE0
&& (bytes[4] & 0xFF) == 0xA1 && (bytes[5] & 0xFF) == 0xB1
&& (bytes[6] & 0xFF) == 0x1A && (bytes[7] & 0xFF) == 0xE1;
}
/**
* Тело задачи воркера. Ядро принимает байты — временные файлы не нужны;
* имя влияет только на заголовок PDF (параметр {@code title}), потому
@@ -163,7 +179,7 @@ final class ConversionService {
/**
* Санитизация имени (единый источник для имени файла и Content-Disposition):
* без каталога, только буквы/цифры/пробел/ {@code . _ -}, без суффикса
* .docx; пустое после очистки → {@code document}. Кириллица разрешена —
* .docx/.doc; пустое после очистки → {@code document}. Кириллица разрешена —
* на Linux это валидное имя файла, и заголовок PDF остаётся читаемым.
*/
static String safeBaseName(String original) {
@@ -171,8 +187,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";
@@ -20,7 +20,7 @@ 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, размер, страницы) —
@@ -57,11 +57,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",
@@ -77,9 +80,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 {
@@ -97,9 +101,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(new String(pdf, 0, 4, StandardCharsets.US_ASCII).equals("%PDF"),
@@ -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