Files
java-word-pdf/AGENTS.md
T
Pjandro 3dd770c542
PR checks / web (pull_request) Successful in 38s
PR checks / java (pull_request) Failing after 1m56s
docs: AGENTS.md — сводный репозиторный гайд по фактам дерева
Пересобран корневой AGENTS.md по результатам параллельного исследования
(core src, tests, build/config, app/web/docs). Сохранены все разделы и
инварианты, добавлены точные счётчики и недостающие детали, полезные
AI-ассистенту (идиомы загрузки фикстур по модулям, жизненный цикл тестов,
правила PMD/JaCoCo, карта HTTP-контракта).

Исправлен фактический дрейф в соседних справках (docs/agent/* объявлены
авторитетными наравне с AGENTS.md):
- счётчики тестов: 891 → 893 (core 848 → 849, app 43 → 44; ApiExceptionHandlerTest = 5);
- internal/chart: 17 → 18 классов, public ещё и ChartImageHandler;
- wordpdf-app: 10 → 11 классов (5 классов исключений);
- константа STEP: 8 → 9 из 10 rewrite-нормализаторов (есть у HiddenTextNormalizer);
- docs/standards: шесть → восемь каталогов; в перечне docs/agent добавлен repo-map.

Проверено: mvn clean verify — 893 теста, PMD (includeTests) и гейты JaCoCo
(LINE 0.90 обоих модулей, BRANCH 0.85 core) зелёные.
2026-11-07 03:19:01 +00:00

41 KiB
Raw Blame History

Repository Guidelines

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 — библиотека конвертации: docx4j → XSL-FO → FOP; бандл шрифтов, chart/SmartArt-движок, мост .doc. 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-реактора, собирается npm и деплоится отдельным образом.

Единственный вход стека — gateway-контейнер nginx (:9010 prod-like compose.yml, :9011 dev compose.dev.yml), не 8080. Авторитетны этот файл, docs/agent/ и код; решения о форматах — по спецификациям из docs/standards/ (ссылка на секцию обязательна).

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, иначе ConversionException с инструкцией
1 new BundledFontMapper() → BundledFonts.init() → restrictToBundled() инициализация шрифтов — инвариант (объяснение в docs/agent/pipeline.md)
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 new FOSettings(pkg) + FopFallbackFonts.declare в FOP-конфиг — все бандл-семейства
4.25 LayoutPostRenderer.register кастомный FORenderer: post-FO padding-компенсация таблиц
4.5 foSettings.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() нет

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

Мост .doc → .docx (internal/doc, 18 классов)

Нормативный источник — [MS-DOC] в docs/standards/doc/, общее OLE-окружение ([MS-CFB], [MS-OLEPS], [MS-ODRAW]) — docs/standards/binary/. Новых runtime-зависимостей нет (POI/POIFS — test-scope). Публичные точки: DocToDocx.convert(byte[]) и DocToDocx.countPages(byte[]); общий разбор — 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], любой брак → ConversionException) + 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)

Нормализаторы (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. 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 (собственный рерайт strict-URI ломать нельзя) — docs/agent/pipeline.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-флаги диаграмм/SmartArt/OLE на .doc не срабатывают (BLIP-плейсхолдеры → картинки) — описано в @Operation. Полный текст — docs/agent/repo-map.md.

Ситуация HTTP Класс
Некорректный вход (размер, подпись zip/CFB, контейнер, страницы) 400 ValidationException (наследник ConversionException)
Ошибка уровня запроса (нет файла, чужое расширение, размер, нечитаемая часть) 400 BadRequestException
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 (/actuator/, /swagger-ui, /v3/api-docs), пути с точечными сегментами — никогда. Механика ApiKeyFilter — docs/agent/repo-map.md.
  • Очередь и лимиты: конвертации сериализованы однопоточным ThreadPoolExecutor (QUEUE_CAPACITY = 16, переполнение → 503) — ядро мутирует глобальный PhysicalFonts и не потокобезопасно; головой очереди на старте стоит WordPdfConverter.warmup(); лимиты входа — только конфигурация сервера (wordpdf.max-mb/max-pages, SpEL-дефолты из WordPdfSettings; ≤ 0 → IllegalStateException на старте; параметрами запроса не переопределяются, в application.properties намеренно не объявлены).
  • SPA: вся сеть в wordpdf-web/src/api.ts (компоненты fetch не вызывают); ключ в localStorage (wordpdf.api.key), экран ApiKeyGate показывается только когда probeApiKey() подтвердил требование ключа (признак открытого сервера — 405, не 200/404); base — VITE_BASE (дефолт /, CORS не нужен); три error-флага (дефолт — выключены), DropZone .docx,.doc.

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

Нормативный источник правок — ECMA-376 (docs/standards/ooxml/: графики §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) только для них — медиа документов остаются в штатном режиме.

Пейнтеры со всеми калибровками, 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 и docx4j.fonts.discoverJarFonts.enabled=false — static-блок WordPdfConverter: BestMatchingMapper (static) сканирует системные шрифты и jar'ы classpath'а, а BundledFonts.restrictToBundled() перед каждой конвертацией всё найденное выбрасывает (~100–140 мс впустую на JVM). discoverJarFonts("fonts-symbol") свойством не гейтится — символ-шрифт регистрируется и снимается restrict'ом как раньше.
  • Единственный 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; AUDIT-FIX-2 — шаблоны w:moveFrom/w:moveTo/w:bdo/w:dir, иначе их ловит catch-all match="*" и текст теряется). Дрейф-гейт WordPdfConverterTest#vendoredXsltTracksJarCopy: вне AUDIT-FIX-регионов вендорная копия обязана быть побайтно равна стилю из jar'а — при апгрейде docx4j перевендорить и перенести патчи. setCustomXsltTemplates принимает предкомпилированный Templates (каст 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, в pom не пинится; пакеты org.apache.fop.*). FopFallbackFonts берёт w:renderer с mime application/pdf, иначе первый со шрифтами.
  • Порядок инициализации шрифтов: new BundledFontMapper() → BundledFonts.init() → restrictToBundled() — до load(). init() идемпотентен и synchronized, распаковывает TTF во временный каталог wordpdf-fonts-* (deleteOnExit на файлы и каталог); dropNonBundled() чистит глобальный реестр PhysicalFonts от всего, что вне бандла.
  • PhysicalFonts — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером. warmup() обязан идти тем же сериализующим потоком.
  • Страницы в валидаторе = 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/)

9 семейств: 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). GlyphFont читает TTF напрямую с classpath через fontbox — без java.awt.Font (нужен fontconfig на хосте).

Key Directories

Путь Назначение
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ публичный API: WordPdfConverter, WordPdfValidator, WordPdfSettings, ConvertOptions, ConversionException/ValidationException/DrawingFoundException
…/wordpdf/fonts/ BundledFonts (реестр/выгрузка TTF), BundledFontMapper (алиасы, self-map), GlyphFont (глиф-движок fontbox)
…/wordpdf/internal/ 11 нормализаторов + DocxRewritePipeline (zip-проход правил 1–10) + OleObjectNormalizer + LayoutPostRenderer + FopFallbackFonts + DependencyGuard + интерфейс DocxNormalizer
…/wordpdf/internal/doc/ мост .doc → .docx (18 классов, детали — docs/agent/doc-bridge.md)
…/wordpdf/internal/chart/ 18 классов Java2D-рендера диаграмм/SmartArt в PNG (public: DrawingPreRenderer.run, ChartImageHandler)
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 (ECMA-376, только в тестах)
wordpdf-app/ REST API (11 классов, public только WordPdfApplication)
wordpdf-web/ SPA: src/api.ts (вся сеть) + src/components/ (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo)
корневые 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/ нормативные спецификации (навигатор — README.md): ooxml/ (ECMA-376 + XSD + MS-OI29500/MS-ODRAWXML), binary/ (OLE2-окружение), doc/ ([MS-DOC]), docx/ (валидатор фикстур), xls/, xlsx/, ppt/, pptx/
docs/agent/ глубокие справочники: pipeline, doc-bridge, chart, render-limitations, testing, ci-cd, repo-map (когда читать — по имени файла)
prod-autotests/ прод-автотесты (pytest, конфиг только env)
develop/ рабочие материалы и эталоны рендера (gitignored) — не фикстуры, в тесты/jar не подключать

Development Commands

Бутстрап toolchain: 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        # app-тест (-am обязателен: app берёт test-jar core)
mvn -pl wordpdf-app -am package           # исполняемый jar бкенда (-am обязателен)
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 ОБЯЗАТЕЛЕН — без него пересобирается образ, а контейнеры остаются на старом
./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 (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.

Пересоздание фикстур (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, 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, 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 — тесты тоже сканируются, валится нарушение любой приоритетности): полные исключения категории, кастомный XPath-правило LiteralFirstInEquals и настройки правил — в самом ruleset.

Important Files

Файл Роль
wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java точка входа библиотеки + static-блок (gsubFeatures, отключение discovery шрифтов) + normalizers(options) (порядок цепочки) + VendoredXslt
wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java валидация входа и lightweight-подсчёт страниц (StAX, без docx4j)
wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java все дефолты ядра (MAX_INPUT_MB = 5, MAX_PAGES = 100, MAX_DECOMPRESSED_MB = 200, MAX_ZIP_ENTRIES = 8192, ERROR_ON_* = false); runtime-конфигурации в ядре нет
wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/DocxRewritePipeline.java единственный zip-проход правил 1–10; порядок вызовов rewrite/rewritePart зафиксирован здесь
wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/doc/DocToDocx.java оркестратор моста .doc (convert/countPages) + вложенный DocxBody
wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/chart/DrawingPreRenderer.java замена диаграмм/SmartArt на PNG; владеет MAX_EXTENT_EMU и деградацией при падении рендера
wordpdf-core/src/main/resources/xslt/docx2fo.xslt единственный XSL-FO-стилист (вендорная копия + AUDIT-FIX-патчи)
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConvertController.java HTTP-слой: presence/расширение/размер → ConvertOptions → ConversionService
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java однопоточная очередь конвертаций + таймаут + прогрев ядра
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiExceptionHandler.java исключение → HTTP-код + {"error": …} (здесь же карта 400/404/405/413/415/422/500/503/504)
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiKeyFilter.java аутентификация X-API-Key; 401 пишет сам
wordpdf-app/src/main/resources/application.properties multipart 100MB (file-size-threshold=2MB — крупные части на диск), wordpdf.convert-timeout=2m, пустой wordpdf.api-key, server.forward-headers-strategy=framework; wordpdf.max-mb/max-pages намеренно отсутствуют
wordpdf-web/src/api.ts весь сетевой слой SPA, хранение ключа, типы ошибок
pom.xml (корень) все версии зависимостей и плагинов (в модулях версии не объявлять)
pmd-ruleset.xml ruleset PMD (код-стиль + unused + NPE-safe equals)
mise.toml версии инструментов и 8 задач
.ci/maven-settings.xml Maven-зеркало Nexus; URL из ${env.MAVEN_MIRROR_URL} (координаты стенда в репо не хранятся)
Containerfile, wordpdf-web/Containerfile multi-stage образы бекенда и SPA
gateway/nginx.conf единственный вход: /api/, /swagger-ui, /v3/api-docs, /actuator → app:8080, остальное → web:80
wordpdf-core/src/test/java/.../SampleDocxGenerator.java, ChartTypesDocxGenerator.java утилиты пересоздания фикстур (main())

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 — ровно как в CI, 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. Закреплено: docx4j 17.3.2, commons-compress 1.28.0, slf4j 2.0.20, Spring Boot 4.1.1, springdoc 3.1.1, JUnit 6.1.3, PDFBox/fontbox 3.0.8, POI 5.5.1 (test), JaCoCo 0.8.15; плагины: compiler 3.16.0, surefire 3.6.0 (-Djava.awt.headless=true), jar 3.5.1, PMD 3.28.0.
  • Зависимости Maven — через зеркало Nexus maven-central: локально ~/.m2/settings.xml (литеральный URL, файл вне репо), CI/Containerfile — .ci/maven-settings.xml + MAVEN_MIRROR_URL (Variable / build-arg).
  • Фронт: 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 — тесты идут по classpath и repackage-специфику не видят; нюанс BundledFontsTest (file:-протокол classpath) — docs/agent/repo-map.md.
  • Git: origin git.pjandro.ru:pjandro/java-word-pdf; защищённые ветки — main, master, dev (локально в репо обычно только main + feature-ветки в работе). Все правки — через PR в дефолтную ветку; push — завершающим шагом задачи, только после ./mise.sh run verify.
  • Прод-координаты и креды в коммитимые файлы не попадают (ни IP, ни хостов, ни пользователей, ни ключей): стенд — 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.* }}. Локальный .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 при провале. Нарратив job'ов и деплоя — 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/). Механика argLine/prepare-agent/jacoco.skip — docs/agent/repo-map.md. Плотность покрытия держат тесты, а не заглушки.
  • Счётчики: 59 тестовых классов / 893 теста (core 53/849 — из них internal/doc/ 17 классов / 225 тестов, internal/chart/ 17 / 271, WordPdfConverterTest 77; app 6/44: ConvertController 23 + ApiKeyFilter 8 + ConversionService 5 + ApiExceptionHandler 5 + ConvertLimits 2 + ConversionTimeout 1). JUnit 6 (org.junit.jupiter), только 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). Пиксельные проверки — только в юнитах chart-пейнтеров (допуски assertRatio < 0.06 / < 0.10, числа зашиты в тесты).
  • Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары XxxNormalizerTest↔тест-в-конвейере воспроизводятся грепом по этим ссылкам; исключения (крафт POIFS, синтетика, app-регрессии) — docs/agent/testing.md.
  • Фикстуры — только закоммиченные samples/*.docx (13) + samples/*.doc (12), в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (assertSame) + неприкосновенность частей вне word/*.xml ([Content_Types].xml).
  • App-тесты: @SpringBootTest + @AutoConfigureMockMvc (Boot 4: org.springframework.boot.webmvc.test.autoconfigure); четыре набора свойств = четыре кэшированных контекста (отдельные классы, не @Nested — @Nested + @TestPropertySource не даёт отдельного контекста); ConversionServiceTest/ApiExceptionHandlerTest — без Spring-контекста. Core-юниты Spring не поднимают; app-тесты не переигрывают семантику конвейера — только HTTP-код/заголовки/текст ошибки.
  • Жизненный цикл: только @Test + два @BeforeAll (прогрев шрифтов в BundledFontsTest, GlyphCoverageNormalizerTest) + @AfterEach drainWorker в ConversionTimeoutTest (дренировать отменённый FOP-рендер — гонка глобального PhysicalFonts). Ни @Nested, ни @ParameterizedTest, ни @Disabled, ни assertAll.
  • Идиомы загрузки фикстур различаются по модулю: core — classloader без ведущего слэша (getResourceAsStream("samples/" + name)), app — class-relative со слэшем (getResourceAsStream("/samples/ru-plain.docx"), ресурсы из core test-jar). Синтетика, когда фикстуры нет: docx — ZipOutputStream по строковому XML, .doc — крафт POIFSFileSystem.
  • Сообщения ассертов — по-русски и с наблюдаемым значением (assertTrue(cond, "нет «Привет, мир!»: " + text)); сравнение строк литерал-слева ("%PDF".equals(...), правило PMD LiteralFirstInEquals); контракт идентичности — assertSame/assertNotSame. Общих test-util-классов в репо нет: хелперы (norm, pdfText, assertRatio) намеренно продублированы по тест-классам.
  • Прод-автотесты: pytest 9.1.1 + requests 2.34.2, 31 проверка (4 открытых + 27 под маркером needs_key → SKIP без ключа); конфигурация стенда только env (WORDPDF_BASE_URL обязателен — без него набор падает, а не подставляет дефолт; WORDPDF_API_KEY/WORDPDF_MAX_PAGES/WORDPDF_MAX_MB/WORDPDF_SAMPLES_DIR — факультативны).
  • mvn test не запускает PMD и JaCoCo-гейты (оба на verify) — «зелёное» состояние проверяется mvn clean verify. mvn -pl wordpdf-app без -am падает: app зависит от core test-jar.
  • Справочник: фикстуры и их смысл, юниты моста/нормализаторов/app, пиксели и стенд без fontconfig, регрессивные записи без javadoc-ссылок — docs/agent/testing.md.