Files
java-word-pdf/AGENTS.md
T

133 lines
29 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Repository Guidelines
## Project Overview
Конвертер `.docx` → `.pdf` на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 21, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-app` (Spring Boot REST API); плюс `wordpdf-web` — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед `git push` — `mvn clean verify` (CI/lint в репозитории нет; SPA гейтуется `npm run build`).
## Architecture & Data Flow
Пайплайн `WordPdfConverter.convertToStream` — порядок шагов фиксирован, менять местами нельзя:
1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз заново добавляет системные шрифты в реестр `PhysicalFonts`; бандл регистрируется поверх; чистка реестра — **до** `load()`. Ключ реестра — имя шрифта, `addPhysicalFont(URI)` НЕ перезаписывает занятый ключ → `BundledFonts.init()` вызывает `dropNonBundled()` (иначе системный `DejaVuSerif.ttf` блокирует наш `DejaVuSerif-Regular.ttf`).
2. Нормализация байтов docx до JAXB-загрузки (цепочка `byte[] → byte[]`, порядок значим):
`DocxOnOffNormalizer` (`w:val="off"/"on"` → `false`/`true`; docx4j 17.x теряет on/off при разборе)
→ `SymbolFontNormalizer` (маркеры списков из PUA U+F0xx в Symbol/Wingdings/Webdings → Unicode + DejaVu Sans; таблица `SymbolMapper` сгенерирована, руками не менять)
→ `FieldNormalizer` (сложные поля `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, иначе во всех колонтитулах печатается один закэшированный номер; штатный `FieldsCombiner` docx4j не заходит внутрь `w:sdt`)
→ `GlyphCoverageNormalizer` (шаг 2.4: режет ран по покрытию глифов и пишет семейство в `w:rFonts`; трогает только раны с одним `w:t` и явным `w:rFonts`; покрытие — `java.awt.Font.canDisplay` через `BundledFonts.awtFont`, не `GlyphCheck` — тот логирует на каждый глиф).
3. `WordprocessingMLPackage.load(байты)` → `WordPdfValidator.checkPageCount(pkg)` — **до** рендера.
4. `pkg.setFontMapper(mapper)` → `DrawingPreRenderer.run(pkg, options)` (шаг 3.5: `c:chart`/`dgm:relIds` docx2fo.xslt не умеет и молча выбрасывает — свой Java2D-движок `internal/chart/*` рендерит их в PNG 300 dpi и подменяет на `pic:pic`; после `setFontMapper`, до `FOSettings`; рисунок, выключенный в `ConvertOptions`, пропускается ранним `continue` до рендера и остаётся в docx — в PDF на его месте пусто, как без движка)
→ `new FOSettings(pkg)` + `FopFallbackFonts.declare` (декларирует в FOP-конфиге **все** бандл-семейства — FOP встраивает только задекларированные)
→ `FORendererApacheFOP` / `FOUserAgent` (заголовок PDF = параметр `title`, если непустой)
→ `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`.
5. `finally`: `deleteEmbeddedFontTempFiles()` (в 17.x `OpcPackage.close()` нет).
### REST API (`wordpdf-app`)
- Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (очередь 16, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` (шаг 1 пайплайна), параллельные конвертации вырывают его друг у друга из-под рендера.
- Разделение ошибок: валидация байтов до очереди (`WordPdfValidator.checkInput(byte[])` + проверка zip-подписи + `checkPageCountLightweight(byte[])`) → `ValidationException` → 400; ошибки ядра/рендера → `ConversionFailedException` → 500; очередь занята → 503; таймаут (`wordpdf.convert-timeout`, 2m) → 504. Граница: сломанный контейнер → 400, валидный zip с мусором внутри → 500.
- Фронт ходит на `${import.meta.env.BASE_URL}api/...` (vite `base` из env `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом `/pdf-converter/`).
- Факультативные параметры `renderCharts`/`renderSmartArt` (query или multipart-form — Spring биндит и то и другое) контроллер превращает в `ConvertOptions`; дефолты — константы ядра `WordPdfSettings.RENDER_CHARTS`/`RENDER_SMARTART`. Лимиты входа задаёт **только конфигурация сервера**: свойства `wordpdf.max-bytes` (байты) / `wordpdf.max-pages` (страниц), env `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES` (relaxed binding, прецедент `WORDPDF_CONVERT_TIMEOUT`); `@Value` в конструкторе `ConvertController` с дефолтом-SpEL из констант ядра (`MAX_INPUT_BYTES`=20 MiB / `MAX_PAGES`=1000), значение ≤ 0 — падение на старте. Параметрами запроса лимиты не переопределяются (регрессии `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `ConvertLimitsTest`). SPA шлёт только чекбоксы. Потолок загрузки — 100 МБ (`client_max_body_size 100m` в nginx + Spring multipart `100MB`); больше отсекается до валидатора.
- **Ключ доступа**: `ApiKeyFilter` (сервлет-фильтр, единственная граница доступа) сверяет заголовок `X-API-Key` со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`; сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты `ConvertControllerTest` — пустой ключ). `/actuator/**` открыт — им дышит Docker HEALTHCHECK (actuator публикует только `health`). 401 отдаёт сам фильтр (`ApiExceptionHandler` ошибок фильтров не видит), тело в той же форме `{"error": …}`. Прод: compose выключает springdoc env'ами `SPRINGDOC_API_DOCS_ENABLED`/`SPRINGDOC_SWAGGER_UI_ENABLED` — документация с валидным ключом даёт 404 (`ApiExceptionHandler.notFound` даёт 404 всем неизвестным путям, а не 500 от catch-all). SPA: экран `ApiKeyGate`, ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается и форма открывается пустой; заголовок подставляет только `api.ts`. Регрессии — `ApiKeyFilterTest`, `ConvertControllerTest#unknownPath_notFound`.
### Критические инварианты (нарушение = битый вывод)
- **`docx4j.convert.out.fo.gsubFeatures=false`** — ставится в статическом блоке `WordPdfConverter`. Иначе docx4j навешивает `fox:gsub-features` без объявления префикса → FO невалиден → `WordLayoutFixups` молча отказывается от всех фиксов → FOP падает на `docx4j-baseline`. Без фиксов нет колонок и колонок таблиц.
- **`slf4j-simple` обязателен** в ядре: без него docx4j пишет «TO HIDE THESE MESSAGES» прямо в выходной PDF (регрессия `noLoggingWarningInPdf`). Приложение (`wordpdf-app`) исключает `slf4j-simple` из зависимости ядра — логи ведёт logback из Boot; предупреждение в PDF возникает только при полном отсутствии SLF4J-провайдера, `slf4j-simple.properties` из core остаётся инертным ресурсом.
- **JAXB-обход обязан раскрывать `JAXBElement`** (иначе таблицы/раны молча пропускаются — оценка «1» вместо 121). Рекурсия через `ContentAccessor` из `org.docx4j.wml` (НЕ `org.docx4j.contentcontrol` — в 17.x его нет). Тип секции — `SectPr$Type.getVal()`; маркер — `R.LastRenderedPageBreak` (`CTLastRenderedPageBreak` в 17.x отсутствует).
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.2 (пакеты `org.apache.fop.*`), умеет хинты `docx4j:baseline`/`docx4j:line-box`. `Fop.Renderers.getRenderer()` возвращает **список** — `FopFallbackFonts.rendererFonts` ищет `application/pdf`.
- `docx2fo.xslt` в репозитория нет — он в jar `docx4j-export-fo`. `WordLayoutFixups` (включён по умолчанию в 17.x) постобработкой DOM FO даёт реальные колонки `w:cols/@w:num` и колонки таблиц; побочный эффект — авто-ширины колонок без `tblGrid`/`tcW` стали уже (слово может перенестись в ячейке).
- Известный остаток эталона: U+2188 (ↈ) и U+218A (↊) — глифов нет ни в одном OFL-шрифте бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
- **nginx `client_max_body_size 100m`** (`gateway/nginx.conf`, шлюз; столько же в прод-`nginx.conf` и Spring multipart) — потолок загрузки стека: без директивы upload режется HTML-413 от шлюза до бэкенда вместо JSON-ошибки API. Авторитетный лимит — свойство `wordpdf.max-bytes` (env `WORDPDF_MAX_BYTES`, дефолт 20 MiB), значения выше 100 МБ держит шлюз/multipart.
### Шрифты (30 TTF в `wordpdf-core/src/main/resources/fonts/`, SIL OFL)
Алиасы MS→open-source (`BundledFontMapper`): Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans. Новый шрифт = файл + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`). Noto Naskh Arabic / Noto Sans Armenian (только regular, ради глифов U+07B1–08FF и U+058D/E) в `BundledFontMapper` не регистрируются — `FontFallback.selectCovering` перебирает весь реестр `PhysicalFonts` сам. У них только regular-начертание: `BundledFonts.families()` это учитывает, `BundledFontsTest.allFamiliesHaveAllVariants` их не проверяет. Символы U+2000–U+2EFF: `RunFontSelector.symbolBlockFont` оставляет шрифт ранa, если глиф есть, иначе виртуальный «Segoe UI Symbol» → fallback (как в Word; регрессия `ruPlain_emDashEmbeddedNotHelvetica`).
### Валидация входа (`WordPdfValidator`)
Константы `MAX_INPUT_BYTES = 20 MiB`, `MAX_PAGES = 1000` лежат в `WordPdfSettings` — едином файле-дефолтах ядра. Оба лимита переопределяются на вызов `ConvertOptions` (у `WordPdfValidator` перегрузки `checkInput(byte[], long)`, `checkPageCount(byte[]|pkg, int)`, `checkPageCountLightweight(byte[], int)`); REST API параметрами запроса их **не** пробрасывает — значения берутся из конфигурации сервера (свойства `wordpdf.max-bytes`/`wordpdf.max-pages`, env `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`). В ядре рантайм-конфигурации нет. Вход валидатора и конвертера — только `byte[]`/`WordprocessingMLPackage`, файловых перегрузок в ядре нет (`.docx` по имени проверяет `ConvertController` — с байтов расширение не видно). Страницы = **максимум трёх нижних оценок**: (1) кэш `docProps/app.xml <Pages>` — недостоверен (реальный кейс: `<Pages>1</Pages>` при 110 маркерах); (2) явные разрывы `w:br type="page"` / `pageBreakBefore` / межсекционные `sectPr` (кроме `continuous`); (3) `w:lastRenderedPageBreak` + 1. Lightweight-путь (zip/StAX, без docx4j) согласован с JAXB: `sectPr` в body — «все минус 1»; `sectPr` в `pPr` не считается; колонтитулы — по содержимому zip. Расхождение допустимо только в завышение. `convert(byte[], String)` (и перегрузка с `ConvertOptions`) возвращает байты и файлового вывода не имеет — отказ структурно не оставляет артефакта (регрессия `staleCachePageCountRejectedBeforeRender`; Lightweight-путь на мусоре без zip-подписи молчит — оценку «1», подпись проверяет приложение).
### Chart-движок (`internal/chart`, package-private кроме `DrawingPreRenderer.run`)
Свой Java2D-рендер DrawingML. Калибровка surface3D зафиксирована тестами, эталон — стр. 3 gitignored `word-export.pdf` (экспорт Word, `pdftoppm -r 300`): `CAMERA_DISTANCE = 2.36` (`perspective` — НЕ угол FOV; fov≈49°), `DEPTH_RATIO = 0.705`, `HEIGHT_RATIO = 0.664`, поля `0.1485/0.116/0.146` от области построения, `rotY` берётся как `-Math.toRadians(...)` (знак обратный правому правилу), Lambert `0.92 + 0.88·dot` кламп `[0.80; 1.25]`, свет `(0.83, 0.48, 0.28)`. Цели: силуэт 314,9×65,3 pt центр (227,3; 82,3), уклон передней кромки 0.1282, аспект 0.207, шаги осей 0.0504/0.1176. Триангуляция ячейки — диагональ с большей суммой значений (седло; фиксированная диагональ даёт невидимую щепку); клиппинг полос — по треугольникам. `w01 = z[r+1][c]`, `w10 = z[r][c+1]` — перестановка закручивает квад в бабочку. `ChartRenderer.axisBounds` без явного `c:min` поднимает нижнюю границу до 0. Пустой `c:title` + `autoTitleDeleted val="0"` → автозаголовок `Chart Title` (для pie/pie3D/doughnut — имя ряда). Границы калибровки менять только вместе с тестами `Surface3dPainterTest`/`PiePainterTest`.
В `DrawingPreRenderer` rels части берутся через `part.getRelationshipsPart()` (`Base`), а **не** `getOwningRelationshipPart()` — у `document.xml` последнее указывает на пакетный `.rels`. Обход `pkg.getParts()` — только по снимку списка: `createImagePart` докидывает части в тот же реестр (живой обход → `ConcurrentModificationException`).
## Key Directories
| Путь | Назначение |
|---|---|
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConversionException`, `WordPdfSettings` (константы-дефолты), `ConvertOptions` (рисование на вызов) |
| `…/wordpdf/fonts/` | `BundledFonts` (реестр/выгрузка TTF), `BundledFontMapper` (алиасы MS→open-source) |
| `…/wordpdf/internal/` | 4 байтовых нормализатора + `FopFallbackFonts` |
| `…/wordpdf/internal/chart/` | Java2D-рендер диаграмм/SmartArt в PNG |
| `wordpdf-core/src/main/resources/fonts/` | 30 TTF + лицензии — бинарные фикстуры, часть jar |
| `wordpdf-core/src/test/resources/samples/` | 11 закоммиченных `.docx`-фикстур (единственные фикстуры) |
| `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/` | REST API: `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler` |
| `wordpdf-web/src/` | SPA (React+TS+Vite+Tailwind): компоненты в `components/`, вся сеть в `api.ts` |
| корневые `Dockerfile`, `docker-compose.yml`, `gateway/nginx.conf` | образ бэкенда (multi-stage, temurin-21); compose app+web+gateway; прод-запуск — из `PROD-DIR`, не отсюда |
| корневой `docker-compose.dev.yml` | dev-стенд без ключа: проект `wordpdf-dev`, вход http://127.0.0.1:9011, springdoc включён |
| корневой `.env.example` | шаблон env деплоя: ключ (`WORDPDF_API_KEY`) и лимиты входа (`WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`); реальный прод `.env` живёт в `PROD-DIR/`, в репо его нет |
| `wordpdf-web/Dockerfile`, `wordpdf-web/nginx.conf` | образ SPA (node→nginx); только статика (прокси — в шлюзе); base сборки — `ARG VITE_BASE` (prod `/pdf-converter/`, дефолт `/`) |
| `references/` | эталон Word 365 (`word.docx` + `word.pdf`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать |
| `diff/`, корневые `word-export.*` | gitignored артефакты ручной калибровки |
## Development Commands
```bash
mvn clean verify # все модули + тесты — обязательный гейт перед push
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, POST /api/v1/convert
npm run dev # (wordpdf-web/) SPA :5173, proxy /api → :8080
docker compose -f docker-compose.dev.yml up -d --build # dev-стенд: вход 127.0.0.1:9011, без ключа
cd PROD-DIR && docker compose up -d --build # прод: PROD-HOST:9010 (только LAN)
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест
```
Compose: `gateway` (nginx) — единственный вход: `/api`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → `app` (`/actuator` открыт фильтром), остальное → `web` (DNS-имена в сети compose). Два режима запуска. **Прод** — каталог `PROD-DIR` (вне репо; проект `wordpdf-prod`, build-context'ы указывают в репозиторий, образы `*:prod`): `gateway` опубликован только на `PROD-HOST:9010` (LAN), ключ — `.env` этого каталога (fail-closed `${WORDPDF_API_KEY:?…}`), springdoc выключен env'ами, SPA собрана с `VITE_BASE=/pdf-converter/`; свой `nginx.conf` (= репозиторный + `proxy_read_timeout 300s`, иначе длинные конвертации рвутся 504). Наружный вход — `https://pjandro.ru/pdf-converter/`: nginx на PROD-HOST (`/etc/nginx/conf.d/localhost.conf`) проксирует IP-литералом `PROD-HOST:9010` и срезает префикс завершающим слэшем `proxy_pass`; при недоступном стеке `error_page` отдаёт 503 (HTML/`{"error": …}`), nginx не падает; мониторинг без ключа — `/pdf-converter/health`. **Dev-стенд** — из репо `docker compose -f docker-compose.dev.yml up -d --build` (проект `wordpdf-dev`, вход http://127.0.0.1:9011, пустой ключ — фильтр прозрачен, springdoc включён). Отзыв ключа = правка прод `.env` + `docker compose up -d` в прод-каталоге. После пересоздания контейнеров `app`/`web` старому `gateway` нужен `restart` (nginx кэширует DNS бэкендов при старте — иначе 502). **Запуск по просьбе пользователя = прод-стек** (каталог прода, `up -d --build`); dev-стенд, `java -jar` / `npm run dev` — внутренняя отладка, запуском приложения не считать. **Обновление прода («эту версию в прод») = та же `docker compose up -d --build` в прод-каталоге**: прод пересобирается из **текущего рабочего дерева репозитория** (`build.context` — каталог, не git-ref: незакоммиченные правки поедут в прод), прод-`.env` с ключом и наружный шлюз 88.88 при этом не меняются; гейт успешности — `docker compose ps` (3× healthy) и `curl -s http://PROD-HOST:9010/actuator/health` → UP. `wordpdf.convert-timeout` переопределяется env `WORDPDF_CONVERT_TIMEOUT` (relaxed binding Boot).
Перезапуск прода — скрипт `./restart.sh` в прод-каталоге: без флага `restart app web` → гейт healthy `app` (до 120 с) → `restart gateway`; с `--build` — `up -d --build` (пересборка из рабочего дерева). Gateway всегда рестартует последним (nginx кэширует DNS бэкендов). Файл живёт только в прод-каталоге, в репозитории его нет.
Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` НЕ генерируется — исключение):
```bash
mvn -pl wordpdf-core test-compile -Dmdep.outputFile=/tmp/cp.txt dependency:build-classpath -q
java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples
```
## Code Conventions & Common Patterns
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе: docx4j-классы `BundledFontMapper` (наследник `BestMatchingMapper`), `DrawMlColor` (палитра темы) и Spring-компоненты `wordpdf-app`.
- Нормализаторы — единая сигнатура `public static byte[] normalize(byte[] docx) throws IOException` с флагом `changed`: нечего менять → вернуть **тот же массив** (`assertSame` в тестах); package-private хук `static String rewrite(String xml)` для юнит-тестов.
- Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние `IOException`/`IllegalStateException` оборачиваются на границе. В chart — деградация вместо падения: неизвестный пресет → прямоугольник + лог.
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же.
- Константы UPPER_SNAKE с числовыми эталонными значениями (`CAMERA_DISTANCE`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/...`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`.
- Внутренние API package-private; наружу из `internal` торчат только `normalize`/`declare`/`DrawingPreRenderer.run`.
- В `wordpdf-app` всё package-private (контроллер, advice, service, исключения); в SPA вся сетевая логика только в `src/api.ts` — компоненты `fetch` не вызывают.
## Important Files
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures`.
- `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён из зависимости ядра.
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox `3.0.8` (test), POI `5.5.1` (test, только генератор фикстур), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; форки FOP/jeuclid приходят транзитивно с `docx4j-export-fo`, пинить не надо.
- `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF.
- `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур (команда в javadoc).
## Runtime & Tooling Preferences
- Java 21 + Maven (обязательны; wrapper `mvnw` нет). UTF-8. Фронт: Node.js ≥ 20.19 (Vite 7+), вне Maven-депа.
- Только Maven (никакого Gradle/Ant); новые зависимости — latest stable, версии только в корневой `dependencyManagement`.
- CI, линтеров, форматтеров, checkstyle — нет; проверка одна: `mvn clean verify`.
- Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят).
## Testing & QA
- JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire c `-Djava.awt.headless=true`; только `Assertions` (без Mockito/AssertJ, несмотря на test-классpath Boot), package-private тесты в mirror-пакетах.
- **PDF сравнивается текстом, не растеризацией**: PDFBox `PDFTextStripper` для текста, override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страницы для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок. Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Пиксели — только в unit-тестах chart-пейнтеров (там сам код — Java2D); допуски 6–10%.
- Текст нормализуется по пробелам (`tableImage_tableAndImage` — полное удаление пробелов: docx4j переносит слова в auto-fit таблицах).
- Фикстуры — закоммиченные `samples/*.docx` (не генерировать в тестах); classpath → `byte[]` (`WordPdfConverterTest.sampleBytes`), PDF для PDFBox — временный файл (`convertPdf`). In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]` (`WordPdfValidatorTest`).
- Юниты нормализаторов работают строками (`rewrite`) и проверяют контракт «нечего менять → null / тот же массив» и неприкосновенность `[Content_Types].xml`.
- Тесты `wordpdf-app` (`ConvertControllerTest`, MockMvc) берут фикстуры из test-jar core (classifier `tests`) → `-pl wordpdf-app` без `-am` не соберётся. Гейт SPA — `npm run build` (tsc -b); UI-тестов нет.
- Каждый фикс бага docx4j/FOP сопровождается: байтовый нормализатор/pre-renderer + регрессионный тест с фикстурой + javadoc-ссылка. Проверенные пары: `DocxOnOffNormalizerTest`/`ruPlain_regularRunsUseRegularFont`, `FieldNormalizerTest`/`pageNumbers_recomputedNotCached`, `SymbolFontNormalizerTest`/`symbolFonts_bulletsAreNotHash`, `GlyphCoverageNormalizerTest`/`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`/`staleCachePageCountRejectedBeforeRender`, `BundledFontsTest`/`noLoggingWarningInPdf`, `Surface3dPainterTest`/`chartsSmartArt_drawingsBecomeImages`.