> Роутер: правила, инварианты и команды — здесь; глубокие детали — `docs/agent/*.md`, нормативные форматы — `docs/standards/` (ссылка с номером секции обязательна), пользовательская документация — `README.md`.
## Project Overview
## 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.
Конвертер `.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/` (ссылка на секцию обязательна).
| 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`.
Единственный вход стека — gateway-контейнер nginx (`:9010` prod-like `compose.yml`, `:9011` dev `compose.dev.yml`), **не** 8080. Авторитетны этот файл, `docs/agent/` и код. Полный путеводитель по каталогам, ключевым файлам и командам — `docs/agent/repo-map.md`.
Контракт: `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` её нет вовсе.
Полные правила с номерами секций, guard'ами и инвариантом про `mc-preprocessor.xslt` (собственный рерайт strict-URI ломать нельзя) — `docs/agent/pipeline.md`.
Порядок: шрифты (`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`.
### REST API (`wordpdf-app`, всё package-private кроме `WordPdfApplication`)
## Нормализаторы (`internal/DocxNormalizer`)
Единственный эндпоинт `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`.
Контракт: `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`.
Тело ошибки — `{"error": …}`. Текст 422 — контракт с фронтом, показывается дословно: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты». `ApiExceptionHandler` не видит ошибок фильтров — 401 пишет сам `ApiKeyFilter`.
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`.
- **Ключ доступа**: `X-API-Key` ↔ `wordpdf.api-key` (пустое = выключено); без ключа открыты только `OPEN_PREFIXES` (`/actuator/`, `/swagger-ui`, `/v3/api-docs`), пути с точечными сегментами — никогда. Механика `ApiKeyFilter` — `docs/agent/repo-map.md`.
## REST API (`wordpdf-app`, всё package-private кроме `WordPdfApplication`)
- **Очередь и лимиты**: конвертации сериализованы однопоточным `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`.
- **Текст 422** — контракт с фронтом: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты».
- **Ключ**: `X-API-Key` ↔ `wordpdf.api-key` (пустое = выключено); без ключа открыты только `OPEN_PREFIXES` (`/actuator/`, `/swagger-ui`, `/v3/api-docs`), пути с точечными сегментами — никогда.
- **Очередь и лимиты**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`QUEUE_CAPACITY = 16`, переполнение → 503) — ядро не потокобезопасно; головой очереди на старте стоит `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`.
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) только для них — медиа документов остаются в штатном режиме.
Нормативный источник — ECMA-376 (`docs/standards/ooxml/`: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D, XSD); поведение Word — `ms-oi29500.md`, `ms-odrawxml.md`. Калибровки (камера, `PIE_DEPTH`) меняются только с пиксельными тестами; невалидная фикстура правится, не код.
Пейнтеры со всеми калибровками, `autoTitleDeleted`/автозаголовки, Combo-семантика, защитные обходы JAXB — `docs/agent/chart.md`.
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.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'ом как раньше.
-`docx4j.fonts.discoverPhysicalFonts.enabled=false` и `discoverJarFonts.enabled=false` — static-блок: иначе`BestMatchingMapper` сканирует системные шрифты и jar'ы classpath'а, а`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).
- Единственный 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.
-`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`, иначе первый со шрифтами.
- 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` от всего, что вне бандла.
-`BundledFonts.init()` идемпотентен и `synchronized`, распаковывает TTF в `wordpdf-fonts-*` (`deleteOnExit`); `dropNonBundled()` чистит `PhysicalFonts` от всего, что вне бандла.
-`PhysicalFonts` — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером.`warmup()`обязан идти тем же сериализующим потоком.
-`PhysicalFonts` — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером;`warmup()`идёт тем же потоком.
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; детальные правила StAX-подсчёта (`attrLocal`, `continuous`, колонтитуки, стриминговый проход) — `docs/agent/pipeline.md`.
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; правила StAX-подсчёта — `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 (описанное поведение верно).
-Комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).
### Шрифты (30 TTF + 3 лицензии, SIL OFL, `wordpdf-core/src/main/resources/fonts/`)
## Шрифты (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 на хосте).
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`.
## Key Directories
## Команды
| Путь | Назначение |
Бутстрап: `sh bootstrap.sh` (Windows: `powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1`) — project-local mise в `./.mise/`, дальше — `./mise.sh` / `.\mise.ps1`.
| `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`.
```bash
```bash
./mise.sh run verify # = mvn clean verify: тесты + PMD + гейты JaCoCo (обязательный гейт перед push)
./mise.sh run verify # = mvn clean verify: тесты + PMD + JaCoCo (гейт перед push)
mvn clean verify # то же самое; mvnw НЕТ — только системный Maven
mvn clean verify # то же; mvnw НЕТ — только системный Maven
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест
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 test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am: core test-jar
./mise.sh run web-install|web-build|web-lint|web-dev # npm ci | tsc -b && vite build | oxlint | vite :5173
./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 -f compose.dev.yml up -d --build --force-recreate # dev-стенд :9011, без ключа
./mise.sh run prod-tests # прод-автотесты: pip install + pytest -q . в prod-autotests/
./mise.sh run prod-tests # прод-автотесты в prod-autotests/
Задачи mise (8): `verify`, `app-package`, `app-run`, `web-install`, `web-build`, `web-lint`, `web-dev`, `prod-tests`.
Задачи 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`.
**«Запусти тестовый сервер» (термин пользователя)** = полный dev-стенд, НЕ `java -jar`: `podman-compose -f compose.dev.yml up -d --build --force-recreate`, вход `http://<LAN-IP хоста>:9011` без API-ключа; гейт — контейнеры healthy + корень SPA отвечает 200. `--force-recreate` обязателен: без него контейнеры остаются на старом образе.
Пересоздание фикстур (POI) и перевендоривание стилиста после апгрейда docx4j — команды в`docs/agent/repo-map.md`.
Пересоздание фикстур и перевендоривание стилиста — `docs/agent/repo-map.md`. Деплой: **прод** — на пользовательском LAN-сервере; **перед деплоем/перезапуском прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md`**; пуск — push в `main` или Run workflow, ручных скриптов нет (детали —`docs/agent/ci-cd.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
## Code Conventions & Common Patterns
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе: `BundledFontMapper` (`extends BestMatchingMapper`), `DrawMlColor`, Spring-компоненты `wordpdf-app`.
- Классы `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/**` классы `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу ограничены: `normalize`/`STEP`/`declare`/`run`/`check`/`register`; `rewrite`-хуки — package-private. В`wordpdf-app` всё package-private кроме `WordPdfApplication`; в`internal/doc` публичны только `DocToDocx` и `CfbReader`.
- Нормализаторы — единый контракт `internal/DocxNormalizer` + константа `STEP`; порядок цепочки — см. «Нормализаторы», правятся только `word/*.xml`.
- Нормализаторы — единый контракт `internal/DocxNormalizer` + константа `STEP`; порядок цепочки — см. «Нормализаторы», правятся только `word/*.xml`.
- Ошибки публичного API — только `ConversionException extends RuntimeException` (unchecked); внутренние исключения оборачиваются на границе. В chart — деградация вместо падения. `ValidationException` — исключительная собственность `WordPdfValidator`; не оборачивать его в общий `ConversionException`.
- Ошибки публичного API — только `ConversionException extends RuntimeException` (unchecked); внутренние исключения оборачиваются на границе. В chart — деградация вместо падения. `ValidationException` — собственность `WordPdfValidator`; не оборачивать в общий `ConversionException`.
- DI в `wordpdf-app` — конструкторная инъекция Spring; состояние сервисов `private final`. SPA: единственный источник состояния — `useState` в `App.tsx`, вся сеть — в `api.ts`.
- DI в `wordpdf-app` — конструкторная инъекция Spring; состояние сервисов `private final`. SPA: единственный источник состояния — `useState` в `App.tsx`, вся сеть — в `api.ts`.
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же.
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`).
- Константы UPPER_SNAKE с числовыми эталонными значениями (`PIE_DEPTH`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/V_ITALIC/V_BOLD_ITALIC`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`.
- Константы 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`.
- Логирование: `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]+)*$`).
- Тестовые методы: регрессионные — `объект_условие` через 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.
- PMD (`pmd-ruleset.xml`, execution `pmd-check` на `verify` в обоих модулях, `includeTests=true`, валится нарушение любой приоритетности): полные исключения категории, кастомное XPath-правило `LiteralFirstInEquals` и настройки — в самом ruleset.
## Important Files
## 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`.
| `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/chart/DrawingPreRenderer.java` | замена диаграмм/SmartArt на PNG; владеет `MAX_EXTENT_EMU` и деградацией при падении рендера |
| `wordpdf-core/src/main/resources/xslt/docx2fo.xslt` | единственный XSL-FO-стилист (вендорная копия + AUDIT-FIX-патчи) |
- Локальная проверка одна: `mvn clean verify` (тесты + PMD + JaCoCo). Форматтеров и checkstyle для Java нет; статический линтер — PMD. Исполняемый jar проверять только `java -jar`; нюанс `BundledFontsTest` (`file:`-протокол classpath) — `docs/agent/repo-map.md`.
-Исполняемый 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`. Все правки — через PR в дефолтную ветку; push — завершающим шагом задачи, только после `./mise.sh run verify`.
-Git: origin `git.pjandro.ru:pjandro/java-word-pdf`; защищённые ветки — `main`, `master`, `dev` (локально в репо обычно только `main` + feature-ветки в работе). Все правки — через PR в дефолтную ветку; push — завершающим шагом задачи, только после `./mise.sh run verify`.
-Прод-координаты и креды в коммитимые файлы **не попадают** (ни IP, ни хостов, ни пользователей, ни ключей): стенд — Gitea Actions Variables, креды — Secrets; workflow-файлы ссылаются только на `${{ vars.* }}`/`${{ secrets.* }}` (список — `GITEA-vars.md`). Локальный `.env` (gitignored) — только для `compose.yml`.
- Прод-координаты и креды в коммитимые файлы **не попадают** (ни 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)
## 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`.
`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 не нужен.
Защита ветки `main`: required-контексты — **`PR checks / java (pull_request)`**, **`PR checks / web (pull_request)`** (deploy/autotests в список не включать — на PR не бегут). Смена лимитов стенда = правка Variables, PR не нужен.
## Testing & QA
## 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`. Плотность покрытия держат тесты, а не заглушки.
- Гейты: 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`. Плотность покрытия держат тесты, а не заглушки.
-Счётчики: 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-пакеты.
-Стек: JUnit 6 (`org.junit.jupiter`), только `Assertions` — Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `containsString` в `andExpect`; тестовые классы package-private, зеркалят main-пакеты. Счётчики — `docs/agent/testing.md`.
- **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, числа зашиты в тесты).
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3, `PDFTextStripper`; негативные маркеры —`.notdef` (`#`) и `Helvetica`; текст нормализуется по пробелам (`norm`). Пиксельные проверки — только в юнитах chart-пейнтеров (допуски `assertRatio` < 0.06 / < 0.10). Детали — `docs/agent/repo-map.md`.
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары `XxxNormalizerTest`↔`тест-в-конвейере` воспроизводятся грепом по этим ссылкам; исключения (крафт POIFS, синтетика, app-регрессии) — `docs/agent/testing.md`.
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары `XxxNormalizerTest`↔`тест-в-конвейере` воспроизводятся грепом по этим ссылкам; исключения — `docs/agent/testing.md`.
- Фикстуры — только закоммиченные `samples/*.docx` (13) + `samples/*.doc` (12), в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (`assertSame`) + неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`).
- Фикстуры — только закоммиченные `samples/*.docx` (13) + `samples/*.doc` (12), в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (`assertSame`) + неприкосновенность частей вне `word/*.xml`.
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); четыре набора свойств = четыре кэшированных контекста (отдельные классы, не `@Nested` — `@Nested` + `@TestPropertySource` не даёт отдельного контекста); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring-контекста. Core-юниты Spring **не поднимают**; app-тесты не переигрывают семантику конвейера — только HTTP-код/заголовки/текст ошибки.
- 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` (прогрев шрифтов в `BundledFontsTest`, `GlyphCoverageNormalizerTest`) +`@AfterEach drainWorker` в `ConversionTimeoutTest` (дренировать отменённый FOP-рендер — гонка глобального `PhysicalFonts`). Ни `@Nested`, ни `@ParameterizedTest`, ни `@Disabled`, ни `assertAll`.
- Жизненный цикл: только `@Test`; исключения — два `@BeforeAll` (прогрев шрифтов) и`@AfterEach drainWorker` в `ConversionTimeoutTest`. Ни `@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`) намеренно продублированы по тест-классам.
- Сообщения ассертов — по-русски и с наблюдаемым значением; сравнение строк литерал-слева (`"%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` — факультативны).
- Прод-автотесты: 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.
-`mvn test`**не** запускает PMD и JaCoCo-гейты (оба на `verify`) — «зелёное» состояние проверяется `mvn clean verify`. `mvn -pl wordpdf-app` без `-am` падает: app зависит от core test-jar.
- Справочник: фикстуры и их смысл, юниты моста/нормализаторов/app, пиксели и стенд без fontconfig, регрессивные записи без javadoc-ссылок — `docs/agent/testing.md`.
> Извлечение из AGENTS.md; читать при правке `internal/chart`. Авторитетно наравне с AGENTS.md.
> читать при правке `internal/chart`. Авторитетно наравне с AGENTS.md.
Нормативный источник любых правок — ECMA-376 (`docs/standards/ooxml/`: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D + полные наборы XSD `schema/strict/`/`schema/transitional/`; поведение Word — `ms-oi29500.md`, `ms-odrawxml.md`), а не догадки по исходникам LibreOffice/Word. Формулировки из стандарта при ссылке — с номером секции (§21.2.2.132 и т.п.). Эмпирические калибровки (камера, `PIE_DEPTH`) менять только вместе с пиксельными тестами. Фикстуры могут быть невалидны — код под фикстуру не правится, правится фикстура (после проверки по XSD/секции).
Нормативный источник любых правок — ECMA-376 (`docs/standards/ooxml/`: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D + полные наборы XSD `schema/strict/`/`schema/transitional/`; поведение Word — `ms-oi29500.md`, `ms-odrawxml.md`), а не догадки по исходникам LibreOffice/Word. Формулировки из стандарта при ссылке — с номером секции (§21.2.2.132 и т.п.). Эмпирические калибровки (камера, `PIE_DEPTH`) менять только вместе с пиксельными тестами. Фикстуры могут быть невалидны — код под фикстуру не правится, правится фикстура (после проверки по XSD/секции).
> Извлечение из AGENTS.md; читать при правке моста `internal/doc`. Авторитетно наравне с AGENTS.md.
> читать при правке моста `internal/doc`. Авторитетно наравне с AGENTS.md.
Нормативный источник — [MS-DOC] в `docs/standards/doc/`, общее OLE-окружение ([MS-CFB], [MS-OLEPS], [MS-ODRAW]) в `docs/standards/binary/`, [MS-ODRAWXML] в `docs/standards/ooxml/`, ссылки — с номерами секций. Новых runtime-зависимостей нет (POI остаётся test-scope; POIFS — только в тестах для упаковки крафтовых CFB). Публичные точки: `DocToDocx.convert(byte[])` (вызывает `WordPdfConverter`) и `DocToDocx.countPages(byte[])` (вызывает `WordPdfValidator.checkPageCountDoc`); общий разбор — `DocFile` (CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table). 16 из 18 классов package-private; наружу — `DocToDocx` и `CfbReader` (public, публичный член — `static readStreams(byte[])`).
Нормативный источник — [MS-DOC] в `docs/standards/doc/`, общее OLE-окружение ([MS-CFB], [MS-OLEPS], [MS-ODRAW]) в `docs/standards/binary/`, [MS-ODRAWXML] в `docs/standards/ooxml/`, ссылки — с номерами секций. Новых runtime-зависимостей нет (POI остаётся test-scope; POIFS — только в тестах для упаковки крафтовых CFB). Публичные точки: `DocToDocx.convert(byte[])` (вызывает `WordPdfConverter`) и `DocToDocx.countPages(byte[])` (вызывает `WordPdfValidator.checkPageCountDoc`); общий разбор — `DocFile` (CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table). 16 из 18 классов package-private; наружу — `DocToDocx` и `CfbReader` (public, публичный член — `static readStreams(byte[])`).
> Извлечение из AGENTS.md; читать при навигации по репо, деплое и работе с REST/шрифтами — полный «путеводитель», вынесенный из AGENTS.md дословно. Авторитетно наравне с AGENTS.md.
> читать при навигации по репо, деплое и работе с REST/шрифтами — полный «путеводитель». Авторитетно наравне с AGENTS.md.
Единственный эндпоинт `POST /api/v1/convert`: multipart-поле `file` + факультативные query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолт каждого — `WordPdfSettings.ERROR_ON_*`). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`/`.doc`-расширения — в `ConvertController` (ошибочный текст 400 — контракт с фронтом); `ConversionService.safeBaseName` — единый источник имени для файла, заголовка ответа и PDF-title (срезает оба расширения; разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). Error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры → картинки, см. «Мост») — описано в `@Operation`.
Единственный эндпоинт `POST /api/v1/convert`: multipart-поле `file` + факультативные query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолт каждого — `WordPdfSettings.ERROR_ON_*`). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`/`.doc`-расширения — в `ConvertController` (ошибочный текст 400 — контракт с фронтом); `ConversionService.safeBaseName` — единый источник имени для файла, заголовка ответа и PDF-title (срезает оба расширения; разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). Error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры → картинки, см. «Мост») — описано в `@Operation`.
- **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). Без ключа открыты `OPEN_PREFIXES` = `/actuator/`, `/swagger-ui`, `/v3/api-docs` — матч по пути **без** forwarded-contextPath (`getRequestURI()` минус `getContextPath()`; иначе под `X-Forwarded-Prefix` HEALTHCHECK получил бы 401). Пути с точечными сегментами (`..`/`%2e`) открытыми не считаются никогда.
- **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). Без ключа открыты `OPEN_PREFIXES` = `/actuator/`, `/swagger-ui`, `/v3/api-docs` — матч по пути **без** forwarded-contextPath (`getRequestURI()` минус `getContextPath()`; иначе под `X-Forwarded-Prefix` HEALTHCHECK получил бы 401). Пути с точечными сегментами (`..`/`%2e`) открытыми не считаются никогда.
- **Очередь**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` и **не потокобезопасно**. Головой очереди конструктор ставит `WordPdfConverter.warmup()` — прогрев ядра минимальным in-code docx + растром (~1,5–2,5 с, Future никто не забирает, warmup не бросает): первый реальный запрос после деплоя — за прогретым ядром (замер 2026-11: 0,13 с против 1,74 с на `main`), запросы периода прогрева ждут в очереди штатно. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс.
- **Очередь**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` и **не потокобезопасно**. Головой очереди конструктор ставит `WordPdfConverter.warmup()` — прогрев ядра минимальным in-code docx + растром (~1,5–2,5 с, Future никто не забирает, warmup не бросает): первый реальный запрос после деплоя — за прогретым ядром (замер 2026-11: 0,13 с против 1,74 с на `main`), запросы периода прогрева ждут в очереди штатно. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс.
- **Лимиты входа** задаёт только конфигурация сервера: `wordpdf.max-mb`/`wordpdf.max-pages` (env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`), `@Value` в `ConvertController` с дефолтом-SpEL из `WordPdfSettings` (5 МБ / 100); значение ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются. Ключи в `application.properties`**не объявлены** — пустое значение затенит SpEL-дефолт.
- **Лимиты входа** задаёт только конфигурация сервера: `wordpdf.max-mb`/`wordpdf.max-pages` (env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`), `@Value` в `ConvertController` с дефолтом-SpEL из `WordPdfSettings` (5 МБ / 100); значение ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются. Ключи в `application.properties`**не объявлены** — пустое значение затенит SpEL-дефолт.
@@ -98,7 +111,7 @@ PMD: `failurePriority` в плагине не задан — на практик
- Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run`/`DependencyGuard.check` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`.
- Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run`/`DependencyGuard.check` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`.
- Гейт JaCoCo `0.8.15`: `jacoco:check` (правило BUNDLE, LINE COVEREDRATIO `0.90` — обоих модулей; в `wordpdf-core/pom.xml` execution `check` переопределён и добавляет BRANCH COVEREDRATIO `0.85` — только для core) на `verify`; агент подключается в surefire через `argLine` = `@{argLine} -Djava.awt.headless=true` (свойство `argLine` в корневом pom по умолчанию пусто и перезаписывается `prepare-agent` — `mvn test -Djacoco.skip=true` без агента работоспособно); `report` и `check` оба на `verify`, report раньше — при провале порога отчёт уже на диске; отчёты `target/site/jacoco/` (html+xml, xml нужен CI-сводке). Плотность покрытия держат тесты, а не заглушки: промахи в основном недостижимые IOException/catch-ветки (`GlyphFont`, `BundledFonts`) и защитные ветви сканеров нормализаторов/валидатора.
- Гейт JaCoCo `0.8.15`: `jacoco:check` (правило BUNDLE, LINE COVEREDRATIO `0.90` — обоих модулей; в `wordpdf-core/pom.xml` execution `check` переопределён и добавляет BRANCH COVEREDRATIO `0.85` — только для core) на `verify`; агент подключается в surefire через `argLine` = `@{argLine} -Djava.awt.headless=true` (свойство `argLine` в корневом pom по умолчанию пусто и перезаписывается `prepare-agent` — `mvn test -Djacoco.skip=true` без агента работоспособно); `report` и `check` оба на `verify`, report раньше — при провале порога отчёт уже на диске; отчёты `target/site/jacoco/` (html+xml, xml нужен CI-сводке). Плотность покрытия держат тесты, а не заглушки: промахи в основном недостижимые IOException/catch-ветки (`GlyphFont`, `BundledFonts`) и защитные ветви сканеров нормализаторов/валидатора.
-59 тестовых классов / 893 теста (core 53/849 — из них 17 классов / 225 тестов в `internal/doc/`, 17 классов / 271 тест в `internal/chart/`, `WordPdfConverterTest` 77 — включая блок аудита .docx 2026-11: правила 9–10, AUDIT-FIX-2 и пиннинг сносок/полей/titlePg/vMerge/sdt/txbx/OMML/highlight на синтетике через хелпер `docx(...)`; app 6/44: ConvertController 23 + ApiKeyFilter 8 + ConversionService 5 + ApiExceptionHandler 5 + ConvertLimits 2 + ConversionTimeout 1). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с`-Djava.awt.headless=true`; только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`), тестовые классы package-private, зеркалят main-пакеты; только `@Test` + два `@BeforeAll` (warm-up шрифтов в `GlyphCoverageNormalizerTest` и `BundledFonts.init()` в `BundledFontsTest`) + `@AfterEach drainWorker` в `ConversionTimeoutTest` (дренировать отменённый FOP-рендер до следующего класса — гонка глобального `PhysicalFonts`).
-Счётчики тестов и описание блока аудита .docx 2026-11 — `docs/agent/testing.md`. JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с`-Djava.awt.headless=true`; только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`), тестовые классы package-private, зеркалят main-пакеты; только `@Test` + два `@BeforeAll` (warm-up шрифтов в `GlyphCoverageNormalizerTest` и `BundledFonts.init()` в `BundledFontsTest`) + `@AfterEach drainWorker` в `ConversionTimeoutTest` (дренировать отменённый FOP-рендер до следующего класса — гонка глобального `PhysicalFonts`).
- Фронт: Node `^20.19.0 || >=22.12.0` (engines vite/rolldown/oxlint из `package-lock.json` — в `package.json` секции `engines` нет), npm с закоммиченным `package-lock.json` (`npm ci`); vite `^8.3`, React `^19.2`, TS `~6.0` (**`strict` нигде не включён** — `npm run build` не является strict-гейтом), Tailwind `^4.3`, oxlint `^1.81`; сборка web-образа на `node:24-alpine`.
- Фронт: Node `^20.19.0 || >=22.12.0` (engines vite/rolldown/oxlint из `package-lock.json` — в `package.json` секции `engines` нет), npm с закоммиченным `package-lock.json` (`npm ci`); vite `^8.3`, React `^19.2`, TS `~6.0` (**`strict` нигде не включён** — `npm run build` не является strict-гейтом), Tailwind `^4.3`, oxlint `^1.81`; сборка web-образа на `node:24-alpine`.
- Контейнеры (podman/buildah): `FROM` только FQDN (`docker.io/library/...` — short-name не резолвится без `unqualified-search-registries`); buildah подмешивает хостовые прокси-переменные в `RUN`/`HEALTHCHECK` — обнулять `HTTP_PROXY= http_proxy= …`**на самой команде** (ENV не перебивает). Chart-движку нужен только модуль `java.desktop` (Graphics2D, он внутри JRE); fontconfig и системные шрифты рантайму не нужны — текст рисуется глифами fontbox (`fonts/GlyphFont`), проверено на musl-стенде без libfontconfig/`/etc/fonts`.
- Контейнеры (podman/buildah): `FROM` только FQDN (`docker.io/library/...` — short-name не резолвится без `unqualified-search-registries`); buildah подмешивает хостовые прокси-переменные в `RUN`/`HEALTHCHECK` — обнулять `HTTP_PROXY= http_proxy= …`**на самой команде** (ENV не перебивает). Chart-движку нужен только модуль `java.desktop` (Graphics2D, он внутри JRE); fontconfig и системные шрифты рантайму не нужны — текст рисуется глифами fontbox (`fonts/GlyphFont`), проверено на musl-стенде без libfontconfig/`/etc/fonts`.
### Пиксели, метрики шрифтов, стенд без fontconfig
### Пиксели, метрики шрифтов, стенд без fontconfig
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.