29 KiB
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 — порядок шагов фиксирован, менять местами нельзя:
new BundledFontMapper()→BundledFonts.init()→BundledFonts.restrictToBundled(). Конструктор маппера каждый раз заново добавляет системные шрифты в реестрPhysicalFonts; бандл регистрируется поверх; чистка реестра — доload(). Ключ реестра — имя шрифта,addPhysicalFont(URI)НЕ перезаписывает занятый ключ →BundledFonts.init()вызываетdropNonBundled()(иначе системныйDejaVuSerif.ttfблокирует нашDejaVuSerif-Regular.ttf).- Нормализация байтов 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(сложные поляfldCharPAGE/NUMPAGES/SECTIONPAGES →w:fldSimple, иначе во всех колонтитулах печатается один закэшированный номер; штатныйFieldsCombinerdocx4j не заходит внутрьw:sdt) →GlyphCoverageNormalizer(шаг 2.4: режет ран по покрытию глифов и пишет семейство вw:rFonts; трогает только раны с однимw:tи явнымw:rFonts; покрытие —java.awt.Font.canDisplayчерезBundledFonts.awtFont, неGlyphCheck— тот логирует на каждый глиф). WordprocessingMLPackage.load(байты)→WordPdfValidator.checkPageCount(pkg)— до рендера.pkg.setFontMapper(mapper)→DrawingPreRenderer.run(pkg, options)(шаг 3.5:c:chart/dgm:relIdsdocx2fo.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).finally:deleteEmbeddedFontTempFiles()(в 17.xOpcPackage.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/...(vitebaseиз envVITE_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(страниц), envWORDPDF_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 multipart100MB); больше отсекается до валидатора. - Ключ доступа:
ApiKeyFilter(сервлет-фильтр, единственная граница доступа) сверяет заголовокX-API-Keyсо свойствомwordpdf.api-key(envWORDPDF_API_KEY; сравнениеMessageDigest.isEqual). Пустое свойство = аутентификация выключена (devjava -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в репозитория нет — он в jardocx4j-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(envWORDPDF_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с явной executionrepackage(в 4.1.1 сам не связывается, jar останется тонким);slf4j-simpleисключён из зависимости ядра.- Корневой
pom.xml— все версии зависимостей (в модулях версии не объявлять): docx4j17.3.2, slf4j2.0.20, JUnit6.1.3, PDFBox3.0.8(test), POI5.5.1(test, только генератор фикстур), Spring Boot4.1.1(BOM-import), springdoc3.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для текста, overrideprocessTextPositionдля шрифта конкретного символа (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 (classifiertests) →-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.