44 KiB
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:
new BundledFontMapper()→BundledFonts.init()→BundledFonts.restrictToBundled(). Конструктор маппера каждый раз добавляет системные шрифты в реестрPhysicalFonts; ключ реестра — имя из name-таблицы TTF,addPhysicalFont(URI)не перезаписывает занятый →init()вызываетdropNonBundled()до регистрации иload()(иначе системный Calibri ломает em-dash-fallback).- Нормализация байтов 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.xsltdocx4j ветка%закомментирована, 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(fldCharPAGE/NUMPAGES/SECTIONPAGES →w:fldSimple, вложенные/битые поля пропускает) →GlyphCoverageNormalizer(режет ран по покрытию глифов, пишет семейство вw:rFonts, иначе FOP рисует «#»; покрытие —java.awt.Font.canDisplay+ BitSet-кэш, НЕ docx4jGlyphCheck— тот плодит INFO-лог; для serif-ран fallback ищется сначала вSERIF_FAMILIES(DejaVu Serif/Tinos/Caladea), затем в sans) →WordprocessingMLPackage.load. WordPdfValidator.checkPageCount(docxBytes, maxPages)— до рендера, lightweight (zip/StAX) по нормализованным байтам — тот же путь, что у приложения до очереди.pkg.setFontMapper(mapper)→DrawingPreRenderer.run(pkg, options)(шаг 3.5:c:chart/dgm:relIdsdocx2fo.xslt не умеет — свой Java2D-движокinternal/chart/*рендерит в PNG 300 dpi и подменяет наpic:pic; объект, выключенный вConvertOptions, пропускается до рендера и остаётся в docx; упавший рендер — объект удаляется из docx (gd.getAny().clear()) + warn, деградация не падение).new FOSettings(pkg)+FopFallbackFonts.declare(декларирует все бандл-семейства — FOP встраивает только задекларированные) →FORendererApacheFOP/FOUserAgent(непустойtitle→ заголовок PDF) →Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL).finally:deleteEmbeddedFontTempFiles()(в 17.xOpcPackage.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(envWORDPDF_API_KEY, сравнениеMessageDigest.isEqual). Пустое свойство = аутентификация выключена (devjava -jar, тесты). Без ключа открыты/actuator/**(HEALTHCHECK),/swagger-ui*,/v3/api-docs*— матч по пути без forwarded-contextPath (getRequestURI()минусgetContextPath(); иначе подX-Forwarded-PrefixHEALTHCHECK получил бы 401). 401 пишет сам фильтр (ApiExceptionHandlerошибок фильтров не видит). Springdoc в repocompose.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-клапан TomcatX-Forwarded-Prefixне понимает). Регрессии —ApiKeyFilterTest#forwardedPrefix_healthStaysOpen,ApiKeyFilterTest#docsOpenWithoutKey. - Лимиты входа задаёт только конфигурация сервера:
wordpdf.max-mb/wordpdf.max-pages(envWORDPDF_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/...(vitebaseиз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-fo17.3.2, в pom не пинится; пакетыorg.apache.fop.*).Fop.Renderers.getRenderer()возвращает список (рендер выбирается по mimeapplication/pdf).docx2fo.xsltв репозитории нет — он в jardocx4j-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 (описанное поведение верно); javadocPrstGeomShapesgear «×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_MB5,MAX_PAGES100,RENDER_CHARTS/SMARTART); рантайм-конфигурации в ядре нет.wordpdf-app/src/main/resources/application.properties— multipart 100MB (max-file-size/max-request-size+file-size-threshold=100MB, держит файл в памяти; в тон gatewayclient_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с явной executionrepackage(в 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-pluginexecutiontest-jar(публикует фикстуры для app).- Корневой
pom.xml— все версии зависимостей (в модулях версии не объявлять): docx4j17.3.2, slf4j2.0.20, JUnit6.1.3, PDFBox3.0.8(test), POI5.5.1(test, только генератор фикстур), Spring Boot4.1.1(BOM-import), springdoc3.1.1; pluginManagement: compiler3.16.0, surefire3.6.0с-Djava.awt.headless=true, jar3.5.1, PMD3.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-plugin3.28.0 (PMD 7.17) наverifyдля обоих модулей, rulesetpmd-ruleset.xml(codestyle без opinionated-правил + unused-правила + XPathLiteralFirstInEquals— строковый литерал слева в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-Hamcrestorg.hamcrest.Matchers.containsStringвandExpect); тестовые классы package-private, зеркалят main-пакеты; только@Test(+ единственный@BeforeAll— warm-up шрифтов вGlyphCoverageNormalizerTest). - PDF сравнивается текстом, не растеризацией: PDFBox 3 (
Loader.loadPDF) —PDFTextStripperдля текста (пер-страничноsetStartPage/setEndPage), overrideprocessTextPositionдля шрифта конкретного символа (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 (classifiertests) →mvn -pl wordpdf-appбез-amне соберётся. In-memory docx —ZipOutputStreamиз литеральных XML или POI вbyte[]. Ключевые:too-many-pages(150 явных разрывов → 151),stale-cache(кэш<Pages>1</Pages>+ 110lastRenderedPageBreak),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_limitBoundary99/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_*↔apperrorFlagCharts_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-проверок.