aaad5d2bb0
- docx-нормализаторы: tblInd без w:type = dxa (§17.4.87); явный vanish=false перекрывает стиль (§17.3.2.70); RubyNormalizer снимает обёртку w:ruby и удаляет rubyBaseText; DocxOnOffNormalizer не трогает w:scrollbar; SymbolFontNormalizer читает прямые коды w:sym - мост .doc: borderVal 0x1B→inset; STK_CHARACTER=2 (§2.4.6.5); grpprl toggle + знаковые XAS; ChpxIndex cb=0; PapxIndex cpara + ключ по последнему символу; sprmCIstd reset+preserve; Sections YAS/bkc/pgnStart/gutter/nfc; NPE-гард Lists; BrcMayBeNil = нет границы; emission (w:id, слоты шрифтов, Kul, ISS, header-картинки); OfficeArt 0x46B/TIFF/DIB/второй UID + warn EMF/WMF/PICT; PrcData стоп-обработка; CfbReader бюджет + MUST-поля заголовка (§2.2); FibHeader csw/cslw + cbRgFcLcb; PieceTable aCP-дубли + cbMac - мёртвый код: девять неиспользуемых STEP-констант, недостижимая ветка pgMar - javadoc: исправлены номера секций ECMA-376/MS-DOC/MS-CFB/MS-ODRAW в нормализаторах, chart-пакете, мосту - доки: pipeline.md, repo-map.md, doc-bridge.md, render-limitations.md, AGENTS.md синхронизированы с кодом
124 lines
21 KiB
Markdown
124 lines
21 KiB
Markdown
# Repository Guidelines
|
||
|
||
> Роутер: правила, инварианты и команды — здесь; глубокие детали — `docs/agent/*.md` (pipeline, doc-bridge, chart, testing, ci-cd, render-limitations, repo-map — каждый авторитетен наравне с этим файлом), нормативные форматы — `docs/standards/` (ссылка с номером секции обязательна).
|
||
|
||
## 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.
|
||
|
||
## Architecture & Data Flow
|
||
|
||
Единственный вход стека — gateway-контейнер nginx (`:9010` prod-like `compose.yml`, `:9011` dev `compose.dev.yml`), **не** 8080.
|
||
|
||
**Пайплайн** `WordPdfConverter.convert(byte[], String[, ConvertOptions])` → `convertToStream`; порядок шагов фиксирован:
|
||
|
||
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)` — последним;
|
||
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`;
|
||
- `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()`.
|
||
|
||
**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-плейсхолдеры — уже растры).
|
||
|
||
**SPA** (`wordpdf-web/src`): вся сеть — единственная точка `api.ts` (ключ в localStorage `wordpdf.api.key`, `probeApiKey()`: 401=required / 405=open); единственный источник состояния — `useState` в `App.tsx`.
|
||
|
||
### Критические инварианты (нарушение = битый вывод, не исключение)
|
||
|
||
- 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).
|
||
- 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-шрифты не добавляем).
|
||
|
||
## Key Directories
|
||
|
||
|Каталог|Назначение|
|
||
|---|---|
|
||
|`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/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/`|
|
||
|`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 не подключать|
|
||
|
||
## Development Commands
|
||
|
||
Бутстрап: `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)
|
||
./mise.sh run verify-nofontconfig # тот же verify в контейнере без fontconfig (как CI)
|
||
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
|
||
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am обязателен: core test-jar
|
||
./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
|
||
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)
|
||
```
|
||
|
||
- «Запусти тестовый сервер» (термин пользователя) = dev-стенд выше, **не** `java -jar`; гейт готовности — контейнеры healthy + корень SPA 200; `--force-recreate` обязателен.
|
||
- `mvn test` PMD/JaCoCo **не** запускает (оба на `verify`); `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`** (вне репо); ручных скриптов нет.
|
||
|
||
## Code Conventions & Common Patterns
|
||
|
||
- Классы `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`.
|
||
- Модели — `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`) запрещены — нарушения чинятся кодом.
|
||
- 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` ни в один файл).
|
||
|
||
## Important Files
|
||
|
||
|Файл|Что держать в голове|
|
||
|---|---|
|
||
|`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|
|
||
|`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-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/`)|
|
||
|
||
## 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`, вне системы).
|
||
- Только Maven (никаких Gradle/Ant). Версии зависимостей/плагинов — только в корневом `pom.xml`; FOP-форк отдельно не пинить; `commons-compress` не завышать (привязан к docx4j 17.3.2); `<repositories>` в 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` привязан к шлюзу).
|
||
- Прод-стек (`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`.
|
||
- Именование: регрессионные — `объект_условие` (`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`.
|
||
- Идиома загрузки (ловушка): **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.
|