Files
java-word-pdf/AGENTS.md
T
Pjandro 334e6a9006
PR checks / web (pull_request) Successful in 1m14s
PR checks / java (pull_request) Successful in 3m1s
Main: tests, deploy, autotests / web (push) Successful in 1m10s
Main: tests, deploy, autotests / images-web (push) Successful in 41s
Main: tests, deploy, autotests / java (push) Successful in 7m19s
Main: tests, deploy, autotests / images-app (push) Failing after 48s
Main: tests, deploy, autotests / deploy (push) Has been skipped
Main: tests, deploy, autotests / autotests (push) Has been skipped
Main: tests, deploy, autotests / rollback (push) Has been skipped
docs: перегенерировать AGENTS.md по структуре Repository Guidelines
- синтез четырёх 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
2026-11-15 01:28:22 +03:00

21 KiB
Raw Blame History

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; порядок шагов фиксирован:

  1. DependencyGuard.check() (commons-compress ≥ 1.25.0 API-проба);
  2. шрифты: new BundledFontMapper() → BundledFonts.init() → restrictToBundled() — строго в этом порядке, до load();
  3. нормализаторы (DocxRewritePipeline.STEP + лямбда OleObjectNormalizer) → WordprocessingMLPackage.load;
  4. setFontMapper; 3.5 DrawingPreRenderer.run (chart/SmartArt → PNG; error-флаги бросаются здесь) — обязателен до FOSettings, иначе FOP молча теряет диаграммы;
  5. FOSettings + ChartImageHandler + FopFallbackFonts.declare + LayoutPostRenderer.register + setCustomXsltTemplates(VendoredXslt.TEMPLATES);
  6. общая FopFactory (DCL); 6. Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL) — последним;
  7. 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_PIXELS 4096² — понижает dpi через fitDpi; MAX_POINTS 100 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 test PMD/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, execution pmd-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-Hamcrest containsString в 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_key SKIP, WORDPDF_MAX_MB/MAX_PAGES — ожидаемые лимиты стенда); запуск ./mise.sh run prod-tests либо job autotests в CI.