- синтез четырёх scout-обходов: core src, тесты, конфигурация/сборка, скрипты/документация - 8 разделов: Overview, Architecture & Data Flow (пайплайн 0–7, инварианты), Key Directories, Development Commands, Conventions, Important Files, Runtime/Tooling, Testing & QA - сохранены критические инварианты, ловушки (test-jar/-am, @Value-дефолты, idiom загрузки фикстур) и ссылки-роутеры на docs/agent
21 KiB
Repository Guidelines
Роутер: правила, инварианты и команды — здесь; глубокие детали —
docs/agent/*.md(pipeline, doc-bridge, chart, testing, ci-cd, render-limitations, repo-map — каждый авторитетен наравне с этим файлом), нормативные форматы —docs/standards/(ссылка с номером секции обязательна).
Project Overview
Конвертер .docx/.doc → .pdf на чистом Java: docx4j 17.3.2 → XSL-FO → форк Apache FOP, без 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 + TS + Vite + Tailwind v4) и pytest-автотесты prod-autotests/. Java 17, только Maven.
Architecture & Data Flow
Единственный вход стека — gateway-контейнер nginx (:9010 prod-like compose.yml, :9011 dev compose.dev.yml), не 8080.
Пайплайн WordPdfConverter.convert(byte[], String[, ConvertOptions]) → convertToStream; порядок шагов фиксирован:
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 → PNG; error-флаги бросаются здесь) — обязателен доFOSettings, иначе FOP молча теряет диаграммы;FOSettings+ChartImageHandler+FopFallbackFonts.declare+LayoutPostRenderer.register+setCustomXsltTemplates(VendoredXslt.TEMPLATES);- общая
FopFactory(DCL); 6.Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)— последним; finally: сброс temp-шрифтов,resetSharedImageCaches()(иначе ~1,5 ГБ за 30 конвертаций),restrictToBundled()(иначе встроенные в предыдущий docx шрифты травят реестр).
Вход роутируется по сигнатуре: PK\x03\x04 → docx; D0 CF 11 E0 A1 B1 1A E1 (CFB) → DocToDocx.convert. Валидация WordPdfValidator — до конвертера (для .doc страницы считаются по сырым байтам); WordPdfValidator не трогает docx4j — его пороги в WordPdfConverter объявлены compile-time literals (javac инлайнит, static-блок конвертера не дёргается).
Слои ядра (wordpdf-core/src/main/java/ru/pjandro/wordpdf/):
- публичный API:
WordPdfConverter,WordPdfValidator,ConvertOptions(record),ConversionException+ValidationException(бросает только валидатор) +Charts/SmartArt/OleFoundException;warmup()— идемпотентный прогрев, решает вызывающий; internal/: контракт нормализатора —byte[] normalize(byte[]), нечего менять → тот же массив (assertSame); правила 1–11 идут одним zip-проходомDocxRewritePipeline.STEPв фиксированном порядке: Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby→MathFallback; неизменённые записи копируются raw-сжатыми байтами; наружу толькоDocxNormalizer,DocxRewritePipeline.STEP,OleObjectNormalizer,FopFallbackFonts,LayoutPostRenderer,DependencyGuard;internal/doc: мост.doc→.docx, 18 классов, наружу толькоDocToDocx.convert/countPages; раскладки —docs/agent/doc-bridge.md;internal/chart: Java2D → PNG (ChartRenderer.DPI = 300,MAX_PIXELS4096² — понижает dpi черезfitDpi;MAX_POINTS100 000, бюджет chart-PNG на документ 128 MiB); модель деградации: битая chart-часть/превышение бюджета → объект удалён + warn, конвертация продолжается;OutOfMemoryError— не деградация, аConversionException(500);fonts/GlyphFont: метрика/глифы через fontbox напрямую, безjava.awt.Font(fontconfig хосту не нужен).
Concurrency-инвариант: PhysicalFonts — глобальный мутируемый реестр → все конвертации сериализованы монитором WordPdfConverter.class (convert, warmup, DCL-фабрика, мутации BundledFonts). Приложение дополнительно держит однопоточный ThreadPoolExecutor (очередь 16 → 503, wordpdf.convert-timeout=2m → 504), головой очереди стоит warmup().
REST (wordpdf-app, всё package-private кроме WordPdfApplication): POST /api/v1/convert (multipart file + errorOnCharts/errorOnSmartArt/errorOnOle, maxMb/maxPages переопределяют серверный дефолт в обе стороны, ≤ 0 → 400). Коды: 400 валидация/битые параметры, 401 ApiKeyFilter (X-API-Key ↔ wordpdf.api-key, пусто = выключено; Advice фильтров не видит — 401 пишет сам), 413 multipart, 422 отказ по графике (DrawingRejectedException, текст — контракт с фронтом), 500 ConversionFailedException (текст ядра только в лог), 503 переполнение очереди, 504 timeout. Полная карта — docs/agent/repo-map.md. На .doc error-флаги не срабатывают (BLIP-плейсхолдеры — уже растры).
SPA (wordpdf-web/src): вся сеть — единственная точка api.ts (ключ в localStorage wordpdf.api.key, probeApiKey(): 401=required / 405=open); единственный источник состояния — useState в App.tsx.
Критические инварианты (нарушение = битый вывод, не исключение)
- 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. slf4j-simpleобязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF; в app исключён (logback).- FOP — форк
org.docx4j:docx4j-fo-renderer*2.11-docx4j.6 (транзитив отdocx4j-export-fo, в pom не пинится); расхождения с upstream-доками FOP нормальны;lineRule=autoне «чинить». - Chart-media префикс
/word/media/chart-*— пакетный контракт сChartImageHandler(отключение пересжатия); переименование молча вернёт мыльный ресемпл. - Стоп-лист «не чинить» (до любой попытки починить расхождение с Word —
docs/agent/render-limitations.md):jc="distribute",suff="tab"/lvlJc, кернинг,framePr,REF/SEQ/TOC-кэш, руби-надстрочница,ptab, U+2188/U+218A (GPL-шрифты не добавляем). - Комментарии в
WordPdfConverter/DocxOnOffNormalizerговорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (поведение описано верно).
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), 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 (сеть), App.tsx (состояние), components/ |
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 с) |
develop/ |
вне git: эталоны Word — не фикстуры, в тесты/jar не подключать |
Development Commands
Бутстрап: sh bootstrap.sh (Windows: powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1) — project-local mise в ./.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
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; гейт готовности — контейнеры healthy + корень SPA 200;--force-recreateобязателен. mvn testPMD/JaCoCo не запускает (оба наverify);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/; 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); алиасы —BundledFontMapper.ALIASES(Calibri→Carlito, Arial→Arimo, Times New Roman→Tinos, …), 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, Boot 4.1.1 BOM, springdoc 3.1.1, JUnit 6.1.3, PDFBox 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 |
convert-timeout=2m, multipart 100 MB; wordpdf.max-mb/max-pages здесь не объявлять намеренно — пустое значение затенит @Value-дефолты 5/100 |
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, wget-healthcheck, FQDN FROM, обнуление прокси на команде) / CI-гейт без fontconfig / стенды :9010–:9011 / шлюз |
.gitea/workflows/pr.yml, main.yml, .ci/maven-settings.xml |
CI-конвейер; шаги java/web в обоих — идентичные; зеркало Nexus ${env.MAVEN_MIRROR_URL}, mirrorOf="*" |
wordpdf-web/src/api.ts, vite.config.ts |
вся сеть SPA; base — только через env VITE_BASE (прод /pdf-converter/) |
Runtime/Tooling Preferences
- Java 17 temurin + Maven 3.9.16 (пин в
mise.toml,mvnwнет — только системный Maven из mise); UTF-8; Node 24, Python 3.15 — всё через project-local mise (./.mise/bin/mise, вне системы). - Только Maven (никаких Gradle/Ant). Версии зависимостей/плагинов — только в корневом
pom.xml; FOP-форк отдельно не пинить;commons-compressне завышать (привязан к docx4j 17.3.2);<repositories>в pom не добавлять (зеркало — через settings). - Контейнеры: podman/buildah;
FROMтолько FQDN; хостовые прокси-переменные обнулять на самой команде вRUN/HEALTHCHECK;DOCKER_BUILDKIT=0(CI); healthcheck через wget, не curl; fontconfig рантайму не нужен (глифы — fontbox). - Сеть: наружу публикуется только gateway (9010/9011); 8080/80 наружу не выставлять; подсети compose зафиксированы (nginx
resolverпривязан к шлюзу). - Прод-стек (
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 (движок плагина 3.21.2 — осознанный откат, 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— имя шрифта символа). Пиксели — только юниты chart-пейнтеров (assertRatio< 0.06 / < 0.10). Сообщения ассертов — по-русски с наблюдаемым значением; литерал слева ("%PDF".equals(…)). - Фикстуры — только закоммиченные
samples/*.docx/*.doc, в тестах не генерировать (пересоздание — одноразовыеSampleDocxGenerator/ChartTypesDocxGenerator, POI test-scope); XSD-невалидная фикстура правится, не код. Синтетика в памяти разрешена: docx —ZipOutputStreamиз литеральных XML,.doc— крафтPOIFSFileSystem. - Идиома загрузки (ловушка): core — classloader без ведущего слэша (
getResourceAsStream("samples/…")); app — class-relative со слэшем ("/samples/…", ресурсы из core test-jar). - App-тесты: 4 набора свойств = 4 класса-контекста (
ConvertControllerTestпинует пустойwordpdf.api-key=;ApiKeyFilterTest;ConvertLimitsTest;ConversionTimeoutTest);ConversionServiceTest/ApiExceptionHandlerTest— без Spring; проверяют только HTTP-код/заголовки/текст ошибки; core-юниты Spring не поднимают. - Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест + javadoc-ссылка. Счётчики и детали —
docs/agent/testing.md. - Прод-автотесты: pytest + requests, конфигурация только env (
WORDPDF_BASE_URLобязателен,WORDPDF_API_KEYфакультативен →needs_keySKIP,WORDPDF_MAX_MB/MAX_PAGES— ожидаемые лимиты стенда); запуск./mise.sh run prod-testsлибо jobautotestsв CI.