diff --git a/AGENTS.md b/AGENTS.md index e550ed4..91a58e0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,11 +4,11 @@ ## Project Overview -Конвертер `.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. +Конвертер `.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.2 + TS ~6.0 + Vite 8.3 + oxlint + Tailwind v4.3, npm; strict-режим TS намеренно не включён — сборка не strict-гейт) и pytest-автотесты `prod-autotests/`. Java 17, только Maven. ## Architecture & Data Flow -Единственный вход стека — gateway-контейнер nginx (`:9010` prod-like `compose.yml`, `:9011` dev `compose.dev.yml`), **не** 8080. Реальный прод-стек (`docker-compose.yml` + прод `nginx.conf`) рендерит CI-job `deploy` — копий на хосте/в репо не заводить. +Единственный вход стека — gateway-контейнер nginx (`:9010` prod-like `compose.yml`, `:9011` dev `compose.dev.yml`), **не** 8080. Реальный прод-стек (`docker-compose.yml` + прод `nginx.conf`) рендерит CI-job `deploy` — копий на хосте/в репо не заводить. Наружный прод-вход — `https://pjandro.ru/pdf-converter/` (образ web собирается с `VITE_BASE=/pdf-converter/`). **Пайплайн** `WordPdfConverter.convert(byte[] docxBytes, String title, ConvertOptions)` → `convertToStream` (публичная сигнатура единственная, 2-аргументной перегрузки **нет**); порядок шагов фиксирован: @@ -16,25 +16,25 @@ 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)`; +4. `FOSettings` + `ChartImageHandler` + `FopFallbackFonts.declare`; 4.25 `LayoutPostRenderer.register`; 4.5 `setCustomXsltTemplates(VendoredXslt.TEMPLATES)`; 5. общая `FopFactory` (DCL на мониторе `WordPdfConverter.class`); 6. `Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)` — последним; -7. `finally`: сброс temp-шрифтов, `resetSharedImageCaches()` (иначе ~1,5 ГБ за 30 конвертаций), `restrictToBundled()` (иначе встроенные в предыдущий docx шрифты травят реестр). +7. `finally`: сброс temp-шрифтов (`FontTablePart.deleteEmbeddedFontTempFiles()`), `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-блок конвертера не дёргается). +`WordPdfValidator.validate` вызывается в `convert()` **до** монитора (параллельно); при `options == null` бросает `ValidationException` сам `convert()`. Вход роутируется по сигнатуре: `PK\x03\x04` → docx; `D0 CF 11 E0 A1 B1 1A E1` (CFB) → `DocToDocx.convert`. Для `.doc` страницы считаются по сырым байтам. Пороги валидатора в `WordPdfConverter` объявлены compile-time literals (javac инлайнит, static-блок конвертера не дёргается). **Слои ядра** (`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`): -- публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConvertOptions` (record `errorOnCharts/errorOnSmartArt/errorOnOle/maxMb/maxPages`), `ConversionException` + `ValidationException` (бросает **только** валидатор) + `Charts/SmartArt/OleFoundException`; `warmup()` — идемпотентный прогрев, решает вызывающий; +- публичный 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); +- `internal/doc`: мост `.doc`→`.docx`, 17 top-level классов (+ вложенный `DocxBody` в `DocToDocx`), наружу только `DocToDocx.convert/countPages`; любая бита/шифрованный/Word 6-95 входов → `ConversionException`; раскладки — `docs/agent/doc-bridge.md`; +- `internal/chart`: Java2D → PNG (`ChartRenderer.DPI = 300`, `MAX_PIXELS` 4096² — `fitDpi` понижает dpi; `MAX_POINTS` 100 000, бюджет chart-PNG на документ 128 MiB); модель **деградации**: битая chart-часть/превышение бюджета → объект удалён + warn; `wp:extent` вне диапазона/ноль → объект **остаётся** + warn (FOP молча потеряет); `OutOfMemoryError` — не деградация, а `ConversionException` (500); - `fonts/GlyphFont`: метрика/глифы через fontbox напрямую, **без** `java.awt.Font` (fontconfig хосту не нужен). **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`, пусто = выключено, сравнение `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-плейсхолдеры — уже растры). +**REST** (`wordpdf-app`, всё package-private кроме `WordPdfApplication`): `POST /api/v1/convert` (multipart `file` + `errorOnCharts/errorOnSmartArt/errorOnOle`, `maxMb/maxPages` переопределяют серверный дефолт в обе стороны, ≤ 0 → 400; `file.getBytes()` — только после проверки размера; имя файла из `Content-Disposition`, UTF-8 + `.pdf`). Коды: 400 валидация/битые параметры, 401 `ApiKeyFilter` (`X-API-Key` ↔ `wordpdf.api-key`, пусто = выключено, сравнение `MessageDigest.isEqual`; открытые префиксы `/actuator/` (со слэшем!), `/swagger-ui`, `/v3/api-docs`; dot-segment (`..`, `%2e`) заставляет требовать ключ даже на открытых; Advice фильтров не видит — 401 пишет сам), 413 multipart, **422** отказ по графике (`DrawingRejectedException`, фиксированные тексты CHARTS/SMART_ART/OLE — контракт с фронтом), 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 / иначе open; имя файла из `Content-Disposition filename*=utf-8''`); единственный источник состояния — `useState` в `components/App.tsx` (+ `useRef` для `AbortController`/blob-URL), store-библиотек нет; лимиты на клиенте не задаются — только сервер. +**SPA** (`wordpdf-web/src`): вся сеть — единственная точка `api.ts` (ровно 2 `fetch`: `convertDocx`, `probeApiKey()` — 401=required / иначе open; ключ в localStorage `wordpdf.api.key`, при 401 стирается; имя файла из `Content-Disposition filename*=utf-8''`); единственный источник состояния — `useState` в `components/App.tsx` (+ `useRef` для `AbortController`/blob-URL), store-библиотек нет; лимиты на клиенте не задаются — только сервер. ### Критические инварианты (нарушение = битый вывод, не исключение) @@ -42,7 +42,7 @@ - Единственный 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` (отключение пересжатия); переименование молча вернёт мыльный ресемпл. +- Chart-media префикс `/word/media/chart-*` (`ChartImageHandler.CHART_MEDIA_URI_PREFIX`) — пакетный контракт с `ChartImageHandler` (отключение пересжатия); переименование молча вернёт мыльный ресемпл. - Стоп-лист «не чинить» (до любой попытки починить расхождение с Word — `docs/agent/render-limitations.md`): `jc="distribute"`, `suff="tab"`/`lvlJc`, кернинг, `framePr`, `REF`/`SEQ`/`TOC`-кэш, руби-надстрочница, `ptab`, U+2188/U+218A (GPL-шрифты не добавляем). ## Key Directories @@ -50,13 +50,13 @@ |Каталог|Назначение| |---|---| |`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API + `internal/` (нормализаторы) + `internal/doc/` (мост) + `internal/chart/` (рендер) + `fonts/`| -|`wordpdf-core/src/main/resources/`|`fonts/` (30 TTF + лицензии OFL), `xslt/docx2fo.xslt`, `slf4j-simple.properties`| +|`wordpdf-core/src/main/resources/`|`fonts/` (30 TTF + лицензии OFL/Bitstream-Vera/Noto), `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` (вся сеть), `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 с)| +|`gateway/nginx.conf`|прод-like шлюз (`client_max_body_size 100m`, таймауты 300 с, `resolver` привязан literal-ом к шлюзу сети)| |`develop/`|вне git (gitignored): эталоны Word — **не фикстуры**, в тесты/jar не подключать| ## Development Commands @@ -71,6 +71,7 @@ mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsP ./mise.sh run app-package && 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 +./mise.sh run mem-bench # замер памяти (membench.sh + core MemoryBench) podman-compose -f compose.dev.yml up -d --build --force-recreate # dev-стенд :9011, без ключа ./mise.sh run prod-tests # pytest; обязателен WORDPDF_BASE_URL python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD (lxml) @@ -87,7 +88,7 @@ python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources - Javadoc на русском: «зачем» со ссылкой на секцию спецификации (§17.3.2.24, [MS-DOC] §2.6.1…) + что сломается без шага + регрессия в формате `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx` (по этой строке грепом восстанавливаются пары «нормализатор-тест ↔ тест-в-конвейере»). - Логирование по пакетам: `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. +- Шрифты: новый шрифт = файл в `resources/fonts/` + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`); алиасы — `BundledFontMapper.ALIASES` (Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine, …), fallback — DejaVu Sans. - PMD (`pmd-ruleset.xml`, execution `pmd-check` на `verify`, `includeTests=true`, валит любой приоритет): правила не перенастраивать, подавления (`@SuppressWarnings("PMD…")`, `// NOPMD`) запрещены — нарушения чинятся кодом. - Git: origin `git.pjandro.ru:pjandro/java-word-pdf`; защищённые `main`/`master`/`dev`; все правки — через PR в дефолтную ветку; push — только после `./mise.sh run verify`. Прод-координаты и креды в репо не попадают (Gitea Variables/Secrets — `GITEA-vars.md`; `WORDPDF_API_KEY` ни в один файл). @@ -97,7 +98,7 @@ 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, 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`|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-app/src/main/resources/application.properties`|multipart 100MB/100MB (зеркалит nginx `client_max_body_size`) + `file-size-threshold=2MB` (сброс больших частей на диск — защита от OOM), `convert-timeout=2m`, `api-key=` (пусто = auth off), `forward-headers-strategy=framework`; `wordpdf.max-mb`/`max-pages` здесь **не объявлять намеренно** — пустое значение затенит `@Value`-дефолты 5/100 (≤ 0 на старте → `IllegalStateException`)| |`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, 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="*"`| @@ -114,12 +115,12 @@ python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources ## 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`. +- Гейты на `verify`: PMD (движок 6.55.0 — default внутри maven-pmd-plugin 3.21.2, отдельно в pom не пинится; осознанный откат — 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`, в тестах не генерировать; XSD-невалидная фикстура правится, не код. Синтетика в памяти разрешена: docx — `ZipOutputStream` из литеральных XML, `.doc` — крафт `POIFSFileSystem`. Пересоздание — одноразовые `SampleDocxGenerator`/`ChartTypesDocxGenerator` (POI test-scope, команда — `docs/agent/repo-map.md`); `charts-smartart.docx` и `ole-embedded.docx` сделаны руками — **никогда не перезаписывать**. +- **PDF сравнивается текстом**: PDFBox 3 `PDFTextStripper` (`norm` схлопывает пробелы; негативные маркеры — `#`/`.notdef` и `Helvetica`; приём `fontNameOf` — имя шрифта символа, живёт только в `WordPdfConverterTest`). Пиксели — только юниты chart-пейнтеров (`assertRatio` < 0.06 / < 0.10, эталонные числа Word-рендеров 300 dpi захардкожены). Тестовых утилит нет — хелперы намеренно дублируются в классах. Сообщения ассертов — по-русски с наблюдаемым значением; литерал слева (`"%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` сделаны руками — **никогда не перезаписывать** (все 12 `.doc` — эталоны заказчика, не вывод генераторов). - Идиома загрузки (ловушка): **core** — classloader без ведущего слэша (`getResourceAsStream("samples/…")`); **app** — class-relative со слэшем (`"/samples/…"`, ресурсы из core test-jar). -- 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`. +- App-тесты: 4 набора свойств = 4 Spring-контекста (`ConvertControllerTest` пинует пустой `wordpdf.api-key=`; `ApiKeyFilterTest`; `ConvertLimitsTest`; `ConversionTimeoutTest`); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring; проверяют только HTTP-код/заголовки/текст ошибки; core-юниты Spring не поднимают. Ловушка: mise инжектирует корневой `.env` в окружение задач — ambient `WORDPDF_API_KEY` взорвёт 401 все MockMvc-тесты, если ключ не запинен свойствами контекста. +- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест + javadoc-ссылка. Счётчики (2026-11): 60 классов / 962 теста (core 54/914, app 6/48); детали — `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.