From 08c68305be63d85cd5281eda49cd0839fe209764 Mon Sep 17 00:00:00 2001 From: Pjandro Date: Tue, 17 Nov 2026 04:14:23 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B0=D0=BA=D1=82=D1=83=D0=B0=D0=BB?= =?UTF-8?q?=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D1=8F=20AGENTS.md=20=D0=BF=D0=BE?= =?UTF-8?q?=20=D1=81=D0=B2=D0=B5=D0=B6=D0=B5=D0=B9=20=D1=81=D0=B2=D0=B5?= =?UTF-8?q?=D1=80=D0=BA=D0=B5=20=D1=81=20=D0=BA=D0=BE=D0=B4=D0=BE=D0=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - convert — только 3-аргументная сигнатура; App.tsx в components/; 11 zip-правил + OleObjectNormalizer как 12-й байтовый - REST: открытые префиксы ApiKeyFilter, тело {"error": …}, карта 404/405/415 в repo-map - расхождение compose (prod-like гасит springdoc, CI-прод держит swagger открытым); VITE_BASE в образе; подсети resolver; WORDPDF_SAMPLES_DIR; ручные фикстуры не перезаписывать --- AGENTS.md | 66 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 346fd5d..e550ed4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,45 +1,46 @@ # Repository Guidelines -> Роутер: правила, инварианты и команды — здесь; глубокие детали — `docs/agent/*.md` (pipeline, doc-bridge, chart, testing, ci-cd, render-limitations, repo-map — каждый авторитетен наравне с этим файлом), нормативные форматы — `docs/standards/` (ссылка с номером секции обязательна). +> Роутер: правила, инварианты и команды — здесь; глубокие детали — `docs/agent/*.md` (pipeline, doc-bridge, chart, testing, ci-cd, repo-map, render-limitations — каждый авторитетен наравне с этим файлом), нормативные форматы — `docs/standards/` (навигатор — `docs/standards/README.md`, ссылка на спецификацию — с номером секции). ## 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` и идёт тем же конвейером. Maven-мультимодуль `ru.pjandro:java-word-pdf:1.0.0`: `wordpdf-core` (библиотека), `wordpdf-app` (REST на Spring Boot 4.1.1); вне Maven-реактора — SPA `wordpdf-web` (React 19 + TS + Vite + Tailwind v4) и pytest-автотесты `prod-autotests/`. Java 17, только Maven. +Конвертер `.docx`/`.doc` → `.pdf` на чистом Java: docx4j 17.3.2 → XSL-FO → форк Apache FOP (`org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 — транзитив от `docx4j-export-fo`), без LibreOffice/Aspose. Бинарный `.doc` (Word 97-2003) переносится мостом MS-DOC/MS-CFB (`internal/doc`) в in-memory `.docx` и идёт тем же конвейером. Maven-мультимодуль `ru.pjandro:java-word-pdf:1.0.0`: `wordpdf-core` (библиотека), `wordpdf-app` (REST на Spring Boot 4.1.1); вне Maven-реактора — SPA `wordpdf-web` (React 19 + TS + Vite 8 + oxlint + Tailwind v4, npm) и pytest-автотесты `prod-autotests/`. Java 17, только Maven. ## Architecture & Data Flow -Единственный вход стека — gateway-контейнер nginx (`:9010` prod-like `compose.yml`, `:9011` dev `compose.dev.yml`), **не** 8080. +Единственный вход стека — gateway-контейнер nginx (`:9010` prod-like `compose.yml`, `:9011` dev `compose.dev.yml`), **не** 8080. Реальный прод-стек (`docker-compose.yml` + прод `nginx.conf`) рендерит CI-job `deploy` — копий на хосте/в репо не заводить. -**Пайплайн** `WordPdfConverter.convert(byte[], String[, ConvertOptions])` → `convertToStream`; порядок шагов фиксирован: +**Пайплайн** `WordPdfConverter.convert(byte[] docxBytes, String title, ConvertOptions)` → `convertToStream` (публичная сигнатура единственная, 2-аргументной перегрузки **нет**); порядок шагов фиксирован: 0. `DependencyGuard.check()` (commons-compress ≥ 1.25.0 API-проба); 1. шрифты: `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` — строго в этом порядке, до `load()`; 2. нормализаторы (`DocxRewritePipeline.STEP` + лямбда `OleObjectNormalizer`) → `WordprocessingMLPackage.load`; 3. `setFontMapper`; 3.5 `DrawingPreRenderer.run` (chart/SmartArt → PNG; error-флаги бросаются здесь) — **обязателен до `FOSettings`**, иначе FOP молча теряет диаграммы; 4. `FOSettings` + `ChartImageHandler` + `FopFallbackFonts.declare` + `LayoutPostRenderer.register` + `setCustomXsltTemplates(VendoredXslt.TEMPLATES)`; -5. общая `FopFactory` (DCL); 6. `Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)` — последним; +5. общая `FopFactory` (DCL на мониторе `WordPdfConverter.class`); +6. `Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)` — последним; 7. `finally`: сброс temp-шрифтов, `resetSharedImageCaches()` (иначе ~1,5 ГБ за 30 конвертаций), `restrictToBundled()` (иначе встроенные в предыдущий docx шрифты травят реестр). Вход роутируется по сигнатуре: `PK\x03\x04` → docx; `D0 CF 11 E0 A1 B1 1A E1` (CFB) → `DocToDocx.convert`. Валидация `WordPdfValidator` — **до** конвертера (для `.doc` страницы считаются по сырым байтам); `WordPdfValidator` не трогает docx4j — его пороги в `WordPdfConverter` объявлены compile-time literals (javac инлайнит, static-блок конвертера не дёргается). **Слои ядра** (`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`): -- публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConvertOptions` (record), `ConversionException` + `ValidationException` (бросает **только** валидатор) + `Charts/SmartArt/OleFoundException`; `warmup()` — идемпотентный прогрев, решает вызывающий; -- `internal/`: контракт нормализатора — `byte[] normalize(byte[])`, нечего менять → **тот же массив** (`assertSame`); правила 1–11 идут одним zip-проходом `DocxRewritePipeline.STEP` в фиксированном порядке: Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby→MathFallback; неизменённые записи копируются raw-сжатыми байтами; наружу только `DocxNormalizer`, `DocxRewritePipeline.STEP`, `OleObjectNormalizer`, `FopFallbackFonts`, `LayoutPostRenderer`, `DependencyGuard`; +- публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConvertOptions` (record `errorOnCharts/errorOnSmartArt/errorOnOle/maxMb/maxPages`), `ConversionException` + `ValidationException` (бросает **только** валидатор) + `Charts/SmartArt/OleFoundException`; `warmup()` — идемпотентный прогрев, решает вызывающий; +- `internal/`: контракт нормализатора — `byte[] normalize(byte[])`, нечего менять → **тот же массив** (`assertSame`); правила 1–11 идут одним zip-проходом `DocxRewritePipeline.STEP` в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby→MathFallback, `OleObjectNormalizer` — 12-й, отдельным байтовым проходом (не zip); неизменённые записи копируются raw-сжатыми байтами; наружу только `DocxNormalizer`, `DocxRewritePipeline.STEP`, `OleObjectNormalizer`, `FopFallbackFonts`, `LayoutPostRenderer`, `DependencyGuard`; - `internal/doc`: мост `.doc`→`.docx`, 18 классов, наружу только `DocToDocx.convert/countPages`; раскладки — `docs/agent/doc-bridge.md`; - `internal/chart`: Java2D → PNG (`ChartRenderer.DPI = 300`, `MAX_PIXELS` 4096² — понижает dpi через `fitDpi`; `MAX_POINTS` 100 000, бюджет chart-PNG на документ 128 MiB); модель **деградации**: битая chart-часть/превышение бюджета → объект удалён + warn, конвертация продолжается; `OutOfMemoryError` — не деградация, а `ConversionException` (500); - `fonts/GlyphFont`: метрика/глифы через fontbox напрямую, **без** `java.awt.Font` (fontconfig хосту не нужен). -**Concurrency-инвариант**: `PhysicalFonts` — глобальный мутируемый реестр → все конвертации сериализованы монитором `WordPdfConverter.class` (convert, warmup, DCL-фабрика, мутации `BundledFonts`). Приложение дополнительно держит однопоточный `ThreadPoolExecutor` (очередь 16 → 503, `wordpdf.convert-timeout=2m` → 504), головой очереди стоит `warmup()`. +**Concurrency-инвариант**: `PhysicalFonts` — глобальный мутируемый реестр → все конвертации сериализованы монитором `WordPdfConverter.class` (convert, warmup, DCL-фабрика, мутации `BundledFonts`, `BundledFonts.font()`). Приложение дополнительно держит однопоточный `ThreadPoolExecutor` (очередь 16 → 503, `wordpdf.convert-timeout=2m` → 504), головой очереди стоит `warmup()`; `WordPdfValidator.checkInput` выполняется синхронно до очереди. -**REST** (`wordpdf-app`, всё package-private кроме `WordPdfApplication`): `POST /api/v1/convert` (multipart `file` + `errorOnCharts/errorOnSmartArt/errorOnOle`, `maxMb/maxPages` переопределяют серверный дефолт в обе стороны, ≤ 0 → 400). Коды: 400 валидация/битые параметры, 401 `ApiKeyFilter` (`X-API-Key` ↔ `wordpdf.api-key`, пусто = выключено; Advice фильтров не видит — 401 пишет сам), 413 multipart, **422** отказ по графике (`DrawingRejectedException`, текст — контракт с фронтом), 500 `ConversionFailedException` (текст ядра только в лог), 503 переполнение очереди, 504 timeout. Полная карта — `docs/agent/repo-map.md`. На `.doc` error-флаги не срабатывают (BLIP-плейсхолдеры — уже растры). +**REST** (`wordpdf-app`, всё package-private кроме `WordPdfApplication`): `POST /api/v1/convert` (multipart `file` + `errorOnCharts/errorOnSmartArt/errorOnOle`, `maxMb/maxPages` переопределяют серверный дефолт в обе стороны, ≤ 0 → 400). Коды: 400 валидация/битые параметры, 401 `ApiKeyFilter` (`X-API-Key` ↔ `wordpdf.api-key`, пусто = выключено, сравнение `MessageDigest.isEqual`; открытые префиксы `/actuator`, `/swagger-ui`, `/v3/api-docs`; Advice фильтров не видит — 401 пишет сам), 413 multipart, **422** отказ по графике (`DrawingRejectedException`, текст — контракт с фронтом), 500 `ConversionFailedException` (текст ядра только в лог), 503 переполнение очереди, 504 timeout; тело ошибки — `{"error": …}` (`record ApiError`). Полная карта, включая 404/405/415, — `docs/agent/repo-map.md`. На `.doc` error-флаги не срабатывают (BLIP-плейсхолдеры — уже растры). -**SPA** (`wordpdf-web/src`): вся сеть — единственная точка `api.ts` (ключ в localStorage `wordpdf.api.key`, `probeApiKey()`: 401=required / 405=open); единственный источник состояния — `useState` в `App.tsx`. +**SPA** (`wordpdf-web/src`): вся сеть — единственная точка `api.ts` (ключ в localStorage `wordpdf.api.key`, `probeApiKey()`: 401=required / иначе open; имя файла из `Content-Disposition filename*=utf-8''`); единственный источник состояния — `useState` в `components/App.tsx` (+ `useRef` для `AbortController`/blob-URL), store-библиотек нет; лимиты на клиенте не задаются — только сервер. ### Критические инварианты (нарушение = битый вывод, не исключение) - Static-блок `WordPdfConverter`: `docx4j.convert.out.fo.gsubFeatures=false` (иначе `WordLayoutFixups` отказывает всем фиксам → FOP падает), `docx4j.fonts.discoverPhysicalFonts.enabled=false`, `discoverJarFonts.enabled=false` — не удалять. -- Единственный XSL-FO-стилист — вендорный `wordpdf-core/src/main/resources/xslt/docx2fo.xslt` (копия из docx4j-export-fo 17.3.2 + AUDIT-FIX-патчи); обновление docx4j = ручной перенос патчей; дрейф-гейт `vendoredXsltTracksJarCopy`. -- `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF; в app исключён (logback). +- Единственный XSL-FO-стилист — вендорный `wordpdf-core/src/main/resources/xslt/docx2fo.xslt` (копия из docx4j-export-fo 17.3.2 + AUDIT-FIX-патчи); обновление docx4j = ручной перенос патчей; дрейф-гейт `vendoredXsltTracksJarCopy`; команда ре-вендоринга — `docs/agent/repo-map.md`. +- `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF; в app исключён (logback). Fontbox логируется commons-logging — единственный мост `jcl-over-slf4j`. - FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 (транзитив от `docx4j-export-fo`, в pom не пинится); расхождения с upstream-доками FOP нормальны; `lineRule=auto` не «чинить». - Chart-media префикс `/word/media/chart-*` — пакетный контракт с `ChartImageHandler` (отключение пересжатия); переименование молча вернёт мыльный ресемпл. - Стоп-лист «не чинить» (до любой попытки починить расхождение с Word — `docs/agent/render-limitations.md`): `jc="distribute"`, `suff="tab"`/`lvlJc`, кернинг, `framePr`, `REF`/`SEQ`/`TOC`-кэш, руби-надстрочница, `ptab`, U+2188/U+218A (GPL-шрифты не добавляем). @@ -52,15 +53,15 @@ |`wordpdf-core/src/main/resources/`|`fonts/` (30 TTF + лицензии OFL), `xslt/docx2fo.xslt`, `slf4j-simple.properties`| |`wordpdf-core/src/test/resources/samples/`|фикстуры: 13 `.docx` + 12 `.doc` (закоммичены, билдятся в test-jar для app)| |`wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/`|REST-слой (11 классов)| -|`wordpdf-web/src/`|SPA: `api.ts` (сеть), `App.tsx` (состояние), `components/`| +|`wordpdf-web/src/`|SPA: `api.ts` (вся сеть), `components/` (`App.tsx` — состояние, `ApiKeyGate`, `DropZone`, `PdfPreview`, `StatusMessage`, `Logo`)| |`prod-autotests/`|pytest-проверки живого стенда (31: 4 открытые + 27 `needs_key`)| |`docs/agent/` · `docs/standards/`|справочники поведения · закоммиченные спецификации (ECMA-376, MS-DOC/CFB/ODRAW…, навигатор — `docs/standards/README.md`)| |`gateway/nginx.conf`|прод-like шлюз (`client_max_body_size 100m`, таймауты 300 с)| -|`develop/`|вне git: эталоны Word — **не фикстуры**, в тесты/jar не подключать| +|`develop/`|вне git (gitignored): эталоны Word — **не фикстуры**, в тесты/jar не подключать| ## Development Commands -Бутстрап: `sh bootstrap.sh` (Windows: `powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1`) — project-local mise в `./.mise/`, дальше всё через `./mise.sh` / `.\mise.ps1`. +Бутстрап: `sh bootstrap.sh` (Windows: `powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1`) — project-local mise 2026.10.19 в `./.mise/`, дальше всё через `./mise.sh` / `.\mise.ps1`. ```bash ./mise.sh run verify # = mvn clean verify: тесты + PMD + JaCoCo (гейт перед push) @@ -75,7 +76,7 @@ podman-compose -f compose.dev.yml up -d --build --force-recreate # dev-сте python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD (lxml) ``` -- «Запусти тестовый сервер» (термин пользователя) = dev-стенд выше, **не** `java -jar`; гейт готовности — контейнеры healthy + корень SPA 200; `--force-recreate` обязателен. +- «Запусти тестовый сервер» (термин пользователя) = dev-стенд выше, **не** `java -jar`; вход — `http://:9011` (`hostname -I`); гейт готовности — контейнеры healthy (`podman-compose -f compose.dev.yml ps`) + корень SPA 200; `--force-recreate` обязателен. - `mvn test` PMD и проверки JaCoCo **не** запускает (оба на `verify`; сам агент JaCoCo подключается и на `test` — execution `prepare-agent` на `initialize`); `mvn -pl wordpdf-app` без `-am` падает (зависимость от core test-jar). - Деплой — push в `main` → Gitea Actions (детали — `docs/agent/ci-cd.md`); **перед деплоем/перезапуском прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md`** (вне репо); ручных скриптов нет. @@ -84,7 +85,7 @@ python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources - Классы `final`, приватный конструктор, только `static` (stateless, DI в ядре нет). Исключения-экземпляры: `BundledFontMapper`, Spring-компоненты app. В `internal/**` классы package-private; `public` — только вызываемые извне пакета, контракт не расширять. - Ошибки публичного API — только `ConversionException extends RuntimeException`; `ValidationException` не оборачивать; в chart — деградация вместо падения; текст 500 наружу фиксированный (сообщения ядра логируются, не отдаются). - Javadoc на русском: «зачем» со ссылкой на секцию спецификации (§17.3.2.24, [MS-DOC] §2.6.1…) + что сломается без шага + регрессия в формате `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx` (по этой строке грепом восстанавливаются пары «нормализатор-тест ↔ тест-в-конвейере»). -- Логирование по пакетам: `java.util.logging` — корневой пакет и `internal/`; SLF4J — `internal/chart` и `wordpdf-app`. +- Логирование по пакетам: `java.util.logging` — корневой пакет и `internal/` (`WordPdfConverter`, `MathMlSupport`, `OleObjectNormalizer`, `DocToDocx`); SLF4J — `internal/chart` и `wordpdf-app`. - Модели — `record` (`ConvertOptions`, `BundledFonts.Entry`, `ApiError`); константы UPPER_SNAKE с javadoc-обоснованием числа; holder-идиомы для ленивой инициализации (`VendoredXslt.TEMPLATES`); compile-time literals там, где важен инлайн (`WordPdfConverter` ↔ `WordPdfValidator`). - Шрифты: новый шрифт = файл в `resources/fonts/` + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`); алиасы — `BundledFontMapper.ALIASES` (Calibri→Carlito, Arial→Arimo, Times New Roman→Tinos, …), fallback — DejaVu Sans. - PMD (`pmd-ruleset.xml`, execution `pmd-check` на `verify`, `includeTests=true`, валит любой приоритет): правила не перенастраивать, подавления (`@SuppressWarnings("PMD…")`, `// NOPMD`) запрещены — нарушения чинятся кодом. @@ -94,30 +95,31 @@ python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources |Файл|Что держать в голове| |---|---| -|`pom.xml` (корень)|единственное место версий (properties + dependencyManagement): docx4j 17.3.2, commons-compress 1.28.0, Boot 4.1.1 BOM, springdoc 3.1.1, JUnit 6.1.3, PDFBox 3.0.8, POI 5.5.1 (test), JaCoCo 0.8.15, PMD-плагин 3.21.2| +|`pom.xml` (корень)|единственное место версий (properties + dependencyManagement): docx4j 17.3.2, commons-compress 1.28.0, slf4j 2.0.20, Boot 4.1.1 BOM, springdoc 3.1.1, JUnit 6.1.3, PDFBox/fontbox 3.0.8, POI 5.5.1 (test), JaCoCo 0.8.15, PMD-плагин 3.21.2| |`wordpdf-core/src/main/java/.../WordPdfConverter.java`|весь конвейер, static-блок sysprops, пороги-константы, монитор сериализации| -|`wordpdf-app/src/main/resources/application.properties`|`convert-timeout=2m`, multipart 100 MB; `wordpdf.max-mb`/`max-pages` здесь **не объявлять намеренно** — пустое значение затенит `@Value`-дефолты 5/100| +|`wordpdf-app/src/main/resources/application.properties`|multipart 100MB/100MB (зеркалит nginx `client_max_body_size`), `convert-timeout=2m`, `api-key=` (пусто = auth off), `forward-headers-strategy=framework`; `wordpdf.max-mb`/`max-pages` здесь **не объявлять намеренно** — пустое значение затенит `@Value`-дефолты 5/100| |`wordpdf-core/pom.xml` / `wordpdf-app/pom.xml`|execution `test-jar`; BRANCH-гейт 0.85 (только core); exclusion `slf4j-simple`; Boot-4 имена: `spring-boot-starter-webmvc` (не `-web`), отдельный `spring-boot-webmvc-test`; `repackage` привязан явно| -|`Containerfile` / `Containerfile.test` / `compose*.yml` / `gateway/nginx.conf`|прод-образ (heap 2G, wget-healthcheck, FQDN FROM, обнуление прокси на команде) / CI-гейт без fontconfig / стенды :9010–:9011 / шлюз| -|`.gitea/workflows/pr.yml`, `main.yml`, `.ci/maven-settings.xml`|CI-конвейер; шаги java/web в обоих — идентичные; зеркало Nexus `${env.MAVEN_MIRROR_URL}`, `mirrorOf="*"`| -|`wordpdf-web/src/api.ts`, `vite.config.ts`|вся сеть SPA; `base` — только через env `VITE_BASE` (прод `/pdf-converter/`)| +|`Containerfile` / `Containerfile.test` / `compose*.yml` / `gateway/nginx.conf`|прод-образ (heap 2G, mem_limit 3G, wget-healthcheck, FQDN FROM, non-root 10001, обнуление прокси на команде) / CI-гейт без fontconfig / стенды :9010–:9011 / шлюз. Нюанс: repo `compose.yml` (prod-like) гасит springdoc env-ами, а реальный прод из CI-рендера держит swagger открытым (`test_swagger_ui_open_without_key`) — не путать| +|`.gitea/workflows/pr.yml`, `main.yml`, `.ci/maven-settings.xml`|CI: jobs `java`/`web` в обоих — идентичные шаги; `main.yml`: `images-* → deploy → autotests (+ rollback при failure)`; Maven в CI живёт в контейнере `maven:3.9-eclipse-temurin-17`; зеркало `${env.MAVEN_MIRROR_URL}`, `mirrorOf="*"`| +|`wordpdf-web/src/api.ts`, `vite.config.ts`|вся сеть SPA; `base` — только через env `VITE_BASE` (в прод-образ запекается `--build-arg VITE_BASE=/pdf-converter/`)| ## Runtime/Tooling Preferences -- Java 17 temurin + Maven 3.9.16 (пин в `mise.toml`, `mvnw` **нет** — только системный Maven из mise); UTF-8; Node 24, Python 3.15 — всё через project-local mise (`./.mise/bin/mise`, вне системы). +- Java 17 temurin + Maven 3.9.16 + Node 24 + Python 3.15 — пинины в `mise.toml`, всё через project-local mise (`./.mise/bin/mise`, вне системы); `mvnw` **нет** (`.mvn/` — пустой) — только Maven из mise. UTF-8. - Только Maven (никаких Gradle/Ant). Версии зависимостей/плагинов — только в корневом `pom.xml`; FOP-форк отдельно не пинить; `commons-compress` не завышать (привязан к docx4j 17.3.2); `` в pom не добавлять (зеркало — через settings). -- Контейнеры: podman/buildah; `FROM` только FQDN; хостовые прокси-переменные обнулять на самой команде в `RUN`/`HEALTHCHECK`; `DOCKER_BUILDKIT=0` (CI); healthcheck через wget, не curl; fontconfig рантайму не нужен (глифы — fontbox). -- Сеть: наружу публикуется только gateway (9010/9011); 8080/80 наружу не выставлять; подсети compose зафиксированы (nginx `resolver` привязан к шлюзу). +- Веб: только npm (`package-lock.json` закоммичен; никаких pnpm/yarn); линтер — oxlint (не eslint). +- Контейнеры: podman/buildah; `FROM` только FQDN; хостовые прокси-переменные обнулять на самой команде в `RUN`/`HEALTHCHECK`; `DOCKER_BUILDKIT=0` (CI); healthcheck через wget, не curl; fontconfig рантайму не нужен (глифы — fontbox); alpine-теги maven/temurin amd64-only — тестовый образ на Debian-базе. +- Сеть: наружу публикуется только gateway (9010/9011); 8080/80 наружу не выставлять; подсети compose зафиксированы (nginx `resolver` привязан literal-ом к шлюзу сети — 10.113.0.1 стенды / 10.112.0.1 прод). - Прод-стек (`docker-compose.yml`, `nginx.conf`) рендерится job'ом `deploy` из Variables — копий на хосте/в репо не заводить; required-контексты защиты `main` — буквально `PR checks / java (pull_request)`, `PR checks / web (pull_request)` (deploy/autotests не включать). ## Testing & QA -- Гейты на `verify`: PMD 6.55.0 (движок плагина 3.21.2 — осознанный откат, ruleset использует удалённые в PMD 7 `*MustUseBraces`) + JaCoCo: LINE ≥ 0.90 оба модуля, BRANCH ≥ 0.85 только core; при провале отчёт уже в `target/site/jacoco/`. CI-эквивалент — `./mise.sh run verify-nofontconfig`. -- Стек: JUnit 6 (`org.junit.jupiter`), **только `Assertions`** — Mockito/AssertJ запрещены (в app-тестах допустим inline-Hamcrest `containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (исключения: два `@BeforeAll` прогрева и `@AfterEach drainWorker` в `ConversionTimeoutTest`); ни `@Nested`, ни `@ParameterizedTest`, ни `@Disabled`, ни `assertAll`. +- Гейты на `verify`: PMD 6.55.0 (движок плагина 3.21.2 — осознанный откат, ruleset использует удалённые в PMD 7 `*MustUseBraces`; подавлений в коде нет и быть не должно) + JaCoCo: LINE ≥ 0.90 оба модуля, BRANCH ≥ 0.85 только core; при провале отчёт уже в `target/site/jacoco/`. CI-эквивалент — `./mise.sh run verify-nofontconfig`. +- Стек: JUnit 6 (`org.junit.jupiter`), **только `Assertions`** — Mockito/AssertJ запрещены (в app-тестах допустим inline-Hamcrest `containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (исключения: два `@BeforeAll` прогрева шрифтов и `@AfterEach drainWorker` в `ConversionTimeoutTest`); ни `@Nested`, ни `@ParameterizedTest`, ни `@Disabled`, ни `assertAll`. - Именование: регрессионные — `объект_условие` (`pageNumbers_recomputedNotCached`), юниты — camelCase (`pageFieldBecomesFldSimple`). -- **PDF сравнивается текстом**: PDFBox 3 `PDFTextStripper` (`norm` схлопывает пробелы; негативные маркеры — `#`/`.notdef` и `Helvetica`; приём `fontNameOf` — имя шрифта символа). Пиксели — только юниты chart-пейнтеров (`assertRatio` < 0.06 / < 0.10). Сообщения ассертов — по-русски с наблюдаемым значением; литерал слева (`"%PDF".equals(…)`). -- Фикстуры — только закоммиченные `samples/*.docx`/`*.doc`, в тестах не генерировать (пересоздание — одноразовые `SampleDocxGenerator`/`ChartTypesDocxGenerator`, POI test-scope); XSD-невалидная фикстура правится, не код. Синтетика в памяти разрешена: docx — `ZipOutputStream` из литеральных XML, `.doc` — крафт `POIFSFileSystem`. +- **PDF сравнивается текстом**: PDFBox 3 `PDFTextStripper` (`norm` схлопывает пробелы; негативные маркеры — `#`/`.notdef` и `Helvetica`; приём `fontNameOf` — имя шрифта символа). Пиксели — только юниты chart-пейнтеров (`assertRatio` < 0.06 / < 0.10). Тестовых утилит нет — хелперы намеренно дублируются в классах. Сообщения ассертов — по-русски с наблюдаемым значением; литерал слева (`"%PDF".equals(…)`). +- Фикстуры — только закоммиченные `samples/*.docx`/`*.doc`, в тестах не генерировать; XSD-невалидная фикстура правится, не код. Синтетика в памяти разрешена: docx — `ZipOutputStream` из литеральных XML, `.doc` — крафт `POIFSFileSystem`. Пересоздание — одноразовые `SampleDocxGenerator`/`ChartTypesDocxGenerator` (POI test-scope, команда — `docs/agent/repo-map.md`); `charts-smartart.docx` и `ole-embedded.docx` сделаны руками — **никогда не перезаписывать**. - Идиома загрузки (ловушка): **core** — classloader без ведущего слэша (`getResourceAsStream("samples/…")`); **app** — class-relative со слэшем (`"/samples/…"`, ресурсы из core test-jar). -- App-тесты: 4 набора свойств = 4 класса-контекста (`ConvertControllerTest` пинует пустой `wordpdf.api-key=`; `ApiKeyFilterTest`; `ConvertLimitsTest`; `ConversionTimeoutTest`); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring; проверяют только HTTP-код/заголовки/текст ошибки; core-юниты Spring не поднимают. -- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест + javadoc-ссылка. Счётчики и детали — `docs/agent/testing.md`. -- Прод-автотесты: pytest + requests, конфигурация **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY` факультативен → `needs_key` SKIP, `WORDPDF_MAX_MB`/`MAX_PAGES` — ожидаемые лимиты стенда); запуск `./mise.sh run prod-tests` либо job `autotests` в CI. +- App-тесты: 4 набора свойств = 4 Spring-контекста (`ConvertControllerTest` пинует пустой `wordpdf.api-key=`; `ApiKeyFilterTest`; `ConvertLimitsTest`; `ConversionTimeoutTest`); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring; проверяют только HTTP-код/заголовки/текст ошибки; core-юниты Spring не поднимают. +- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест + javadoc-ссылка. Счётчики (2026-11): 59 классов / 898 тестов (core 53/849, app 6/49); детали — `docs/agent/testing.md`. +- Прод-автотесты: pytest 9.1.1 + requests (timeout `(10,180)` — больше серверных 2m), конфигурация **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY` факультативен → `needs_key` SKIP, `WORDPDF_MAX_MB`/`MAX_PAGES` — ожидаемые лимиты стенда 5/100, `WORDPDF_SAMPLES_DIR` — путь к фикстурам); запуск `./mise.sh run prod-tests` либо job `autotests` в CI.