Files
java-word-pdf/AGENTS.md
T

41 KiB
Raw Blame History

Repository Guidelines

Project Overview

Конвертер .docx/.doc → .pdf на чистом Java (docx4j 17.3.2 + форк Apache FOP; бинарный .doc Word 97-2003 — через POI HWPF, без LibreOffice/Aspose). Java 21, только Maven. Модули: wordpdf-core (библиотека), wordpdf-app (Spring Boot 4.1.1 REST API); wordpdf-web — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед git push — mvn clean verify (CI нет; SPA гейтуется npm run build + npm run lint). Вход стека — контейнер gateway (nginx), НЕ 8080. README устарел шире Docker-секции: лимиты (пишет 5 МБ/100 стр./6 МБ multipart — фактически 20 MiB/1000/100 MB), порты («всё на :8080» — фактически gateway :9010/:9011), API-ключ вообще не упомянут; плюс «фикстуры генерируются POI» (они закоммичены, POI только в генераторе) и Swagger UI без оговорки, что в проде она открыта без ключа, — авторитет этот файл.

Architecture & Data Flow

Пайплайн WordPdfConverter.convert(byte[], String[, ConvertOptions]) (порядок фиксирован, менять местами нельзя)

Наружу checkInput(bytes, maxBytes) вызывается до приватного convertToStream; внутри convertToStream:

Шаг 0: вход с OLE2-магиком D0 CF 11 E0 A1 B1 1A E1 (бинарный .doc) уходит в internal.DocToPdfRenderer.render до создания BundledFontMapper — docx4j-машинерия и все нормализаторы (zip-путь) для него бессмысленны; см. «Ветка .doc» ниже.

  1. new BundledFontMapper() → BundledFonts.init() → BundledFonts.restrictToBundled(). Конструктор маппера каждый раз добавляет системные шрифты в реестр PhysicalFonts; ключ реестра — имя из name-таблицы TTF, addPhysicalFont(URI) не перезаписывает занятый → init() вызывает dropNonBundled() до регистрации и load() (иначе системный Calibri ломает em-dash-fallback).
  2. Нормализация байтов docx до JAXB-загрузки (цепочка byte[] → byte[], порядок значим): StrictOoxmlNormalizer (strict-OOXML → transitional-байт: a:-проценты и w14:fillToRect → тысячные ×1000, текст wp14:pctWidth/pctHeight, элементы и атрибуты w:start/w:end → w:left/w:right (кроме w:lvl/w:start в numbering.xml), значения start/end у w:jc/w:tab; в mc-preprocessor.xslt docx4j ветка % закомментирована, start/end не маппятся; namespaces и pt-значения правит сам mc-preprocessor — собственный рерайт URI ломает его pt-конверсию) → DocxOnOffNormalizer (w:val="off"/"on" → false/true) → SymbolFontNormalizer (PUA U+F0xx Symbol/Wingdings/Webdings → Unicode + DejaVu Sans, переписывает и элементы <w:sym>; 5 карт по 256 слотов, таблица SymbolMapper сгенерирована из docx4j 17.x) → FieldNormalizer (fldChar PAGE/NUMPAGES/SECTIONPAGES → w:fldSimple, вложенные/битые поля пропускает) → GlyphCoverageNormalizer (режет ран по покрытию глифов, пишет семейство в w:rFonts, иначе FOP рисует «#»; покрытие — java.awt.Font.canDisplay + BitSet-кэш, НЕ docx4j GlyphCheck — тот плодит INFO-лог; для serif-ран fallback ищется сначала в SERIF_FAMILIES (DejaVu Serif/Tinos/Caladea), затем в sans) → WordprocessingMLPackage.load.
  3. WordPdfValidator.checkPageCount(pkg, maxPages) — до рендера.
  4. pkg.setFontMapper(mapper) → DrawingPreRenderer.run(pkg, options) (шаг 3.5: c:chart/dgm:relIds docx2fo.xslt не умеет — свой Java2D-движок internal/chart/* рендерит в PNG 300 dpi и подменяет на pic:pic; объект, выключенный в ConvertOptions, пропускается до рендера и остаётся в docx; упавший рендер — объект удаляется из docx (gd.getAny().clear()) + warn, деградация не падение).
  5. new FOSettings(pkg) + FopFallbackFonts.declare (декларирует все бандл-семейства — FOP встраивает только задекларированные) → FORendererApacheFOP/FOUserAgent (непустой title → заголовок PDF) → Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL).
  6. finally: deleteEmbeddedFontTempFiles() (в 17.x OpcPackage.close() нет).

Ветка .doc (internal/DocToPdfRenderer, public только render)

POI WordToFoConverter (HWPF→XSL-FO) → тот же FOP-форк. Порядок: BundledFonts.init() (без restrictToBundled — FOP-конфиг строится строкой с auto-detect="false", системные шрифты в рендер не попадают) → POIFSFileSystem/HWPFDocument → FontReplacer (имя = name-таблица TTF через BundledFontMapper.bundledFamily) → PicturesManager во временный каталог (без него POI молча пропускает картинки; пустые картинки — null, иначе FOP падает EOFException) → processDocument → пост-обработка FO-DOM: applyDefaultFont (инлайны POI без font-family — иначе базовый Helvetica) и injectHeadersAndFooters (POI колонтитулы не пишет): HeaderStories odd/even/first × header/footer, чанки по \u000c; в мастер — region-before/region-after (extent = top/bottom margin из margin-шортхэнда region-body, margin'ы region-body сохраняются — форк FOP не вычитает extent'ы регионов из body-области, единственная защита от наезда текста на колонтитулы — собственные margin'ы body; порядок детей body→before→after — требование валидации форка; зазор — маргинами блоков, padding регионов FOP валит), в page-sequence — fo:static-content перед fo:flow; first/even — эвристика «непустая история ⇒ вариант» (флаги titlePg/evenAndOdd POI не отдаёт) через fo:page-sequence-master + conditional-page-master-reference first/even/rest. Поля в текстах историй — управляющие символы \u0013/\u0014/\u0015: PAGE → fo:page-number, NUMPAGES/SECTIONPAGES → fo:page-number-citation-last по последнему мастеру; fo:page-number без font-family блока рисуется Helvetica — блок получает семейство первого рана. Свойство tabs FOP-форк не знает — табы = пробелы до дефолтной остановки 1,25 см. Принятая деградация против Word: дрейф вёрстки (18 стр. против 12 на фикстуре), экзотические глифы остаются .notdef (аналога GlyphCoverageNormalizer нет), first/even-варианты эвристикой. Флаги renderCharts/renderSmartArt/errorOn* — no-op.

REST API (wordpdf-app, всё package-private кроме WordPdfApplication)

  • Единственный эндпоинт POST /api/v1/convert (multipart-поле file, факультативные renderCharts/renderSmartArt — query или form) → application/pdf, Content-Disposition: attachment; filename*=UTF-8''…. Проверка расширений .docx/.doc — в ConvertController; safeBaseName в ConversionService — единый источник имени для файла, заголовка ответа и PDF-title (разрешены [\p{L}\p{N} ._-], пустое → document). Для .doc ответ несёт X-Wordpdf-Degraded: headers-footers-exotic-glyphs (деградация вёрстки/колонтитулов/экзотических глифов).
  • Конвертации сериализованы однопоточным ThreadPoolExecutor (ConversionService.QUEUE_CAPACITY = 16, переполнение → 503): ядро мутирует глобальный реестр PhysicalFonts. future.cancel(true) при таймауте не останавливает FOP мгновенно — осознанный компромисс.
  • Ошибки (ApiExceptionHandler, тело {"error": …}): ValidationException → 400; ConversionFailedException → 500; ConversionRejectedException → 503; ConversionTimeoutException (wordpdf.convert-timeout, 2m) → 504; MaxUploadSizeExceededException → 413; MissingServletRequestPartException/MissingServletRequestParameterException → 400; NoResourceFoundException (неизвестный путь) → 404; catch-all → 500 (подробности только в лог). Четыре app-исключения (ValidationException, ConversionFailedException, ConversionRejectedException, ConversionTimeoutException) — package-private, несут семантику 400/500/503/504. Граница: сломанный контейнер (не zip / не OLE2 / размер / страницы) → 400, валидный контейнер с мусором внутри → 500. Валидация до очереди — развилка по магiku: checkInput → zip PK\x03\x04 → checkPageCountLightweight или OLE2 D0 CF 11 E0 → checkDocPageCountLightweight (порядок значим).
  • Ключ доступа: ApiKeyFilter сверяет заголовок X-API-Key (ApiKeyFilter.HEADER) со свойством wordpdf.api-key (env WORDPDF_API_KEY, сравнение MessageDigest.isEqual). Пустое свойство = аутентификация выключена (dev java -jar, тесты). Без ключа открыты /actuator/** (HEALTHCHECK) и документация springdoc (/swagger-ui*, /v3/api-docs*) — матч по пути без forwarded-contextPath (getRequestURI() минус getContextPath(); иначе под X-Forwarded-Prefix HEALTHCHECK получил бы 401). 401 пишет сам фильтр (ApiExceptionHandler ошибок фильтров не видит). Springdoc в проде включён, документация открыта без ключа под https://pjandro.ru/pdf-converter/swagger-ui.html (server-URL/swagger-config собираются из X-Forwarded-*, server.forward-headers-strategy=framework — native-клапан Tomcat X-Forwarded-Prefix не понимает). Регрессии — ApiKeyFilterTest#forwardedPrefix_healthStaysOpen, ApiKeyFilterTest#docsOpenWithoutKey.
  • Лимиты входа задаёт только конфигурация сервера: wordpdf.max-bytes/wordpdf.max-pages (env WORDPDF_MAX_BYTES/WORDPDF_MAX_PAGES), @Value в ConvertController с дефолтом-SpEL из WordPdfSettings (20 MiB / 1000); значение ≤ 0 → IllegalStateException на старте; параметрами запроса не переопределяются. Ключи в application.properties не объявлены — пустое значение затенит SpEL-дефолт.
  • SPA: вся сеть в src/api.ts (компоненты fetch не вызывают); ключ в localStorage (wordpdf.api.key), при 401 очищается, экран ApiKeyGate (UnauthorizedError — наследник ApiError, проверяется раньше); запросы на ${import.meta.env.BASE_URL}api/... (vite base из VITE_BASE, дефолт /) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом /pdf-converter/).

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

Java2D → PNG 300 dpi (ChartRenderer.DPI = 300, PADDING = 4.0, растр × DPI/72, размеры — в пунктах, EMU→pt cx/12700.0). ChartSpec.parse (enum Type: PIE/PIE3D/DOUGHNUT/BAR/BAR_HORIZONTAL/LINE/AREA/SURFACE3D/UNSUPPORTED; пустой c:title + autoTitleDeleted="0" → у круговых имя первого ряда, у прочих — AUTO_TITLE = "Chart Title"; палитра accent1..6 темы, легенда по умолчанию снизу, позиция t поддержана, overlay → место не резервируется) → ChartRenderer (осевые «круглые» шаги niceUnit 1/2/5·10ⁿ как Word; маркеры легенды 0.32/0.55 кегля, отрезок 2.4 кегля) → пейнтеры CartesianPainter/PiePainter (DEPTH_RATIO=0.22, TILT_CORRECTION=0.95, FIT_MARGIN=0.865)/Surface3dPainter (калибровка по стр. 3 develop/word-export.pdf: CAMERA_DISTANCE=2.36, DEPTH_RATIO=0.705, HEIGHT_RATIO=0.664, GUTTER_LEFT/RIGHT=0.1485, GUTTER_TOP=0.116, GUTTER_BOTTOM=0.146, свет LIGHT_X/Y/Z=0.83/0.48/0.28); SmartArtRenderer рисует кэш разложенной схемы (relationship …/office/2007/relationships/diagramDrawing, фактически word/diagrams/drawing1.xml); палитра темы — DrawMlColor (instance; без ThemePart — дефолтная Office-палитра accent1=4472C4…); текст — DrawMlText; утилиты RgbHsl, PrstGeomShapes. Калибровочные константы менять только вместе с Surface3dPainterTest/PiePainterTest. Обход pkg.getParts() — только по снимку списка (createImagePart мутирует реестр → CME); rels частей — part.getRelationshipsPart(), НЕ getOwningRelationshipPart() (это rels ссылающегося); обход XML обязан раскрывать JAXBElement.

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

  • docx4j.convert.out.fo.gsubFeatures=false — static-блок WordPdfConverter. Иначе FO невалиден → WordLayoutFixups молча отказывает всем фиксам (без них нет колонок) → FOP падает на docx4j-baseline.
  • slf4j-simple обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия noLoggingWarningInPdf). Приложение исключает его из зависимости ядра — логи ведёт logback.
  • FOP — форк org.docx4j:docx4j-fo-renderer* 2.11-docx4j.6 (пакеты org.apache.fop.*); Fop.Renderers.getRenderer() возвращает список (рендер выбирается по mime application/pdf). docx2fo.xslt в репозитории нет — он в jar docx4j-export-fo.
  • Форк FOP вырезал PageMaster.setupRegions (в jar нет layoutmgr/PageMaster*/RegionXY): area.Page строит viewport region-body как page-area минус собственные margin'ы body, extent у region-before/region-after body-регион не уменьшает — в .doc-ветке разводка body и колонтитулов только margin'ами region-body (регрессия DocToPdfTest#legacyDoc_bodyClearsHeaderFooterRegions). Docx-ветку не касается: docx4j сам закладывает высоты колонтитулов в margin'ы мастера.
  • Страницы в валидаторе = max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1); explicit = межсекционные sectPr в body + w:br type="page" + pageBreakBefore (рекурсивно, включая таблицы и w:sdt). Lightweight-путь (StAX по zip, secure-ридер без DTD/external entities): атрибуты — по локальному имени (attrLocal, не по transitional-URI: иначе в strict-документе w:br type="page" не засчитываются); sectPr внутри pPr не считает, последнюю body-direct секцию не считает, continuous-секции не считает, в колонтитулах — только w:br type="page", pageBreakBefore — только внутри pPr вне sectPr (truthy-значения val: null|true|1|on); на не-zip молчит — подпись проверяет вызывающий. Расхождение lightweight↔JAXB допустимо только в завышение. pageCountOf package-private намеренно (тесты); при провале JAXB-разбора (getJaxbElement() → null) бросает ConversionException, а не NPE.
  • .doc: checkDocPageCountLightweight = кэш SummaryInformation.getPacket().getPageCount() (Word 97-2003 писал число страниц в OLE2-метаданные; явных разрывов из FIB не извлечь) — тот же stale-cache риск, что и docProps/app.xml; 0/отсутствие пакета → молча. FOP-конфиг .doc-ветки — строка с auto-detect="false" + resource://fonts/... (классы FOPFontProvider/FopConfParser package-private, JAXB-обход rendererFonts к ним не применим). Кэш шрифтов отключён (FOUserAgent.getFontManager().disableFontCache() в renderFo): дефолт форка — <user.home>/.fop/fop-fonts.cache, а при непригодном user.home (null/несуществующий каталог — non-root контейнер без HOME) файл .fop в текущем каталоге, /app в образе не пишется → 500 на .doc (регрессия DocToPdfTest#legacyDoc_fontCacheNotWrittenToWorkingDir).
  • Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются .notdef (GNU FreeSerif GPL — не добавляем намеренно).
  • Внимательно: комментарии в WordPdfConverter/DocxOnOffNormalizer говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).

Шрифты (30 TTF + 3 лицензии, SIL OFL, wordpdf-core/src/main/resources/fonts/)

7 семейств × 4 начертания (Carlito/Caladea/Arimo/Tinos/Cousine/DejaVu Sans/DejaVu Serif) + Noto Naskh Arabic / Noto Sans Armenian (только regular). Алиасы в BundledFontMapper.ALIASES (15 записей, ключи lowercase): MS→аналоги — Calibri→Carlito, Calibri Light→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; self-map всех бандл-семейств, включая Noto (иначе unmatched уходит в DejaVu-фолбэк); fallback — DejaVu Sans; виртуальный SYMBOL_FONT «Segoe UI Symbol» (U+2000–U+2EFF) → fallback до основного цикла. DISPLAY_NAMES — обратный маппинг lowercase→отображаемое имя для documentFontName (пишет GlyphCoverageNormalizer в w:rFonts); BundledFontMapper.bundledFamily — public-хук «имя шрифта из docx → бандл-семейство или fallback» (пользуется chart-движок). Публичный API BundledFonts шире реестра: families() (источник для FopFallbackFonts), font/regular/bold/italic/boldItalic(family), FALLBACK_FAMILY; awtFont возвращает Font размера 1 — всегда deriveFont(size). Новый шрифт = файл + запись в BundledFonts.ENTRIES (синхрон проверяет BundledFontsTest).

Key Directories

Путь Назначение
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ публичный API: WordPdfConverter, WordPdfValidator (перегрузки checkInput/checkPageCountLightweight/checkPageCount — byte[] или pkg, с лимитом/без; checkDocPageCountLightweight — только byte[] + лимит, для OLE2-.doc), ConversionException, WordPdfSettings (константы-дефолты), ConvertOptions (record: renderCharts, renderSmartArt, maxBytes, maxPages)
…/wordpdf/fonts/ BundledFonts (реестр/выгрузка TTF, families(), FALLBACK_FAMILY), BundledFontMapper (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук bundledFamily)
…/wordpdf/internal/ 5 байтовых нормализатора + FopFallbackFonts + DocToPdfRenderer (ветка .doc; классы public — вызываются из родительского пакета; публичные члены только normalize/declare/render)
…/wordpdf/internal/chart/ 11 классов Java2D-рендера диаграмм/SmartArt в PNG (public только DrawingPreRenderer)
wordpdf-core/src/main/resources/fonts/ 30 TTF + 3 лицензии — бинарные фикстуры, часть jar
wordpdf-core/src/test/resources/samples/ 12 закоммиченных фикстур: 11 .docx + legacy-doc.doc (OLE2, ветка .doc)
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ REST API (10 классов): WordPdfApplication (единственный public), ConvertController, ConversionService (очередь), ApiExceptionHandler, ApiKeyFilter, OpenApiConfig (@SecurityScheme X-API-Key для springdoc) + 4 класса исключений
wordpdf-web/src/ SPA (React 19 + TS + Vite + Tailwind): api.ts (вся сеть), components/ (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo)
корневые Dockerfile, docker-compose.yml, docker-compose.dev.yml, gateway/nginx.conf образ бэкенда (multi-stage maven:3.9-temurin-21 → temurin-21-jre, non-root, HEALTHCHECK actuator); compose app+web+gateway: web-образ со своим HEALTHCHECK (wget /), в обоих compose depends_on web: condition: service_healthy (без health web gateway не стартует); прод-compose интерполирует WORDPDF_MAX_BYTES:-20971520/WORDPDF_MAX_PAGES:-1000
корневой .env.example шаблон env: WORDPDF_API_KEY (openssl rand -hex 32), закомментированные WORDPDF_MAX_BYTES/WORDPDF_MAX_PAGES; реальный прод .env — на прод-сервере (координаты: /home/pjandro/prod/java-word-pdf/DEPLOY.md, вне репо)
develop/ (вне git) рабочие материалы и эталоны Word 365 (word.docx+word.pdf, word-export.*, convert.pdf, 1212.pdf, diff/) — ручное сравнение, не фикстуры, в тесты/jar не подключать

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, ключ выключен
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf   # -am обязателен (test-jar core)
npm run dev                             # (wordpdf-web/) SPA :5173, vite-proxy /api → :8080
npm run build                           # (wordpdf-web/) tsc -b && vite build — гейт SPA; lint: npm run lint (oxlint)
docker compose -f docker-compose.dev.yml up -d --build   # dev-стенд: http://127.0.0.1:9011, без ключа, springdoc вкл

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

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

Деплой. Прод — на пользовательском LAN-сервере; координаты сервера, каталог, restart-секвенция, ключ и гейты успешности — вне репо: /home/pjandro/prod/java-word-pdf/DEPLOY.md (обязательно прочитать перед любым деплоем/перезапуском; в том каталоге лежат архивные файлы старого стека 88.14 — restart.sh.old-88.14, старый compose/nginx — не поднимать). Единая точка входа с dev-машины — /home/pjandro/prod/java-word-pdf/restart.sh (пробрасывает флаги удалённому скрипту: --build — пересборка образов из origin/main + перезапуск; без флага — restart контейнеров; предупреждает о не запушенном в main). В прод попадает только запушенное в main — рабочее дерево на сборку не влияет. Наружный вход https://pjandro.ru/pdf-converter/ (префикс срезает наружный nginx прод-хоста, не репозиторный gateway-конф; прод-копия gateway-конфа дополнительно содержит proxy_read_timeout 300s — в репо её нет, дефолтные 60s рвут 2-минутные конвертации). Тот же наружный nginx в location /pdf-converter/ добавляет X-Forwarded-Host: $host и X-Forwarded-Prefix: /pdf-converter — из них springdoc собирает server-URL спека и swagger-config под префиксом (без X-Forwarded-Host server = https://app:8080, gateway шлёт приложению Host: app:8080); канонический URL документации https://pjandro.ru/pdf-converter/swagger-ui.html — открыт без ключа. Dev-стенд — из репо docker-compose.dev.yml (проект wordpdf-dev, 127.0.0.1:9011:80, без env → ключ пуст, springdoc вкл). Репозиторный docker-compose.yml — третий вариант (проект wordpdf, 9010:80 на все интерфейсы, WORDPDF_API_KEY fail-closed без .env — up упадёт, VITE_BASE — build-arg wordpdf-web/Dockerfile — репо-compose НЕ передаёт: compose build без arg даёт base / и битые ассеты под префиксом, прод передаёт arg по DEPLOY.md). Запуск по просьбе пользователя = прод-стек; dev/java -jar/npm run dev — внутренняя отладка.

Code Conventions & Common Patterns

  • Классы final, приватный конструктор, только static (stateless, DI нет; конфигурация — Docx4jProperties + classpath-ресурсы). Исключения — экземпляры по природе: docx4j-наследник BundledFontMapper (extends BestMatchingMapper), обёртка цветов DrawMlColor (тоже instance, но НЕ наследник docx4j) и Spring-компоненты wordpdf-app.
  • Нормализаторы — единая сигнатура public static byte[] normalize(byte[] docx) throws IOException с флагом changed: нечего менять → вернуть тот же массив (assertSame в тестах); package-private хук static String rewrite(String xml) для юнит-тестов (возвращает null при отсутствии изменений); правятся только части word/*.xml.
  • Ошибки публичного API — только ConversionException extends RuntimeException; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения.
  • Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx) — новый фикс оформлять так же (в существующем main-коде convention соблюдён лишь частично — SymbolFontNormalizer, WordPdfValidator, Surface3dPainter и классы app; новые правки обязаны ссылаться).
  • Константы UPPER_SNAKE с числовыми эталонными значениями (CAMERA_DISTANCE, MAX_PAGES); начертания V_REGULAR/V_BOLD/...; модели — record; размеры в chart — в пунктах, растр × DPI/72.
  • Классы в internal — public (иначе родительский пакет не вызвал бы), но публичные члены наружу только normalize/declare/DrawingPreRenderer.run (rewrite, split, карты — package-private); в wordpdf-app всё package-private кроме WordPdfApplication.
  • Тестовые методы: регрессионные — объект_условие через underscore (ruPlain_cyrillicAndStyles, checkInput_bytesOverLimit, noKey_rejected); чистые юниты — camelCase (pageFieldBecomesFldSimple, splitsRunForUncoveredGlyph).

Important Files

  • wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java — точка входа библиотеки + static-блок gsubFeatures.
  • wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java — все дефолты ядра (MAX_INPUT_BYTES 20 MiB, MAX_PAGES 1000, RENDER_CHARTS/SMARTART); рантайм-конфигурации в ядре нет.
  • wordpdf-app/src/main/resources/application.properties — multipart 100MB (max-file-size/max-request-size + file-size-threshold=100MB, держит файл в памяти; в тон gateway client_max_body_size 100m), wordpdf.convert-timeout=2m, пустой wordpdf.api-key, server.forward-headers-strategy=framework (префикс прод-прокси для springdoc) + springdoc.swagger-ui.persist-authorization=true; wordpdf.max-bytes/max-pages здесь намеренно нет.
  • wordpdf-app/pom.xml — spring-boot-maven-plugin с явной execution repackage (в 4.1.1 сам не связывается, jar останется тонким); slf4j-simple исключён; spring-boot-starter-webmvc (Boot 4: переименован из starter-web) + spring-boot-starter-actuator (нужен Docker HEALTHCHECK /actuator/health); тест-зависимости: spring-boot-webmvc-test (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.
  • wordpdf-core/pom.xml — maven-jar-plugin execution test-jar (публикует фикстуры для app).
  • Корневой pom.xml — все версии зависимостей (в модулях версии не объявлять): docx4j 17.3.2, slf4j 2.0.20, JUnit 6.1.3, PDFBox 3.0.8 (test), POI 5.5.1 (compile в core — poi-scratchpad, ветка .doc; test — poi-ooxml, генератор фикстур), Spring Boot 4.1.1 (BOM-import), springdoc 3.1.1; pluginManagement: compiler 3.16.0, surefire 3.6.0 с -Djava.awt.headless=true, jar 3.5.1.
  • wordpdf-core/src/main/resources/slf4j-simple.properties — без него предупреждение лезет в PDF.
  • gateway/nginx.conf — единственный вход: /api/, /swagger-ui, /v3/api-docs, /actuator → app:8080, остальное → web:80; client_max_body_size 100m (без директивы upload режется HTML-413 шлюза вместо JSON-ошибки API). wordpdf-web/nginx.conf — чистая статика с SPA-fallback, /api НЕ проксирует.
  • wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java — main()-утилита пересоздания фикстур.
  • wordpdf-web/vite.local.config.ts — легаси-одноразовщик (прокси /api → :8091), коммит против воли автора (*.local в gitignore не накрывает .ts-суффикс), в tsconfig.node.json не включён; кандидат на удаление, не тиражировать паттерн.

Runtime & Tooling Preferences

  • Java 21 + Maven (обязательны; wrapper mvnw нет); UTF-8. Только Maven — никакого Gradle/Ant.
  • Версии зависимостей — только в корневом pom.xml (properties + dependencyManagement); новые зависимости — latest stable.
  • Фронт: Node ^20.19.0 || >=22.12.0 (engines vite/oxlint из lockfile), npm с закоммиченным package-lock.json (npm ci); vite ^8.3.0, React ^19.2, TS ~6.0 (strict нигде не включён — npm run build не является strict-гейтом), Tailwind ^4.3, oxlint ^1.81; docker-сборка web на node:24-alpine.
  • CI, линтеров, форматтеров, checkstyle для Java — нет; проверка одна: mvn clean verify.
  • Исполняемый jar бэкенда проверять только java -jar (тесты идут по classpath и repackage-специфику не видят; BundledFontsTest#listedFilesCoverAllTtfInResources требует file:-протокол classpath — только surefire, не fat-jar).
  • Git: origin git.pjandro.ru:pjandro/java-word-pdf, main/dev защищены (правила глобального AGENTS.md; локально только main, dev нет; на origin висит остаточная смерженная docs/regenerate-agents-md).

Testing & QA

  • 15 тестовых классов / 142 @Test (core 12/116, app 3/26). JUnit 6 (org.junit.jupiter:junit-jupiter), surefire 3.6.0 с -Djava.awt.headless=true в argLine; только Assertions (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest org.hamcrest.Matchers.containsString в andExpect); тестовые классы package-private, зеркалят main-пакеты; только @Test (+ единственный @BeforeAll — warm-up шрифтов в GlyphCoverageNormalizerTest).
  • PDF сравнивается текстом, не растеризацией: PDFBox 3 (Loader.loadPDF) — PDFTextStripper для текста (пер-странично setStartPage/setEndPage), override processTextPosition для шрифта конкретного символа (fontNameOf), обход ресурсов страниц для встроенных шрифтов (EAAAAA+Carlito-Bold) и счётчика картинок (imageCount). Негативные маркеры — регрессии: assertFalse(text.contains("#")) (.notdef), assertFalse(font.startsWith("Helvetica")). Текст нормализуется по пробелам (norm); в tableImage_tableAndImage — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах). В DocToPdfTest маркер # НЕ проверяется: в .doc-ветке нет GlyphCoverageNormalizer, экзотические глифы легально остаются .notdef, а PDFBox «ремонтирует» подмножества установленных в системе шрифтов и извлекает # — текст/assertions только по Tinos/Carlito-ранам.
  • Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word (PiePainterTest аспект h/w=0.585, assertRatio отклонение <0.06; Surface3dPainterTest assertRange ±6 pt для центров силуэта + assertRatio допуск 0.10 для геометрических отношений; shading — не допуск, а перцентильные коридоры яркости p5∈[0.74,0.90], median∈[0.90,1.10], p95∈[1.02,1.20]).
  • Фикстуры — закоммиченные samples/* (12; в тестах не генерировать): core грузит classpath-ресурсом → byte[], PDF для PDFBox — временный файл; app читает /samples/… из test-jar core (classifier tests) → mvn -pl wordpdf-app без -am не соберётся. In-memory docx — ZipOutputStream из литеральных XML или POI в byte[]. Ключевые: too-many-pages (150 явных разрывов → 151), stale-cache (кэш <Pages>1</Pages> + 110 lastRenderedPageBreak), charts-smartart (4 растра; SmartArt-одиночка = ровно 2 Image XObject), legacy-doc.doc (реальный Word 97-2003: 43 картинки, колонтитулы с PAGE-полем, кэш Pages=12).
  • Юниты нормализаторов работают строками (rewrite) + zip'ами из ZipOutputStream; обязательные контракты: «нечего менять → тот же массив» (assertSame покрыт тестами только у zip-нормализаторов DocxOnOff/SymbolFont/StrictOoxml; у Field/GlyphCoverage — rewrite→null) и неприкосновенность частей вне word/*.xml ([Content_Types].xml). Тесты бьют и в package-private API (GlyphCoverageNormalizer.split(text, family), pageCountOf, ChartSpec.readTitle).
  • App-тесты: @SpringBootTest + @AutoConfigureMockMvc (Boot 4: org.springframework.boot.webmvc.test.autoconfigure); три контекста — ConvertControllerTest (пустой ключ), ApiKeyFilterTest (properties = "wordpdf.api-key=…"), ConvertLimitsTest (@TestPropertySource с лимитами — отдельный класс, не @Nested).
  • Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): StrictOoxmlNormalizerTest↔strictOoxml_convertsNotRejected (+pageCount_strictBreaksCountedLightweight — lightweight против strict), DocxOnOffNormalizerTest↔ruPlain_regularRunsUseRegularFont, SymbolFontNormalizerTest↔symbolFonts_bulletsAreNotHash, FieldNormalizerTest↔pageNumbers_recomputedNotCached, GlyphCoverageNormalizerTest↔exoticGlyphs_drawnNotHash, WordPdfValidatorTest↔staleCachePageCountRejectedBeforeRender (+checkPageCountLightweight_agreesWithJaxbPath 99/100/101, pageCount_breaksInsideTablesAreCounted, pageCount_continuousSectionsNotCountedLightweight), BundledFontsTest↔ruPlain_emDashEmbeddedNotHelvetica, ChartSpecTest↔автозаголовки, chart-пейнтеры↔chartsSmartArt_drawingsBecomeImages (+drawingToggles_offRemovesRasters/drawingToggles_chartsOffSmartArtOn), DocToPdfTest↔DocToPdfRenderer (legacyDoc_convertsToPdf — Tinos/Carlito без Helvetica + 43 картинки; legacyDoc_footersCarryPageNumbers — инъекция колонтитулов + PAGE; ole2Junk_rejected; legacyDoc_fontCacheNotWrittenToWorkingDir — кэш шрифтов не в CWD (контейнер: /app не пишется)); noLoggingWarningInPdf — регрессия slf4j-simple, pdfTitle_comesFromParameter — регрессия PDF-title (юнит-партнёра нет). App-регрессии: requestLimitParams_areIgnored, nonPositiveLimits_failStartup, unknownPath_notFound, concurrentRequests_bothSucceed (гонка реестра PhysicalFonts), corruptNotAZip_rejected, junkInsideValidZip_conversionError, nonDocxFilename_rejected, oversizedOverCoreLimit_rejected, renderFlagsOff_convertsWithoutDrawings, cyrillicAndPathInFilename_sanitizedResponseName (RFC 5987 + path-traversal), docsOpenWithoutKey/forwardedPrefix_healthStaysOpen/forwardedPrefix_docsOpenWithoutKey (открытая документация + матч фильтра без forwarded-contextPath), legacyDoc_convertsToPdf (OLE2-развилка ConversionService.validate + заголовок X-Wordpdf-Degraded).
  • UI-тестов нет; гейт SPA — npm run build (tsc -b) + npm run lint (oxlint, .oxlintrc.json: rules-of-hooks error, only-export-components warn).