Files
java-word-pdf/AGENTS.md
T
Pjandro 08c68305be
PR checks / web (pull_request) Successful in 42s
Main: tests, deploy, autotests / web (push) Successful in 45s
PR checks / java (pull_request) Successful in 1m36s
Main: tests, deploy, autotests / images-web (push) Successful in 33s
Main: tests, deploy, autotests / java (push) Successful in 2m59s
Main: tests, deploy, autotests / images-app (push) Successful in 6m29s
Main: tests, deploy, autotests / deploy (push) Successful in 2m35s
Main: tests, deploy, autotests / autotests (push) Successful in 52s
Main: tests, deploy, autotests / rollback (push) Has been skipped
docs: актуализация AGENTS.md по свежей сверке с кодом
- convert — только 3-аргументная сигнатура; App.tsx в components/; 11 zip-правил + OleObjectNormalizer как 12-й байтовый
- REST: открытые префиксы ApiKeyFilter, тело {"error": …}, карта 404/405/415 в repo-map
- расхождение compose (prod-like гасит springdoc, CI-прод держит swagger открытым); VITE_BASE в образе; подсети resolver; WORDPDF_SAMPLES_DIR; ручные фикстуры не перезаписывать
2026-11-17 04:14:23 +03:00

24 KiB
Raw Blame History

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 + TS + Vite 8 + oxlint + Tailwind v4, npm) и 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 — копий на хосте/в репо не заводить.

Пайплайн WordPdfConverter.convert(byte[] docxBytes, String title, ConvertOptions) → convertToStream (публичная сигнатура единственная, 2-аргументной перегрузки нет); порядок шагов фиксирован:

  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 на мониторе WordPdfConverter.class);
  7. Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL) — последним;
  8. 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 errorOnCharts/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→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby→MathFallback, OleObjectNormalizer — 12-й, отдельным байтовым проходом (не zip); неизменённые записи копируются 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, 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). Коды: 400 валидация/битые параметры, 401 ApiKeyFilter (X-API-Key ↔ wordpdf.api-key, пусто = выключено, сравнение MessageDigest.isEqual; открытые префиксы /actuator, /swagger-ui, /v3/api-docs; Advice фильтров не видит — 401 пишет сам), 413 multipart, 422 отказ по графике (DrawingRejectedException, текст — контракт с фронтом), 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 (ключ в localStorage wordpdf.api.key, probeApiKey(): 401=required / иначе open; имя файла из 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 (отключение пересжатия); переименование молча вернёт мыльный ресемпл.
  • Стоп-лист «не чинить» (до любой попытки починить расхождение с 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), 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 с)
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
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 test PMD и проверки JaCoCo не запускает (оба на verify; сам агент JaCoCo подключается и на test — execution prepare-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, MathMlSupport, 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); алиасы — 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, 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), convert-timeout=2m, api-key= (пусто = auth off), forward-headers-strategy=framework; 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, 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 (движок плагина 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, в тестах не генерировать; XSD-невалидная фикстура правится, не код. Синтетика в памяти разрешена: docx — ZipOutputStream из литеральных XML, .doc — крафт POIFSFileSystem. Пересоздание — одноразовые SampleDocxGenerator/ChartTypesDocxGenerator (POI test-scope, команда — docs/agent/repo-map.md); charts-smartart.docx и ole-embedded.docx сделаны руками — никогда не перезаписывать.
  • Идиома загрузки (ловушка): 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 не поднимают.
  • Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест + javadoc-ссылка. Счётчики (2026-11): 59 классов / 898 тестов (core 53/849, app 6/49); детали — docs/agent/testing.md.
  • Прод-автотесты: pytest 9.1.1 + requests (timeout (10,180) — больше серверных 2m), конфигурация только env (WORDPDF_BASE_URL обязателен, WORDPDF_API_KEY факультативен → needs_key SKIP, WORDPDF_MAX_MB/MAX_PAGES — ожидаемые лимиты стенда 5/100, WORDPDF_SAMPLES_DIR — путь к фикстурам); запуск ./mise.sh run prod-tests либо job autotests в CI.