# 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`) Нормативный источник — [MS-DOC] в `docs/standards/doc/`, общее OLE-окружение ([MS-CFB], [MS-OLEPS], [MS-ODRAW]) в `docs/standards/binary/`, [MS-ODRAWXML] в `docs/standards/ooxml/`, ссылки — с номерами секций. Новых 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], любой брак → `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)| Перечень остатков моста — `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-бинарники вычищаются, `` → плейсхолдер-картинка; `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` и **не потокобезопасно**; головой очереди на старте стоит `WordPdfConverter.warmup()` (первый запрос после деплоя — за прогретым ядром, ~0,1–0,4 с вместо 1,4–1,9 с); лимиты входа — только конфигурация сервера (`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/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) только для них — медиа документов остаются в штатном docx4j-режиме. Пейнтеры со всеми калибровками, `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'ом как раньше (замер: реестр без гейта 114 шрифтов, с гейтом 0 + 7 symbol). - Единственный 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/`|нормативные спецификации форматов Word/Excel/PowerPoint (навигатор — `README.md`): `ooxml/` (ECMA-376 + XSD + MS-OI29500/MS-ODRAWXML), `binary/` (OLE2-окружение), `doc/` ([MS-DOC]), `docx/` (валидатор фикстур), `xls/` ([MS-XLS]), `xlsx/` ([MS-XLSX]), `ppt/` ([MS-PPT]), `pptx/` (навигатор PresentationML)| | `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`. ```bash ./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://: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://: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`. Плотность покрытия держат тесты, а не заглушки. - Счётчики: 59 тестовых класса / 891 тест (core 53/848, 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`.