23 KiB
Repository Guidelines
Project Overview
Конвертер .docx → .pdf на чистом Java (docx4j 17.3.2 + форк Apache FOP, без 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/lint нет; SPA гейтуется npm run build). Вход стека — контейнер gateway (nginx), НЕ 8080; Docker-секция README устарела — авторитет этот файл.
Architecture & Data Flow
Пайплайн WordPdfConverter.convertToStream (порядок фиксирован, менять местами нельзя)
new BundledFontMapper()→BundledFonts.init()→BundledFonts.restrictToBundled(). Конструктор маппера каждый раз добавляет системные шрифты в реестрPhysicalFonts; ключ реестра — имя шрифта,addPhysicalFont(URI)не перезаписывает занятый →init()вызываетdropNonBundled()до регистрации иload().- Нормализация байтов docx до JAXB-загрузки (цепочка
byte[] → byte[], порядок значим):DocxOnOffNormalizer(w:val="off"/"on"→false/true) →SymbolFontNormalizer(PUA U+F0xx Symbol/Wingdings/Webdings → Unicode + DejaVu Sans; таблицаSymbolMapperсгенерирована) →FieldNormalizer(fldCharPAGE/NUMPAGES/SECTIONPAGES →w:fldSimple, иначе во всех колонтитулах один закэшированный номер) →GlyphCoverageNormalizer(режет ран по покрытию глифов, пишет семейство вw:rFonts, иначе FOP рисует «#»). WordprocessingMLPackage.load→WordPdfValidator.checkPageCount(pkg, maxPages)— до рендера.pkg.setFontMapper(mapper)→DrawingPreRenderer.run(pkg, options)(шаг 3.5:c:chart/dgm:relIdsdocx2fo.xslt не умеет — свой Java2D-движокinternal/chart/*рендерит в PNG 300 dpi и подменяет наpic:pic; объект, выключенный вConvertOptions, пропускается до рендера и остаётся в docx).new FOSettings(pkg)+FopFallbackFonts.declare(декларирует все бандл-семейства — FOP встраивает только задекларированные) →FORendererApacheFOP/FOUserAgent(непустойtitle→ заголовок PDF) →Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL).finally:deleteEmbeddedFontTempFiles()(в 17.xOpcPackage.close()нет).
REST API (wordpdf-app, все классы package-private)
- Единственный эндпоинт
POST /api/v1/convert(multipart-полеfile, факультативныеrenderCharts/renderSmartArt— query или form) →application/pdf,Content-Disposition: attachment; filename*=UTF-8''…. - Конвертации сериализованы однопоточным
ThreadPoolExecutor(ConversionService.QUEUE_CAPACITY = 16, переполнение → 503): ядро мутирует глобальный реестрPhysicalFonts. - Ошибки (
ApiExceptionHandler, тело{"error": …}):ValidationException→ 400;ConversionFailedException→ 500;ConversionRejectedException→ 503;ConversionTimeoutException(wordpdf.convert-timeout, 2m) → 504;MaxUploadSizeExceededException→ 413; неизвестный путь → 404; catch-all → 500 (подробности только в лог). Граница: сломанный контейнер (не zip / размер / страницы) → 400, валидный zip с мусором внутри → 500. Валидация до очереди:checkInput→ zip-магикPK\x03\x04→checkPageCountLightweight(порядок значим). - Ключ доступа:
ApiKeyFilterсверяет заголовокX-API-Keyсо свойствомwordpdf.api-key(envWORDPDF_API_KEY, сравнениеMessageDigest.isEqual). Пустое свойство = аутентификация выключена (devjava -jar, тесты)./actuator/**открыт (HEALTHCHECK). 401 пишет сам фильтр (ApiExceptionHandlerошибок фильтров не видит). Прод compose выключает springdoc env'ами — документация с валидным ключом даёт 404. - Лимиты входа задаёт только конфигурация сервера:
wordpdf.max-bytes/wordpdf.max-pages(envWORDPDF_MAX_BYTES/WORDPDF_MAX_PAGES),@ValueвConvertControllerс дефолтом-SpEL изWordPdfSettings(20 MiB / 1000); значение ≤ 0 → падение на старте; параметрами запроса не переопределяются. Ключи вapplication.propertiesне объявлены — пустое значение затенит SpEL-дефолт. - SPA: вся сеть в
src/api.ts(компонентыfetchне вызывают); ключ вlocalStorage(wordpdf.api.key), при 401 очищается, экранApiKeyGate; запросы на${import.meta.env.BASE_URL}api/...(vitebaseиз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). ChartSpec.parse (enum Type: PIE/PIE3D/DOUGHNUT/BAR/BAR_HORIZONTAL/LINE/AREA/SURFACE3D/UNSUPPORTED; пустой c:title + autoTitleDeleted="0" → автозаголовок Chart Title) → ChartRenderer (осевые «круглые» шаги 1/2/5·10ⁿ как Word) → пейнтеры CartesianPainter/PiePainter/Surface3dPainter (калибровка по стр. 3 develop/word-export.pdf: CAMERA_DISTANCE=2.36, DEPTH_RATIO=0.705, HEIGHT_RATIO=0.664, свет (0.83,0.48,0.28)); SmartArtRenderer рисует кэш разложенной схемы word/diagrams/drawing1.xml; палитра темы — DrawMlColor. Калибровочные константы менять только вместе с Surface3dPainterTest/PiePainterTest. Обход pkg.getParts() — только по снимку списка (createImagePart мутирует реестр → CME); rels частей — part.getRelationshipsPart(), не getOwningRelationshipPart(); обход XML обязан раскрывать JAXBElement; при падении рендера — gd.getAny().clear() + warn (деградация, не падение).
Критические инварианты (нарушение = битый вывод)
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.2 (пакетыorg.apache.fop.*);Fop.Renderers.getRenderer()возвращает список.docx2fo.xsltв репозитория нет — он в jardocx4j-export-fo. - Страницы в валидаторе =
max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1); lightweight-путь (StAX по zip, без docx4j) на не-zip молчит — подпись проверяет вызывающий. Расхождение lightweight↔JAXB допустимо только в завышение. - Известный остаток эталона: 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/)
Алиасы MS→open-source в BundledFontMapper.ALIASES: Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans; виртуальный «Segoe UI Symbol» для U+2000–U+2EFF → fallback. Noto Naskh Arabic / Noto Sans Armenian — только regular, в маппер не регистрируются (покрытие подбирает PhysicalFonts-реестр). Новый шрифт = файл + запись в BundledFonts.ENTRIES (синхрон проверяет BundledFontsTest).
Key Directories
| Путь | Назначение |
|---|---|
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ |
публичный API: WordPdfConverter, WordPdfValidator, ConversionException, WordPdfSettings (константы-дефолты), ConvertOptions (record: renderCharts, renderSmartArt, maxBytes, maxPages) |
…/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: WordPdfApplication, ConvertController, ConversionService (очередь), ApiExceptionHandler, ApiKeyFilter |
wordpdf-web/src/ |
SPA (React 19 + TS + Vite + Tailwind): компоненты в components/, вся сеть в api.ts |
корневые Dockerfile, docker-compose.yml, docker-compose.dev.yml, gateway/nginx.conf |
образ бэкенда (multi-stage, temurin-21); compose app+web+gateway |
корневой .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.*, 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 НЕ генерируется — создана вручную, не перезаписывать):
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 (обязательно прочитать перед любым деплоем/перезапуском). Единая точка входа с dev-машины — /home/pjandro/prod/java-word-pdf/restart.sh (пробрасывает флаги удалённому скрипту: --build — пересборка образов из origin/main + перезапуск; без флага — restart контейнеров; предупреждает о не запушенном в main). В прод попадает только запушенное в main — рабочее дерево на сборку не влияет. Наружный вход https://pjandro.ru/pdf-converter/. Dev-стенд — из репо docker-compose.dev.yml (проект wordpdf-dev, :9011, пустой ключ). Репозиторный docker-compose.yml — третий вариант (проект wordpdf, 9010:80 на все интерфейсы, VITE_BASE не передаётся). Запуск по просьбе пользователя = прод-стек; dev/java -jar/npm run dev — внутренняя отладка.
Code Conventions & Common Patterns
- Классы
final, приватный конструктор, толькоstatic(stateless, DI нет; конфигурация —Docx4jProperties+ classpath-ресурсы). Исключения — экземпляры по природе: docx4j-наследникиBundledFontMapper,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; внутренние исключения оборачиваются на границе. В 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. - Тестовые методы:
объект_условиечерез underscore —ruPlain_cyrillicAndStyles,checkInput_bytesOverLimit,noKey_rejected.
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_BYTES20 MiB,MAX_PAGES1000,RENDER_CHARTS/SMARTART); рантайм-конфигурации в ядре нет.wordpdf-app/src/main/resources/application.properties— multipart 100MB (в тон gatewayclient_max_body_size 100m),wordpdf.convert-timeout=2m, пустойwordpdf.api-key;wordpdf.max-bytes/max-pagesздесь намеренно нет.wordpdf-app/pom.xml—spring-boot-maven-pluginс явной executionrepackage(в 4.1.1 сам не связывается, jar останется тонким);slf4j-simpleисключён; тест-зависимости:spring-boot-webmvc-test(в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.wordpdf-core/pom.xml—maven-jar-pluginexecutiontest-jar(публикует фикстуры для app).- Корневой
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; surefire с-Djava.awt.headless=true. 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-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java— main()-утилита пересоздания фикстур.
Runtime & Tooling Preferences
- Java 21 + Maven (обязательны; wrapper
mvnwнет); UTF-8. Только Maven — никакого Gradle/Ant. - Версии зависимостей — только в корневом
pom.xml(properties + dependencyManagement); новые зависимости — latest stable. - Фронт: Node ≥ 20.19 (фактически vite
^8.3.0, React^19.2, TS~6.0, Tailwind^4.3, oxlint; docker-сборка наnode:24-alpine), npm с закоммиченнымpackage-lock.json(npm ci). - CI, линтеров, форматтеров, checkstyle для Java — нет; проверка одна:
mvn clean verify. - Исполняемый jar бэкенда проверять только
java -jar(тесты идут по classpath и repackage-специфику не видят). - Git: origin
git.pjandro.ru:pjandro/java-word-pdf, рабочие веткиmain/devзащищены (правила глобального AGENTS.md).
Testing & QA
- JUnit 6 (
org.junit.jupiter:junit-jupiter), surefire 3.6.0 с-Djava.awt.headless=trueв argLine; толькоAssertions(Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrestorg.hamcrest.Matchers.containsStringвandExpect); тестовые классы package-private, зеркалят main-пакеты; только@Test(+@BeforeAllгде нужен warm-up шрифтов). - PDF сравнивается текстом, не растеризацией: PDFBox 3 (
Loader.loadPDF) —PDFTextStripperдля текста (пер-страничноsetStartPage/setEndPage), overrideprocessTextPositionдля шрифта конкретного символа (fontNameOf), обход ресурсов страниц для встроенных шрифтов (EAAAAA+Carlito-Bold) и счётчика картинок (imageCount). Негативные маркеры — регрессии:assertFalse(text.contains("#"))(.notdef),assertFalse(font.startsWith("Helvetica")). Текст нормализуется по пробелам (norm); вtableImage_tableAndImage— полное удаление пробелов (docx4j переносит слова в auto-fit таблицах). - Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word.
- Фикстуры — закоммиченные
samples/*.docx(11; в тестах не генерировать): core грузит classpath-ресурсом →byte[], PDF для PDFBox — временный файл; app читает/samples/…из test-jar core (classifiertests) →mvn -pl wordpdf-appбез-amне соберётся. In-memory docx —ZipOutputStreamиз литеральных XML или POI вbyte[]. - Юниты нормализаторов работают строками (
rewrite) + zip'ами изZipOutputStream; обязательные контракты: «нечего менять → тот же массив (assertSame)» и неприкосновенность частей внеword/*.xml([Content_Types].xml). - App-тесты:
@SpringBootTest+@AutoConfigureMockMvc(Boot 4:org.springframework.boot.webmvc.test.autoconfigure); три контекста —ConvertControllerTest(пустой ключ),ApiKeyFilterTest(properties = "wordpdf.api-key=…"),ConvertLimitsTest(@TestPropertySourceс лимитами — отдельный класс, не@Nested). - Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой + javadoc-ссылка):
DocxOnOffNormalizerTest↔ruPlain_regularRunsUseRegularFont,SymbolFontNormalizerTest↔symbolFonts_bulletsAreNotHash,FieldNormalizerTest↔pageNumbers_recomputedNotCached,GlyphCoverageNormalizerTest↔exoticGlyphs_drawnNotHash,WordPdfValidatorTest↔staleCachePageCountRejectedBeforeRender,BundledFontsTest↔ruPlain_emDashEmbeddedNotHelvetica, chart-пейнтеры↔chartsSmartArt_drawingsBecomeImages(+drawingToggles_*);noLoggingWarningInPdf— регрессияslf4j-simple(юнит-партнёра нет). App-регрессии:requestLimitParams_areIgnored,nonPositiveLimits_failStartup,unknownPath_notFound,concurrentRequests_bothSucceed(гонка реестраPhysicalFonts). - UI-тестов нет; гейт SPA —
npm run build(tsc -b) +npm run lint(oxlint).