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

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

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

231 lines
41 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`/`.doc` → `.pdf` на чистом Java: docx4j 17.3.2 → XSL-FO → форк Apache FOP. Без LibreOffice/Aspose. Бинарный `.doc` (Word 97-2003) переносится собственным мостом MS-DOC/MS-CFB (`internal/doc`) в in-memory `.docx` и идёт тем же конвейером. Java 17, только Maven.
Три независимых модуля:
- `wordpdf-core` — библиотека конвертации: docx4j → XSL-FO → FOP; бандл шрифтов, chart/SmartArt-движок, мост `.doc`. 62 Java-файла: 7 в корневом пакете (публичный API), 16 в `internal/`, 18 в `internal/doc/`, 18 в `internal/chart/`, 3 в `fonts/`.
- `wordpdf-app` — REST API на Spring Boot 4.1.1. 11 классов, единственный `public` — `WordPdfApplication`.
- `wordpdf-web` — SPA (React 19 + TS + Vite + Tailwind), вне Maven-реактора, собирается npm и деплоится отдельным образом.
Единственный вход стека — gateway-контейнер nginx (`:9010` prod-like `compose.yml`, `:9011` dev `compose.dev.yml`), **не** 8080. Авторитетны этот файл, `docs/agent/` и код; решения о форматах — по спецификациям из `docs/standards/` (ссылка на секцию обязательна).
## Architecture & Data Flow
### Пайплайн `WordPdfConverter.convert(byte[], String[, ConvertOptions])`
Порядок фиксирован, местами менять нельзя (`WordPdfConverter.convertToStream`). Вход роутируется по сигнатуре байтов: `PK\x03\x04` → docx-путь; `D0 CF 11 E0 A1 B1 1A E1` (CFB, MS-CFB §2.2) → мост `DocToDocx.convert` → in-memory `.docx` → тот же конвейер (единый предикат — `WordPdfValidator.isBinaryDoc`).
| # | Шаг | Что делает |
|---|---|---|
| 0 | `DependencyGuard.check()` | API-проба commons-compress ≥ 1.25.0, иначе `ConversionException` с инструкцией |
| 1 | `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` | инициализация шрифтов — инвариант (объяснение в `docs/agent/pipeline.md`) |
| 2 | `DocxRewritePipeline.STEP` → `OleObjectNormalizer` → `WordprocessingMLPackage.load` | один zip-проход правил 1–10 + условная OLE-вычистка (правило 11) |
| 3 | `pkg.setFontMapper(mapper)` | привязка шрифтов документа к бандл-TTF |
| 3.5 | `DrawingPreRenderer.run(pkg, options)` | `c:chart`/`dgm:relIds` → PNG 300 dpi → `pic:pic` |
| 4 | `new FOSettings(pkg)` + `FopFallbackFonts.declare` | в FOP-конфиг — **все** бандл-семейства |
| 4.25 | `LayoutPostRenderer.register` | кастомный `FORenderer`: post-FO padding-компенсация таблиц |
| 4.5 | `foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES)` | вендорный `xslt/docx2fo.xslt` с AUDIT-FIX-патчами (инвариант) |
| 5–6 | `getFopFactoryBuilder`/`getFOUserAgent` → `Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)` | XSL-FO → PDF; непустой `title` → заголовок PDF |
| 7 | `finally` → `deleteEmbeddedFontTempFiles()` | в docx4j 17.x `OpcPackage.close()` нет |
Вход валидируется **до** `convertToStream`: `WordPdfValidator.validate(bytes, options)` (размер → подпись zip/CFB → контейнер → страницы). Для `.doc` — `checkPageCountDoc` по сырым байтам (MS-DOC), до конвертации. Полные обоснования шагов и правила подсчёта страниц — `docs/agent/pipeline.md`.
### Мост `.doc` → `.docx` (`internal/doc`, 18 классов)
Нормативный источник — [MS-DOC] в `docs/standards/doc/`, общее OLE-окружение ([MS-CFB], [MS-OLEPS], [MS-ODRAW]) — `docs/standards/binary/`. Новых runtime-зависимостей нет (POI/POIFS — test-scope). Публичные точки: `DocToDocx.convert(byte[])` и `DocToDocx.countPages(byte[])`; общий разбор — `DocFile` (CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table). 16 из 18 классов package-private; наружу — `DocToDocx` и `CfbReader`.
|Класс|Семантика (полные байтовые раскладки — `docs/agent/doc-bridge.md`)|
|---|---|
|`CfbReader`, `FibHeader`, `PieceTable`|CFB ([MS-CFB], любой брак → `ConversionException`) + FIB (§2.4.1: `fWhichTblStm`, пары `fc*`) + текст §2.9.135 (compressed CP1252 / UTF-16LE)|
|`Grpprl`, `ChpxIndex`, `PapxIndex`, `PrcData`|sprm'ы CHPX/PAPX/TAP/Sepx (§2.6.2) + FKP-индексы (§2.4.6; bOffset=0 — дефолт с сохранением границы рана) + разворот grpprl вне FKP (§2.9.210)|
|`Styles`, `FontTable`, `Lists`|STSH-цепочки base-first, символьные stk=3 → `charChain` (§2.9.271) + ftc→`w:rFonts` (§2.9.147) + PlfLst/PlfLfo → `word/numbering.xml` (§2.9.200/.201)|
|`Tables`, `Sections`, `Headers`|TAP → сетка/границы/`w:jc`/vAlign/`w:tcMar` (§2.6.3; битый TDefTable → плоские абзацы) + секции (PlcfSed §2.8.26: continuous/landscape/колонтитулы/колонки/titlePage) + Plcfhdd → `headerN.xml`/`footerN.xml`|
|`SummaryInfo`, `OfficeArt`|кэш PageCount [MS-OLEPS] (offset'ы относительны начала PropertySet) + BLIP → PNG/JPEG/DIB; EMF/WMF/PICT → пропуск + warn|
|`DocToDocx`, `DocxWriter`|оркестратор + `DocxBody` (раны/pPr/табличный автомат 0x07/TTP → docx-XML) + мульти-частный zip (document/numbering/hdr/ftr/media)|
### Нормализаторы (`internal/DocxNormalizer`)
Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame` в тестах). Порядок фиксирован: Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby. Правила 1–10 применяет `DocxRewritePipeline.STEP` одним zip-проходом (неизменённые записи копируются raw-сжатыми байтами), `OleObjectNormalizer` (правило 11) подключается лямбдой в `WordPdfConverter.normalizers()`. Константу `STEP` выставляют 9 из 10 rewrite-нормализаторов (нет у `RubyNormalizer`), у `OleObjectNormalizer` её нет вовсе.
1. `StrictOoxmlNormalizer` — strict-OOXML → transitional (`w:start`/`w:end` → `w:left`/`w:right`, проценты ×1000, `jc val="end"`).
2. `DocxOnOffNormalizer` — `w:val="off"/"on"` → `"false"/"true"`.
3. `SymbolFontNormalizer` — PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans.
4. `FieldNormalizer` — `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`.
5. `InvisibleCharNormalizer` — вырезание невидимых/bidi-символов из `w:t`.
6. `GlyphCoverageNormalizer` — резка ранов по покрытию глифов, `w:rFonts` (иначе FOP рисует «#»).
7. `TableIndentNormalizer` — `w:jc` center/right + `w:tblInd` → абсолютный `w:tblInd`.
8. `NumberingSuffixNormalizer` — `w:suff="space"` → пробел в `w:lvlText`.
9. `HiddenTextNormalizer` — вырезание скрытых ранов (`w:vanish`), guard защищённого содержимого.
10. `RubyNormalizer` — руби: база → обычные раны, надстрочница вырезается.
11. `OleObjectNormalizer` — OLE-бинарники вычищаются, `<w:object>` → плейсхолдер-картинка; `errorOnOle` → 422.
Полные правила с номерами секций, guard'ами и инвариантом про `mc-preprocessor.xslt` (собственный рерайт strict-URI ломать нельзя) — `docs/agent/pipeline.md`.
### REST API (`wordpdf-app`, всё package-private кроме `WordPdfApplication`)
Единственный эндпоинт `POST /api/v1/convert`: multipart-поле `file` (`.docx`/`.doc`) + факультативные query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолты — `WordPdfSettings.ERROR_ON_*`). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`; имя — `ConversionService.safeBaseName`. Error-флаги диаграмм/SmartArt/OLE на `.doc` **не срабатывают** (BLIP-плейсхолдеры → картинки) — описано в `@Operation`. Полный текст — `docs/agent/repo-map.md`.
| Ситуация | HTTP | Класс |
|---|---|---|
| Некорректный вход (размер, подпись zip/CFB, контейнер, страницы) | 400 | `ValidationException` (наследник `ConversionException`) |
| Ошибка уровня запроса (нет файла, чужое расширение, размер, нечитаемая часть) | 400 | `BadRequestException` |
| Error-флаг на диаграммы/SmartArt/OLE | **422** | `DrawingRejectedException` (core-`DrawingFoundException`, `Kind {CHARTS, SMARTART, OLE}`) |
| Ошибка ядра/рендера | 500 | `ConversionFailedException` |
| Очередь переполнена | 503 | `ConversionRejectedException` |
| Дольше `wordpdf.convert-timeout` (2m) | 504 | `ConversionTimeoutException` |
| Превышен multipart-лимит | 413 | `MaxUploadSizeExceededException` |
| Неизвестный путь / метод / content-type | 404 / 405 / 415 | `NoResourceFoundException` / `HttpRequestMethodNotSupportedException` / `HttpMediaTypeNotSupportedException` |
| Битый error-флаг, нет части/параметра | 400 | `MethodArgumentTypeMismatchException`, `MissingServletRequestPartException`, `MissingServletRequestParameterException` |
Тело ошибки — `{"error": …}`. Текст 422 — контракт с фронтом, показывается дословно: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты». `ApiExceptionHandler` не видит ошибок фильтров — 401 пишет сам `ApiKeyFilter`.
- **Ключ доступа**: `X-API-Key` ↔ `wordpdf.api-key` (пустое = выключено); без ключа открыты только `OPEN_PREFIXES` (`/actuator/`, `/swagger-ui`, `/v3/api-docs`), пути с точечными сегментами — никогда. Механика `ApiKeyFilter` — `docs/agent/repo-map.md`.
- **Очередь и лимиты**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`QUEUE_CAPACITY = 16`, переполнение → 503) — ядро мутирует глобальный `PhysicalFonts` и **не потокобезопасно**; головой очереди на старте стоит `WordPdfConverter.warmup()`; лимиты входа — только конфигурация сервера (`wordpdf.max-mb`/`max-pages`, SpEL-дефолты из `WordPdfSettings`; ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются, в `application.properties` намеренно не объявлены).
- **SPA**: вся сеть в `wordpdf-web/src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), экран `ApiKeyGate` показывается только когда `probeApiKey()` подтвердил требование ключа (признак открытого сервера — **405**, не 200/404); base — `VITE_BASE` (дефолт `/`, CORS не нужен); три error-флага (дефолт — выключены), DropZone `.docx,.doc`.
### Chart/SmartArt-движок (`internal/chart`, 18 классов)
Нормативный источник правок — ECMA-376 (`docs/standards/ooxml/`: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D, XSD `schema/strict/`/`schema/transitional/`); поведение Word — `ms-oi29500.md`, `ms-odrawxml.md`. Эмпирические калибровки (камера, `PIE_DEPTH`) менять только вместе с пиксельными тестами; фикстура невалидна — правится фикстура, не код.
Java2D → PNG: `ChartRenderer.DPI = 300`, потолок растра `MAX_PIXELS = 16_777_216` (`fitDpi` понижает эффективный dpi). Защитные лимиты: `ChartSpec.MAX_POINTS = 100_000`, `ChartRenderer.MAX_TICKS = 1000`, `DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000` — деградация «объект остаётся как есть / удалён + warn», не OOM.
chart-PNG вставляются media-частями вручную (`DrawingPreRenderer.addChartMedia`, имена `/word/media/chart-*`, без docx4j-decode'а `createImagePart`); `ChartImageHandler` отключает docx4j «Compress Pictures» (CR-029) только для них — медиа документов остаются в штатном режиме.
Пейнтеры со всеми калибровками, `autoTitleDeleted`/автозаголовки, Combo-семантика, защитные обходы JAXB — `docs/agent/chart.md`.
### Критические инварианты (нарушение = битый вывод, не исключение)
- `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`. Иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам → FOP падает на `docx4j-baseline`.
- `docx4j.fonts.discoverPhysicalFonts.enabled=false` и `docx4j.fonts.discoverJarFonts.enabled=false` — static-блок `WordPdfConverter`: `BestMatchingMapper` (static) сканирует системные шрифты и jar'ы classpath'а, а `BundledFonts.restrictToBundled()` перед каждой конвертацией всё найденное выбрасывает (~100–140 мс впустую на JVM). `discoverJarFonts("fonts-symbol")` свойством не гейтится — символ-шрифт регистрируется и снимается restrict'ом как раньше.
- Единственный XSL-FO-стилист — вендорный `wordpdf-core/src/main/resources/xslt/docx2fo.xslt` (копия `docx2fo.xslt` из docx4j-export-fo 17.3.2 + два AUDIT-FIX-патча: `w:rPr/w:position` → `baseline-shift`, Part 1 §17.3.2.24; AUDIT-FIX-2 — шаблоны `w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir`, иначе их ловит catch-all `match="*"` и текст теряется). Дрейф-гейт `WordPdfConverterTest#vendoredXsltTracksJarCopy`: вне AUDIT-FIX-регионов вендорная копия обязана быть побайтно равна стилю из jar'а — при апгрейде docx4j перевендорить и перенести патчи. `setCustomXsltTemplates` принимает предкомпилированный `Templates` (каст Object→Templates, поток кидает CCE).
- `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия `noLoggingWarningInPdf`). Приложение исключает его из зависимости ядра — логи ведёт logback.
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 (транзитив от `docx4j-export-fo`, в pom не пинится; пакеты `org.apache.fop.*`). `FopFallbackFonts` берёт `w:renderer` с mime `application/pdf`, иначе первый со шрифтами.
- Порядок инициализации шрифтов: `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` — **до** `load()`. `init()` идемпотентен и `synchronized`, распаковывает TTF во временный каталог `wordpdf-fonts-*` (`deleteOnExit` на файлы и каталог); `dropNonBundled()` чистит глобальный реестр `PhysicalFonts` от всего, что вне бандла.
- `PhysicalFonts` — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером. `warmup()` обязан идти тем же сериализующим потоком.
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; детальные правила StAX-подсчёта (`attrLocal`, `continuous`, колонтитуки, стриминговый проход) — `docs/agent/pipeline.md`.
- Не чинить (невозможности FOP/docx4j и ограничения эталона): `jc="distribute"`, `suff="tab"`/`lvlJc`, метрика «single», кернинг, `framePr`, `REF`/`SEQ`/`TOC`-кэш, руби-надстрочница, U+2188/U+218A — перечень с доказательствами: `docs/agent/render-limitations.md`.
- Внимание: комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).
### Шрифты (30 TTF + 3 лицензии, SIL OFL, `wordpdf-core/src/main/resources/fonts/`)
9 семейств: 7 × 4 начертания (Carlito/Caladea/Arimo/Tinos/Cousine/DejaVu Sans/DejaVu Serif) + Noto Naskh Arabic / Noto Sans Armenian (только regular). Алиасы в `BundledFontMapper.ALIASES` (ключи lowercase): Calibri→Carlito, Calibri Light→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; **self-map** всех бандл-семейств, включая Noto (иначе unmatched уходит в DejaVu-фолбэк); fallback — DejaVu Sans; виртуальный `SYMBOL_FONT` «Segoe UI Symbol» (U+2000–U+2EFF) → fallback до основного цикла. Публичный API `BundledFonts`: `families()`, `font/regular/bold/italic/boldItalic(family)`, `FALLBACK_FAMILY`. Новый шрифт = файл + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`). `GlyphFont` читает TTF напрямую с classpath через fontbox — **без `java.awt.Font`** (нужен fontconfig на хосте).
## Key Directories
| Путь | Назначение |
|---|---|
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | публичный API: `WordPdfConverter`, `WordPdfValidator`, `WordPdfSettings`, `ConvertOptions`, `ConversionException`/`ValidationException`/`DrawingFoundException` |
| `…/wordpdf/fonts/` | `BundledFonts` (реестр/выгрузка TTF), `BundledFontMapper` (алиасы, self-map), `GlyphFont` (глиф-движок fontbox) |
| `…/wordpdf/internal/` | 11 нормализаторов + `DocxRewritePipeline` (zip-проход правил 1–10) + `OleObjectNormalizer` + `LayoutPostRenderer` + `FopFallbackFonts` + `DependencyGuard` + интерфейс `DocxNormalizer` |
| `…/wordpdf/internal/doc/` | мост `.doc` → `.docx` (18 классов, детали — `docs/agent/doc-bridge.md`) |
| `…/wordpdf/internal/chart/` | 18 классов Java2D-рендера диаграмм/SmartArt в PNG (public: `DrawingPreRenderer.run`, `ChartImageHandler`) |
| `wordpdf-core/src/main/resources/` | `fonts/` (30 TTF), `xslt/docx2fo.xslt` (вендорный стилист), `slf4j-simple.properties` |
| `wordpdf-core/src/test/resources/` | `samples/` (25 закоммиченных фикстур: 13 `.docx` + 12 `.doc`), `geom/presetShapeDefinitions.xml` (ECMA-376, только в тестах) |
| `wordpdf-app/` | REST API (11 классов, public только `WordPdfApplication`) |
| `wordpdf-web/` | SPA: `src/api.ts` (вся сеть) + `src/components/` (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo) |
| корневые `Containerfile`, `compose.yml`, `compose.dev.yml`, `gateway/nginx.conf` | контейнеры; единственный вход — gateway (`:9010`/`:9011`) |
| `.gitea/workflows/` | Gitea Actions (`pr.yml`, `main.yml`) — нарратив job'ов `docs/agent/ci-cd.md` |
| `docs/standards/` | нормативные спецификации (навигатор — `README.md`): `ooxml/` (ECMA-376 + XSD + MS-OI29500/MS-ODRAWXML), `binary/` (OLE2-окружение), `doc/` ([MS-DOC]), `docx/` (валидатор фикстур), `xls/`, `xlsx/`, `ppt/`, `pptx/` |
| `docs/agent/` | глубокие справочники: `pipeline`, `doc-bridge`, `chart`, `render-limitations`, `testing`, `ci-cd`, `repo-map` (когда читать — по имени файла) |
| `prod-autotests/` | прод-автотесты (pytest, конфиг только env) |
| `develop/` | рабочие материалы и эталоны рендера (gitignored) — **не фикстуры**, в тесты/jar не подключать |
## Development Commands
Бутстрап toolchain: `sh bootstrap.sh` (Windows: `powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1`) — project-local mise в `./.mise/` (в систему ничего не ставится), дальше — `./mise.sh` / `.\mise.ps1`.
```bash
./mise.sh run verify # = mvn clean verify: тесты + PMD + гейты JaCoCo (обязательный гейт перед push)
mvn clean verify # то же самое; mvnw НЕТ — только системный Maven
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # app-тест (-am обязателен: app берёт test-jar core)
mvn -pl wordpdf-app -am package # исполняемый jar бкенда (-am обязателен)
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
./mise.sh run web-install|web-build|web-lint|web-dev # npm ci | tsc -b && vite build | oxlint | vite :5173
podman-compose -f compose.dev.yml up -d --build --force-recreate # dev-стенд: http://<LAN-IP хоста>:9011, без ключа, springdoc вкл; --force-recreate ОБЯЗАТЕЛЕН — без него пересобирается образ, а контейнеры остаются на старом
./mise.sh run prod-tests # прод-автотесты: pip install + pytest -q . в prod-autotests/
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD-валидация фикстур (lxml)
```
Задачи mise (8): `verify`, `app-package`, `app-run`, `web-install`, `web-build`, `web-lint`, `web-dev`, `prod-tests`.
**«Запусти тестовый сервер» (термин пользователя)** = полный dev-стенд, НЕ `java -jar`: `podman-compose -f compose.dev.yml up -d --build --force-recreate`, вход `http://<LAN-IP хоста>:9011` без API-ключа; гейт — контейнеры healthy + корень SPA отвечает 200. Обоснования (`--force-recreate`, почему без ключа) — `docs/agent/repo-map.md`.
Пересоздание фикстур (POI) и перевендоривание стилиста после апгрейда docx4j — команды в `docs/agent/repo-map.md`.
Деплой. **Прод** — на пользовательском LAN-сервере; **перед любым деплоем/перезапуском прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md`**. Передёдплой — push в `main` или Run workflow (`workflow_dispatch`), ручных скриптов нет. Детали (рендер прод-конфигов job'ом `deploy`, гейты, откат) — `docs/agent/ci-cd.md`.
## Code Conventions & Common Patterns
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе: `BundledFontMapper` (`extends BestMatchingMapper`), `DrawMlColor`, Spring-компоненты `wordpdf-app`.
- В `internal/**` классы `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу ограничены: `normalize`/`STEP`/`declare`/`run`/`check`/`register`; `rewrite`-хуки — package-private. В `wordpdf-app` всё package-private кроме `WordPdfApplication`. В `internal/doc` публичны только `DocToDocx` и `CfbReader`.
- Нормализаторы — единый контракт `internal/DocxNormalizer` + константа `STEP`; порядок цепочки — см. «Нормализаторы», правятся только `word/*.xml`.
- Ошибки публичного API — только `ConversionException extends RuntimeException` (unchecked); внутренние исключения оборачиваются на границе. В chart — деградация вместо падения. `ValidationException` — исключительная собственность `WordPdfValidator`; не оборачивать его в общий `ConversionException`.
- DI в `wordpdf-app` — конструкторная инъекция Spring; состояние сервисов `private final`. SPA: единственный источник состояния — `useState` в `App.tsx`, вся сеть — в `api.ts`.
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же.
- Константы UPPER_SNAKE с числовыми эталонными значениями (`PIE_DEPTH`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/V_ITALIC/V_BOLD_ITALIC`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`.
- Логирование: `java.util.logging.Logger` в корневом пакете и `internal/`, SLF4J — в `internal/chart` и в `wordpdf-app`.
- Тестовые методы: регрессионные — `объект_условие` через underscore (`ruPlain_cyrillicAndStyles`, `checkInput_bytesOverLimit`, `noKey_rejected`); чистые юниты — camelCase (`pageFieldBecomesFldSimple`, `splitsRunForUncoveredGlyph`); оба стиля разрешает PMD-паттерн `junit5TestPattern` (`^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$`).
- PMD (`pmd-ruleset.xml`, execution `pmd-check` на `verify` в обоих модулях, `includeTests=true` — тесты тоже сканируются, валится нарушение любой приоритетности): полные исключения категории, кастомный XPath-правило `LiteralFirstInEquals` и настройки правил — в самом ruleset.
## Important Files
| Файл | Роль |
|---|---|
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` | точка входа библиотеки + static-блок (`gsubFeatures`, отключение discovery шрифтов) + `normalizers(options)` (порядок цепочки) + `VendoredXslt` |
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java` | валидация входа и lightweight-подсчёт страниц (StAX, без docx4j) |
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` | все дефолты ядра (`MAX_INPUT_MB = 5`, `MAX_PAGES = 100`, `MAX_DECOMPRESSED_MB = 200`, `MAX_ZIP_ENTRIES = 8192`, `ERROR_ON_* = false`); runtime-конфигурации в ядре нет |
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/DocxRewritePipeline.java` | единственный zip-проход правил 1–10; порядок вызовов `rewrite`/`rewritePart` зафиксирован здесь |
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/doc/DocToDocx.java` | оркестратор моста `.doc` (`convert`/`countPages`) + вложенный `DocxBody` |
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/chart/DrawingPreRenderer.java` | замена диаграмм/SmartArt на PNG; владеет `MAX_EXTENT_EMU` и деградацией при падении рендера |
| `wordpdf-core/src/main/resources/xslt/docx2fo.xslt` | единственный XSL-FO-стилист (вендорная копия + AUDIT-FIX-патчи) |
| `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConvertController.java` | HTTP-слой: presence/расширение/размер → `ConvertOptions` → `ConversionService` |
| `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java` | однопоточная очередь конвертаций + таймаут + прогрев ядра |
| `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiExceptionHandler.java` | исключение → HTTP-код + `{"error": …}` (здесь же карта 400/404/405/413/415/422/500/503/504) |
| `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiKeyFilter.java` | аутентификация `X-API-Key`; 401 пишет сам |
| `wordpdf-app/src/main/resources/application.properties` | multipart 100MB (`file-size-threshold=2MB` — крупные части на диск), `wordpdf.convert-timeout=2m`, пустой `wordpdf.api-key`, `server.forward-headers-strategy=framework`; `wordpdf.max-mb`/`max-pages` намеренно отсутствуют |
| `wordpdf-web/src/api.ts` | весь сетевой слой SPA, хранение ключа, типы ошибок |
| `pom.xml` (корень) | **все** версии зависимостей и плагинов (в модулях версии не объявлять) |
| `pmd-ruleset.xml` | ruleset PMD (код-стиль + unused + NPE-safe equals) |
| `mise.toml` | версии инструментов и 8 задач |
| `.ci/maven-settings.xml` | Maven-зеркало Nexus; URL из `${env.MAVEN_MIRROR_URL}` (координаты стенда в репо не хранятся) |
| `Containerfile`, `wordpdf-web/Containerfile` | multi-stage образы бекенда и SPA |
| `gateway/nginx.conf` | единственный вход: `/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → `app:8080`, остальное → `web:80` |
| `wordpdf-core/src/test/java/.../SampleDocxGenerator.java`, `ChartTypesDocxGenerator.java` | утилиты пересоздания фикстур (main()) |
## Runtime & Tooling Preferences
- Java 17 + Maven (обязательны; wrapper `mvnw` НЕТ — только системный Maven); UTF-8. Только Maven — никаких Gradle/Ant. Java/Maven/Node/Python ставит project-local mise (бинарь в `.mise/`, вне системы), версии пинятся в корневом `mise.toml` (`java = temurin-17`, `maven = 3.9.16` — ровно как в CI, `node = 24`, `python = 3.15`), ежедневный запуск — `./mise.sh` / `.\mise.ps1`. Bootstrap качает mise `2026.10.19` → `./.mise/bin`, затем `mise trust` → `mise install` → `mise run web-install`.
- Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement); новые зависимости — latest stable. Закреплено: docx4j `17.3.2`, commons-compress `1.28.0`, slf4j `2.0.20`, Spring Boot `4.1.1`, springdoc `3.1.1`, JUnit `6.1.3`, PDFBox/fontbox `3.0.8`, POI `5.5.1` (test), JaCoCo `0.8.15`; плагины: compiler `3.16.0`, surefire `3.6.0` (`-Djava.awt.headless=true`), jar `3.5.1`, PMD `3.28.0`.
- Зависимости Maven — через зеркало Nexus `maven-central`: локально `~/.m2/settings.xml` (литеральный URL, файл вне репо), CI/Containerfile — `.ci/maven-settings.xml` + `MAVEN_MIRROR_URL` (Variable / build-arg).
- Фронт: Node из engines vite/oxlint, `npm ci` с закоммиченным `package-lock.json`, TS `strict` нигде не включён. Контейнеры (podman/buildah): `FROM` только FQDN, хостовые прокси-переменные обнулять на самой команде (`RUN`/`HEALTHCHECK`), `DOCKER_BUILDKIT=0` обязателен, fontconfig рантайму не нужен (глифы — fontbox).
- Локальная проверка одна: `mvn clean verify` (тесты + PMD + JaCoCo). Форматтеров и checkstyle для Java нет; статический линтер — PMD.
- Исполняемый jar бекенда проверять только `java -jar` — тесты идут по classpath и repackage-специфику не видят; нюанс `BundledFontsTest` (`file:`-протокол classpath) — `docs/agent/repo-map.md`.
- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`; защищённые ветки — `main`, `master`, `dev` (локально в репо обычно только `main` + feature-ветки в работе). Все правки — через PR в дефолтную ветку; push — завершающим шагом задачи, только после `./mise.sh run verify`.
- Прод-координаты и креды в коммитимые файлы **не попадают** (ни IP, ни хостов, ни пользователей, ни ключей): стенд — Gitea Actions **Variables** (`DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_DIR`, `WORDPDF_BASE_URL`, `WORDPDF_MAX_PAGES`, `WORDPDF_MAX_MB`, `REGISTRY`, `PIP_INDEX_URL`, `MAVEN_MIRROR_URL`), креды — **Secrets** (`DEPLOY_SSH_KEY`, `DEPLOY_KNOWN_HOSTS`, `WORDPDF_API_KEY`, `REGISTRY_USER`, `REGISTRY_PASSWORD`); workflow-файлы ссылаются только на `${{ vars.* }}`/`${{ secrets.* }}`. Локальный `.env` (gitignored) — только для `compose.yml`.
## CI/CD (Gitea Actions)
`pr.yml` (`PR checks`): job `java` (`mvn -B -s .ci/maven-settings.xml clean verify` через зеркало Nexus) + coverage-сводка и комментарий в PR, job `web` (`npm ci` → build → lint). `main.yml`: `java`/`web` → `images-app`/`images-web` (build+push в Nexus, теги `prod` + `sha-<7>`) → `deploy` (SSH, рендер прод-конфигов, гейты healthy) → `autotests` → `rollback` при провале. Нарратив job'ов и деплоя — `docs/agent/ci-cd.md`.
Защита ветки `main`: required-контексты — **`PR checks / java (pull_request)`**, **`PR checks / web (pull_request)`** (deploy/autotests в список не включать — на PR не бегут). Смена лимитов стенда = правка Variables, PR не нужен.
## Testing & QA
- Гейты: PMD `maven-pmd-plugin` 3.28.0 (`includeTests=true`) и JaCoCo `0.8.15` (`jacoco:check` на `verify`) — пороги LINE `0.90` (оба модуля), BRANCH `0.85` (только core); отчёт `report` раньше `check` (при провале порога отчёт уже на диске, `target/site/jacoco/`). Механика `argLine`/`prepare-agent`/`jacoco.skip` — `docs/agent/repo-map.md`. Плотность покрытия держат тесты, а не заглушки.
- Счётчики: 59 тестовых классов / 893 теста (core 53/849 — из них `internal/doc/` 17 классов / 225 тестов, `internal/chart/` 17 / 271, `WordPdfConverterTest` 77; app 6/44: ConvertController 23 + ApiKeyFilter 8 + ConversionService 5 + ApiExceptionHandler 5 + ConvertLimits 2 + ConversionTimeout 1). JUnit 6 (`org.junit.jupiter`), только `Assertions` — Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`; тестовые классы package-private, зеркалят main-пакеты.
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` (пер-странично), `processTextPosition` для шрифта символа, обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`), счётчик картинок (`imageCount`/`distinctImageCount` — SMask игнорируется). Негативные маркеры: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`). Пиксельные проверки — только в юнитах chart-пейнтеров (допуски `assertRatio` < 0.06 / < 0.10, числа зашиты в тесты).
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары `XxxNormalizerTest`↔`тест-в-конвейере` воспроизводятся грепом по этим ссылкам; исключения (крафт POIFS, синтетика, app-регрессии) — `docs/agent/testing.md`.
- Фикстуры — только закоммиченные `samples/*.docx` (13) + `samples/*.doc` (12), в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (`assertSame`) + неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`).
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); четыре набора свойств = четыре кэшированных контекста (отдельные классы, не `@Nested` — `@Nested` + `@TestPropertySource` не даёт отдельного контекста); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring-контекста. Core-юниты Spring **не поднимают**; app-тесты не переигрывают семантику конвейера — только HTTP-код/заголовки/текст ошибки.
- Жизненный цикл: только `@Test` + два `@BeforeAll` (прогрев шрифтов в `BundledFontsTest`, `GlyphCoverageNormalizerTest`) + `@AfterEach drainWorker` в `ConversionTimeoutTest` (дренировать отменённый FOP-рендер — гонка глобального `PhysicalFonts`). Ни `@Nested`, ни `@ParameterizedTest`, ни `@Disabled`, ни `assertAll`.
- Идиомы загрузки фикстур различаются по модулю: **core** — classloader без ведущего слэша (`getResourceAsStream("samples/" + name)`), **app** — class-relative со слэшем (`getResourceAsStream("/samples/ru-plain.docx")`, ресурсы из core test-jar). Синтетика, когда фикстуры нет: docx — `ZipOutputStream` по строковому XML, `.doc` — крафт `POIFSFileSystem`.
- Сообщения ассертов — по-русски и с наблюдаемым значением (`assertTrue(cond, "нет «Привет, мир!»: " + text)`); сравнение строк литерал-слева (`"%PDF".equals(...)`, правило PMD `LiteralFirstInEquals`); контракт идентичности — `assertSame`/`assertNotSame`. Общих test-util-классов в репо нет: хелперы (`norm`, `pdfText`, `assertRatio`) намеренно продублированы по тест-классам.
- Прод-автотесты: pytest 9.1.1 + requests 2.34.2, 31 проверка (4 открытых + 27 под маркером `needs_key` → SKIP без ключа); конфигурация стенда **только env** (`WORDPDF_BASE_URL` обязателен — без него набор падает, а не подставляет дефолт; `WORDPDF_API_KEY`/`WORDPDF_MAX_PAGES`/`WORDPDF_MAX_MB`/`WORDPDF_SAMPLES_DIR` — факультативны).
- `mvn test` **не** запускает PMD и JaCoCo-гейты (оба на `verify`) — «зелёное» состояние проверяется `mvn clean verify`. `mvn -pl wordpdf-app` без `-am` падает: app зависит от core test-jar.
- Справочник: фикстуры и их смысл, юниты моста/нормализаторов/app, пиксели и стенд без fontconfig, регрессивные записи без javadoc-ссылок — `docs/agent/testing.md`.