Files
java-word-pdf/AGENTS.md
T
Pjandro 2116ec43a4
PR checks / web (pull_request) Successful in 35s
PR checks / java (pull_request) Successful in 1m19s
fix(core): сериализация конвертаций монитором класса WordPdfConverter
Публичный convert() теперь безопасен из нескольких потоков: секция после
валидации (мост .doc + convertToStream) выполняется под монитором класса —
общая FopFactory (per-render disableFontCache, имиджевые кеши) и её сброс в
finally больше не могут пересечься с параллельным рендером. warmup()
синхронизирован тем же монитором (реентельно). WordPdfValidator остаётся
до монитора: stateless, вызывается параллельно HTTP-потоками.
Регрессия — WordPdfConverterTest#concurrentConversions_twoThreadsBothSucceed.
Комментарии ConversionService/AGENTS/repo-map приведены к новому контракту.
2026-11-08 14:22:56 +00:00

25 KiB
Raw Blame History

Repository Guidelines

Роутер: правила, инварианты и команды — здесь; глубокие детали — docs/agent/*.md, нормативные форматы — docs/standards/ (ссылка с номером секции обязательна), пользовательская документация — README.md.

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 и идёт тем же конвейером. Java 17, только Maven.

Модуль Содержимое
wordpdf-core библиотека: 62 Java-файла (7 — публичный API, 16 internal/, 18 internal/doc/, 18 internal/chart/, 3 fonts/)
wordpdf-app REST API на Spring Boot 4.1.1: 11 классов, единственный public — WordPdfApplication
wordpdf-web SPA (React 19 + TS + Vite + Tailwind), вне Maven-реактора, отдельный образ

Единственный вход стека — gateway-контейнер nginx (:9010 prod-like compose.yml, :9011 dev compose.dev.yml), не 8080. Авторитетны этот файл, docs/agent/ и код. Полный путеводитель по каталогам, ключевым файлам и командам — docs/agent/repo-map.md.

Пайплайн WordPdfConverter.convert(byte[], String[, ConvertOptions])

Порядок шагов 0–7 фиксирован (convertToStream), местами менять нельзя. Вход роутируется по сигнатуре: PK\x03\x04 → docx-путь; D0 CF 11 E0 A1 B1 1A E1 (CFB, MS-CFB §2.2) → DocToDocx.convert → in-memory .docx → тот же конвейер (предикат — WordPdfValidator.isBinaryDoc). Валидация — до convertToStream: WordPdfValidator.validate(bytes, options) (размер → подпись zip/CFB → контейнер → страницы); для .doc — checkPageCountDoc по сырым байтам.

Порядок: шрифты (BundledFontMapper → BundledFonts.init → restrictToBundled) и правила 1–10 (DocxRewritePipeline.STEP) + OleObjectNormalizer — до WordprocessingMLPackage.load; FOSettings/FopFallbackFonts/LayoutPostRenderer — до setCustomXsltTemplates(VendoredXslt.TEMPLATES); Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL) — последним; finally → deleteEmbeddedFontTempFiles(). Полная таблица шагов и подсчёт страниц — docs/agent/pipeline.md.

Нормализаторы (internal/DocxNormalizer)

Контракт: byte[] normalize(byte[]) throws IOException; нечего менять → вернуть тот же массив (assertSame). Порядок фиксирован: Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby. Правила 1–10 применяет DocxRewritePipeline.STEP одним zip-проходом (неизменённые записи копируются raw-сжатыми байтами); OleObjectNormalizer (правило 11) — лямбдой в WordPdfConverter.normalizers(). STEP выставляют 9 из 10 rewrite-нормализаторов (нет у RubyNormalizer), у OleObjectNormalizer её нет. Правила 1–11, guard'ы, номера секций и инвариант mc-preprocessor.xslt (собственный рерайт strict-URI ломать нельзя) — docs/agent/pipeline.md.

Мост .doc → .docx (internal/doc)

18 классов, 16 package-private; наружу — DocToDocx (convert/countPages) и CfbReader. Общий разбор — DocFile: CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table. Новых runtime-зависимостей нет (POI/POIFS — test-scope). Источники: [MS-DOC] (docs/standards/doc/), [MS-CFB]/[MS-OLEPS]/[MS-ODRAW] (docs/standards/binary/). Байтовые раскладки по классам — docs/agent/doc-bridge.md.

REST API (wordpdf-app, всё package-private кроме WordPdfApplication)

POST /api/v1/convert: multipart-поле file (.docx/.doc) + query/form-параметры errorOnCharts/errorOnSmartArt/errorOnOle (дефолты — WordPdfSettings.ERROR_ON_*). Ответ — application/pdf, Content-Disposition: attachment; filename*=UTF-8''…; имя — ConversionService.safeBaseName. Тело ошибки — {"error": …}. Error-флаги на .doc не срабатывают (BLIP-плейсхолдеры → картинки). ApiExceptionHandler не видит ошибок фильтров — 401 пишет сам ApiKeyFilter.

  • Коды: 400 — ValidationException/BadRequestException/битые параметры; 401 — ApiKeyFilter; 404/405/415 — путь/метод/content-type; 413 — multipart; 422 — DrawingRejectedException (core-DrawingFoundException, Kind {CHARTS, SMARTART, OLE}); 500/503/504 — ConversionFailedException/ConversionRejectedException/ConversionTimeoutException. Полная карта — docs/agent/repo-map.md.
  • Текст 422 — контракт с фронтом: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты».
  • Ключ: X-API-Key ↔ wordpdf.api-key (пустое = выключено); без ключа открыты только OPEN_PREFIXES (/actuator/, /swagger-ui, /v3/api-docs), пути с точечными сегментами — никогда.
  • Очередь и лимиты: конвертации сериализованы однопоточным ThreadPoolExecutor (QUEUE_CAPACITY = 16, переполнение → 503): ядро дополнительно сериализует конвертации монитором WordPdfConverter.class (convert() безопасен из нескольких потоков); головой очереди на старте стоит warmup(). Лимиты входа — только конфигурация сервера (wordpdf.max-mb/max-pages, дефолты из WordPdfSettings; ≤ 0 → IllegalStateException; параметрами запроса не переопределяются).
  • SPA: вся сеть в wordpdf-web/src/api.ts; ключ в localStorage (wordpdf.api.key); ApiKeyGate — только если probeApiKey() подтвердил требование ключа (признак открытого сервера — 405); base — VITE_BASE; DropZone .docx,.doc.

Chart/SmartArt-движок (internal/chart, 18 классов)

Нормативный источник — ECMA-376 (docs/standards/ooxml/: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D, XSD); поведение Word — ms-oi29500.md, ms-odrawxml.md. Калибровки (камера, PIE_DEPTH) меняются только с пиксельными тестами; невалидная фикстура правится, не код.

Java2D → PNG: ChartRenderer.DPI = 300, потолок MAX_PIXELS = 16_777_216 (fitDpi); лимиты ChartSpec.MAX_POINTS = 100_000, ChartRenderer.MAX_TICKS = 1000, DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000 — деградация «объект как есть / удалён + warn», не OOM. Chart-PNG вставляются media-частями вручную (addChartMedia, /word/media/chart-*, без createImagePart); ChartImageHandler отключает «Compress Pictures» (CR-029) только для них. Пейнтеры, autoTitleDeleted, Combo, обходы JAXB — docs/agent/chart.md.

Критические инварианты (нарушение = битый вывод, не исключение)

  • docx4j.convert.out.fo.gsubFeatures=false — static-блок WordPdfConverter; иначе FO невалиден → WordLayoutFixups молча отказывает всем фиксам → FOP падает на docx4j-baseline.
  • docx4j.fonts.discoverPhysicalFonts.enabled=false и discoverJarFonts.enabled=false — static-блок: иначе BestMatchingMapper сканирует системные шрифты и jar'ы classpath'а, а restrictToBundled() всё найденное выбрасывает (~100–140 мс впустую на JVM). discoverJarFonts("fonts-symbol") свойством не гейтится — символ-шрифт регистрируется и снимается restrict'ом как раньше.
  • Единственный XSL-FO-стилист — вендорный xslt/docx2fo.xslt (копия из docx4j-export-fo 17.3.2 + два AUDIT-FIX-патча: w:rPr/w:position → baseline-shift, Part 1 §17.3.2.24; AUDIT-FIX-2 — w:moveFrom/w:moveTo/w:bdo/w:dir, иначе их ловит catch-all match="*" и текст теряется). Дрейф-гейт vendoredXsltTracksJarCopy: вне AUDIT-FIX-регионов копия побайтно равна стилю из jar'а. setCustomXsltTemplates принимает предкомпилированный Templates.
  • slf4j-simple обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия noLoggingWarningInPdf); приложение исключает его — логи ведёт logback.
  • FOP — форк org.docx4j:docx4j-fo-renderer* 2.11-docx4j.6 (транзитив от docx4j-export-fo, в pom не пинится; пакеты org.apache.fop.*). FopFallbackFonts берёт w:renderer с mime application/pdf, иначе первый со шрифтами.
  • BundledFonts.init() идемпотентен и synchronized, распаковывает TTF в wordpdf-fonts-* (deleteOnExit); dropNonBundled() чистит PhysicalFonts от всего, что вне бандла.
  • PhysicalFonts — глобальный и мутируемый → конвертации сериализуются монитором WordPdfConverter.class внутри ядра (общая FopFactory и сброс её image-кешей — под тем же монитором); приложение держит однопоточный воркер ради 503/timeout; warmup() идёт тем же потоком.
  • Страницы в валидаторе = max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1); правила StAX-подсчёта — docs/agent/pipeline.md.
  • Не чинить: jc="distribute", suff="tab"/lvlJc, метрика «single», кернинг, framePr, REF/SEQ/TOC-кэш, руби-надстрочница, U+2188/U+218A — доказательства в docs/agent/render-limitations.md.
  • Комментарии в WordPdfConverter/DocxOnOffNormalizer говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).

Шрифты (30 TTF + 3 лицензии, SIL OFL, wordpdf-core/src/main/resources/fonts/)

9 семейств: 7 × 4 начертания (Carlito/Caladea/Arimo/Tinos/Cousine/DejaVu Sans/DejaVu Serif) + Noto Naskh Arabic / Noto Sans Armenian (только regular). BundledFontMapper.ALIASES: Calibri→Carlito, Calibri Light→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; self-map всех бандл-семейств, включая Noto; fallback — DejaVu Sans; виртуальный SYMBOL_FONT «Segoe UI Symbol» (U+2000–U+2EFF) → fallback до основного цикла. Новый шрифт = файл + запись в BundledFonts.ENTRIES (синхрон проверяет BundledFontsTest). GlyphFont читает TTF напрямую с classpath через fontbox, без java.awt.Font (нужен fontconfig на хосте). Публичный API и детали — docs/agent/repo-map.md.

Команды

Бутстрап: 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)
mvn clean verify                          # то же; mvnw НЕТ — только системный Maven
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached   # один тест
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf        # -am: core test-jar
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
./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                 # прод-автотесты в prod-autotests/
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx   # XSD (lxml)

Задачи mise (8): verify, app-package, app-run, web-install, web-build, web-lint, web-dev, prod-tests.

«Запусти тестовый сервер» (термин пользователя) = полный dev-стенд, НЕ java -jar: podman-compose -f compose.dev.yml up -d --build --force-recreate, вход http://<LAN-IP хоста>:9011 без API-ключа; гейт — контейнеры healthy + корень SPA отвечает 200. --force-recreate обязателен: без него контейнеры остаются на старом образе.

Пересоздание фикстур и перевендоривание стилиста — docs/agent/repo-map.md. Деплой: прод — на пользовательском LAN-сервере; перед деплоем/перезапуском прочитать /home/pjandro/prod/java-word-pdf/DEPLOY.md; пуск — push в main или Run workflow, ручных скриптов нет (детали — docs/agent/ci-cd.md).

Code Conventions & Common Patterns

  • Классы final, приватный конструктор, только static (stateless, DI нет; конфигурация — Docx4jProperties + classpath-ресурсы). Исключения — экземпляры по природе: BundledFontMapper, DrawMlColor, Spring-компоненты wordpdf-app.
  • В internal/** классы public (иначе родительский пакет не вызвал бы), но публичные члены наружу ограничены: normalize/STEP/declare/run/check/register; rewrite-хуки — package-private. В wordpdf-app всё package-private кроме WordPdfApplication; в internal/doc публичны только DocToDocx и CfbReader.
  • Нормализаторы — единый контракт internal/DocxNormalizer + константа STEP; порядок цепочки — см. «Нормализаторы», правятся только word/*.xml.
  • Ошибки публичного API — только ConversionException extends RuntimeException (unchecked); внутренние исключения оборачиваются на границе. В chart — деградация вместо падения. ValidationException — собственность WordPdfValidator; не оборачивать в общий ConversionException.
  • DI в wordpdf-app — конструкторная инъекция Spring; состояние сервисов private final. SPA: единственный источник состояния — useState в App.tsx, вся сеть — в api.ts.
  • Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx).
  • Константы UPPER_SNAKE с эталонными значениями (PIE_DEPTH, MAX_PAGES); начертания V_REGULAR/V_BOLD/V_ITALIC/V_BOLD_ITALIC; модели — record; размеры в chart — в пунктах, растр × DPI/72.
  • Логирование: java.util.logging.Logger в корневом пакете и internal/, SLF4J — в internal/chart и wordpdf-app.
  • Тестовые методы: регрессионные — объект_условие через underscore (ruPlain_cyrillicAndStyles), юниты — camelCase (pageFieldBecomesFldSimple); оба стиля разрешает PMD-паттерн junit5TestPattern (^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$).
  • PMD (pmd-ruleset.xml, execution pmd-check на verify в обоих модулях, includeTests=true, валится нарушение любой приоритетности): полные исключения категории, кастомное XPath-правило LiteralFirstInEquals и настройки — в самом ruleset.

Runtime & Tooling

  • Java 17 + Maven (обязательны; wrapper mvnw НЕТ); UTF-8; только Maven — никаких Gradle/Ant. Инструменты (Java/Maven/Node/Python) ставит project-local mise (бинарь в .mise/, вне системы), версии пинятся в корневом mise.toml; ежедневный запуск — ./mise.sh.
  • Версии зависимостей — только в корневом pom.xml (properties + dependencyManagement), новые — latest stable; закреплённый список — docs/agent/repo-map.md. Maven-зависимости — через Nexus maven-central: локально ~/.m2/settings.xml (файл вне репо), CI/Containerfile — .ci/maven-settings.xml + MAVEN_MIRROR_URL.
  • Фронт: Node из engines vite/oxlint, npm ci с закоммиченным package-lock.json, TS strict нигде не включён. Контейнеры (podman/buildah): FROM только FQDN, хостовые прокси-переменные обнулять на самой команде (RUN/HEALTHCHECK), DOCKER_BUILDKIT=0 обязателен, fontconfig рантайму не нужен (глифы — fontbox).
  • Локальная проверка одна: mvn clean verify (тесты + PMD + JaCoCo). Форматтеров и checkstyle для Java нет; статический линтер — PMD. Исполняемый jar проверять только java -jar; нюанс BundledFontsTest (file:-протокол classpath) — docs/agent/repo-map.md.
  • Git: origin git.pjandro.ru:pjandro/java-word-pdf; защищённые ветки — main, master, dev. Все правки — через PR в дефолтную ветку; push — завершающим шагом задачи, только после ./mise.sh run verify.
  • Прод-координаты и креды в коммитимые файлы не попадают (ни IP, ни хостов, ни пользователей, ни ключей): стенд — Gitea Actions Variables, креды — Secrets; workflow-файлы ссылаются только на ${{ vars.* }}/${{ secrets.* }} (список — GITEA-vars.md). Локальный .env (gitignored) — только для compose.yml.

CI/CD (Gitea Actions)

pr.yml (PR checks): job java (mvn -B -s .ci/maven-settings.xml clean verify через Nexus) + coverage-сводка и комментарий в PR, job web (npm ci → build → lint). main.yml: java/web → images-app/images-web (build+push в Nexus, теги prod + sha-<7>) → deploy (SSH, рендер прод-конфигов, гейты healthy) → autotests → rollback при провале. Нарратив — docs/agent/ci-cd.md.

Защита ветки main: required-контексты — PR checks / java (pull_request), PR checks / web (pull_request) (deploy/autotests в список не включать — на PR не бегут). Смена лимитов стенда = правка Variables, PR не нужен.

Testing & QA

  • Гейты: PMD maven-pmd-plugin 3.28.0 (includeTests=true) и JaCoCo 0.8.15 (jacoco:check на verify) — LINE 0.90 (оба модуля), BRANCH 0.85 (только core); отчёт report раньше check (target/site/jacoco/). Механика — docs/agent/repo-map.md. Плотность покрытия держат тесты, а не заглушки.
  • Стек: JUnit 6 (org.junit.jupiter), только Assertions — Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest containsString в andExpect; тестовые классы package-private, зеркалят main-пакеты. Счётчики — docs/agent/testing.md.
  • PDF сравнивается текстом, не растеризацией: PDFBox 3, PDFTextStripper; негативные маркеры — .notdef (#) и Helvetica; текст нормализуется по пробелам (norm). Пиксельные проверки — только в юнитах chart-пейнтеров (допуски assertRatio < 0.06 / < 0.10). Детали — docs/agent/repo-map.md.
  • Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары XxxNormalizerTest↔тест-в-конвейере воспроизводятся грепом по этим ссылкам; исключения — docs/agent/testing.md.
  • Фикстуры — только закоммиченные samples/*.docx (13) + samples/*.doc (12), в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (assertSame) + неприкосновенность частей вне word/*.xml.
  • App-тесты: @SpringBootTest + @AutoConfigureMockMvc (Boot 4: org.springframework.boot.webmvc.test.autoconfigure); четыре набора свойств = четыре контекста (отдельные классы, не @Nested); ConversionServiceTest/ApiExceptionHandlerTest — без Spring. Core-юниты Spring не поднимают; app-тесты проверяют только HTTP-код/заголовки/текст ошибки. Детали — docs/agent/testing.md.
  • Жизненный цикл: только @Test; исключения — два @BeforeAll (прогрев шрифтов) и @AfterEach drainWorker в ConversionTimeoutTest. Ни @Nested, ни @ParameterizedTest, ни @Disabled, ни assertAll.
  • Идиомы загрузки фикстур: core — classloader без ведущего слэша, app — class-relative со слэшем (core test-jar). Синтетика: docx — ZipOutputStream, .doc — крафт POIFSFileSystem.
  • Сообщения ассертов — по-русски и с наблюдаемым значением; сравнение строк литерал-слева ("%PDF".equals(...), PMD LiteralFirstInEquals); контракт идентичности — assertSame/assertNotSame. Общих test-util-классов нет: хелперы (norm, pdfText, assertRatio) намеренно продублированы.
  • Прод-автотесты: pytest + requests; под маркером needs_key без ключа SKIP; конфигурация стенда только env (WORDPDF_BASE_URL обязателен).
  • mvn test не запускает PMD и JaCoCo-гейты (оба на verify) — «зелёное» состояние проверяется mvn clean verify. mvn -pl wordpdf-app без -am падает: app зависит от core test-jar.