Files
java-word-pdf/AGENTS.md
T

29 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, options) (шаг 3.5: c:chart/dgm:relIds docx2fo.xslt не умеет и молча выбрасывает — свой Java2D-движок internal/chart/* рендерит их в PNG 300 dpi и подменяет на pic:pic; после setFontMapper, до FOSettings; рисунок, выключенный в ConvertOptions, пропускается ранним continue до рендера и остаётся в docx — в PDF на его месте пусто, как без движка) → new FOSettings(pkg) + FopFallbackFonts.declare (декларирует в FOP-конфиге все бандл-семейства — FOP встраивает только задекларированные) → FORendererApacheFOP / FOUserAgent (заголовок PDF = параметр title, если непустой) → 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.
  • Фронт ходит на ${import.meta.env.BASE_URL}api/... (vite base из env VITE_BASE, дефолт /) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом /pdf-converter/).
  • Факультативные параметры renderCharts/renderSmartArt (query или multipart-form — Spring биндит и то и другое) контроллер превращает в ConvertOptions; дефолты — константы ядра WordPdfSettings.RENDER_CHARTS/RENDER_SMARTART. Лимиты входа задаёт только конфигурация сервера: свойства wordpdf.max-bytes (байты) / wordpdf.max-pages (страниц), env WORDPDF_MAX_BYTES/WORDPDF_MAX_PAGES (relaxed binding, прецедент WORDPDF_CONVERT_TIMEOUT); @Value в конструкторе ConvertController с дефолтом-SpEL из констант ядра (MAX_INPUT_BYTES=20 MiB / MAX_PAGES=1000), значение ≤ 0 — падение на старте. Параметрами запроса лимиты не переопределяются (регрессии requestLimitParams_areIgnored, nonPositiveLimits_failStartup, ConvertLimitsTest). SPA шлёт только чекбоксы. Потолок загрузки — 100 МБ (client_max_body_size 100m в nginx + Spring multipart 100MB); больше отсекается до валидатора.
  • Ключ доступа: ApiKeyFilter (сервлет-фильтр, единственная граница доступа) сверяет заголовок X-API-Key со свойством wordpdf.api-key (env WORDPDF_API_KEY; сравнение MessageDigest.isEqual). Пустое свойство = аутентификация выключена (dev java -jar, тесты ConvertControllerTest — пустой ключ). /actuator/** открыт — им дышит Docker HEALTHCHECK (actuator публикует только health). 401 отдаёт сам фильтр (ApiExceptionHandler ошибок фильтров не видит), тело в той же форме {"error": …}. Прод: compose выключает springdoc env'ами SPRINGDOC_API_DOCS_ENABLED/SPRINGDOC_SWAGGER_UI_ENABLED — документация с валидным ключом даёт 404 (ApiExceptionHandler.notFound даёт 404 всем неизвестным путям, а не 500 от catch-all). SPA: экран ApiKeyGate, ключ в localStorage (wordpdf.api.key), при 401 очищается и форма открывается пустой; заголовок подставляет только api.ts. Регрессии — ApiKeyFilterTest, ConvertControllerTest#unknownPath_notFound.

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

  • 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 100m (gateway/nginx.conf, шлюз; столько же в прод-nginx.conf и Spring multipart) — потолок загрузки стека: без директивы upload режется HTML-413 от шлюза до бэкенда вместо JSON-ошибки API. Авторитетный лимит — свойство wordpdf.max-bytes (env WORDPDF_MAX_BYTES, дефолт 20 MiB), значения выше 100 МБ держит шлюз/multipart.

Шрифты (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 = 20 MiB, MAX_PAGES = 1000 лежат в WordPdfSettings — едином файле-дефолтах ядра. Оба лимита переопределяются на вызов ConvertOptions (у WordPdfValidator перегрузки checkInput(byte[], long), checkPageCount(byte[]|pkg, int), checkPageCountLightweight(byte[], int)); REST API параметрами запроса их не пробрасывает — значения берутся из конфигурации сервера (свойства wordpdf.max-bytes/wordpdf.max-pages, env WORDPDF_MAX_BYTES/WORDPDF_MAX_PAGES). В ядре рантайм-конфигурации нет. Вход валидатора и конвертера — только byte[]/WordprocessingMLPackage, файловых перегрузок в ядре нет (.docx по имени проверяет ConvertController — с байтов расширение не видно). Страницы = максимум трёх нижних оценок: (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(byte[], String) (и перегрузка с ConvertOptions) возвращает байты и файлового вывода не имеет — отказ структурно не оставляет артефакта (регрессия staleCachePageCountRejectedBeforeRender; Lightweight-путь на мусоре без zip-подписи молчит — оценку «1», подпись проверяет приложение).

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, WordPdfSettings (константы-дефолты), ConvertOptions (рисование на вызов)
…/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, gateway/nginx.conf образ бэкенда (multi-stage, temurin-21); compose app+web+gateway; прод-запуск — из PROD-DIR, не отсюда
корневой docker-compose.dev.yml dev-стенд без ключа: проект wordpdf-dev, вход http://127.0.0.1:9011, springdoc включён
корневой .env.example шаблон env деплоя: ключ (WORDPDF_API_KEY) и лимиты входа (WORDPDF_MAX_BYTES/WORDPDF_MAX_PAGES); реальный прод .env живёт в PROD-DIR/, в репо его нет
wordpdf-web/Dockerfile, wordpdf-web/nginx.conf образ SPA (node→nginx); только статика (прокси — в шлюзе); base сборки — ARG VITE_BASE (prod /pdf-converter/, дефолт /)
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 -f docker-compose.dev.yml up -d --build      # dev-стенд: вход 127.0.0.1:9011, без ключа
cd PROD-DIR && docker compose up -d --build   # прод: PROD-HOST:9010 (только LAN)
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached   # один тест

Compose: gateway (nginx) — единственный вход: /api, /swagger-ui, /v3/api-docs, /actuator → app (/actuator открыт фильтром), остальное → web (DNS-имена в сети compose). Два режима запуска. Прод — каталог PROD-DIR (вне репо; проект wordpdf-prod, build-context'ы указывают в репозиторий, образы *:prod): gateway опубликован только на PROD-HOST:9010 (LAN), ключ — .env этого каталога (fail-closed ${WORDPDF_API_KEY:?…}), springdoc выключен env'ами, SPA собрана с VITE_BASE=/pdf-converter/; свой nginx.conf (= репозиторный + proxy_read_timeout 300s, иначе длинные конвертации рвутся 504). Наружный вход — https://pjandro.ru/pdf-converter/: nginx на PROD-HOST (/etc/nginx/conf.d/localhost.conf) проксирует IP-литералом PROD-HOST:9010 и срезает префикс завершающим слэшем proxy_pass; при недоступном стеке error_page отдаёт 503 (HTML/{"error": …}), nginx не падает; мониторинг без ключа — /pdf-converter/health. Dev-стенд — из репо docker compose -f docker-compose.dev.yml up -d --build (проект wordpdf-dev, вход http://127.0.0.1:9011, пустой ключ — фильтр прозрачен, springdoc включён). Отзыв ключа = правка прод .env + docker compose up -d в прод-каталоге. После пересоздания контейнеров app/web старому gateway нужен restart (nginx кэширует DNS бэкендов при старте — иначе 502). Запуск по просьбе пользователя = прод-стек (каталог прода, up -d --build); dev-стенд, java -jar / npm run dev — внутренняя отладка, запуском приложения не считать. Обновление прода («эту версию в прод») = та же docker compose up -d --build в прод-каталоге: прод пересобирается из текущего рабочего дерева репозитория (build.context — каталог, не git-ref: незакоммиченные правки поедут в прод), прод-.env с ключом и наружный шлюз 88.88 при этом не меняются; гейт успешности — docker compose ps (3× healthy) и curl -s http://PROD-HOST:9010/actuator/health → UP. wordpdf.convert-timeout переопределяется env WORDPDF_CONVERT_TIMEOUT (relaxed binding Boot).

Перезапуск прода — скрипт ./restart.sh в прод-каталоге: без флага restart app web → гейт healthy app (до 120 с) → restart gateway; с --build — up -d --build (пересборка из рабочего дерева). Gateway всегда рестартует последним (nginx кэширует DNS бэкендов). Файл живёт только в прод-каталоге, в репозитории его нет.

Пересоздать 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 → byte[] (WordPdfConverterTest.sampleBytes), PDF для PDFBox — временный файл (convertPdf). 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.