feat(xlsx): REST + фронт + документация (шаг 8)
PR checks / web (pull_request) Successful in 39s
PR checks / java (pull_request) Successful in 1m37s

- ConvertController: расширение .xlsx, текст 400 «только .docx, .doc и .xlsx»
  (контракт с фронтом), @Operation — флаг errorOnSmartArt на .xlsx не
  срабатывает; safeBaseName срезает .xlsx
- фронт: DropZone accept/подпись, подзаголовок App, api.ts фолбэк-имя режет
  .xlsx; web build+lint зелёные
- app-тесты: xlsxFile_convertsToPdf (200, PDF, filename* Отчёт.pdf, текст
  доехал), nonDocxFilename_rejected — .xlsx в тексте, safeBaseName .XLSX
- прод-автотест test_convert_xlsx (32 проверки)
- docs: новая docs/agent/xlsx-bridge.md (классы, единицы, деградации,
  соглашения PrintLayout↔валидатора); AGENTS.md — роутинг входа, секция
  моста .xlsx, REST/фронт/счётчики (75 классов/1095 тестов, 32 фикстуры);
  pipeline.md (ContainerKind, estimateXlsxPages), repo-map.md (пакет,
  DocxPackageWriter, генераторы, пересоздание xlsx), testing.md,
  doc-bridge.md (DocxWriter → internal/DocxPackageWriter)

Сквозная проверка java -jar + curl: xlsx→PDF 200 (filename* RFC5987),
chart-fixture 200 с отрисованными PNG, errorOnCharts=true → 422 контрактный
текст, .txt → 400 новый текст, .doc-регресс 200
This commit is contained in:
Pjandro
2026-11-03 02:37:43 +00:00
parent 4a59662027
commit 733662770b
14 changed files with 182 additions and 36 deletions
@@ -146,7 +146,7 @@ final class ConversionService {
/**
* Санитизация имени (единый источник для имени файла и Content-Disposition):
* без каталога, только буквы/цифры/пробел/ {@code . _ -}, без суффикса
* .docx/.doc; пустое после очистки → {@code document}. Кириллица разрешена —
* .docx/.doc/.xlsx; пустое после очистки → {@code document}. Кириллица разрешена —
* на Linux это валидное имя файла, и заголовок PDF остаётся читаемым.
*/
static String safeBaseName(String original) {
@@ -157,6 +157,8 @@ final class ConversionService {
String lower = base.toLowerCase(Locale.ROOT);
if (lower.endsWith(".docx")) {
base = base.substring(0, base.length() - ".docx".length());
} else if (lower.endsWith(".xlsx")) {
base = base.substring(0, base.length() - ".xlsx".length());
} else if (lower.endsWith(".doc")) {
base = base.substring(0, base.length() - ".doc".length());
}
@@ -21,7 +21,7 @@ import java.util.Locale;
/**
* Единственный эндпоинт API: {@code POST /api/v1/convert} — multipart-поле
* {@code file} (.docx) → синхронный ответ байтами PDF.
* {@code file} (.docx/.doc/.xlsx) → синхронный ответ байтами PDF.
*
* <p>Здесь только HTTP-слой: проверка presence/расширения и формирование
* {@code Content-Disposition}; проверка содержимого (zip, размер, страницы) —
@@ -58,11 +58,14 @@ final class ConvertController {
this.maxPages = maxPages;
}
@Operation(summary = "Конвертировать .docx/.doc в PDF",
description = "Принимаются .docx (OOXML) и .doc (Word 97–2003, переносится в .docx "
+ "мостом: текст и прямое форматирование). errorOnCharts/errorOnSmartArt/errorOnOle — факультативно, по умолчанию "
@Operation(summary = "Конвертировать .docx/.doc/.xlsx в PDF",
description = "Принимаются .docx (OOXML), .doc (Word 97–2003) и .xlsx (SpreadsheetML); "
+ ".doc и .xlsx переносятся в .docx мостами: текст и прямое форматирование. "
+ "errorOnCharts/errorOnSmartArt/errorOnOle — факультативно, по умолчанию "
+ "настройки ядра (ошибка не выбрасывается); диаграммы/SmartArt "
+ "конвертируются всегда, OLE-объекты при выключенном флаге тихо удаляются. "
+ "Для .xlsx errorOnSmartArt не срабатывает (SmartArt отбрасывается), "
+ "errorOnCharts и errorOnOle работают. "
+ "Лимиты входа (размер/страницы) задаёт только конфигурация сервера "
+ "(свойства wordpdf.max-mb/wordpdf.max-pages), параметрами запроса не переопределяются")
@SecurityRequirement(name = OpenApiConfig.SCHEME)
@@ -80,10 +83,11 @@ final class ConvertController {
}
String name = file.getOriginalFilename();
String lower = name == null ? "" : name.toLowerCase(Locale.ROOT);
if (!lower.endsWith(".docx") && !lower.endsWith(".doc")) {
if (!lower.endsWith(".docx") && !lower.endsWith(".doc") && !lower.endsWith(".xlsx")) {
// расширение проверяется здесь: ядро с байтов его не видит;
// .doc (Word 97–2003) переносится в .docx мостом internal.doc
throw new ValidationException("Поддерживаются только .docx и .doc: " + name);
// .doc (Word 97–2003) переносится в .docx мостом internal.doc,
// .xlsx — мостом internal.xlsx
throw new ValidationException("Поддерживаются только .docx, .doc и .xlsx: " + name);
}
// Размер проверяется до getBytes(): multipart-лимит сервера (100 МБ)
// больше логического лимита входа (wordpdf.max-mb), и без этого гварда
@@ -132,6 +132,7 @@ class ConversionServiceTest {
assertEquals("evil", ConversionService.safeBaseName("C:\\tmp\\evil.docx"));
assertEquals("отчёт", ConversionService.safeBaseName("отчёт.DOCX"));
assertEquals("отчёт", ConversionService.safeBaseName("отчёт.DOC"));
assertEquals("отчёт", ConversionService.safeBaseName("отчёт.XLSX"));
assertEquals("doc", ConversionService.safeBaseName("doc.doc"));
assertEquals("файл", ConversionService.safeBaseName("каталог\\файл.doc"));
}
@@ -277,7 +277,27 @@ class ConvertControllerTest {
.file(docx("notes.txt", bytes("/samples/ru-plain.docx"))))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString(".docx")));
org.hamcrest.Matchers.containsString(".docx")))
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString(".xlsx")));
}
/** .xlsx принимается расширением и конвертируется мостом internal.xlsx. */
@Test
void xlsxFile_convertsToPdf() throws Exception {
MvcResult result = mockMvc.perform(multipart("/api/v1/convert")
.file(docx("Отчёт.xlsx", bytes("/samples/xlsx-basic.xlsx"))))
.andExpect(status().isOk())
.andExpect(content().contentType(MediaType.APPLICATION_PDF))
.andExpect(header().string(HttpHeaders.CONTENT_DISPOSITION,
org.hamcrest.Matchers.containsString(
"filename*=UTF-8''%D0%9E%D1%82%D1%87%D1%91%D1%82.pdf")))
.andReturn();
byte[] pdf = result.getResponse().getContentAsByteArray();
assertTrue("%PDF".equals(new String(pdf, 0, 4, StandardCharsets.US_ASCII)),
"тело не начинается с %PDF");
// «Товар» — заголовок широкой колонки A: не режется переносом по ширине
assertTrue(norm(pdfText(pdf)).contains("Товар"), "текст .xlsx не доехал");
}
/** Бинарный .doc принимается расширением и конвертируется мостом internal.doc. */