Замена JEuclid/AWT-ветки формул на детерминированный растер только бандл-шрифтами jar (без fontconfig); FOP-конфиг дополняется всеми бандл-начертаниями при каждом declare — иначе общая FopFactory замораживает fopconf первого документа и теряет глифы. MathModel/MathRenderer: OMML (§22.1) → дерево боксов → PNG 300 dpi (только GlyphFont/fontbox, без java.awt.Font); метрики боксов равны габариту paint (пределы nary/sPre не обрезаются канвой). Unsupported конструкция или переполнение бюджета — текстовая деградация (m:t). Inline-картинка опускается раном w:rPr/w:position на базовую линию строки (FOP ставит инлайн-графику нижним краем на базу; AUDIT-FIX baseline-shift). Байтовое правило 6 MathFallbackNormalizer (перед GlyphCoverage) срезает unsupported-формулы до загрузки docx4j; формула в wps:txbx уходит в docx4j-фолбэк mathText. JEuclid исключён из pom (de.rototor jeuclid-core/jeuclid-fop); порядок zip-правил сдвинут (MathFallback → 6). Порядок сканов шрифтов закрыт гейтом FontsBundledOnlyInvariantTest + BundledFontAliases (единый алиас-реестр вместо рефлексивных мутаций реестра). Счётчики: 63 класса / 1004 теста (core 57/956, app 6/48); JaCoCo BRANCH core 0.8518. Доки: pipeline/render-limitations/repo-map/ testing/doc-bridge/MEM_USAGE_UPGRADE синхронизированы.
26 KiB
Repository Guidelines
Роутер: правила, инварианты и команды — здесь; глубокие детали —
docs/agent/*.md(pipeline, doc-bridge, chart, testing, ci-cd, repo-map, render-limitations — каждый авторитетен наравне с этим файлом), нормативные форматы —docs/standards/(навигатор —docs/standards/README.md, ссылка на спецификацию — с номером секции).
Project Overview
Конвертер .docx/.doc → .pdf на чистом Java: docx4j 17.3.2 → XSL-FO → форк Apache FOP (org.docx4j:docx4j-fo-renderer* 2.11-docx4j.6 — транзитив от docx4j-export-fo), без LibreOffice/Aspose. Бинарный .doc (Word 97-2003) переносится мостом MS-DOC/MS-CFB (internal/doc) в in-memory .docx и идёт тем же конвейером. Maven-мультимодуль ru.pjandro:java-word-pdf:1.0.0: wordpdf-core (библиотека), wordpdf-app (REST на Spring Boot 4.1.1); вне Maven-реактора — SPA wordpdf-web (React 19.2 + TS ~6.0 + Vite 8.3 + oxlint + Tailwind v4.3, npm; strict-режим TS намеренно не включён — сборка не strict-гейт) и pytest-автотесты prod-autotests/. Java 17, только Maven.
Architecture & Data Flow
Единственный вход стека — gateway-контейнер nginx (:9010 prod-like compose.yml, :9011 dev compose.dev.yml), не 8080. Реальный прод-стек (docker-compose.yml + прод nginx.conf) рендерит CI-job deploy — копий на хосте/в репо не заводить. Наружный прод-вход — https://pjandro.ru/pdf-converter/ (образ web собирается с VITE_BASE=/pdf-converter/).
Пайплайн WordPdfConverter.convert(byte[] docxBytes, String title, ConvertOptions) → convertToStream (публичная сигнатура единственная, 2-аргументной перегрузки нет); порядок шагов фиксирован:
DependencyGuard.check()(commons-compress ≥ 1.25.0 API-проба);- шрифты:
new BundledFontMapper()→BundledFonts.init()→restrictToBundled()— строго в этом порядке, доload(); - нормализаторы (
DocxRewritePipeline.STEP+ лямбдаOleObjectNormalizer) →WordprocessingMLPackage.load; setFontMapper; 3.5DrawingPreRenderer.run(chart/SmartArt/OMML-формулы → PNG; error-флаги бросаются здесь) — обязателен доFOSettings, иначе FOP молча теряет диаграммы;FOSettings+ChartImageHandler+FopFallbackFonts.declare; 4.25LayoutPostRenderer.register; 4.5setCustomXsltTemplates(VendoredXslt.TEMPLATES);- общая
FopFactory(DCL на монитореWordPdfConverter.class); Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)— последним;finally: сброс temp-шрифтов (FontTablePart.deleteEmbeddedFontTempFiles()),resetSharedImageCaches()(иначе ~1,5 ГБ за 30 конвертаций),restrictToBundled()(иначе встроенные в предыдущий docx шрифты травят реестр).
WordPdfValidator.validate вызывается в convert() до монитора (параллельно); при options == null бросает ValidationException сам convert(). Вход роутируется по сигнатуре: PK\x03\x04 → docx; D0 CF 11 E0 A1 B1 1A E1 (CFB) → DocToDocx.convert. Для .doc страницы считаются по сырым байтам. Пороги валидатора в WordPdfConverter объявлены compile-time literals (javac инлайнит, static-блок конвертера не дёргается).
Слои ядра (wordpdf-core/src/main/java/ru/pjandro/wordpdf/):
- публичный API:
WordPdfConverter,WordPdfValidator,ConvertOptions(recorderrorOnCharts/errorOnSmartArt/errorOnOle/maxMb/maxPages— порядок полей фиксирован),ConversionException+ValidationException+Charts/SmartArt/OleFoundException;warmup()— идемпотентный прогрев (никогда не бросает), решает вызывающий; internal/: контракт нормализатора —byte[] normalize(byte[]), нечего менять → тот же массив (assertSame); правила 1–11 идут одним zip-проходомDocxRewritePipeline.STEPв фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→MathFallback→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby,OleObjectNormalizer— 12-й, отдельным байтовым проходом (не zip); неизменённые записи копируются raw-сжатыми байтами; наружу толькоDocxNormalizer,DocxRewritePipeline.STEP,OleObjectNormalizer,FopFallbackFonts,LayoutPostRenderer,DependencyGuard;internal/doc: мост.doc→.docx, 17 top-level классов (+ вложенныйDocxBodyвDocToDocx), наружу толькоDocToDocx.convert/countPages; любая бита/шифрованный/Word 6-95 входов →ConversionException; раскладки —docs/agent/doc-bridge.md;internal/chart: Java2D → PNG (ChartRenderer.DPI = 300,MAX_PIXELS4096² —fitDpiпонижает dpi;MAX_POINTS100 000, бюджет chart/math-PNG на документ 128 MiB); формулы OMML — собственный растерMathModel(разбор §22.1 в дерево боксов,SUPPORTED— единый список конструкций) +MathRenderer(без AWT/JEuclid, только бандл черезGlyphFont); модель деградации: битая chart-часть/превышение бюджета → объект удалён + warn; неподдерживаемая/битая формула → текст (конкатенацияm:t) + warn;wp:extentвне диапазона/ноль → объект остаётся + warn (FOP молча потеряет);OutOfMemoryError— не деградация, аConversionException(500);fonts/GlyphFont: метрика/глифы через fontbox напрямую, безjava.awt.Font(fontconfig хосту не нужен).
Concurrency-инвариант: PhysicalFonts — глобальный мутируемый реестр → все конвертации сериализованы монитором WordPdfConverter.class (convert, warmup, DCL-фабрика, мутации BundledFonts, BundledFonts.font()). Приложение дополнительно держит однопоточный ThreadPoolExecutor (очередь 16 → 503, wordpdf.convert-timeout=2m → 504), головой очереди стоит warmup(); WordPdfValidator.checkInput выполняется синхронно до очереди.
REST (wordpdf-app, всё package-private кроме WordPdfApplication): POST /api/v1/convert (multipart file + errorOnCharts/errorOnSmartArt/errorOnOle, maxMb/maxPages переопределяют серверный дефолт в обе стороны, ≤ 0 → 400; file.getBytes() — только после проверки размера; имя файла из Content-Disposition, UTF-8 + .pdf). Коды: 400 валидация/битые параметры, 401 ApiKeyFilter (X-API-Key ↔ wordpdf.api-key, пусто = выключено, сравнение MessageDigest.isEqual; открытые префиксы /actuator/ (со слэшем!), /swagger-ui, /v3/api-docs; dot-segment (.., %2e) заставляет требовать ключ даже на открытых; Advice фильтров не видит — 401 пишет сам), 413 multipart, 422 отказ по графике (DrawingRejectedException, фиксированные тексты CHARTS/SMART_ART/OLE — контракт с фронтом), 500 ConversionFailedException (текст ядра только в лог, наружу фиксированный), 503 переполнение очереди, 504 timeout; тело ошибки — {"error": …} (record ApiError). Полная карта, включая 404/405/415, — docs/agent/repo-map.md. На .doc error-флаги не срабатывают (BLIP-плейсхолдеры — уже растры).
SPA (wordpdf-web/src): вся сеть — единственная точка api.ts (ровно 2 fetch: convertDocx, probeApiKey() — 401=required / иначе open; ключ в localStorage wordpdf.api.key, при 401 стирается; имя файла из Content-Disposition filename*=utf-8''); единственный источник состояния — useState в components/App.tsx (+ useRef для AbortController/blob-URL), store-библиотек нет; лимиты на клиенте не задаются — только сервер.
Критические инварианты (нарушение = битый вывод, не исключение)
- Static-блок
WordPdfConverter:docx4j.convert.out.fo.gsubFeatures=false(иначеWordLayoutFixupsотказывает всем фиксам → FOP падает),docx4j.fonts.discoverPhysicalFonts.enabled=false,discoverJarFonts.enabled=false— не удалять. - Единственный XSL-FO-стилист — вендорный
wordpdf-core/src/main/resources/xslt/docx2fo.xslt(копия из docx4j-export-fo 17.3.2 + AUDIT-FIX-патчи); обновление docx4j = ручной перенос патчей; дрейф-гейтvendoredXsltTracksJarCopy; команда ре-вендоринга —docs/agent/repo-map.md. slf4j-simpleобязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF; в app исключён (logback). Fontbox логируется commons-logging — единственный мостjcl-over-slf4j.- FOP — форк
org.docx4j:docx4j-fo-renderer*2.11-docx4j.6 (транзитив отdocx4j-export-fo, в pom не пинится); расхождения с upstream-доками FOP нормальны;lineRule=autoне «чинить». - Chart-media префикс
/word/media/chart-*(ChartImageHandler.CHART_MEDIA_URI_PREFIX) — пакетный контракт сChartImageHandler(отключение пересжатия); переименование молча вернёт мыльный ресемпл. - Стоп-лист «не чинить» (до любой попытки починить расхождение с Word —
docs/agent/render-limitations.md):jc="distribute",suff="tab"/lvlJc, кернинг,framePr,REF/SEQ/TOC-кэш, руби-надстрочница,ptab, U+2188/U+218A (GPL-шрифты не добавляем).
Key Directories
| Каталог | Назначение |
|---|---|
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ |
публичный API + internal/ (нормализаторы) + internal/doc/ (мост) + internal/chart/ (рендер) + fonts/ |
wordpdf-core/src/main/resources/ |
fonts/ (30 TTF + лицензии OFL/Bitstream-Vera/Noto), xslt/docx2fo.xslt, slf4j-simple.properties |
wordpdf-core/src/test/resources/samples/ |
фикстуры: 13 .docx + 12 .doc (закоммичены, билдятся в test-jar для app) |
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ |
REST-слой (11 классов) |
wordpdf-web/src/ |
SPA: api.ts (вся сеть), components/ (App.tsx — состояние, ApiKeyGate, DropZone, PdfPreview, StatusMessage, Logo) |
prod-autotests/ |
pytest-проверки живого стенда (31: 4 открытые + 27 needs_key) |
docs/agent/ · docs/standards/ |
справочники поведения · закоммиченные спецификации (ECMA-376, MS-DOC/CFB/ODRAW…, навигатор — docs/standards/README.md) |
gateway/nginx.conf |
прод-like шлюз (client_max_body_size 100m, таймауты 300 с, resolver привязан literal-ом к шлюзу сети) |
develop/ |
вне git (gitignored): эталоны Word — не фикстуры, в тесты/jar не подключать |
Development Commands
Бутстрап: sh bootstrap.sh (Windows: powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1) — project-local mise 2026.10.19 в ./.mise/, дальше всё через ./mise.sh / .\mise.ps1.
./mise.sh run verify # = mvn clean verify: тесты + PMD + JaCoCo (гейт перед push)
./mise.sh run verify-nofontconfig # тот же verify в контейнере без fontconfig (как CI)
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am обязателен: core test-jar
./mise.sh run app-package && 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
./mise.sh run web-install|web-build|web-lint|web-dev # npm ci | tsc -b && vite build | oxlint | vite :5173
./mise.sh run mem-bench # замер памяти (membench.sh + core MemoryBench)
podman-compose -f compose.dev.yml up -d --build --force-recreate # dev-стенд :9011, без ключа
./mise.sh run prod-tests # pytest; обязателен WORDPDF_BASE_URL
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD (lxml)
- «Запусти тестовый сервер» (термин пользователя) = dev-стенд выше, не
java -jar; вход —http://<LAN-IP>:9011(hostname -I); гейт готовности — контейнеры healthy (podman-compose -f compose.dev.yml ps) + корень SPA 200;--force-recreateобязателен. mvn testPMD и проверки JaCoCo не запускает (оба наverify; сам агент JaCoCo подключается и наtest— executionprepare-agentнаinitialize);mvn -pl wordpdf-appбез-amпадает (зависимость от core test-jar).- Деплой — push в
main→ Gitea Actions (детали —docs/agent/ci-cd.md); перед деплоем/перезапуском прочитать/home/pjandro/prod/java-word-pdf/DEPLOY.md(вне репо); ручных скриптов нет.
Code Conventions & Common Patterns
- Классы
final, приватный конструктор, толькоstatic(stateless, DI в ядре нет). Исключения-экземпляры:BundledFontMapper, Spring-компоненты app. Вinternal/**классы package-private;public— только вызываемые извне пакета, контракт не расширять. - Ошибки публичного API — только
ConversionException extends RuntimeException;ValidationExceptionне оборачивать; в chart — деградация вместо падения; текст 500 наружу фиксированный (сообщения ядра логируются, не отдаются). - Javadoc на русском: «зачем» со ссылкой на секцию спецификации (§17.3.2.24, [MS-DOC] §2.6.1…) + что сломается без шага + регрессия в формате
Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx(по этой строке грепом восстанавливаются пары «нормализатор-тест ↔ тест-в-конвейере»). - Логирование по пакетам:
java.util.logging— корневой пакет иinternal/(WordPdfConverter,OleObjectNormalizer,DocToDocx); SLF4J —internal/chartиwordpdf-app. - Модели —
record(ConvertOptions,BundledFonts.Entry,ApiError); константы UPPER_SNAKE с javadoc-обоснованием числа; holder-идиомы для ленивой инициализации (VendoredXslt.TEMPLATES); compile-time literals там, где важен инлайн (WordPdfConverter↔WordPdfValidator). - Шрифты: новый шрифт = файл в
resources/fonts/+ запись вBundledFonts.ENTRIES(синхрон проверяетBundledFontsTest); алиасы —BundledFontAliases.ALIASES(Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine, …; вынесено изBundledFontMapper, чтобы обращение к статикам не инициировало ungated-сканBestMatchingMapper.<clinit>), fallback — DejaVu Sans. - PMD (
pmd-ruleset.xml, executionpmd-checkнаverify,includeTests=true, валит любой приоритет): правила не перенастраивать, подавления (@SuppressWarnings("PMD…"),// NOPMD) запрещены — нарушения чинятся кодом. - Git: origin
git.pjandro.ru:pjandro/java-word-pdf; защищённыеmain/master/dev; все правки — через PR в дефолтную ветку; push — только после./mise.sh run verify. Прод-координаты и креды в репо не попадают (Gitea Variables/Secrets —GITEA-vars.md;WORDPDF_API_KEYни в один файл).
Important Files
| Файл | Что держать в голове |
|---|---|
pom.xml (корень) |
единственное место версий (properties + dependencyManagement): docx4j 17.3.2, commons-compress 1.28.0, slf4j 2.0.20, Boot 4.1.1 BOM, springdoc 3.1.1, JUnit 6.1.3, PDFBox/fontbox 3.0.8, POI 5.5.1 (test), JaCoCo 0.8.15, PMD-плагин 3.21.2 |
wordpdf-core/src/main/java/.../WordPdfConverter.java |
весь конвейер, static-блок sysprops, пороги-константы, монитор сериализации |
wordpdf-app/src/main/resources/application.properties |
multipart 100MB/100MB (зеркалит nginx client_max_body_size) + file-size-threshold=2MB (сброс больших частей на диск — защита от OOM), convert-timeout=2m, api-key= (пусто = auth off), forward-headers-strategy=framework; wordpdf.max-mb/max-pages здесь не объявлять намеренно — пустое значение затенит @Value-дефолты 5/100 (≤ 0 на старте → IllegalStateException) |
wordpdf-core/pom.xml / wordpdf-app/pom.xml |
execution test-jar; BRANCH-гейт 0.85 (только core); exclusion slf4j-simple; Boot-4 имена: spring-boot-starter-webmvc (не -web), отдельный spring-boot-webmvc-test; repackage привязан явно |
Containerfile / Containerfile.test / compose*.yml / gateway/nginx.conf |
прод-образ (heap 2G, mem_limit 3G, wget-healthcheck, FQDN FROM, non-root 10001, обнуление прокси на команде) / CI-гейт без fontconfig / стенды :9010–:9011 / шлюз. Нюанс: repo compose.yml (prod-like) гасит springdoc env-ами, а реальный прод из CI-рендера держит swagger открытым (test_swagger_ui_open_without_key) — не путать |
.gitea/workflows/pr.yml, main.yml, .ci/maven-settings.xml |
CI: jobs java/web в обоих — идентичные шаги; main.yml: images-* → deploy → autotests (+ rollback при failure); Maven в CI живёт в контейнере maven:3.9-eclipse-temurin-17; зеркало ${env.MAVEN_MIRROR_URL}, mirrorOf="*" |
wordpdf-web/src/api.ts, vite.config.ts |
вся сеть SPA; base — только через env VITE_BASE (в прод-образ запекается --build-arg VITE_BASE=/pdf-converter/) |
Runtime/Tooling Preferences
- Java 17 temurin + Maven 3.9.16 + Node 24 + Python 3.15 — пинины в
mise.toml, всё через project-local mise (./.mise/bin/mise, вне системы);mvnwнет (.mvn/— пустой) — только Maven из mise. UTF-8. - Только Maven (никаких Gradle/Ant). Версии зависимостей/плагинов — только в корневом
pom.xml; FOP-форк отдельно не пинить;commons-compressне завышать (привязан к docx4j 17.3.2);<repositories>в pom не добавлять (зеркало — через settings). - Веб: только npm (
package-lock.jsonзакоммичен; никаких pnpm/yarn); линтер — oxlint (не eslint). - Контейнеры: podman/buildah;
FROMтолько FQDN; хостовые прокси-переменные обнулять на самой команде вRUN/HEALTHCHECK;DOCKER_BUILDKIT=0(CI); healthcheck через wget, не curl; fontconfig рантайму не нужен (глифы — fontbox); alpine-теги maven/temurin amd64-only — тестовый образ на Debian-базе. - Сеть: наружу публикуется только gateway (9010/9011); 8080/80 наружу не выставлять; подсети compose зафиксированы (nginx
resolverпривязан literal-ом к шлюзу сети — 10.113.0.1 стенды / 10.112.0.1 прод). - Прод-стек (
docker-compose.yml,nginx.conf) рендерится job'омdeployиз Variables — копий на хосте/в репо не заводить; required-контексты защитыmain— буквальноPR checks / java (pull_request),PR checks / web (pull_request)(deploy/autotests не включать).
Testing & QA
- Гейты на
verify: PMD (движок 6.55.0 — default внутри maven-pmd-plugin 3.21.2, отдельно в pom не пинится; осознанный откат — ruleset использует удалённые в PMD 7*MustUseBraces; подавлений в коде нет и быть не должно) + JaCoCo: LINE ≥ 0.90 оба модуля, BRANCH ≥ 0.85 только core; при провале отчёт уже вtarget/site/jacoco/. CI-эквивалент —./mise.sh run verify-nofontconfig. - Стек: JUnit 6 (
org.junit.jupiter), толькоAssertions— Mockito/AssertJ запрещены (в app-тестах допустим inline-HamcrestcontainsStringвandExpect); тестовые классы package-private, зеркалят main-пакеты; только@Test(исключения: два@BeforeAllпрогрева шрифтов и@AfterEach drainWorkerвConversionTimeoutTest); ни@Nested, ни@ParameterizedTest, ни@Disabled, ниassertAll. - Именование: регрессионные —
объект_условие(pageNumbers_recomputedNotCached), юниты — camelCase (pageFieldBecomesFldSimple). - PDF сравнивается текстом: PDFBox 3
PDFTextStripper(normсхлопывает пробелы; негативные маркеры —#/.notdefиHelvetica; приёмfontNameOf— имя шрифта символа, живёт только вWordPdfConverterTest). Пиксели — только юниты chart-пейнтеров (assertRatio< 0.06 / < 0.10, эталонные числа Word-рендеров 300 dpi захардкожены). Тестовых утилит нет — хелперы намеренно дублируются в классах. Сообщения ассертов — по-русски с наблюдаемым значением; литерал слева ("%PDF".equals(…)). - Фикстуры — только закоммиченные
samples/*.docx/*.doc, в тестах не генерировать; XSD-невалидная фикстура правится, не код. Синтетика в памяти разрешена: docx —ZipOutputStreamиз литеральных XML,.doc— крафтPOIFSFileSystem. Пересоздание — одноразовыеSampleDocxGenerator/ChartTypesDocxGenerator(POI test-scope, команда —docs/agent/repo-map.md);charts-smartart.docxиole-embedded.docxсделаны руками — никогда не перезаписывать (все 12.doc— эталоны заказчика, не вывод генераторов). - Идиома загрузки (ловушка): core — classloader без ведущего слэша (
getResourceAsStream("samples/…")); app — class-relative со слэшем ("/samples/…", ресурсы из core test-jar). - App-тесты: 4 набора свойств = 4 Spring-контекста (
ConvertControllerTestпинует пустойwordpdf.api-key=;ApiKeyFilterTest;ConvertLimitsTest;ConversionTimeoutTest);ConversionServiceTest/ApiExceptionHandlerTest— без Spring; проверяют только HTTP-код/заголовки/текст ошибки; core-юниты Spring не поднимают. Ловушка: mise инжектирует корневой.envв окружение задач — ambientWORDPDF_API_KEYвзорвёт 401 все MockMvc-тесты, если ключ не запинен свойствами контекста. - Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест + javadoc-ссылка. Счётчики (2026-11): 63 класса / 1004 теста (core 57/956, app 6/48); детали —
docs/agent/testing.md. - Прод-автотесты: pytest 9.1.1 + requests (timeout
(10,180)— больше серверных 2m), конфигурация только env (WORDPDF_BASE_URLобязателен,WORDPDF_API_KEYфакультативен →needs_keySKIP,WORDPDF_MAX_MB/MAX_PAGES— ожидаемые лимиты стенда 5/100,WORDPDF_SAMPLES_DIR— путь к фикстурам); запуск./mise.sh run prod-testsлибо jobautotestsв CI.