Files
java-word-pdf/AGENTS.md
T

21 KiB
Raw Blame History

Repository Guidelines

Project Overview

Конвертер .docx → .pdf на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 21, только Maven. Модули: wordpdf-core (библиотека), wordpdf-app (Spring Boot REST API); плюс wordpdf-web — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед git push — mvn clean verify (CI/lint в репозитории нет; SPA гейтуется npm run build).

Architecture & Data Flow

Пайплайн WordPdfConverter.convertToStream — порядок шагов фиксирован, менять местами нельзя:

  1. new BundledFontMapper() → BundledFonts.init() → BundledFonts.restrictToBundled(). Конструктор маппера каждый раз заново добавляет системные шрифты в реестр PhysicalFonts; бандл регистрируется поверх; чистка реестра — до load(). Ключ реестра — имя шрифта, addPhysicalFont(URI) НЕ перезаписывает занятый ключ → BundledFonts.init() вызывает dropNonBundled() (иначе системный DejaVuSerif.ttf блокирует наш DejaVuSerif-Regular.ttf).
  2. Нормализация байтов docx до JAXB-загрузки (цепочка byte[] → byte[], порядок значим): DocxOnOffNormalizer (w:val="off"/"on" → false/true; docx4j 17.x теряет on/off при разборе) → SymbolFontNormalizer (маркеры списков из PUA U+F0xx в Symbol/Wingdings/Webdings → Unicode + DejaVu Sans; таблица SymbolMapper сгенерирована, руками не менять) → FieldNormalizer (сложные поля fldChar PAGE/NUMPAGES/SECTIONPAGES → w:fldSimple, иначе во всех колонтитулах печатается один закэшированный номер; штатный FieldsCombiner docx4j не заходит внутрь w:sdt) → GlyphCoverageNormalizer (шаг 2.4: режет ран по покрытию глифов и пишет семейство в w:rFonts; трогает только раны с одним w:t и явным w:rFonts; покрытие — java.awt.Font.canDisplay через BundledFonts.awtFont, не GlyphCheck — тот логирует на каждый глиф).
  3. WordprocessingMLPackage.load(байты) → WordPdfValidator.checkPageCount(pkg) — до рендера.
  4. pkg.setFontMapper(mapper) → DrawingPreRenderer.run(pkg) (шаг 3.5: c:chart/dgm:relIds docx2fo.xslt не умеет и молча выбрасывает — свой Java2D-движок internal/chart/* рендерит их в PNG 300 dpi и подменяет на pic:pic; после setFontMapper, до FOSettings) → new FOSettings(pkg) + FopFallbackFonts.declare (декларирует в FOP-конфиге все бандл-семейства — FOP встраивает только задекларированные) → FORendererApacheFOP / FOUserAgent (заголовок PDF = имя файла) → Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL).
  5. finally: deleteEmbeddedFontTempFiles() (в 17.x OpcPackage.close() нет).

REST API (wordpdf-app)

  • Конвертации сериализованы однопоточным ThreadPoolExecutor (очередь 16, переполнение → 503): ядро мутирует глобальный реестр PhysicalFonts (шаг 1 пайплайна), параллельные конвертации вырывают его друг у друга из-под рендера.
  • Разделение ошибок: валидация байтов до очереди (WordPdfValidator.checkInput(byte[]) + проверка zip-подписи + checkPageCountLightweight(byte[])) → ValidationException → 400; ошибки ядра/рендера → ConversionFailedException → 500; очередь занята → 503; таймаут (wordpdf.convert-timeout, 2m) → 504. Граница: сломанный контейнер → 400, валидный zip с мусором внутри → 500.
  • Фронт ходит только на относительный /api/... — CORS не нужен (dev: vite-proxy → :8080; prod: nginx).

Критические инварианты (нарушение = битый вывод)

  • docx4j.convert.out.fo.gsubFeatures=false — ставится в статическом блоке WordPdfConverter. Иначе docx4j навешивает fox:gsub-features без объявления префикса → FO невалиден → WordLayoutFixups молча отказывается от всех фиксов → FOP падает на docx4j-baseline. Без фиксов нет колонок и колонок таблиц.
  • slf4j-simple обязателен в ядре: без него docx4j пишет «TO HIDE THESE MESSAGES» прямо в выходной PDF (регрессия noLoggingWarningInPdf). Приложение (wordpdf-app) исключает slf4j-simple из зависимости ядра — логи ведёт logback из Boot; предупреждение в PDF возникает только при полном отсутствии SLF4J-провайдера, slf4j-simple.properties из core остаётся инертным ресурсом.
  • JAXB-обход обязан раскрывать JAXBElement (иначе таблицы/раны молча пропускаются — оценка «1» вместо 121). Рекурсия через ContentAccessor из org.docx4j.wml (НЕ org.docx4j.contentcontrol — в 17.x его нет). Тип секции — SectPr$Type.getVal(); маркер — R.LastRenderedPageBreak (CTLastRenderedPageBreak в 17.x отсутствует).
  • FOP — форк org.docx4j:docx4j-fo-renderer* 2.11-docx4j.2 (пакеты org.apache.fop.*), умеет хинты docx4j:baseline/docx4j:line-box. Fop.Renderers.getRenderer() возвращает список — FopFallbackFonts.rendererFonts ищет application/pdf.
  • docx2fo.xslt в репозитория нет — он в jar docx4j-export-fo. WordLayoutFixups (включён по умолчанию в 17.x) постобработкой DOM FO даёт реальные колонки w:cols/@w:num и колонки таблиц; побочный эффект — авто-ширины колонок без tblGrid/tcW стали уже (слово может перенестись в ячейке).
  • Известный остаток эталона: U+2188 (ↈ) и U+218A (↊) — глифов нет ни в одном OFL-шрифте бандла, остаются .notdef (GNU FreeSerif GPL — не добавляем намеренно).
  • nginx client_max_body_size 6m (wordpdf-web/nginx.conf) обязателен: без него upload > 1 МБ режется HTML-413 от nginx до бэкенда вместо JSON-ошибки API.

Шрифты (30 TTF в wordpdf-core/src/main/resources/fonts/, SIL OFL)

Алиасы MS→open-source (BundledFontMapper): Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans. Новый шрифт = файл + запись в BundledFonts.ENTRIES (синхрон проверяет BundledFontsTest). Noto Naskh Arabic / Noto Sans Armenian (только regular, ради глифов U+07B1–08FF и U+058D/E) в BundledFontMapper не регистрируются — FontFallback.selectCovering перебирает весь реестр PhysicalFonts сам. У них только regular-начертание: BundledFonts.families() это учитывает, BundledFontsTest.allFamiliesHaveAllVariants их не проверяет. Символы U+2000–U+2EFF: RunFontSelector.symbolBlockFont оставляет шрифт ранa, если глиф есть, иначе виртуальный «Segoe UI Symbol» → fallback (как в Word; регрессия ruPlain_emDashEmbeddedNotHelvetica).

Валидация входа (WordPdfValidator)

MAX_INPUT_BYTES = 5 MiB, MAX_PAGES = 100. Страницы = максимум трёх нижних оценок: (1) кэш docProps/app.xml <Pages> — недостоверен (реальный кейс: <Pages>1</Pages> при 110 маркерах); (2) явные разрывы w:br type="page" / pageBreakBefore / межсекционные sectPr (кроме continuous); (3) w:lastRenderedPageBreak + 1. Lightweight-путь (zip/StAX, без docx4j) согласован с JAXB: sectPr в body — «все минус 1»; sectPr в pPr не считается; колонтитулы — по содержимому zip. Расхождение допустимо только в завышение. При отказе convert(Path,Path) удаляет уже открытый PDF (регрессия staleCachePageCountRejectedBeforeRender проверяет отсутствие артефакта).

Chart-движок (internal/chart, package-private кроме DrawingPreRenderer.run)

Свой Java2D-рендер DrawingML. Калибровка surface3D зафиксирована тестами, эталон — стр. 3 gitignored word-export.pdf (экспорт Word, pdftoppm -r 300): CAMERA_DISTANCE = 2.36 (perspective — НЕ угол FOV; fov≈49°), DEPTH_RATIO = 0.705, HEIGHT_RATIO = 0.664, поля 0.1485/0.116/0.146 от области построения, rotY берётся как -Math.toRadians(...) (знак обратный правому правилу), Lambert 0.92 + 0.88·dot кламп [0.80; 1.25], свет (0.83, 0.48, 0.28). Цели: силуэт 314,9×65,3 pt центр (227,3; 82,3), уклон передней кромки 0.1282, аспект 0.207, шаги осей 0.0504/0.1176. Триангуляция ячейки — диагональ с большей суммой значений (седло; фиксированная диагональ даёт невидимую щепку); клиппинг полос — по треугольникам. w01 = z[r+1][c], w10 = z[r][c+1] — перестановка закручивает квад в бабочку. ChartRenderer.axisBounds без явного c:min поднимает нижнюю границу до 0. Пустой c:title + autoTitleDeleted val="0" → автозаголовок Chart Title (для pie/pie3D/doughnut — имя ряда). Границы калибровки менять только вместе с тестами Surface3dPainterTest/PiePainterTest.

В DrawingPreRenderer rels части берутся через part.getRelationshipsPart() (Base), а не getOwningRelationshipPart() — у document.xml последнее указывает на пакетный .rels. Обход pkg.getParts() — только по снимку списка: createImagePart докидывает части в тот же реестр (живой обход → ConcurrentModificationException).

Key Directories

Путь Назначение
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ публичный API: WordPdfConverter, WordPdfValidator, ConversionException
…/wordpdf/fonts/ BundledFonts (реестр/выгрузка TTF), BundledFontMapper (алиасы MS→open-source)
…/wordpdf/internal/ 4 байтовых нормализатора + FopFallbackFonts
…/wordpdf/internal/chart/ Java2D-рендер диаграмм/SmartArt в PNG
wordpdf-core/src/main/resources/fonts/ 30 TTF + лицензии — бинарные фикстуры, часть jar
wordpdf-core/src/test/resources/samples/ 11 закоммиченных .docx-фикстур (единственные фикстуры)
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ REST API: ConvertController, ConversionService (очередь), ApiExceptionHandler
wordpdf-web/src/ SPA (React+TS+Vite+Tailwind): компоненты в components/, вся сеть в api.ts
корневые Dockerfile, docker-compose.yml образ бэкенда (multi-stage, temurin-21); compose web+app
wordpdf-web/Dockerfile, wordpdf-web/nginx.conf образ SPA (node→nginx); прокси /api, /swagger-ui, /v3/api-docs
references/ эталон Word 365 (word.docx + word.pdf) — ручное сравнение, не фикстуры, в тесты/jar не подключать
diff/, корневые word-export.* gitignored артефакты ручной калибровки

Development Commands

mvn clean verify                        # все модули + тесты — обязательный гейт перед push
mvn -pl wordpdf-app -am package         # исполняемый jar бэкенда
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar   # :8080, POST /api/v1/convert
npm run dev                             # (wordpdf-web/) SPA :5173, proxy /api → :8080
docker compose up -d --build            # всё вместе: SPA+nginx публикует :8080, app не публикуется
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached   # один тест

Compose: web проксирует /api, /swagger-ui, /v3/api-docs на app (DNS-имя в сети compose); бэкенд наружу не публикуется. wordpdf.convert-timeout переопределяется env WORDPDF_CONVERT_TIMEOUT (relaxed binding Boot).

Пересоздать 10 фикстур (POI, test scope; charts-smartart.docx НЕ генерируется — исключение):

mvn -pl wordpdf-core test-compile -Dmdep.outputFile=/tmp/cp.txt dependency:build-classpath -q
java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
    ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples

Code Conventions & Common Patterns

  • Классы final, приватный конструктор, только static (stateless, DI нет; конфигурация — Docx4jProperties + classpath-ресурсы). Исключения — экземпляры по природе: docx4j-классы BundledFontMapper (наследник BestMatchingMapper), DrawMlColor (палитра темы) и Spring-компоненты wordpdf-app.
  • Нормализаторы — единая сигнатура public static byte[] normalize(byte[] docx) throws IOException с флагом changed: нечего менять → вернуть тот же массив (assertSame в тестах); package-private хук static String rewrite(String xml) для юнит-тестов.
  • Ошибки публичного API — только ConversionException extends RuntimeException; внутренние IOException/IllegalStateException оборачиваются на границе. В chart — деградация вместо падения: неизвестный пресет → прямоугольник + лог.
  • Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx) — новый фикс оформлять так же.
  • Константы UPPER_SNAKE с числовыми эталонными значениями (CAMERA_DISTANCE, MAX_PAGES); начертания V_REGULAR/V_BOLD/...; модели — record; размеры в chart — в пунктах, растр × DPI/72.
  • Внутренние API package-private; наружу из internal торчат только normalize/declare/DrawingPreRenderer.run.
  • В wordpdf-app всё package-private (контроллер, advice, service, исключения); в SPA вся сетевая логика только в src/api.ts — компоненты fetch не вызывают.

Important Files

  • wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java — точка входа библиотеки + static-блок gsubFeatures.
  • wordpdf-app/pom.xml — spring-boot-maven-plugin с явной execution repackage (в 4.1.1 сам не связывается, jar останется тонким); slf4j-simple исключён из зависимости ядра.
  • Корневой pom.xml — все версии зависимостей (в модулях версии не объявлять): docx4j 17.3.2, slf4j 2.0.20, JUnit 6.1.3, PDFBox 3.0.8 (test), POI 5.5.1 (test, только генератор фикстур), Spring Boot 4.1.1 (BOM-import), springdoc 3.1.1; форки FOP/jeuclid приходят транзитивно с docx4j-export-fo, пинить не надо.
  • wordpdf-core/src/main/resources/slf4j-simple.properties — без него предупреждение лезет в PDF.
  • wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java — main()-утилита пересоздания фикстур (команда в javadoc).

Runtime & Tooling Preferences

  • Java 21 + Maven (обязательны; wrapper mvnw нет). UTF-8. Фронт: Node.js ≥ 20.19 (Vite 7+), вне Maven-депа.
  • Только Maven (никакого Gradle/Ant); новые зависимости — latest stable, версии только в корневой dependencyManagement.
  • CI, линтеров, форматтеров, checkstyle — нет; проверка одна: mvn clean verify.
  • Исполняемый jar бэкенда проверять только java -jar (тесты идут по classpath и repackage-специфику не видят).

Testing & QA

  • JUnit 6 (org.junit.jupiter:junit-jupiter), surefire c -Djava.awt.headless=true; только Assertions (без Mockito/AssertJ, несмотря на test-классpath Boot), package-private тесты в mirror-пакетах.
  • PDF сравнивается текстом, не растеризацией: PDFBox PDFTextStripper для текста, override processTextPosition для шрифта конкретного символа (fontNameOf), обход ресурсов страницы для встроенных шрифтов (EAAAAA+Carlito-Bold) и счётчика картинок. Негативные маркеры — регрессии: assertFalse(text.contains("#")) (.notdef), assertFalse(font.startsWith("Helvetica")). Пиксели — только в unit-тестах chart-пейнтеров (там сам код — Java2D); допуски 6–10%.
  • Текст нормализуется по пробелам (tableImage_tableAndImage — полное удаление пробелов: docx4j переносит слова в auto-fit таблицах).
  • Фикстуры — закоммиченные samples/*.docx (не генерировать в тестах); classpath → временный файл (extractSample/extractToTemp). In-memory docx — ZipOutputStream из литеральных XML или POI в byte[] (WordPdfValidatorTest).
  • Юниты нормализаторов работают строками (rewrite) и проверяют контракт «нечего менять → null / тот же массив» и неприкосновенность [Content_Types].xml.
  • Тесты wordpdf-app (ConvertControllerTest, MockMvc) берут фикстуры из test-jar core (classifier tests) → -pl wordpdf-app без -am не соберётся. Гейт SPA — npm run build (tsc -b); UI-тестов нет.
  • Каждый фикс бага docx4j/FOP сопровождается: байтовый нормализатор/pre-renderer + регрессионный тест с фикстурой + javadoc-ссылка. Проверенные пары: DocxOnOffNormalizerTest/ruPlain_regularRunsUseRegularFont, FieldNormalizerTest/pageNumbers_recomputedNotCached, SymbolFontNormalizerTest/symbolFonts_bulletsAreNotHash, GlyphCoverageNormalizerTest/exoticGlyphs_drawnNotHash, WordPdfValidatorTest/staleCachePageCountRejectedBeforeRender, BundledFontsTest/noLoggingWarningInPdf, Surface3dPainterTest/chartsSmartArt_drawingsBecomeImages.