feat(core): правило 9 DistributeStampNormalizer - w:jc=distribute растягивает все строки (Part 1 17.18.44)
docx4j для DISTRIBUTE не эмитит в FO ничего - абзац печатался по левому краю. Нормализатор ставит в distribute-абзацы закладку-якорь pj-distribute-<часть>-<n> (после Hidden, content-части, идемпотентно), LayoutPostRenderer по якорю дописывает блоку пару text-align/text-align-last=justify - межсловный разнос всех строк, включая последнюю (пин форка DistributeLineTestCase). Паттерн якоря принимает и префиксную, и безпрефиксную сериализацию fo:inline (DOM-поддерево toNode). Фикстура distribute.docx (хвост трёхсловный - одно слово растягивать нечем), регрессии distribute_allLinesReachRightMargin + юниты нормализатора и фильтра. Доки: правила 1-9 (Ole - правило 10), шаг 4.25, FOP-оверлей в инвариантах и новая секция AGENTS; render-limitations - distribute перенесён в починенное. Дополнительно в AGENTS: заметки про гейт готовности podman-контейнеров.
This commit is contained in:
@@ -18,16 +18,20 @@
|
||||
|
||||
Порядок шагов 0–7 фиксирован (`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`). Валидация — **до** `convertToStream`: `WordPdfValidator.validate(bytes, options)` (размер → подпись zip/CFB → контейнер → страницы); для `.doc` — `checkPageCountDoc` по сырым байтам.
|
||||
|
||||
Порядок: шрифты (`BundledFontMapper` → `BundledFonts.init` → `restrictToBundled`) и правила 1–8 (`DocxRewritePipeline.STEP`) + `OleObjectNormalizer` — до `WordprocessingMLPackage.load`; `FOSettings`/`FopFallbackFonts`/`LayoutPostRenderer` — до `setCustomXsltTemplates(VendoredXslt.TEMPLATES)`; `Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)` — последним; `finally` → `deleteEmbeddedFontTempFiles()` + сброс имиджевых кешей общей FopFactory + `BundledFonts.restrictToBundled()` (реестр шрифтов возвращается в бандл-состояние: `load()` регистрирует встроенные шрифты документа в глобальном `PhysicalFonts`). Полная таблица шагов и подсчёт страниц — `docs/agent/pipeline.md`.
|
||||
Порядок: шрифты (`BundledFontMapper` → `BundledFonts.init` → `restrictToBundled`) и правила 1–9 (`DocxRewritePipeline.STEP`) + `OleObjectNormalizer` — до `WordprocessingMLPackage.load`; `FOSettings`/`FopFallbackFonts`/`LayoutPostRenderer` — до `setCustomXsltTemplates(VendoredXslt.TEMPLATES)`; `Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)` — последним; `finally` → `deleteEmbeddedFontTempFiles()` + сброс имиджевых кешей общей FopFactory + `BundledFonts.restrictToBundled()` (реестр шрифтов возвращается в бандл-состояние: `load()` регистрирует встроенные шрифты документа в глобальном `PhysicalFonts`). Полная таблица шагов и подсчёт страниц — `docs/agent/pipeline.md`.
|
||||
|
||||
## Нормализаторы (`internal/DocxNormalizer`)
|
||||
|
||||
Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame`). Порядок фиксирован: Strict→OnOff→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby. Правила 1–8 применяет `DocxRewritePipeline.STEP` одним zip-проходом (неизменённые записи копируются raw-сжатыми байтами); `OleObjectNormalizer` (правило 9) — лямбдой в `WordPdfConverter.normalizers()`. `STEP` выставляют 7 из 8 rewrite-нормализаторов (нет у `RubyNormalizer`), у `OleObjectNormalizer` её нет. Правил Symbol-шрифтов и complex-полей PAGE/NUMPAGES больше нет — с docx4j 17.3.x их делает сам экспорт (#701, CR-067); пины отсутствия регрессии — `symbolFonts_bulletsAreNotHash`, `pageNumbers_recomputedNotCached`. Правила 1–9, guard'ы, номера секций и инвариант `mc-preprocessor.xslt` (собственный рерайт strict-URI ломать нельзя) — `docs/agent/pipeline.md`.
|
||||
Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame`). Порядок фиксирован: Strict→OnOff→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby→Distribute. Правила 1–9 применяет `DocxRewritePipeline.STEP` одним zip-проходом (неизменённые записи копируются raw-сжатыми байтами); `OleObjectNormalizer` (правило 10) — лямбдой в `WordPdfConverter.normalizers()`. `STEP` выставляют 8 из 9 rewrite-нормализаторов (нет у `RubyNormalizer`), у `OleObjectNormalizer` её нет. Правил Symbol-шрифтов и complex-полей PAGE/NUMPAGES больше нет — с docx4j 17.3.x их делает сам экспорт (#701, CR-067); пины отсутствия регрессии — `symbolFonts_bulletsAreNotHash`, `pageNumbers_recomputedNotCached`. Правила 1–9, guard'ы, номера секций и инвариант `mc-preprocessor.xslt` (собственный рерайт strict-URI ломать нельзя) — `docs/agent/pipeline.md`.
|
||||
|
||||
## Мост `.doc` → `.docx` (`internal/doc`)
|
||||
|
||||
18 классов, 17 package-private; наружу — только `DocToDocx` (`convert`/`countPages`). Общий разбор — `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`.
|
||||
|
||||
## FOP-оверлей (`ru.pjandro:docx4j-fo-renderer-core`)
|
||||
|
||||
Форк `org.docx4j:docx4j-fo-renderer-core` 2.12-docx4j.1 (он же Apache FOP 2.12) в репо `ai/xmlgraphics-fop-pj` (Gitea); версии вида `2.12-docx4j.1-pj.N` (наследование по схеме форка, README репо), артефакты — Nexus maven-hosted (входит в `maven-public`). Подключение: в `wordpdf-core/pom.xml` — exclusion `org.docx4j:docx4j-fo-renderer-core` из `docx4j-export-fo` + зависимость `ru.pjandro:docx4j-fo-renderer-core` (версия `${fop-overlay.version}` в корневом pom); тонкий `docx4j-fo-renderer` (hooks-маркер `Docx4jFop`) НЕ исключается. В оверлее наши патчи помечены `Added by pjandro`/`CR-0xx`, тесты — package `org.apache.fop.layoutmgr.word` (в т.ч. `DistributeLineTestCase` — пин justify-пары для distribute). Новый релиз оверлея: `mvn deploy` в репо форка → bump `fop-overlay.version` → `mvn clean verify` здесь. Пайплайн CI форка не связан с этим репо.
|
||||
|
||||
## REST API (`wordpdf-app`, всё package-private кроме `WordPdfApplication`)
|
||||
|
||||
`POST /api/v1/convert`: multipart-поле `file` (`.docx`/`.doc`) + query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолт каждого — `false`), `maxMb`/`maxPages` (лимиты входа: переопределяют серверный дефолт в обе стороны; ≤ 0 → 400). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`; имя — `ConversionService.safeBaseName`. Тело ошибки — `{"error": …}`. Error-флаги на `.doc` **не срабатывают** (BLIP-плейсхолдеры → картинки). `ApiExceptionHandler` не видит ошибок фильтров — 401 пишет сам `ApiKeyFilter`.
|
||||
@@ -51,11 +55,11 @@ Java2D → PNG: `ChartRenderer.DPI = 300`, потолок `MAX_PIXELS = 16_777_2
|
||||
- `docx4j.fonts.discoverPhysicalFonts.enabled=false` и `discoverJarFonts.enabled=false` — static-блок: иначе `BestMatchingMapper` сканирует системные шрифты и jar'ы classpath'а, а `restrictToBundled()` всё найденное выбрасывает (~100–140 мс впустую на JVM). `discoverJarFonts("fonts-symbol")` свойством не гейтится — символ-шрифт регистрируется и снимается restrict'ом как раньше.
|
||||
- Единственный XSL-FO-стилист — вендорный `xslt/docx2fo.xslt` (копия из docx4j-export-fo 17.3.6 + два 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.
|
||||
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.12-docx4j.1 (транзитив от `docx4j-export-fo`, в pom не пинится; пакеты `org.apache.fop.*`). `FopFallbackFonts` берёт `w:renderer` с mime `application/pdf`, иначе первый со шрифтами.
|
||||
- FOP — собственный оверлей `ru.pjandro:docx4j-fo-renderer-core:${fop-overlay.version}` (форк `org.docx4j:docx4j-fo-renderer-core` 2.12-docx4j.1 = FOP 2.12 + word-layout; пакеты `org.apache.fop.*`; репо `ai/xmlgraphics-fop-pj`, артефакт — Nexus). `docx4j-export-fo` исключает центральный `org.docx4j:docx4j-fo-renderer-core`; тонкий `docx4j-fo-renderer` (маркер `Docx4jFop`, хук word-layout) остаётся из `docx4j-export-fo`. `FopFallbackFonts` берёт `w:renderer` с mime `application/pdf`, иначе первый со шрифтами.
|
||||
- `BundledFonts.init()` идемпотентен, распаковывает TTF в `wordpdf-fonts-*` (`deleteOnExit`); `dropNonBundled()` чистит `PhysicalFonts` от всего, что вне бандла; ВСЕ синхронизированные методы `BundledFonts` (`init`/`restrictToBundled`/`font`) держат монитор `WordPdfConverter.class` (не собственный замок класса) — тот же, что сериализует конвертации, поэтому внешний вызов рядом с идущей конвертацией безопасен автоматически. Регрессия — `WordPdfConverterTest#concurrentFontMutators_conversionsUnharmed`.
|
||||
- `PhysicalFonts` — глобальный и мутируемый → конвертации сериализуются монитором `WordPdfConverter.class` внутри ядра (общая `FopFactory` и сброс её image-кешей — под тем же монитором); приложение держит однопоточный воркер ради 503/timeout; `warmup()` идёт тем же потоком.
|
||||
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; правила StAX-подсчёта — `docs/agent/pipeline.md`.
|
||||
- Не чинить: `jc="distribute"` (в FOP-форке 2.12 есть `text-align-last`, но маппинг `Justification` не эмитит его и межсимвольного разноса нет), `suff="tab"`/`lvlJc`, метрика «single», кернинг, `REF`/`SEQ`/`TOC`-кэш, руби-надстрочница, U+2188/U+218A — доказательства в `docs/agent/render-limitations.md`. `framePr` починен апстримом 17.3.6 (фрейм позиционируется).
|
||||
- Не чинить: `suff="tab"`/`lvlJc`, метрика «single», кернинг, `REF`/`SEQ`/`TOC`-кэш, руби-надстрочница, U+2188/U+218A — доказательства в `docs/agent/render-limitations.md`. `framePr` починен апстримом 17.3.6 (фрейм позиционируется); `jc="distribute"` починен правилом 9 + justify-парой в `LayoutPostRenderer` (межсловный разнос всех строк, межсимвольный kashida не реализован).
|
||||
- Комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.6 (описанное поведение верно).
|
||||
|
||||
## Шрифты (30 TTF + 3 лицензии, SIL OFL, `wordpdf-core/src/main/resources/fonts/`)
|
||||
@@ -84,6 +88,13 @@ python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources
|
||||
|
||||
**«Запусти тестовый сервер» (термин пользователя)** = полный dev-стенд, НЕ `java -jar`: `podman-compose -f compose.dev.yml up -d --build --force-recreate`, вход `http://<LAN-IP хоста>:9011` без API-ключа; гейт — контейнеры healthy + корень SPA отвечает 200. `--force-recreate` обязателен: без него контейнеры остаются на старом образе.
|
||||
|
||||
**Ожидание готовности podman-контейнеров** (одинаково для dev-стенда и для собственных тестовых контейнеров):
|
||||
- Гейт — наблюдаемый факт готовности, а не «подождал N секунд»: HTTP-эндпоинт сервиса (`curl -fs --max-time 2 …`) или, для контейнера с healthcheck, `podman inspect <name> --format '{{.State.Health.Status}}'` = `healthy`.
|
||||
- Ждать — синхронным `until`-циклом с жёстким потолком и коротким шагом, в том же вызове, что и идущая сразу за гейтом проверка: `timeout 180 sh -c 'until curl -fs --max-time 2 http://127.0.0.1:9011/ -o /dev/null; do sleep 2; done' && <смоук>`. Готово — цикл выходит за секунды; потолок срабатывает только при настоящей неполадке (тогда читать `podman logs <name>`).
|
||||
- **Нельзя** считать `healthy` по всему списку контейнеров (`grep -c healthy`): у контейнеров без healthcheck (nginx-гейтстенд) статус никогда не содержит `healthy` — такой цикл молча крутится до самого дедлайна, стена при этом уже готова. У контейнеров без healthcheck единственный гейт — HTTP.
|
||||
- **Нельзя** крутить цикл ожидания отдельным async-job'ом и поллить его: либо `podman-compose up` + `until`-гейт + смоук одним синхронным вызовом, либо (если сборка образа долгая и уходит в фон) — по её завершении гейт-цикл синхронно.
|
||||
- Одноразовая проверка в контейнере вообще не ждёт готовности: `podman run --rm <image> <cmd>` блокирующий — читать exit code и stdout.
|
||||
|
||||
Пересоздание фикстур и перевендоривание стилиста — `docs/agent/repo-map.md`. Деплой: **прод** — на пользовательском LAN-сервере; **перед деплоем/перезапуском прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md`**; пуск — push в `main` или Run workflow, ручных скриптов нет (детали — `docs/agent/ci-cd.md`).
|
||||
|
||||
## Code Conventions & Common Patterns
|
||||
|
||||
Reference in New Issue
Block a user