Files
java-word-pdf/AGENTS.md
T
Pjandro de9995bba3
PR checks / web (pull_request) Successful in 43s
PR checks / java (pull_request) Successful in 1m51s
Main: tests, deploy, autotests / web (push) Successful in 58s
Main: tests, deploy, autotests / images-web (push) Successful in 31s
Main: tests, deploy, autotests / java (push) Successful in 1m38s
Main: tests, deploy, autotests / images-app (push) Successful in 49s
Main: tests, deploy, autotests / deploy (push) Failing after 2m46s
Main: tests, deploy, autotests / autotests (push) Has been skipped
Main: tests, deploy, autotests / rollback (push) Successful in 2m20s
core: chart-PNG без docx4j-декода и без пересжатия CR-029 (−23% alloc chart-документов)
DrawingPreRenderer.swapForPicture вставляет media-часть вручную
(newPartForContentType → setBinaryData → rels.addPart, имена
/word/media/chart-*): createImagePart писал temp-файл и декодировал
PNG обратно ради mime/размеров, которые нам и так известны.
ChartImageHandler (foSettings.setImageHandler) возвращает null из
compressedVariant для chart-* — «Compress Pictures» не ресемплит и не
декодирует наши 300-dpi растры; медиа документов остаются в штатном
docx4j-режиме. Замер (25 фикстур × 6 прогонов): chart-types.docx
657→507 МБ alloc (тёплый), суммарно 11640→10604 МБ, прочие 23 файла
±0%; ретеншн не изменился (144 MiB после GC), temp-файлов 0.
Регрессии: chartMedia_notDownsampled, DrawingPreRendererTest,
ChartImageHandlerTest.
2026-11-02 21:36:10 +00:00

32 KiB
Raw Blame History

Repository Guidelines

Project Overview

Конвертер .docx/.doc → .pdf на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Бинарный .doc (Word 97-2003) — собственный мост MS-DOC/MS-CFB internal/doc → in-memory .docx → тот же конвейер. Java 17, только Maven.

Три независимых модуля:

  • wordpdf-core — библиотека конвертации (docx4j → XSL-FO → Apache FOP), шрифты и chart/SmartArt-движок внутри.
  • wordpdf-app — REST API (Spring Boot 4.1.1), единственный public-класс — WordPdfApplication.
  • wordpdf-web — SPA (React 19 + TS + Vite + Tailwind), собирается npm, деплоится отдельно от Maven.

Вход стека — gateway-контейнер nginx (:9010 prod-like compose / :9011 dev), не 8080. Авторитетны этот файл, docs/agent/ и код.

Architecture & Data Flow

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

Порядок фиксирован, местами менять нельзя (WordPdfConverter.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 — единый предикат):

# Шаг Что делает
0 DependencyGuard.check() API-проба commons-compress ≥ 1.25.0
1 BundledFontMapper → BundledFonts.init() → restrictToBundled() инициализация шрифтов — инвариант
2 DocxRewritePipeline.STEP → OleObjectNormalizer → WordprocessingMLPackage.load один zip-проход правил 1–10 + условная OLE-вычистка (правило 11)
3 pkg.setFontMapper(mapper) привязка шрифтов документа к бандл-TTF
3.5 DrawingPreRenderer.run(pkg, options) c:chart/dgm:relIds → PNG 300 dpi → pic:pic
4 FOSettings + FopFallbackFonts.declare в FOP-конфиг — все бандл-семейства
4.25 LayoutPostRenderer.register кастомный FORenderer: post-FO padding-компенсация таблиц
4.5 setCustomXsltTemplates(VendoredXslt.TEMPLATES) вендорный xslt/docx2fo.xslt с AUDIT-FIX-патчами (инвариант)
5–6 getFopFactoryBuilder/getFOUserAgent → Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL) XSL-FO → PDF; непустой title → заголовок PDF
7 finally → deleteEmbeddedFontTempFiles() в docx4j 17.x OpcPackage.close() нет

Полные обоснования шагов и правила подсчёта страниц — docs/agent/pipeline.md. Вход валидируется до convertToStream: WordPdfValidator.validate(bytes, options) (размер → подпись zip/CFB → контейнер → страницы); для .doc — checkPageCountDoc по сырым байтам до конвертации.

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

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

Класс Семантика (полные байтовые раскладки — docs/agent/doc-bridge.md)
CfbReader, FibHeader, PieceTable CFB ([MS-CFB], любой брак → ValidationException) + FIB (§2.4.1: fWhichTblStm, пары fc*) + текст §2.9.135 (compressed CP1252 / UTF-16LE)
Grpprl, ChpxIndex, PapxIndex, PrcData sprm'ы CHPX/PAPX/TAP/Sepx (§2.6.2) + FKP-индексы (§2.4.6; bOffset=0 — дефолт с сохранением границы рана) + разворот grpprl вне FKP (§2.9.210)
Styles, FontTable, Lists STSH-цепочки base-first, символьные stk=3 → charChain (§2.9.271) + ftc→w:rFonts (§2.9.147) + PlfLst/PlfLfo → word/numbering.xml (§2.9.200/.201)
Tables, Sections, Headers TAP → сетка/границы/w:jc/vAlign/w:tcMar (§2.6.3; битый TDefTable → плоские абзацы) + секции (PlcfSed §2.8.26: continuous/landscape/колонтитуки/колонки/titlePage) + Plcfhdd → headerN.xml/footerN.xml
SummaryInfo, OfficeArt кэш PageCount [MS-OLEPS] (offset'ы относительны начала PropertySet) + BLIP → PNG/JPEG/DIB, EMF/WMF/PICT → пропуск + warn
DocToDocx, DocxWriter оркестратор + DocxBody (раны/pPr/табличный автомат 0x07/TTP → docx-XML) + мульти-частный zip (document/numbering/hdr/ftr/media)

Перечень остатков моста — docs/agent/doc-bridge.md.

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

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

  1. StrictOoxmlNormalizer — strict-OOXML → transitional (w:start/w:end → w:left/w:right, проценты ×1000, jc val="end").
  2. DocxOnOffNormalizer — w:val="off"/"on" → "false"/"true".
  3. SymbolFontNormalizer — PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans.
  4. FieldNormalizer — fldChar PAGE/NUMPAGES/SECTIONPAGES → w:fldSimple.
  5. InvisibleCharNormalizer — вырезание невидимых/bidi-символов из w:t.
  6. GlyphCoverageNormalizer — резка ранов по покрытию глифов, w:rFonts (иначе FOP рисует «#»).
  7. TableIndentNormalizer — w:jc center/right + w:tblInd → абсолютный w:tblInd.
  8. NumberingSuffixNormalizer — w:suff="space" → пробел в w:lvlText.
  9. HiddenTextNormalizer — вырезание скрытых ранов (w:vanish), guard защищённого содержимого.
  10. RubyNormalizer — руби: база → обычные раны, надстрочница вырезается.
  11. OleObjectNormalizer — OLE-бинарники вычищаются, <w:object> → плейсхолдер-картинка; errorOnOle → 422.

Полные правила с номерами секций и guard'ами, инвариант про mc-preprocessor.xslt (ломать собственный рерайт URI нельзя) — docs/agent/pipeline.md.

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

Единственный эндпоинт POST /api/v1/convert: multipart-поле file + факультативные query/form-параметры errorOnCharts/errorOnSmartArt/errorOnOle (дефолты — WordPdfSettings.ERROR_ON_*). Ответ — application/pdf, Content-Disposition: attachment; filename*=UTF-8''…. Имя файла — ConversionService.safeBaseName; расширение .docx/.doc проверяет ConvertController (текст ошибки 400 — контракт с фронтом). Error-флаги диаграмм/SmartArt/OLE на .doc не срабатывают (BLIP-плейсхолдеры → картинки) — описано в @Operation. Полный текст — docs/agent/repo-map.md.

Ситуация HTTP Класс
Некорректный вход (размер, подпись zip/CFB, контейнер, страницы) 400 ValidationException (наследник ConversionException)
Error-флаг на диаграммы/SmartArt/OLE 422 DrawingRejectedException (core-DrawingFoundException, Kind {CHARTS, SMARTART, OLE})
Ошибка ядра/рендера 500 ConversionFailedException
Очередь переполнена 503 ConversionRejectedException
Дольше wordpdf.convert-timeout (2m) 504 ConversionTimeoutException
Превышен multipart-лимит 413 MaxUploadSizeExceededException
Неизвестный путь / метод / content-type 404 / 405 / 415 NoResourceFoundException / HttpRequestMethodNotSupportedException / HttpMediaTypeNotSupportedException
Битый error-флаг, нет части/параметра 400 MethodArgumentTypeMismatchException, MissingServletRequestPartException, MissingServletRequestParameterException

Тело ошибки — {"error": …}. Текст 422 — контракт с фронтом, показывается дословно: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты». ApiExceptionHandler не видит ошибок фильтров — 401 пишет сам ApiKeyFilter.

  • Ключ доступа: X-API-Key ↔ wordpdf.api-key (пустое = выключено); без ключа открыты только OPEN_PREFIXES, пути с точечными сегментами — никогда. Механика ApiKeyFilter — docs/agent/repo-map.md.
  • Очередь и лимиты: конвертации сериализованы однопоточным ThreadPoolExecutor (переполнение → 503) — ядро мутирует глобальный PhysicalFonts и не потокобезопасно; лимиты входа — только конфигурация сервера (wordpdf.max-mb/max-pages, SpEL-дефолты из WordPdfSettings; ≤ 0 → IllegalStateException на старте; параметрами запроса не переопределяются, в application.properties не объявлены). Подробности — docs/agent/repo-map.md.
  • SPA: вся сеть в wordpdf-web/src/api.ts (компоненты fetch не вызывают); ключ в localStorage (wordpdf.api.key), экран ApiKeyGate показывается только когда probeApiKey() подтвердил требование ключа; base — VITE_BASE (дефолт /, CORS не нужен); три error-флага (дефолт — выключены), DropZone .docx,.doc. Полный текст — docs/agent/repo-map.md.

Chart/SmartArt-движок (internal/chart)

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

Java2D → PNG: ChartRenderer.DPI = 300, потолок растра MAX_PIXELS = 16_777_216 (fitDpi понижает эффективный dpi). Защитные лимиты: ChartSpec.MAX_POINTS = 100_000, ChartRenderer.MAX_TICKS = 1000, DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000 — деградация «объект остаётся как есть / удалён + warn», не OOM.

chart-PNG вставляются media-частями вручную (DrawingPreRenderer.addChartMedia, имена /word/media/chart-*, без docx4j-decode'а createImagePart); ChartImageHandler отключает docx4j «Compress Pictures» (CR-029) только для них — медиа документов остаются в штатном docx4j-режиме.

Пейнтеры со всеми калибровками, autoTitleDeleted/автозаголовки, Combo-семантика, защитные обходы JAXB — docs/agent/chart.md.

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

  • docx4j.convert.out.fo.gsubFeatures=false — static-блок WordPdfConverter. Иначе FO невалиден → WordLayoutFixups молча отказывает всем фиксам → FOP падает на docx4j-baseline.
  • Единственный XSL-FO-стилист — вендорный wordpdf-core/src/main/resources/xslt/docx2fo.xslt (копия docx2fo.xslt из docx4j-export-fo 17.3.2 + два AUDIT-FIX-патча: w:rPr/w:position → baseline-shift, полупункты, Part 1 §17.3.2.24 — docx4j position игнорирует; AUDIT-FIX-2 — шаблоны w:moveFrom/w:moveTo/w:bdo/w:dir (plain-text passthrough, move-правки не раскрашиваются, bidi — принятая деградация), иначе их ловит catch-all match="*" и текст теряется; руби тут не чинится — схема docx4j не биндит w:rubyBase/w:rt, их разбирает правило 10 в байтах). Дрейф-гейт WordPdfConverterTest#vendoredXsltTracksJarCopy: вне AUDIT-FIX-регионов вендорная копия обязана быть побайтно равна стилисту из jar'а (сравнение с возвратом AUDIT-FIX-региона к исходному вызову createBlockForRPr и удалением региона AUDIT-FIX-2) — при апгрейде docx4j перевендорить и перенести патчи. setCustomXsltTemplates принимает предкомпилированный Templates (getTemplates кастит Object→Templates, поток кидает CCE).
  • slf4j-simple обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия noLoggingWarningInPdf). Приложение исключает его из зависимости ядра — логи ведёт logback.
  • FOP — форк org.docx4j:docx4j-fo-renderer* 2.11-docx4j.6 (транзитив от docx4j-export-fo 17.3.2, в pom не пинится; пакеты org.apache.fop.*). w:renderers в docx4j 17.x содержит несколько w:renderer (по mime) — FopFallbackFonts берёт тот, у которого mime application/pdf, иначе первый со шрифтами. Оригинал docx2fo.xslt — в jar docx4j-export-fo, в конвейере используется вендорная копия (bullet «Единственный XSL-FO-стилист»).
  • Порядок инициализации шрифтов: new BundledFontMapper() → BundledFonts.init() → restrictToBundled() — до load(). BundledFonts.init() идемпотентен и synchronized, распаковывает TTF во временный каталог wordpdf-fonts-* (deleteOnExit на файлы и на каталог). dropNonBundled() чистит глобальный реестр PhysicalFonts от всего, что вне бандла.
  • PhysicalFonts — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером.
  • Страницы в валидаторе = max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1); детальные правила StAX-подсчёта (attrLocal, continuous, колонтитуки, стриминговый проход) — docs/agent/pipeline.md.
  • Не чинить (невозможности FOP/docx4j и ограничения эталона): 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/)

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

Key Directories

Путь Назначение
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ публичный API; fonts/ (бандл+глиф-движок), internal/ (нормализаторы, пайплайн), internal/doc/ (мост), internal/chart/ (диаграммы)
wordpdf-core/src/main/resources/ fonts/ (30 TTF), xslt/docx2fo.xslt (вендорный стилист), slf4j-simple.properties
wordpdf-core/src/test/resources/ samples/ (25 закоммиченных фикстур: 13 .docx + 12 .doc), geom/ (presetShapeDefinitions.xml, тесты)
wordpdf-app/ REST API (10 классов, public только WordPdfApplication)
wordpdf-web/ SPA: src/api.ts (вся сеть) + компоненты
корневые Containerfile, compose.yml, compose.dev.yml, gateway/nginx.conf контейнеры; единственный вход — gateway (:9010/:9011)
.gitea/workflows/ Gitea Actions (pr.yml, main.yml) — нарратив job'ов docs/agent/ci-cd.md
docs/standards/ нормативные спецификации OOXML/.doc + XSD + validate-fixtures.py
docs/agent/ глубокие справочники (когда читать — по имени файла)
prod-autotests/ прод-автотесты (pytest, конфиг только env)

Полная таблица (.env.example, GITEA-vars.md, develop/ — рабочие материалы, не фикстуры) и «Important Files» — docs/agent/repo-map.md.

Development Commands

Бутстрап toolchain: sh bootstrap.sh (Windows: bootstrap.ps1) — project-local mise в ./.mise/ (в систему ничего не ставится), дальше — ./mise.sh / .\mise.ps1. Полный текст — docs/agent/repo-map.md.

./mise.sh run verify                      # = mvn clean verify: тесты + PMD + гейты JaCoCo (обязательный гейт перед push)
mvn clean verify                          # то же самое; mvnw НЕТ — только системный Maven
mvn -pl wordpdf-app -am package           # исполняемый jar бэкенда (-am обязателен: app берёт test-jar core)
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-стенд: http://<LAN-IP хоста>:9011, без ключа, springdoc вкл; --force-recreate ОБЯЗАТЕЛЕН: без него podman-compose пересобирает образ, но контейнеры оставляет на старом (проверено: свежий image, а в app крутится jar прошлой сборки)
./mise.sh run prod-tests                 # прод-автотесты: pip install + pytest -q . в prod-autotests/
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx   # XSD-валидация фикстур (lxml)

Задачи mise: verify, app-package, app-run, web-* (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.

Пересоздание фикстур (POI) и перевендоривание стилиста после апгрейда docx4j — команды в docs/agent/repo-map.md.

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

Code Conventions & Common Patterns

  • Классы final, приватный конструктор, только static (stateless, DI нет; конфигурация — Docx4jProperties + classpath-ресурсы). Исключения — экземпляры по природе: BundledFontMapper (extends BestMatchingMapper), обёртка цветов DrawMlColor (instance, но не наследник docx4j) и Spring-компоненты wordpdf-app.
  • Нормализаторы — единый контракт internal/DocxNormalizer + константа STEP; порядок цепочки — см. «Нормализаторы», правятся только word/*.xml, package-private хук rewrite (null при отсутствии изменений). Полный текст — docs/agent/repo-map.md.
  • Ошибки публичного API — только ConversionException extends RuntimeException; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения.
  • Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx) — новый фикс оформлять так же.
  • Константы UPPER_SNAKE с числовыми эталонными значениями (PIE_DEPTH, MAX_PAGES); начертания V_REGULAR/V_BOLD/...; модели — record; размеры в chart — в пунктах, растр × DPI/72.
  • Классы в internal — public (иначе родительский пакет не вызвал бы), публичные члены наружу ограничены (normalize/STEP/declare/run/check/register, перечни — docs/agent/repo-map.md); в wordpdf-app всё package-private кроме WordPdfApplication.
  • Тестовые методы: регрессионные — объект_условие через underscore (ruPlain_cyrillicAndStyles, checkInput_bytesOverLimit, noKey_rejected); чистые юниты — camelCase (pageFieldBecomesFldSimple, splitsRunForUncoveredGlyph); оба стиля разрешает PMD-паттерн junit5TestPattern (^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$).
  • PMD (pmd-ruleset.xml, execution pmd-check на verify, includeTests=true — тесты тоже сканируются, валится нарушение любой приоритетности): полные исключения категории и настройки правил — в самом ruleset.

Runtime & Tooling Preferences

  • Java 17 + Maven (обязательны; wrapper mvnw нет — только системный Maven); UTF-8. Только Maven — никаких Gradle/Ant. Java/Maven/Node/Python для локальной разработки ставит project-local mise (бинарь в .mise/, вне системы), версии пинятся в корневом mise.toml (java = temurin-17, maven = 3.9.16, node = 24, python = 3.15), ежедневный запуск — ./mise.sh / .\mise.ps1. Bootstrap качает mise 2026.10.19 → ./.mise/bin, затем mise trust → mise install → mise run web-install.
  • Версии зависимостей — только в корневом pom.xml (properties + dependencyManagement); новые зависимости — latest stable.
  • Зависимости Maven — через зеркало Nexus maven-central: локально ~/.m2/settings.xml (литеральный URL, файл вне репо), CI/Containerfile — .ci/maven-settings.xml + MAVEN_MIRROR_URL (Variable / build-arg).
  • Фронт: Node из engines vite/rolldown/oxlint, npm ci с закоммиченным package-lock.json, TS strict нигде не включён. Контейнеры (podman/buildah): FROM только FQDN, хостовые прокси-переменные обнулять на самой команде (RUN/HEALTHCHECK), fontconfig рантайму не нужен (глифы — fontbox). Полные bullet'ы — docs/agent/repo-map.md.
  • Локальная проверка одна: mvn clean verify (тесты + PMD + JaCoCo). Форматтеров и checkstyle для Java нет; статический линтер — PMD.
  • Исполняемый jar бэкенда проверять только java -jar — тесты идут по classpath и repackage-специфику не видят; нюанс BundledFontsTest (file:-протокол classpath) — docs/agent/repo-map.md.
  • Git: origin git.pjandro.ru:pjandro/java-word-pdf, main/dev защищены (правила глобального AGENTS.md; локально только main).
  • Push всегда в конце задачи: git push (и следующий за ним PR) — завершающий шаг, только когда вся реализация готова и обязательные гейты пройдены (./mise.sh run verify). Промежуточные push запрещены; коммиты в ходе работы — по правилам глобального AGENTS.md.

CI/CD (Gitea Actions)

pr.yml (PR checks): job java (mvn clean verify через зеркало Nexus) + coverage-комментарий в PR, job web (npm ci → build → lint). main.yml: java/web → образы images-app/images-web в Nexus → deploy (SSH, рендер прод-конфигов, гейты healthy) → autotests → rollback при провале. Нарратив job'ов и деплоя — docs/agent/ci-cd.md.

Правило: координаты прода и креды в коммитимые файлы не попадают — ни внутренние IP, ни SSH-пользователи/логины, ни хосты, ни директория деплоя, ни ключи/токены/пароли. Координаты стенда — Gitea Actions Variables (DEPLOY_HOST, DEPLOY_USER, DEPLOY_DIR, WORDPDF_BASE_URL, WORDPDF_MAX_PAGES, WORDPDF_MAX_MB, REGISTRY, PIP_INDEX_URL, MAVEN_MIRROR_URL), креды — Secrets (DEPLOY_SSH_KEY, DEPLOY_KNOWN_HOSTS, WORDPDF_API_KEY, REGISTRY_USER, REGISTRY_PASSWORD); workflow-файлы ссылаются на них только ${{ vars.* }}/${{ secrets.* }}. Смена лимитов = правка Variables, PR не нужен. Защита ветки main: required-контексты PR checks / java (pull_request), PR checks / web (pull_request) (deploy/autotests в список НЕ включать — на 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 (при провале порога отчёт уже на диске). Механика argLine/prepare-agent/jacoco.skip — docs/agent/repo-map.md. Плотность покрытия держат тесты, а не заглушки.
  • Счётчики: 57 тестовых класса / 886 теста (core 51/843, app 6/43; разбивка — docs/agent/repo-map.md). JUnit 6, только Assertions (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest org.hamcrest.Matchers.containsString в andExpect); тестовые классы package-private, зеркалят main-пакеты.
  • PDF сравнивается текстом, не растеризацией: PDFBox 3 (Loader.loadPDF) — PDFTextStripper (пер-странично), processTextPosition для шрифта символа, обход ресурсов страниц для встроенных шрифтов (EAAAAA+Carlito-Bold), счётчик картинок (imageCount/distinctImageCount — SMask игнорируется). Негативные маркеры: assertFalse(text.contains("#")) (.notdef), assertFalse(font.startsWith("Helvetica")). Текст нормализуется по пробелам (norm).
  • Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары XxxNormalizerTest↔тест-в-конвейере воспроизводятся грепом по этим ссылкам; исключения (крафт POIFS, синтетика, app-регрессии) — docs/agent/testing.md.
  • Фикстуры — только закоммиченные samples/*.docx + samples/*.doc, в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (assertSame) + неприкосновенность частей вне word/*.xml.
  • App-тесты: @SpringBootTest + @AutoConfigureMockMvc; четыре набора свойств = четыре кэшированных контекста (отдельные классы, не @Nested); ConversionServiceTest/ApiExceptionHandlerTest — без Spring-контекста.
  • Справочник: фикстуры и их смысл, юниты моста/нормализаторов/app, пиксели и стенд без fontconfig, регрессивные записи без javadoc-ссылок — docs/agent/testing.md.