Files
java-word-pdf/AGENTS.md
T

128 lines
37 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 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Java 21, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-app` (Spring Boot 4.1.1 REST API); `wordpdf-web` — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед `git push` — `mvn clean verify` (CI нет; SPA гейтуется `npm run build` + `npm run lint`). Вход стека — контейнер `gateway` (nginx), НЕ 8080. README устарел шире секции про контейнеры: лимиты (пишет 5 МБ/100 стр. — совпадает с кодом; 6 МБ multipart — фактически 100 MB), порты («всё на :8080» — фактически gateway :9010/:9011), API-ключ вообще не упомянут; плюс «фикстуры генерируются POI» (они закоммичены, POI только в генераторе) и Swagger UI без оговорки, что в проде она открыта без ключа, — авторитет этот файл.
## Architecture & Data Flow
### Пайплайн `WordPdfConverter.convert(byte[], String[, ConvertOptions])` (порядок фиксирован, менять местами нельзя)
Наружу `WordPdfValidator.validate(docxBytes, options)` (размер → zip-подпись `PK\x03\x04` → страницы) вызывается **до** приватного `convertToStream`; внутри `convertToStream`:
1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз добавляет системные шрифты в реестр `PhysicalFonts`; ключ реестра — имя из name-таблицы TTF, `addPhysicalFont(URI)` не перезаписывает занятый → `init()` вызывает `dropNonBundled()` **до** регистрации и `load()` (иначе системный Calibri ломает em-dash-fallback).
2. Нормализация байтов docx до JAXB-загрузки (цепочка `byte[] → byte[]`, порядок значим): `StrictOoxmlNormalizer` (strict-OOXML → transitional-байт: `a:`-проценты и `w14:fillToRect` → тысячные ×1000, текст `wp14:pctWidth`/`pctHeight`, элементы и атрибуты `w:start`/`w:end` → `w:left`/`w:right` (кроме `w:lvl/w:start` в numbering.xml), значения `start`/`end` у `w:jc`/`w:tab`; в `mc-preprocessor.xslt` docx4j ветка `%` закомментирована, start/end не маппятся; namespaces и `pt`-значения правит сам mc-preprocessor — собственный рерайт URI ломает его pt-конверсию) → `DocxOnOffNormalizer` (`w:val="off"/"on"` → `false`/`true`) → `SymbolFontNormalizer` (PUA U+F0xx Symbol/Wingdings/Webdings → Unicode + DejaVu Sans, переписывает и элементы `<w:sym>`; 5 карт по 256 слотов, таблица `SymbolMapper` сгенерирована из docx4j 17.x) → `FieldNormalizer` (`fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, вложенные/битые поля пропускает) → `GlyphCoverageNormalizer` (режет ран по покрытию глифов, пишет семейство в `w:rFonts`, иначе FOP рисует «#»; покрытие — `java.awt.Font.canDisplay` + BitSet-кэш, НЕ docx4j `GlyphCheck` — тот плодит INFO-лог; для serif-ран fallback ищется сначала в `SERIF_FAMILIES` (DejaVu Serif/Tinos/Caladea), затем в sans) → `WordprocessingMLPackage.load`.
3. `WordPdfValidator.checkPageCount(docxBytes, maxPages)` — **до** рендера, lightweight (zip/StAX) по нормализованным байтам — тот же путь, что у приложения до очереди.
4. `pkg.setFontMapper(mapper)` → `DrawingPreRenderer.run(pkg, options)` (шаг 3.5: `c:chart`/`dgm:relIds` docx2fo.xslt не умеет — свой Java2D-движок `internal/chart/*` рендерит в PNG 300 dpi и подменяет на `pic:pic`; объект, выключенный в `ConvertOptions`, пропускается до рендера и остаётся в docx; упавший рендер — объект **удаляется** из docx (`gd.getAny().clear()`) + warn, деградация не падение).
5. `new FOSettings(pkg)` + `FopFallbackFonts.declare` (декларирует **все** бандл-семейства — FOP встраивает только задекларированные) → `FORendererApacheFOP`/`FOUserAgent` (непустой `title` → заголовок PDF) → `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`.
6. `finally`: `deleteEmbeddedFontTempFiles()` (в 17.x `OpcPackage.close()` нет).
### REST API (`wordpdf-app`, всё package-private кроме `WordPdfApplication`)
- Единственный эндпоинт `POST /api/v1/convert` (multipart-поле `file`, факультативные `renderCharts`/`renderSmartArt` — query или form) → `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`-расширения — в `ConvertController`; `safeBaseName` в `ConversionService` — единый источник имени для файла, заголовка ответа и PDF-title (разрешены `[\p{L}\p{N} ._-]`, пустое → `document`).
- Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts`. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс.
- Ошибки (`ApiExceptionHandler`, тело `{"error": …}`): `ValidationException` → 400; `ConversionFailedException` → 500; `ConversionRejectedException` → 503; `ConversionTimeoutException` (`wordpdf.convert-timeout`, 2m) → 504; `MaxUploadSizeExceededException` → 413; `MissingServletRequestPartException`/`MissingServletRequestParameterException` → 400; `NoResourceFoundException` (неизвестный путь) → 404; catch-all → 500 (подробности только в лог). `ValidationException` — тип ядра `ru.pjandro.wordpdf.ValidationException extends ConversionException` (публичный), валидатор бросает его сам, app-дубликата нет; три app-исключения (`ConversionFailedException`, `ConversionRejectedException`, `ConversionTimeoutException`) — package-private, несут семантику 500/503/504. `doConvert` перехватывает `ValidationException` раньше `ConversionException` — отказ страницы-лимита из конвейера ядра даёт 400, а не 500. Граница: сломанный контейнер (не zip / размер / страницы) → 400, валидный zip с мусором внутри → 500. Валидация до очереди: `WordPdfValidator.validate(docxBytes, options)` (внутри порядок значим: `checkInput` → zip-магик `PK\x03\x04` → `checkPageCount`); тот же метод — вход ядра.
- **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). Без ключа открыты `/actuator/**` (HEALTHCHECK) и документация springdoc (`/swagger-ui*`, `/v3/api-docs*`) — матч по пути **без forwarded-contextPath** (`getRequestURI()` минус `getContextPath()`; иначе под `X-Forwarded-Prefix` HEALTHCHECK получил бы 401). 401 пишет сам фильтр (`ApiExceptionHandler` ошибок фильтров не видит). Springdoc в проде **включён**, документация открыта без ключа под `https://pjandro.ru/pdf-converter/swagger-ui.html` (server-URL/swagger-config собираются из `X-Forwarded-*`, `server.forward-headers-strategy=framework` — `native`-клапан Tomcat `X-Forwarded-Prefix` не понимает). Регрессии — `ApiKeyFilterTest#forwardedPrefix_healthStaysOpen`, `ApiKeyFilterTest#docsOpenWithoutKey`.
- Лимиты входа задаёт **только конфигурация сервера**: `wordpdf.max-bytes`/`wordpdf.max-pages` (env `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`), `@Value` в `ConvertController` с дефолтом-SpEL из `WordPdfSettings` (5 MiB / 100); значение ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются. Ключи в `application.properties` **не объявлены** — пустое значение затенит SpEL-дефолт.
- SPA: вся сеть в `src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается, экран `ApiKeyGate` (`UnauthorizedError` — наследник `ApiError`, проверяется раньше); гейт показывается только когда `probeApiKey()` (GET /api/v1/convert → 401 от `ApiKeyFilter`) подтвердил требование ключа — в dev без ключа форма открывается сразу; запросы на `${import.meta.env.BASE_URL}api/...` (vite `base` из `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом `/pdf-converter/`).
### Chart-движок (`internal/chart`, package-private кроме `DrawingPreRenderer.run`)
Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр × `DPI/72`, размеры — в пунктах, EMU→pt `cx/12700.0`). `ChartSpec.parse` (`enum Type`: PIE/PIE3D/DOUGHNUT/BAR/BAR_HORIZONTAL/LINE/AREA/SURFACE3D/UNSUPPORTED; пустой `c:title` + `autoTitleDeleted="0"` → у **круговых** имя первого ряда, у прочих — `AUTO_TITLE = "Chart Title"`; палитра `accent1..6` темы, легенда по умолчанию снизу, позиция `t` поддержана, `overlay` → место не резервируется) → `ChartRenderer` (осевые «круглые» шаги `niceUnit` 1/2/5·10ⁿ как Word; маркеры легенды 0.32/0.55 кегля, отрезок 2.4 кегля) → пейнтеры `CartesianPainter`/`PiePainter` (`DEPTH_RATIO=0.22`, `TILT_CORRECTION=0.95`, `FIT_MARGIN=0.865`)/`Surface3dPainter` (калибровка по стр. 3 `develop/word-export.pdf`: `CAMERA_DISTANCE=2.36`, `DEPTH_RATIO=0.705`, `HEIGHT_RATIO=0.664`, `GUTTER_LEFT/RIGHT=0.1485`, `GUTTER_TOP=0.116`, `GUTTER_BOTTOM=0.146`, свет `LIGHT_X/Y/Z=0.83/0.48/0.28`); `SmartArtRenderer` рисует кэш разложенной схемы (relationship `…/office/2007/relationships/diagramDrawing`, фактически `word/diagrams/drawing1.xml`); палитра темы — `DrawMlColor` (instance; без ThemePart — дефолтная Office-палитра `accent1=4472C4`…); текст — `DrawMlText`; утилиты `RgbHsl`, `PrstGeomShapes`. Калибровочные константы менять только вместе с `Surface3dPainterTest`/`PiePainterTest`. Обход `pkg.getParts()` — только по **снимку** списка (`createImagePart` мутирует реестр → CME); rels частей — `part.getRelationshipsPart()`, НЕ `getOwningRelationshipPart()` (это rels ссылающегося); обход XML обязан раскрывать `JAXBElement`.
### Критические инварианты (нарушение = битый вывод)
- `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`. Иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам (без них нет колонок) → FOP падает на `docx4j-baseline`.
- `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия `noLoggingWarningInPdf`). Приложение исключает его из зависимости ядра — логи ведёт logback.
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.2 (пакеты `org.apache.fop.*`); `Fop.Renderers.getRenderer()` возвращает **список** (рендер выбирается по mime `application/pdf`). `docx2fo.xslt` в репозитории нет — он в jar `docx4j-export-fo`.
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; explicit = межсекционные `sectPr` в body + `w:br type="page"` + `pageBreakBefore` (включая таблицы и `w:sdt`). Единственный путь — lightweight (StAX по zip, secure-ридер без DTD/external entities; JAXB-обход удалён — `WordPdfValidator` не зависит от docx4j): атрибуты — по локальному имени (`attrLocal`, не по transitional-URI: иначе в strict-документе `w:br type="page"` не засчитываются); `sectPr` внутри `pPr` не считает, последнюю body-direct секцию не считает, `continuous`-секции не считает, в колонтитулах — только `w:br type="page"`, `pageBreakBefore` — только внутри `pPr` вне `sectPr` (truthy-значения `val`: `null|true|1|on`); на не-zip молчит — подпись проверяет вызывающий. Все отказы — `ValidationException`.
- Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
- Внимательно: комментарии в `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` (15 записей, ключи lowercase): MS→аналоги — 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 до основного цикла. `DISPLAY_NAMES` — обратный маппинг lowercase→отображаемое имя для `documentFontName` (пишет `GlyphCoverageNormalizer` в `w:rFonts`); `BundledFontMapper.bundledFamily` — public-хук «имя шрифта из docx → бандл-семейство или fallback» (пользуется chart-движок). Публичный API `BundledFonts` шире реестра: `families()` (источник для `FopFallbackFonts`), `font/regular/bold/italic/boldItalic(family)`, `FALLBACK_FAMILY`; `awtFont` возвращает `Font` размера 1 — всегда `deriveFont(size)`. Новый шрифт = файл + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`).
## Key Directories
|Путь|Назначение|
|---|---|
|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` — `byte[]`, с лимитом/без, и `validate(byte[], ConvertOptions)` — полная цепочка размер → zip-подпись → страницы; без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `WordPdfSettings` (константы-дефолты), `ConvertOptions` (record: renderCharts, renderSmartArt, maxBytes, maxPages)|
|`…/wordpdf/fonts/`|`BundledFonts` (реестр/выгрузка TTF, `families()`, `FALLBACK_FAMILY`), `BundledFontMapper` (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук `bundledFamily`)|
|`…/wordpdf/internal/`|5 байтовых нормализатора + `FopFallbackFonts` (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`declare`)|
|`…/wordpdf/internal/chart/`|11 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)|
|`wordpdf-core/src/main/resources/fonts/`|30 TTF + 3 лицензии — бинарные фикстуры, часть jar|
|`wordpdf-core/src/test/resources/samples/`|11 закоммиченных `.docx`-фикстур (единственные фикстуры)|
|`wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/`|REST API (10 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`, `OpenApiConfig` (`@SecurityScheme` X-API-Key для springdoc) + 4 класса исключений|
|`wordpdf-web/src/`|SPA (React 19 + TS + Vite + Tailwind): `api.ts` (вся сеть), `components/` (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo)|
|корневые `Containerfile`, `compose.yml`, `compose.dev.yml`, `gateway/nginx.conf`|образ бэкенда (multi-stage maven:3.9-temurin-21 → temurin-21-jre, non-root, HEALTHCHECK actuator); compose app+web+gateway: web-образ со своим HEALTHCHECK (`wget /`), в обоих compose `depends_on web: condition: service_healthy` (без health web gateway не стартует); прод-compose интерполирует `WORDPDF_MAX_BYTES:-5242880`/`WORDPDF_MAX_PAGES:-100`; podman-специфика обоих compose: `x-podman.name_separator_compat` (docker-style имена контейнеров), явные `healthcheck` app/web (дубли Containerfile-HEALTHCHECK — OCI-выгрузка его теряет), зафиксированная подсеть `10.113.0.0/24` gw `10.113.0.1` под резолвер aardvark-dns; два repo-стенда одновременно не поднять (общая подсеть)|
|корневой `.env.example`|шаблон env: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`; реальный прод `.env` — на прод-сервере (координаты: `/home/pjandro/prod/java-word-pdf/DEPLOY.md`, вне репо)|
|`develop/` (вне git)|рабочие материалы и эталоны Word 365 (`word.docx`+`word.pdf`, `word-export.*`, `convert.pdf`, `1212.pdf`, `diff/`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать|
## 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, ключ выключен
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am обязателен (test-jar core)
npm run dev # (wordpdf-web/) SPA :5173, vite-proxy /api → :8080
npm run build # (wordpdf-web/) tsc -b && vite build — гейт SPA; lint: npm run lint (oxlint)
podman-compose -f compose.dev.yml up -d --build # dev-стенд: http://<LAN-IP хоста>:9011 (0.0.0.0), без ключа, springdoc вкл
```
Пересоздать 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
```
Деплой. **Прод** — на пользовательском LAN-сервере (podman 5.8.2 + podman-compose 1.6.0, бинарников `docker`/`docker-compose` на сервере нет); координаты сервера, каталог, restart-секвенция, ключ и гейты успешности — вне репо: `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (обязательно прочитать перед любым деплоем/перезапуском; в том каталоге лежат архивные файлы старого стека 88.14 — `restart.sh.old-88.14`, старый compose/nginx — **не поднимать**). Единая точка входа с dev-машины — `/home/pjandro/prod/java-word-pdf/restart.sh` (пробрасывает флаги удалённому скрипту: `--build` — пересборка образов из `origin/main` + перезапуск; без флага — restart контейнеров; предупреждает о не запушенном в `main`). В прод попадает только запушенное в `main` — рабочее дерево на сборку не влияет. Прод-compose `/opt/wordpdf/docker-compose.yml` (вне git) содержит podman-специфику: `x-podman.name_separator_compat` (имена `wordpdf-prod-app-1`, от них зависит `restart.sh`), явные healthcheck app/web и фиксированную подсеть `10.112.0.0/24` gw `10.112.0.1`. Наружный вход `https://pjandro.ru/pdf-converter/` (префикс срезает наружный nginx прод-хоста, не репозиторный gateway-конф; прод-копия gateway-конфа отличается от репо только резолвером `10.112.0.1` — под свою подсеть — и `proxy_read_timeout 300s` — в репо его нет, дефолтные 60s рвут 2-минутные конвертации; resolver + `proxy_pass` через переменную есть и там и там). Тот же наружный nginx в `location /pdf-converter/` добавляет `X-Forwarded-Host: $host` и `X-Forwarded-Prefix: /pdf-converter` — из них springdoc собирает server-URL спека и swagger-config под префиксом (без `X-Forwarded-Host` server = `https://app:8080`, gateway шлёт приложению `Host: app:8080`); канонический URL документации `https://pjandro.ru/pdf-converter/swagger-ui.html` — открыт без ключа. **Dev-стенд** — из репо `compose.dev.yml` (проект `wordpdf-dev`, `9011:80` на все интерфейсы — вход по LAN-IP хоста, без env → ключ пуст, springdoc вкл). Репозиторный `compose.yml` — третий вариант (проект `wordpdf`, `9010:80` на все интерфейсы, `WORDPDF_API_KEY` fail-closed без `.env` — `up` упадёт, `VITE_BASE` — build-arg `wordpdf-web/Containerfile` — репо-compose НЕ передаёт: `compose build` без arg даёт base `/` и битые ассеты под префиксом, прод передаёт arg по DEPLOY.md). Запуск по просьбе пользователя = прод-стек; dev/`java -jar`/`npm run dev` — внутренняя отладка.
## Code Conventions & Common Patterns
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе: docx4j-наследник `BundledFontMapper` (`extends BestMatchingMapper`), обёртка цветов `DrawMlColor` (тоже instance, но НЕ наследник docx4j) и Spring-компоненты `wordpdf-app`.
- Нормализаторы — единая сигнатура `public static byte[] normalize(byte[] docx) throws IOException` с флагом `changed`: нечего менять → вернуть **тот же массив** (`assertSame` в тестах); package-private хук `static String rewrite(String xml)` для юнит-тестов (возвращает `null` при отсутствии изменений); правятся только части `word/*.xml`.
- Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения.
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же (в существующем main-коде convention соблюдён лишь частично — `SymbolFontNormalizer`, `WordPdfValidator`, `Surface3dPainter` и классы app; новые правки обязаны ссылаться).
- Константы UPPER_SNAKE с числовыми эталонными значениями (`CAMERA_DISTANCE`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/...`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`.
- Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`declare`/`DrawingPreRenderer.run` (`rewrite`, `split`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`.
- Тестовые методы: регрессионные — `объект_условие` через underscore (`ruPlain_cyrillicAndStyles`, `checkInput_bytesOverLimit`, `noKey_rejected`); чистые юниты — camelCase (`pageFieldBecomesFldSimple`, `splitsRunForUncoveredGlyph`).
## Important Files
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures`.
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_BYTES` 5 MiB, `MAX_PAGES` 100, `RENDER_CHARTS/SMARTART`); рантайм-конфигурации в ядре нет.
- `wordpdf-app/src/main/resources/application.properties` — multipart 100MB (`max-file-size`/`max-request-size` + `file-size-threshold=100MB`, держит файл в памяти; в тон gateway `client_max_body_size 100m`), `wordpdf.convert-timeout=2m`, пустой `wordpdf.api-key`, `server.forward-headers-strategy=framework` (префикс прод-прокси для springdoc) + `springdoc.swagger-ui.persist-authorization=true`; `wordpdf.max-bytes`/`max-pages` здесь намеренно нет.
- `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён; `spring-boot-starter-webmvc` (Boot 4: переименован из starter-web) + `spring-boot-starter-actuator` (нужен HEALTHCHECK контейнера `/actuator/health`); тест-зависимости: `spring-boot-webmvc-test` (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.
- `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app).
- Корневой `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`; pluginManagement: compiler `3.16.0`, surefire `3.6.0` с `-Djava.awt.headless=true`, jar `3.5.1`.
- `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF.
- `gateway/nginx.conf` — единственный вход: `/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → `app:8080`, остальное → `web:80`; `client_max_body_size 100m` (без директивы upload режется HTML-413 шлюза вместо JSON-ошибки API). `wordpdf-web/nginx.conf` — чистая статика с SPA-fallback, `/api` НЕ проксирует.
- `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур.
- `wordpdf-web/vite.local.config.ts` — легаси-одноразовщик (прокси `/api` → :8091), коммит против воли автора (`*.local` в gitignore не накрывает `.ts`-суффикс), в `tsconfig.node.json` не включён; кандидат на удаление, не тиражировать паттерн.
## Runtime & Tooling Preferences
- Java 21 + Maven (обязательны; wrapper `mvnw` нет); UTF-8. Только Maven — никакого Gradle/Ant.
- Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement); новые зависимости — latest stable.
- Фронт: Node `^20.19.0 || >=22.12.0` (engines vite/oxlint из lockfile), npm с закоммиченным `package-lock.json` (`npm ci`); vite `^8.3.0`, React `^19.2`, TS `~6.0` (**`strict` нигде не включён** — `npm run build` не является strict-гейтом), Tailwind `^4.3`, oxlint `^1.81`; podman-сборка web на `node:24-alpine`.
- CI, линтеров, форматтеров, checkstyle для Java — нет; проверка одна: `mvn clean verify`.
- Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят; `BundledFontsTest#listedFilesCoverAllTtfInResources` требует `file:`-протокол classpath — только surefire, не fat-jar).
- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`, `main`/`dev` защищены (правила глобального AGENTS.md; локально только `main`, `dev` нет; на origin висит остаточная смерженная `docs/regenerate-agents-md`).
## Testing & QA
- 14 тестовых классов / 132 `@Test` (core 11/107, app 3/25). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ единственный `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest`).
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` для текста (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок (`imageCount`). Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`); в `tableImage_tableAndImage` — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах).
- Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word (`PiePainterTest` аспект h/w=0.585, `assertRatio` отклонение <0.06; `Surface3dPainterTest` `assertRange` ±6 pt для центров силуэта + `assertRatio` допуск 0.10 для геометрических отношений; shading — не допуск, а перцентильные коридоры яркости p5∈[0.74,0.90], median∈[0.90,1.10], p95∈[1.02,1.20]).
- Фикстуры — закоммиченные `samples/*.docx` (11; в тестах не генерировать): core грузит classpath-ресурсом → `byte[]`, PDF для PDFBox — временный файл; app читает `/samples/…` из **test-jar core** (classifier `tests`) → `mvn -pl wordpdf-app` без `-am` не соберётся. In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]`. Ключевые: `too-many-pages` (150 явных разрывов → 151), `stale-cache` (кэш `<Pages>1</Pages>` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject).
- Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив» (`assertSame` покрыт тестами только у zip-нормализаторов `DocxOnOff`/`SymbolFont`/`StrictOoxml`; у `Field`/`GlyphCoverage` — `rewrite`→`null`) и неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`). Тесты бьют и в package-private API (`GlyphCoverageNormalizer.split(text, family)`, `ChartSpec.readTitle`).
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); три контекста — `ConvertControllerTest` (пустой ключ), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest` (`@TestPropertySource` с лимитами — отдельный класс, не `@Nested`).
- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight` — lightweight против strict), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCount_limitBoundary` 99/100/101, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`, `validate_notAZip`↔`inputNotAZip_rejectedBeforeRender`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `ChartSpecTest`↔автозаголовки, chart-пейнтеры↔`chartsSmartArt_drawingsBecomeImages` (+`drawingToggles_offRemovesRasters`/`drawingToggles_chartsOffSmartArtOn`); `noLoggingWarningInPdf` — регрессия `slf4j-simple`, `pdfTitle_comesFromParameter` — регрессия PDF-title (юнит-партнёра нет). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed` (гонка реестра `PhysicalFonts`), `corruptNotAZip_rejected`, `junkInsideValidZip_conversionError`, `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `renderFlagsOff_convertsWithoutDrawings`, `cyrillicAndPathInFilename_sanitizedResponseName` (RFC 5987 + path-traversal), `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey` (открытая документация + матч фильтра без forwarded-contextPath).
- UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint, `.oxlintrc.json`: rules-of-hooks error, only-export-components warn).