Files
java-word-pdf/AGENTS.md
T
Pjandro f506940219
PR checks / java (pull_request) Successful in 2m3s
PR checks / web (pull_request) Successful in 1m11s
docs: пересобрать AGENTS.md — error-флаги 422, FOP 2.11-docx4j.6, springdoc/лимиты/CI по фактическому коду
2026-10-20 22:01:01 +00:00

44 KiB
Raw Blame History

Repository Guidelines

Project Overview

Конвертер .docx → .pdf на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Java 21, только Maven. Модули: wordpdf-core (библиотека), wordpdf-app (Spring Boot 4.1.1 REST API); wordpdf-web — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед git push — mvn clean verify (CI нет; SPA гейтуется npm run build + npm run lint). Вход стека — gateway-контейнер nginx (:9010 prod / :9011 dev), НЕ 8080. README устарел (порты/топология, «413 6 МБ» — фактически 100 МБ, нет API-ключа, лимиты подаёт как константы — они конфигурируемы); авторитетен этот файл.

Architecture & Data Flow

Пайплайн WordPdfConverter.convert(byte[], String[, ConvertOptions]) (порядок фиксирован, менять местами нельзя)

Наружу WordPdfValidator.validate(docxBytes, options) (размер → zip-подпись PK\x03\x04 → контейнер (.docx-манифест + zip-бомба) → страницы) вызывается до приватного convertToStream; внутри convertToStream:

  1. new BundledFontMapper() → BundledFonts.init() → BundledFonts.restrictToBundled(). Конструктор маппера каждый раз добавляет системные шрифты в реестр PhysicalFonts; ключ реестра — имя из name-таблицы TTF, addPhysicalFont(URI) не перезаписывает занятый → init() вызывает dropNonBundled() до регистрации и load() (иначе системный Calibri ломает em-dash-fallback).
  2. Нормализация байтов docx до JAXB-загрузки (цепочка byte[] → byte[], порядок значим): StrictOoxmlNormalizer (strict-OOXML → transitional-байт: a:-проценты и w14:fillToRect → тысячные ×1000, текст wp14:pctWidth/pctHeight, элементы и атрибуты w:start/w:end → w:left/w:right (кроме w:lvl/w:start в numbering.xml), значения start/end у w:jc/w:tab; в mc-preprocessor.xslt docx4j ветка % закомментирована, start/end не маппятся; namespaces и pt-значения правит сам mc-preprocessor — собственный рерайт URI ломает его pt-конверсию) → DocxOnOffNormalizer (w:val="off"/"on" → false/true) → SymbolFontNormalizer (PUA U+F0xx Symbol/Wingdings/Webdings → Unicode + DejaVu Sans, переписывает и элементы <w:sym>; 5 карт по 256 слотов, таблица SymbolMapper сгенерирована из docx4j 17.x) → FieldNormalizer (fldChar PAGE/NUMPAGES/SECTIONPAGES → w:fldSimple, вложенные/битые поля пропускает) → GlyphCoverageNormalizer (режет ран по покрытию глифов, пишет семейство в w:rFonts, иначе FOP рисует «#»; покрытие — java.awt.Font.canDisplay + BitSet-кэш, НЕ docx4j GlyphCheck — тот плодит INFO-лог; для serif-ран fallback ищется сначала в SERIF_FAMILIES (DejaVu Serif/Tinos/Caladea), затем в sans) → WordprocessingMLPackage.load.
  3. WordPdfValidator.checkPageCount(docxBytes, maxPages) — до рендера, lightweight (zip/StAX) по нормализованным байтам — тот же путь, что у приложения до очереди.
  4. pkg.setFontMapper(mapper) → DrawingPreRenderer.run(pkg, options) (шаг 3.5: c:chart/dgm:relIds docx2fo.xslt не умеет — свой Java2D-движок internal/chart/* рендерит в PNG 300 dpi и подменяет на pic:pic; объект, выключенный в ConvertOptions, пропускается до рендера и остаётся в docx; упавший рендер — объект удаляется из docx (gd.getAny().clear()) + warn, деградация не падение).
  5. new FOSettings(pkg) + FopFallbackFonts.declare (декларирует все бандл-семейства — FOP встраивает только задекларированные) → FORendererApacheFOP/FOUserAgent (непустой title → заголовок PDF) → Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL).
  6. finally: deleteEmbeddedFontTempFiles() (в 17.x OpcPackage.close() нет).

REST API (wordpdf-app, всё package-private кроме WordPdfApplication)

  • Единственный эндпоинт POST /api/v1/convert (multipart-поле file, факультативные query/form-параметры renderCharts/renderSmartArt/errorOnCharts/errorOnSmartArt) → application/pdf, Content-Disposition: attachment; filename*=UTF-8''…. Проверка .docx-расширения — в ConvertController; safeBaseName в ConversionService — единый источник имени для файла, заголовка ответа и PDF-title (разрешены [\p{L}\p{N} ._-], пустое → document).
  • Конвертации сериализованы однопоточным ThreadPoolExecutor (ConversionService.QUEUE_CAPACITY = 16, переполнение → 503): ядро мутирует глобальный реестр PhysicalFonts. future.cancel(true) при таймауте не останавливает FOP мгновенно — осознанный компромисс.
  • Ошибки (ApiExceptionHandler, тело {"error": …}): ValidationException → 400; DrawingRejectedException (core-DrawingFoundException от error-флагов, конвертируется в ConversionService.doConvert) → 422 (текст — контракт с фронтом, показывается дословно); ConversionFailedException → 500; ConversionRejectedException → 503; ConversionTimeoutException (wordpdf.convert-timeout, 2m) → 504; MaxUploadSizeExceededException → 413; MissingServletRequestPartException/MissingServletRequestParameterException → 400; NoResourceFoundException (неизвестный путь) → 404; catch-all → 500 (подробности только в лог). ValidationException — тип ядра ru.pjandro.wordpdf.ValidationException extends ConversionException (публичный), валидатор бросает его сам, app-дубликата нет; четыре app-исключения (ConversionFailed/Rejected/Timeout/DrawingRejected) — package-private, несут семантику 500/503/504/422. Граница: сломанный контейнер (не zip / голый zip без манифеста wordprocessingml / zip-бомба / размер / страницы) → 400, валидный .docx-контейнер с мусором внутри → 500. Валидация до очереди: WordPdfValidator.validate(docxBytes, options) (внутри порядок значим: checkInput → zip-магик PK\x03\x04 → checkDocxContainer — потоковый проход: декларация wordprocessingml.document в [Content_Types].xml + лимиты zip-бомбы WordPdfSettings.MAX_DECOMPRESSED_MB/MAX_ZIP_ENTRIES, не переопределяются ConvertOptions — → checkPageCount); тот же метод — вход ядра.
  • Ключ доступа: ApiKeyFilter сверяет заголовок X-API-Key (ApiKeyFilter.HEADER) со свойством wordpdf.api-key (env WORDPDF_API_KEY, сравнение MessageDigest.isEqual). Пустое свойство = аутентификация выключена (dev java -jar, тесты). Без ключа открыты /actuator/** (HEALTHCHECK), /swagger-ui*, /v3/api-docs* — матч по пути без forwarded-contextPath (getRequestURI() минус getContextPath(); иначе под X-Forwarded-Prefix HEALTHCHECK получил бы 401). 401 пишет сам фильтр (ApiExceptionHandler ошибок фильтров не видит). Springdoc в repo compose.yml выключён (SPRINGDOC_API_DOCS_ENABLED/SPRINGDOC_SWAGGER_UI_ENABLED=false); на живом проде (compose вне репо) включён и документация открыта без ключа под https://pjandro.ru/pdf-converter/swagger-ui.html — это безусловно проверяют prod-автотесты; server-URL спека собирается из X-Forwarded-* (server.forward-headers-strategy=framework — native-клапан Tomcat X-Forwarded-Prefix не понимает). Регрессии — ApiKeyFilterTest#forwardedPrefix_healthStaysOpen, ApiKeyFilterTest#docsOpenWithoutKey.
  • Лимиты входа задаёт только конфигурация сервера: wordpdf.max-mb/wordpdf.max-pages (env WORDPDF_MAX_MB/WORDPDF_MAX_PAGES), @Value в ConvertController с дефолтом-SpEL из WordPdfSettings (5 МБ / 100); значение ≤ 0 → IllegalStateException на старте; параметрами запроса не переопределяются. Ключи в application.properties не объявлены — пустое значение затенит SpEL-дефолт.
  • SPA: вся сеть в src/api.ts (компоненты fetch не вызывают); ключ в localStorage (wordpdf.api.key), при 401 очищается, экран ApiKeyGate (UnauthorizedError — наследник ApiError, проверяется раньше); гейт показывается только когда probeApiKey() (GET /api/v1/convert → 401 от ApiKeyFilter) подтвердил требование ключа — в dev без ключа форма открывается сразу; запросы на ${import.meta.env.BASE_URL}api/... (vite base из VITE_BASE, дефолт /) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом /pdf-converter/).

Chart-движок (internal/chart, package-private кроме DrawingPreRenderer.run)

Java2D → PNG 300 dpi (ChartRenderer.DPI = 300, PADDING = 4.0, растр × DPI/72, размеры — в пунктах, EMU→pt cx/12700.0). ChartSpec.parse (enum Type: PIE/PIE3D/DOUGHNUT/BAR/BAR_HORIZONTAL/LINE/AREA/SURFACE3D/UNSUPPORTED; пустой c:title + autoTitleDeleted="0" → у круговых имя первого ряда, у прочих — AUTO_TITLE = "Chart Title"; палитра accent1..6 темы, легенда по умолчанию снизу, позиция t поддержана, overlay → место не резервируется) → ChartRenderer (осевые «круглые» шаги niceUnit 1/2/5·10ⁿ как Word) → пейнтеры CartesianPainter/PiePainter (DEPTH_RATIO=0.22, TILT_CORRECTION=0.95, FIT_MARGIN=0.865)/Surface3dPainter (калибровка по эталону Word 300 dpi: CAMERA_DISTANCE=2.36, DEPTH_RATIO=0.705, HEIGHT_RATIO=0.664, GUTTER_LEFT/RIGHT=0.1485, GUTTER_TOP=0.116, GUTTER_BOTTOM=0.146, свет LIGHT_X/Y/Z=0.83/0.48/0.28); SmartArtRenderer рисует кэш разложенной схемы (relationship …/office/2007/relationships/diagramDrawing, фактически word/diagrams/drawing1.xml; fit-scale ×0.80); палитра темы — DrawMlColor (instance; без ThemePart — дефолтная Office-палитра accent1=4472C4…); текст — DrawMlText; утилиты RgbHsl, PrstGeomShapes. Калибровочные константы менять только вместе с Surface3dPainterTest/PiePainterTest. Обход pkg.getParts() — только по снимку списка (createImagePart мутирует реестр → CME); rels частей — part.getRelationshipsPart(), НЕ getOwningRelationshipPart() (это rels ссылающегося); обход XML обязан раскрывать JAXBElement.

Критические инварианты (нарушение = битый вывод)

  • docx4j.convert.out.fo.gsubFeatures=false — static-блок WordPdfConverter. Иначе FO невалиден → WordLayoutFixups молча отказывает всем фиксам (без них нет колонок) → FOP падает на docx4j-baseline.
  • slf4j-simple обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия noLoggingWarningInPdf). Приложение исключает его из зависимости ядра — логи ведёт logback.
  • FOP — форк org.docx4j:docx4j-fo-renderer* 2.11-docx4j.6 (транзитив от docx4j-export-fo 17.3.2, в pom не пинится; пакеты org.apache.fop.*). Fop.Renderers.getRenderer() возвращает список (рендер выбирается по mime application/pdf). docx2fo.xslt в репозитории нет — он в jar docx4j-export-fo.
  • Страницы в валидаторе = max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1); explicit = межсекционные sectPr в body + w:br type="page" + pageBreakBefore (включая таблицы и w:sdt). Единственный путь — lightweight (StAX по zip, secure-ридер без DTD/external entities; JAXB-обход удалён — WordPdfValidator не зависит от docx4j): атрибуты — по локальному имени (attrLocal, не по transitional-URI: иначе в strict-документе w:br type="page" не засчитываются); sectPr внутри pPr не считает, последнюю body-direct секцию не считает, continuous-секции не считает, в колонтитулах — только w:br type="page", pageBreakBefore — только внутри pPr вне sectPr (truthy-значения val: null|true|1|on); на не-zip молчит — подпись проверяет вызывающий. Все отказы — ValidationException.
  • Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются .notdef (GNU FreeSerif GPL — не добавляем намеренно).
  • Внимательно: комментарии в WordPdfConverter/DocxOnOffNormalizer говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно); javadoc PrstGeomShapes gear «×0.92» vs код ×0.82.

Шрифты (30 TTF + 3 лицензии, SIL OFL, wordpdf-core/src/main/resources/fonts/)

7 семейств × 4 начертания (Carlito/Caladea/Arimo/Tinos/Cousine/DejaVu Sans/DejaVu Serif) + Noto Naskh Arabic / Noto Sans Armenian (только regular). Алиасы в BundledFontMapper.ALIASES (ключи lowercase): MS→аналоги — Calibri→Carlito, Calibri Light→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; self-map всех бандл-семейств, включая Noto (иначе unmatched уходит в DejaVu-фолбэк); fallback — DejaVu Sans; виртуальный SYMBOL_FONT «Segoe UI Symbol» (U+2000–U+2EFF) → fallback до основного цикла. DISPLAY_NAMES — обратный маппинг lowercase→отображаемое имя для documentFontName (пишет GlyphCoverageNormalizer в w:rFonts); BundledFontMapper.bundledFamily — public-хук «имя шрифта из docx → бандл-семейство или fallback» (пользуется chart-движок). Публичный API BundledFonts шире реестра: families() (источник для FopFallbackFonts), font/regular/bold/italic/boldItalic(family), FALLBACK_FAMILY; awtFont возвращает Font размера 1 — всегда deriveFont(size). Новый шрифт = файл + запись в BundledFonts.ENTRIES (синхрон проверяет BundledFontsTest).

Key Directories

Путь Назначение
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ публичный API: WordPdfConverter, WordPdfValidator (перегрузки checkInput/checkPageCount и validate(byte[], ConvertOptions) — полная цепочка; без зависимости от docx4j), ConversionException, ValidationException (наследник — «вход некорректен»), DrawingFoundException (enum Kind {CHARTS, SMARTART} — отказ по error-флагу), WordPdfSettings (константы-дефолты: MAX_INPUT_MB=5, MAX_PAGES=100, защитные MAX_DECOMPRESSED_MB=200/MAX_ZIP_ENTRIES=8192, RENDER_*=true, ERROR_*=false), ConvertOptions (record: renderCharts, renderSmartArt, errorOnCharts, errorOnSmartArt, maxMb, maxPages)
…/wordpdf/fonts/ BundledFonts (реестр/выгрузка TTF, families(), FALLBACK_FAMILY), BundledFontMapper (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук bundledFamily)
…/wordpdf/internal/ 5 байтовых нормализатора + FopFallbackFonts (классы public — вызываются из родительского пакета; публичные члены только normalize/declare)
…/wordpdf/internal/chart/ 11 классов Java2D-рендера диаграмм/SmartArt в PNG (public только DrawingPreRenderer)
wordpdf-core/src/main/resources/fonts/ 30 TTF + 3 лицензии — бинарные фикстуры, часть jar
wordpdf-core/src/test/resources/samples/ 11 закоммиченных .docx-фикстур (единственные фикстуры)
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ REST API (10 классов): WordPdfApplication (единственный public), ConvertController, ConversionService (очередь), ApiExceptionHandler, ApiKeyFilter, OpenApiConfig (@SecurityScheme X-API-Key для springdoc) + 5 класса исключений
wordpdf-web/src/ SPA (React 19 + TS + Vite + Tailwind): api.ts (вся сеть), components/ (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo)
корневые Containerfile, compose.yml, compose.dev.yml, gateway/nginx.conf образ бэкенда (multi-stage maven:3.9-temurin-21 → полный temurin-21-jre — Java2D нужны AWT/fontconfig; non-root uid 10001, HEALTHCHECK actuator); compose app+web+gateway: web-образ со своим HEALTHCHECK (wget /), в обоих compose depends_on web: condition: service_healthy; прод-compose интерполирует WORDPDF_MAX_MB:-5/WORDPDF_MAX_PAGES:-100; podman-специфика обоих compose: x-podman.name_separator_compat (docker-style имена), явные healthcheck app/web (дубли Containerfile-HEALTHCHECK — OCI-выгрузка его теряет), зафиксированная подсеть 10.113.0.0/24 gw 10.113.0.1 под резолвер aardvark-dns; два repo-стенда одновременно не поднять (общая подсеть)
корневой .env.example шаблон env: WORDPDF_API_KEY (openssl rand -hex 32), закомментированные WORDPDF_MAX_MB/WORDPDF_MAX_PAGES (пустое значение ломает старт — binding long/int); реальный прод .env — на прод-сервере (координаты: /home/pjandro/prod/java-word-pdf/DEPLOY.md, вне репо)
.gitea/workflows/ Gitea Actions: pr.yml (PR checks), main.yml (тесты → images (build+push в Nexus) → deploy (pull) → autotests → rollback)
корневой GITEA-vars.md инструкция владельца: Secrets/Variables, защита ветки, перезапуск — только имена переменных, без значений
корневой prod-autotests/ прод-автотесты API (pytest + requests, 20 проверок): конфигурация стенда только env (WORDPDF_BASE_URL обязателен, WORDPDF_API_KEY/WORDPDF_MAX_PAGES/WORDPDF_MAX_MB/WORDPDF_SAMPLES_DIR факультативны) — прод-хостов/ключей в коде нет; окружение — mise (mise.toml: python 3.15 + автосоздаваемый .venv); прод-раннер вне git — /home/pjandro/prod/java-word-pdf/run-prod-tests.sh
develop/ (вне git) рабочие материалы и эталоны Word (testDoc.doc/.pdf, testDoc.convert.pdf, openxml.docx/.pdf) — ручное сравнение, не фикстуры, в тесты/jar не подключать

Development Commands

mvn clean verify                        # все модули + тесты + PMD (pmd-ruleset.xml) — обязательный гейт перед push
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
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf   # -am обязателен (test-jar core)
npm run dev                             # (wordpdf-web/) SPA :5173, vite-proxy /api|/swagger-ui|/v3/api-docs → :8080
npm run build                           # (wordpdf-web/) tsc -b && vite build — гейт SPA; lint: npm run lint (oxlint)
podman-compose -f compose.dev.yml up -d --build   # dev-стенд: http://<LAN-IP хоста>:9011 (0.0.0.0), без ключа, springdoc вкл

Пересоздать 10 фикстур (POI, test scope; charts-smartart.docx НЕ генерируется — создана вручную, не перезаписывать):

mvn -pl wordpdf-core test-compile -Dmdep.outputFile=/tmp/cp.txt dependency:build-classpath -q
java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
    ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples

Деплой. Прод — на пользовательском LAN-сервере (podman + podman-compose, docker-бинарников нет); координаты сервера, каталог, restart-секвенция, ключ и гейты успешности — вне репо: /home/pjandro/prod/java-word-pdf/DEPLOY.md (обязательно прочитать перед любым деплоем/перезапуском). Единая точка входа с dev-машины — /home/pjandro/prod/java-word-pdf/restart.sh (пробрасывает флаги удалённому скрипту: --deploy — pull образов wordpdf-{app,web}:prod из Nexus-реестра (их собирает CI, job images) и пересоздание app/web; без флага — restart контейнеров; предупреждает о не запушенном в main). В прод попадает только собранное CI из main; прод не собирает код и git-клона на проде нет (insecure-запись реестра в /etc/containers/registries.conf.d/, креды REGISTRY_USER/REGISTRY_PASSWORD в прод .env). Прод-compose /opt/wordpdf/docker-compose.yml (вне git) содержит podman-специфику: x-podman.name_separator_compat (имена wordpdf-prod-app-1, от них зависит restart.sh), явные healthcheck app/web и фиксированную подсеть 10.112.0.0/24 gw 10.112.0.1. Наружный вход https://pjandro.ru/pdf-converter/ (префикс срезает наружный nginx прод-хоста, не репозиторный gateway-конф; прод-копия gateway-конфа отличается от репо только резолвером 10.112.0.1 — под свою подсеть — и proxy_read_timeout 300s — в репо его нет, дефолтные 60s рвут 2-минутные конвертации; resolver + proxy_pass через переменную есть и там и там). Тот же наружный nginx в location /pdf-converter/ добавляет X-Forwarded-Host/X-Forwarded-Prefix — из них springdoc собирает server-URL спека под префиксом. Dev-стенд — из репо compose.dev.yml (проект wordpdf-dev, 9011:80 на все интерфейсы, без env → ключ пуст, springdoc вкл). Репозиторный compose.yml — третий вариант (проект wordpdf, 9010:80, WORDPDF_API_KEY fail-closed без .env — up упадёт; VITE_BASE — build-arg wordpdf-web/Containerfile, репо-compose НЕ передаёт: compose build без arg даёт base / и битые ассеты под префиксом; на прод-путь не влияет — там VITE_BASE=/pdf-converter/ запекает CI в job images). Запуск по просьбе пользователя = прод-стек; dev/java -jar/npm run dev — внутренняя отладка.

CI/CD (Gitea Actions)

Два workflow. .gitea/workflows/pr.yml — PR checks (pull_request + workflow_dispatch): job java (temurin 21, кеш ~/.m2 через actions/cache, Maven 3.9.16 ставится вручную с dlcdn, mvn -B clean verify) и web (кеш ~/.npm, npm ci/build/lint). .gitea/workflows/main.yml — Main: tests, deploy, autotests (push в main + workflow_dispatch): те же java/web (байт-в-байт дубль — файлы самодостаточны, reusable-workflow не вводить), затем images (docker build обоих Containerfile + docker push в Nexus-реестр ${{ vars.REGISTRY }}, теги prod + immovable sha-<7 символов GITHUB_SHA>; web пекётся с --build-arg VITE_BASE=/pdf-converter/; DOCKER_BUILDKIT=0 обязателен — daemon за раннером podman, BuildKit-сессий нет; креды — вручную пишется ~/.docker/config.json, job-контейнеры видят podman-сокет хоста — настройка раннера вне репо, см. DEPLOY.md), deploy (SSH на прод: сохранить .rollback.env — image ID контейнеров app/web — затем restart.sh --deploy в директории деплоя (Variable DEPLOY_DIR); export Variables WORDPDF_MAX_MB/WORDPDF_MAX_PAGES в окружение compose — лимиты прода задаются ими, autotests/rollback используют те же), autotests (venv + prod-autotests/ против прода), rollback (if: failure() — retag прежних image ID на ${{ vars.REGISTRY }}/wordpdf-app:prod и …/wordpdf-web:prod, --force-recreate app web, рестарт gateway). Кеш раннеров — сервер act_runner (серверная часть, вне репо).

Правило: координаты прода и креды в коммитимые файлы не попадают — ни внутренние IP, ни SSH-пользователи/логины, ни хосты, ни директория деплоя, ни ключи/токены/пароли. Координаты стенда — Gitea Actions Variables (DEPLOY_HOST, DEPLOY_USER, DEPLOY_DIR, WORDPDF_BASE_URL, WORDPDF_MAX_PAGES, WORDPDF_MAX_MB, REGISTRY), креды — Secrets (DEPLOY_SSH_KEY, WORDPDF_API_KEY, REGISTRY_USER, REGISTRY_PASSWORD); workflow-файлы ссылаются на них только ${{ vars.* }}/${{ secrets.* }}. Инструкция владельца — корневой GITEA-vars.md (только имена, без значений). Защита ветки main: required-контексты PR checks / java (pull_request), PR checks / web (pull_request) (формат Gitea 1.26; deploy/autotests в список НЕ включать — на PR не бегут, мерж блокировался бы навсегда).

Code Conventions & Common Patterns

  • Классы final, приватный конструктор, только static (stateless, DI нет; конфигурация — Docx4jProperties + classpath-ресурсы). Исключения — экземпляры по природе: docx4j-наследник BundledFontMapper (extends BestMatchingMapper), обёртка цветов DrawMlColor (тоже instance, но НЕ наследник docx4j) и Spring-компоненты wordpdf-app.
  • Нормализаторы — единая сигнатура public static byte[] normalize(byte[] docx) throws IOException с флагом changed: нечего менять → вернуть тот же массив (assertSame в тестах); package-private хук static String rewrite(String xml) для юнит-тестов (возвращает null при отсутствии изменений); правятся только части word/*.xml.
  • Ошибки публичного API — только ConversionException extends RuntimeException; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения.
  • Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx) — новый фикс оформлять так же (в существующем main-коде convention соблюдён лишь частично — SymbolFontNormalizer, WordPdfValidator, Surface3dPainter и классы app; новые правки обязаны ссылаться).
  • Константы UPPER_SNAKE с числовыми эталонными значениями (CAMERA_DISTANCE, MAX_PAGES); начертания V_REGULAR/V_BOLD/...; модели — record; размеры в chart — в пунктах, растр × DPI/72.
  • Классы в internal — public (иначе родительский пакет не вызвал бы), но публичные члены наружу только normalize/declare/DrawingPreRenderer.run (rewrite, split, карты — package-private); в wordpdf-app всё package-private кроме WordPdfApplication.
  • Тестовые методы: регрессионные — объект_условие через underscore (ruPlain_cyrillicAndStyles, checkInput_bytesOverLimit, noKey_rejected); чистые юниты — camelCase (pageFieldBecomesFldSimple, splitsRunForUncoveredGlyph).

Important Files

  • wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java — точка входа библиотеки + static-блок gsubFeatures.
  • wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java — все дефолты ядра (MAX_INPUT_MB 5, MAX_PAGES 100, RENDER_CHARTS/SMARTART); рантайм-конфигурации в ядре нет.
  • wordpdf-app/src/main/resources/application.properties — multipart 100MB (max-file-size/max-request-size + file-size-threshold=100MB, держит файл в памяти; в тон gateway client_max_body_size 100m), wordpdf.convert-timeout=2m, пустой wordpdf.api-key, server.forward-headers-strategy=framework (префикс прод-прокси для springdoc) + springdoc.swagger-ui.persist-authorization=true; wordpdf.max-mb/max-pages здесь намеренно нет.
  • wordpdf-app/pom.xml — spring-boot-maven-plugin с явной execution repackage (в 4.1.1 сам не связывается, jar останется тонким); slf4j-simple исключён; spring-boot-starter-webmvc (Boot 4: переименован из starter-web) + spring-boot-starter-actuator (нужен HEALTHCHECK контейнера /actuator/health); тест-зависимости: spring-boot-webmvc-test (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.
  • wordpdf-core/pom.xml — maven-jar-plugin execution test-jar (публикует фикстуры для app).
  • Корневой pom.xml — все версии зависимостей (в модулях версии не объявлять): docx4j 17.3.2, slf4j 2.0.20, JUnit 6.1.3, PDFBox 3.0.8 (test), POI 5.5.1 (test, только генератор фикстур), Spring Boot 4.1.1 (BOM-import), springdoc 3.1.1; pluginManagement: compiler 3.16.0, surefire 3.6.0 с -Djava.awt.headless=true, jar 3.5.1, PMD 3.28.0.
  • Корневой pmd-ruleset.xml — ruleset PMD (см. Testing & QA): category/java/codestyle.xml минус opinionated-правила, MethodNamingConventions с junit5TestPattern под underscore-имена регрессий, TooManyStaticImports до 12, XPath-правило LiteralFirstInEquals, unused-правила из bestpractices.xml.
  • wordpdf-core/src/main/resources/slf4j-simple.properties — без него предупреждение лезет в PDF.
  • gateway/nginx.conf — единственный вход: /api/, /swagger-ui, /v3/api-docs, /actuator → app:8080, остальное → web:80; client_max_body_size 100m (без директивы upload режется HTML-413 шлюза вместо JSON-ошибки API); resolver 10.113.0.1 + proxy_pass через переменные (статический proxy_pass резолвит имя один раз при старте — gateway раньше app поднялся бы с 502 до перезапуска). wordpdf-web/nginx.conf — чистая статика с SPA-fallback, /api НЕ проксирует.
  • wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java — main()-утилита пересоздания фикстур.
  • wordpdf-web/vite.local.config.ts — легаси-одноразовщик (прокси /api → :8091), коммит против воли автора (*.local в gitignore не накрывает .ts-суффикс), в tsconfig.node.json не включён; кандидат на удаление, не тиражировать паттерн.

Runtime & Tooling Preferences

  • Java 21 + Maven (обязательны; wrapper mvnw нет); UTF-8. Только Maven — никакого Gradle/Ant.
  • Версии зависимостей — только в корневом pom.xml (properties + dependencyManagement); новые зависимости — latest stable.
  • Фронт: Node ^20.19.0 || >=22.12.0 (engines vite/oxlint из lockfile; 21.x и 22.0–22.11 НЕ поддерживаются), npm с закоммиченным package-lock.json (npm ci); vite ^8.3, React ^19.2, TS ~6.0 (strict нигде не включён — npm run build не является strict-гейтом), Tailwind ^4.3, oxlint ^1.81; podman-сборка web на node:24-alpine.
  • Контейнеры (podman/buildah): FROM только FQDN (docker.io/library/... — short-name не резолвится без unqualified-search-registries); buildah подмешивает хостовые прокси-переменные в RUN/HEALTHCHECK — обнулять HTTP_PROXY= http_proxy= … на самой команде (ENV не перебивает).
  • CI, форматтеров, checkstyle для Java — нет; статический линтер — PMD на verify (см. Testing & QA); проверка одна: mvn clean verify.
  • Исполняемый jar бэкенда проверять только java -jar (тесты идут по classpath и repackage-специфику не видят; BundledFontsTest#listedFilesCoverAllTtfInResources требует file:-протокол classpath — только surefire, не fat-jar).
  • Git: origin git.pjandro.ru:pjandro/java-word-pdf, main/dev защищены (правила глобального AGENTS.md; локально только main).

Testing & QA

  • Гейт maven-pmd-plugin 3.28.0 (PMD 7.17) на verify для обоих модулей, ruleset pmd-ruleset.xml (codestyle без opinionated-правил + unused-правила + XPath LiteralFirstInEquals — строковый литерал слева в equals/equalsIgnoreCase; junit5TestPattern разрешает underscore-имена регрессий; includeTests=true — тесты сканируются).
  • 14 тестовых классов / 138 @Test (core 11/112, app 3/26). JUnit 6 (org.junit.jupiter:junit-jupiter), surefire 3.6.0 с -Djava.awt.headless=true в argLine; только Assertions (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest org.hamcrest.Matchers.containsString в andExpect); тестовые классы package-private, зеркалят main-пакеты; только @Test (+ единственный @BeforeAll — warm-up шрифтов в GlyphCoverageNormalizerTest).
  • PDF сравнивается текстом, не растеризацией: PDFBox 3 (Loader.loadPDF) — PDFTextStripper для текста (пер-странично setStartPage/setEndPage), override processTextPosition для шрифта конкретного символа (fontNameOf), обход ресурсов страниц для встроенных шрифтов (EAAAAA+Carlito-Bold) и счётчика картинок (imageCount). Негативные маркеры — регрессии: assertFalse(text.contains("#")) (.notdef), assertFalse(font.startsWith("Helvetica")). Текст нормализуется по пробелам (norm); в tableImage_tableAndImage — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах).
  • Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров: безразмерные отношения к эталону Word, допуски assertRatio <0.06 (PiePainterTest аспект h/w=0.585) / <0.10 (Surface3dPainterTest, + assertRange ±6 pt для центров силуэта); пороги залитых px и перцентильные коридоры яркости. Эталонные замеры — по Word-экспорту 300 dpi (develop/, вне git).
  • Фикстуры — закоммиченные samples/*.docx (11; в тестах не генерировать): core грузит classpath-ресурсом → byte[], PDF для PDFBox — временный файл; app читает /samples/… из test-jar core (classifier tests) → mvn -pl wordpdf-app без -am не соберётся. In-memory docx — ZipOutputStream из литеральных XML или POI в byte[]. Ключевые: too-many-pages (150 явных разрывов → 151), stale-cache (кэш <Pages>1</Pages> + 110 lastRenderedPageBreak), charts-smartart (4 растра; SmartArt-одиночка = ровно 2 Image XObject).
  • Юниты нормализаторов работают строками (rewrite) + zip'ами из ZipOutputStream; обязательные контракты: «нечего менять → тот же массив» (assertSame покрыт тестами только у zip-нормализаторов DocxOnOff/SymbolFont/StrictOoxml; у Field/GlyphCoverage — rewrite→null) и неприкосновенность частей вне word/*.xml ([Content_Types].xml). Тесты бьют и в package-private API (GlyphCoverageNormalizer.split(text, family), ChartSpec.readTitle).
  • App-тесты: @SpringBootTest + @AutoConfigureMockMvc (Boot 4: org.springframework.boot.webmvc.test.autoconfigure); три контекста — ConvertControllerTest (пустой ключ), ApiKeyFilterTest (properties = "wordpdf.api-key=…"), ConvertLimitsTest (@TestPropertySource с лимитами — отдельный класс, не @Nested).
  • Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): StrictOoxmlNormalizerTest↔strictOoxml_convertsNotRejected (+pageCount_strictBreaksCountedLightweight — lightweight против strict), DocxOnOffNormalizerTest↔ruPlain_regularRunsUseRegularFont, SymbolFontNormalizerTest↔symbolFonts_bulletsAreNotHash, FieldNormalizerTest↔pageNumbers_recomputedNotCached, GlyphCoverageNormalizerTest↔exoticGlyphs_drawnNotHash, WordPdfValidatorTest↔staleCachePageCountRejectedBeforeRender (+checkPageCount_limitBoundary 99/100/101, pageCount_breaksInsideTablesAreCounted, pageCount_continuousSectionsNotCountedLightweight, validate_notAZip↔inputNotAZip_rejectedBeforeRender, validate_plainZipRejected/validate_xlsxRenamedRejected/validate_zipBombRejected/validate_tooManyEntriesRejected↔plainZipNotDocx_rejected/inputNotDocx_rejectedBeforeRender — контейнер и zip-бомба), BundledFontsTest↔ruPlain_emDashEmbeddedNotHelvetica, ChartSpecTest↔автозаголовки, chart-пейнтеры↔chartsSmartArt_drawingsBecomeImages (+drawingToggles_offRemovesRasters/drawingToggles_chartsOffSmartArtOn, drawingErrors_*↔app errorFlagCharts_rejected/errorFlagSmartArt_rejected/errorFlags_renderWins); noLoggingWarningInPdf — регрессия slf4j-simple, pdfTitle_comesFromParameter — регрессия PDF-title (юнит-партнёра нет). App-регрессии: requestLimitParams_areIgnored, nonPositiveLimits_failStartup, unknownPath_notFound, concurrentRequests_bothSucceed (гонка реестра PhysicalFonts), corruptNotAZip_rejected, plainZipNotDocx_rejected (голый zip без манифеста → 400), junkInsideValidZip_conversionError (500 на валидном .docx-контейнере с мусором), nonDocxFilename_rejected, oversizedOverCoreLimit_rejected, renderFlagsOff_convertsWithoutDrawings, cyrillicAndPathInFilename_sanitizedResponseName (RFC 5987 + path-traversal), docsOpenWithoutKey/forwardedPrefix_healthStaysOpen/forwardedPrefix_docsOpenWithoutKey (открытая документация + матч фильтра без forwarded-contextPath).
  • UI-тестов нет; гейт SPA — npm run build (tsc -b) + npm run lint (oxlint, .oxlintrc.json: rules-of-hooks error, only-export-components warn). Прод-автотесты (pytest 9 + requests, 20 проверок, env-конфиг, mise exec -- python -m pytest -q . из prod-autotests/) гоняются CI после deploy против живого прода; WORDPDF_API_KEY пуст → честный SKIP @needs_key-проверок.