838ec29a69
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-контейнеров.
141 lines
32 KiB
Markdown
141 lines
32 KiB
Markdown
# Repository Guidelines
|
||
|
||
> Роутер: правила, инварианты и команды — здесь; глубокие детали — `docs/agent/*.md`, нормативные форматы — `docs/standards/` (ссылка с номером секции обязательна), пользовательская документация — `README.md`.
|
||
|
||
## Project Overview
|
||
|
||
Конвертер `.docx`/`.doc` → `.pdf` на чистом Java: docx4j 17.3.6 → XSL-FO → форк Apache FOP, без LibreOffice/Aspose. Бинарный `.doc` (Word 97-2003) переносится мостом MS-DOC/MS-CFB (`internal/doc`) в in-memory `.docx` и идёт тем же конвейером. Java 17, только Maven.
|
||
|
||
| Модуль | Содержимое |
|
||
|---|---|
|
||
|`wordpdf-core`|библиотека: 59 Java-файл (6 — публичный API, 14 `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-реактора, отдельный образ |
|
||
|
||
Единственный вход стека — gateway-контейнер nginx (`:9010` prod-like `compose.yml`, `:9011` dev `compose.dev.yml`), **не** 8080. Авторитетны этот файл, `docs/agent/` и код. Полный путеводитель по каталогам, ключевым файлам и командам — `docs/agent/repo-map.md`.
|
||
|
||
## Пайплайн `WordPdfConverter.convert(byte[], String[, ConvertOptions])`
|
||
|
||
Порядок шагов 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–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→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`.
|
||
|
||
- **Коды**: 400 — `ValidationException`/`BadRequestException`/битые параметры; 401 — `ApiKeyFilter`; 404/405/415 — путь/метод/content-type; 413 — multipart; **422** — `DrawingRejectedException` (core-`DrawingFoundException`, `Kind {CHARTS, SMARTART, OLE}`); 500/503/504 — `ConversionFailedException`/`ConversionRejectedException`/`ConversionTimeoutException`. 500 отвечает фиксированный текст («Внутренняя ошибка конвертации») — сообщение ядра логируется, наружу не попадает. Полная карта — `docs/agent/repo-map.md`.
|
||
- **Текст 422** — контракт с фронтом: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты».
|
||
- **Ключ**: `X-API-Key` ↔ `wordpdf.api-key` (пустое = выключено); без ключа открыты только `OPEN_PREFIXES` (`/actuator/`, `/swagger-ui`, `/v3/api-docs`), пути с точечными сегментами — никогда.
|
||
- **Очередь и лимиты**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`QUEUE_CAPACITY = 16`, переполнение → 503): ядро дополнительно сериализует конвертации монитором `WordPdfConverter.class` (`convert()` безопасен из нескольких потоков); головой очереди на старте стоит `warmup()`. До очереди — только дешёвый гейт размера (`WordPdfValidator.checkInput` на потоке Tomcat); полный `validate` (контейнер/страницы — бюджеты распаковки и прочие пороги выводятся из лимитов входа `maxMb`/`maxPages` методом `WordPdfValidator.max*`, крышек нет) выполняется внутри воркера ядром, `ValidationException` из `ExecutionException` пробрасывается как 400. Лимиты входа: `wordpdf.max-mb`/`max-pages` — дефолт эндпоинта (литералы 5/100 в `@Value`; значение свойства ≤ 0 → `IllegalStateException` на старте); параметры запроса `maxMb`/`maxPages` переопределяют дефолт в обе стороны (≤ 0 → 400), верхнего потолка нет.
|
||
- **SPA**: вся сеть в `wordpdf-web/src/api.ts`; ключ в `localStorage` (`wordpdf.api.key`); `ApiKeyGate` — только если `probeApiKey()` подтвердил требование ключа (признак открытого сервера — **405**); base — `VITE_BASE`; DropZone `.docx,.doc`.
|
||
|
||
## Chart/SmartArt-движок (`internal/chart`, 18 классов)
|
||
|
||
Нормативный источник — ECMA-376 (`docs/standards/ooxml/`: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D, XSD); поведение Word — `ms-oi29500.md`, `ms-odrawxml.md`. Калибровки (камера, `PIE_DEPTH`) меняются только с пиксельными тестами; невалидная фикстура правится, не код.
|
||
|
||
Java2D → PNG: `ChartRenderer.DPI = 300`, потолок `MAX_PIXELS = 16_777_216` (`fitDpi`); лимиты `ChartSpec.MAX_POINTS = 100_000`, `ChartRenderer.MAX_TICKS = 1000`, `DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000`, суммарный бюджет chart-PNG на документ `MAX_CHART_PNG_BYTES_TOTAL = 128 MiB` (превышение — объект удалён + warn; тестовый шов `run(pkg, options, maxPngBytesTotal)`) — деградация «объект как есть / удалён + warn», не OOM; сам `OutOfMemoryError` при рендере — не деградация, а `ConversionException` (500: состояние кучи после OOM ненадёжно). Chart-PNG вставляются media-частями вручную (`addChartMedia`, `/word/media/chart-*`, без `createImagePart`); `ChartImageHandler` отключает «Compress Pictures» (CR-029) только для них. Пейнтеры, `autoTitleDeleted`, Combo, обходы JAXB — `docs/agent/chart.md`.
|
||
|
||
## Критические инварианты (нарушение = битый вывод, не исключение)
|
||
|
||
- `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`; иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам → FOP падает на `docx4j-baseline`.
|
||
- `docx4j.openpackaging.load.repair=word` — static-блок `WordPdfConverter` (17.3.6, `RepairMode`): с дефолтным NONE пакеты, которые Word открывает через «восстановить» (напр. case-folded дубликаты zip-записей), отказываются грузиться — для конвертера это 500 на читаемых Word файлах.
|
||
- `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 — собственный оверлей `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`.
|
||
- Не чинить: `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/`)
|
||
|
||
9 семейств: 7 × 4 начертания (Carlito/Caladea/Arimo/Tinos/Cousine/DejaVu Sans/DejaVu Serif) + Noto Naskh Arabic / Noto Sans Armenian (только regular). `BundledFontMapper.ALIASES`: Calibri→Carlito, Calibri Light→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; **self-map** всех бандл-семейств, включая Noto; fallback — DejaVu Sans; виртуальный `SYMBOL_FONT` «Segoe UI Symbol» (U+2000–U+2EFF) → fallback до основного цикла. Новый шрифт = файл + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`). `GlyphFont` читает TTF напрямую с classpath через fontbox, **без** `java.awt.Font` (нужен fontconfig на хосте). Публичный API и детали — `docs/agent/repo-map.md`.
|
||
|
||
## Команды
|
||
|
||
Бутстрап: `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 # -am: core test-jar
|
||
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
|
||
./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-стенд :9011, без ключа
|
||
./mise.sh run prod-tests # прод-автотесты в 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` обязателен: без него контейнеры остаются на старом образе.
|
||
|
||
**Ожидание готовности 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
|
||
|
||
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе: `BundledFontMapper`, `DrawMlColor`, Spring-компоненты `wordpdf-app`.
|
||
- В `internal/**` классы package-private, `public` — только вызываемые извне пакета: в `internal` — `DocxNormalizer`, `DocxRewritePipeline` (наружу только `STEP`), `OleObjectNormalizer` (только `normalize(byte[], boolean)`), `FopFallbackFonts` (`declare`), `LayoutPostRenderer` (`register`/`render`), `DependencyGuard` (`check`); в `internal/chart` — `DrawingPreRenderer` (`run`) и `ChartImageHandler`. Публичные члены наружу ничем шире этого не расширять; `rewrite`-хуки — package-private. В `wordpdf-app` всё package-private кроме `WordPdfApplication`; в `internal/doc` публичен только `DocToDocx`.
|
||
- Нормализаторы — единый контракт `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`, `DECOMPRESS_MB_PER_MAX_MB`); начертания `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`), юниты — camelCase (`pageFieldBecomesFldSimple`); оба стиля разрешает PMD-паттерн `junit5TestPattern` (`^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$`).
|
||
- PMD (`pmd-ruleset.xml`, execution `pmd-check` на `verify` в обоих модулях, `includeTests=true`, валится нарушение любой приоритетности): полные исключения категории, кастомное XPath-правило `LiteralFirstInEquals` и настройки — в самом ruleset.
|
||
|
||
## Runtime & Tooling
|
||
|
||
- Java 17 + Maven (обязательны; wrapper `mvnw` НЕТ); UTF-8; только Maven — никаких Gradle/Ant. Инструменты (Java/Maven/Node/Python) ставит project-local mise (бинарь в `.mise/`, вне системы), версии пинятся в корневом `mise.toml`; ежедневный запуск — `./mise.sh`.
|
||
- Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement), новые — latest stable; закреплённый список — `docs/agent/repo-map.md`. Maven-зависимости — через Nexus `maven-central`: локально `~/.m2/settings.xml` (файл вне репо), CI/Containerfile — `.ci/maven-settings.xml` + `MAVEN_MIRROR_URL`.
|
||
- Фронт: 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`; нюанс `BundledFontsTest` (`file:`-протокол classpath) — `docs/agent/repo-map.md`.
|
||
- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`; защищённые ветки — `main`, `master`, `dev`. Все правки — через PR в дефолтную ветку; push — завершающим шагом задачи, только после `./mise.sh run verify`.
|
||
- Прод-координаты и креды в коммитимые файлы **не попадают** (ни IP, ни хостов, ни пользователей, ни ключей): стенд — Gitea Actions Variables, креды — Secrets; workflow-файлы ссылаются только на `${{ vars.* }}`/`${{ secrets.* }}` (список — `GITEA-vars.md`). Локальный `.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` при провале. Нарратив — `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/`). Механика — `docs/agent/repo-map.md`. Плотность покрытия держат тесты, а не заглушки.
|
||
- Стек: JUnit 6 (`org.junit.jupiter`), только `Assertions` — Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `containsString` в `andExpect`; тестовые классы package-private, зеркалят main-пакеты. Счётчики — `docs/agent/testing.md`.
|
||
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3, `PDFTextStripper`; негативные маркеры — `.notdef` (`#`) и `Helvetica`; текст нормализуется по пробелам (`norm`). Пиксельные проверки — только в юнитах chart-пейнтеров (допуски `assertRatio` < 0.06 / < 0.10). Детали — `docs/agent/repo-map.md`.
|
||
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары `XxxNormalizerTest`↔`тест-в-конвейере` воспроизводятся грепом по этим ссылкам; исключения — `docs/agent/testing.md`.
|
||
- Фикстуры — только закоммиченные `samples/*.docx` (13) + `samples/*.doc` (12), в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (`assertSame`) + неприкосновенность частей вне `word/*.xml`.
|
||
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); четыре набора свойств = четыре контекста (отдельные классы, не `@Nested`); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring. Core-юниты Spring **не поднимают**; app-тесты проверяют только HTTP-код/заголовки/текст ошибки. Детали — `docs/agent/testing.md`.
|
||
- Жизненный цикл: только `@Test`; исключения — два `@BeforeAll` (прогрев шрифтов) и `@AfterEach drainWorker` в `ConversionTimeoutTest`. Ни `@Nested`, ни `@ParameterizedTest`, ни `@Disabled`, ни `assertAll`.
|
||
- Идиомы загрузки фикстур: **core** — classloader без ведущего слэша, **app** — class-relative со слэшем (core test-jar). Синтетика: docx — `ZipOutputStream`, `.doc` — крафт `POIFSFileSystem`.
|
||
- Сообщения ассертов — по-русски и с наблюдаемым значением; сравнение строк литерал-слева (`"%PDF".equals(...)`, PMD `LiteralFirstInEquals`); контракт идентичности — `assertSame`/`assertNotSame`. Общих test-util-классов нет: хелперы (`norm`, `pdfText`, `assertRatio`) намеренно продублированы.
|
||
- Прод-автотесты: pytest + requests; под маркером `needs_key` без ключа SKIP; конфигурация стенда **только env** (`WORDPDF_BASE_URL` обязателен).
|
||
- `mvn test` **не** запускает PMD и JaCoCo-гейты (оба на `verify`) — «зелёное» состояние проверяется `mvn clean verify`. `mvn -pl wordpdf-app` без `-am` падает: app зависит от core test-jar.
|