48 KiB
Repository Guidelines
Project Overview
Конвертер .docx/.doc → .pdf на чистом Java (docx4j 17.3.2 + форк Apache FOP; бинарный .doc Word 97-2003 — через POI HWPF, без 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), НЕ 8080. README устарел шире секции про контейнеры: лимиты (пишет 5 МБ/100 стр. — совпадает с кодом; 6 МБ multipart — фактически 100 MB), порты («всё на :8080» — фактически gateway :9010/:9011), API-ключ вообще не упомянут; плюс «фикстуры генерируются POI» (они закоммичены, POI только в генераторе) и Swagger UI без оговорки, что в проде она открыта без ключа, — авторитет этот файл.
Architecture & Data Flow
Пайплайн WordPdfConverter.convert(byte[], String[, ConvertOptions]) (порядок фиксирован, менять местами нельзя)
Наружу WordPdfValidator.validate(docxBytes, options) (размер → zip-подпись PK\x03\x04 → страницы) вызывается до приватного convertToStream; внутри convertToStream:
Шаг 0: вход с OLE2-магиком D0 CF 11 E0 A1 B1 1A E1 (бинарный .doc) уходит в internal.DocToPdfRenderer.render до создания BundledFontMapper — docx4j-машинерия и все нормализаторы (zip-путь) для него бессмысленны; см. «Ветка .doc» ниже.
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()нет).
Ветка .doc (internal/DocToPdfRenderer, public только render)
POI WordToFoConverter (HWPF→XSL-FO) → тот же FOP-форк. Порядок: BundledFonts.init() (без restrictToBundled — FOP-конфиг строится строкой с auto-detect="false", системные шрифты в рендер не попадают) → POIFSFileSystem/HWPFDocument → FontReplacer (имя = name-таблица TTF через BundledFontMapper.bundledFamily) → PicturesManager во временный каталог (без него POI молча пропускает картинки; пустые картинки — null, иначе FOP падает EOFException) → processDocument → пост-обработка FO-DOM: applyDefaultFont (инлайны POI без font-family — иначе базовый Helvetica) и injectHeadersAndFooters (POI колонтитулы не пишет): HeaderStories odd/even/first × header/footer, чанки по \u000c; в мастер — region-before/region-after (extent = top/bottom margin из margin-шортхэнда region-body, margin'ы region-body сохраняются — форк FOP не вычитает extent'ы регионов из body-области, единственная защита от наезда текста на колонтитулы — собственные margin'ы body; порядок детей body→before→after — требование валидации форка; зазор — маргинами блоков, padding регионов FOP валит), в page-sequence — fo:static-content перед fo:flow; first/even — эвристика «непустая история ⇒ вариант» (флаги titlePg/evenAndOdd POI не отдаёт) через fo:page-sequence-master + conditional-page-master-reference first/even/rest. Поля в текстах историй — управляющие символы \u0013/\u0014/\u0015: PAGE → fo:page-number, NUMPAGES/SECTIONPAGES → fo:page-number-citation-last по последнему мастеру; fo:page-number без font-family блока рисуется Helvetica — блок получает семейство первого рана. Свойство tabs FOP-форк не знает — табы = пробелы до дефолтной остановки 1,25 см. Принятая деградация против Word: дрейф вёрстки (18 стр. против 12 на фикстуре), экзотические глифы остаются .notdef (аналога GlyphCoverageNormalizer нет), first/even-варианты эвристикой. Флаги renderCharts/renderSmartArt/errorOn* — no-op.
REST API (wordpdf-app, всё package-private кроме WordPdfApplication)
- Единственный эндпоинт
POST /api/v1/convert(multipart-полеfile, факультативныеrenderCharts/renderSmartArt— query или form) →application/pdf,Content-Disposition: attachment; filename*=UTF-8''…. Проверка расширений.docx/.doc— вConvertController;safeBaseNameвConversionService— единый источник имени для файла, заголовка ответа и PDF-title (разрешены[\p{L}\p{N} ._-], пустое →document). Для.docответ несётX-Wordpdf-Degraded: headers-footers-exotic-glyphs(деградация вёрстки/колонтитулов/экзотических глифов). - Конвертации сериализованы однопоточным
ThreadPoolExecutor(ConversionService.QUEUE_CAPACITY = 16, переполнение → 503): ядро мутирует глобальный реестрPhysicalFonts.future.cancel(true)при таймауте не останавливает FOP мгновенно — осознанный компромисс. - Ошибки (
ApiExceptionHandler, тело{"error": …}):ValidationException→ 400;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-исключения (ConversionFailedException,ConversionRejectedException,ConversionTimeoutException) — package-private, несут семантику 500/503/504.doConvertперехватываетValidationExceptionраньшеConversionException— отказ страницы-лимита из конвейера ядра даёт 400, а не 500. Граница: сломанный контейнер (не zip / не OLE2 / размер / страницы) → 400, валидный контейнер с мусором внутри → 500. Валидация до очереди:WordPdfValidator.validate(docxBytes, options)(внутри порядок значим:checkInput→ подпись контейнера (zipPK\x03\x04или OLE2D0 CF 11 E0) → страницы); тот же метод — вход ядра. - Ключ доступа:
ApiKeyFilterсверяет заголовокX-API-Key(ApiKeyFilter.HEADER) со свойствомwordpdf.api-key(envWORDPDF_API_KEY, сравнениеMessageDigest.isEqual). Пустое свойство = аутентификация выключена (devjava -jar, тесты). Без ключа открыты/actuator/**(HEALTHCHECK) и документация springdoc (/swagger-ui*,/v3/api-docs*) — матч по пути без forwarded-contextPath (getRequestURI()минусgetContextPath(); иначе подX-Forwarded-PrefixHEALTHCHECK получил бы 401). 401 пишет сам фильтр (ApiExceptionHandlerошибок фильтров не видит). Springdoc в проде включён, документация открыта без ключа подhttps://pjandro.ru/pdf-converter/swagger-ui.html(server-URL/swagger-config собираются из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; маркеры легенды 0.32/0.55 кегля, отрезок 2.4 кегля) → пейнтеры CartesianPainter/PiePainter (DEPTH_RATIO=0.22, TILT_CORRECTION=0.95, FIT_MARGIN=0.865)/Surface3dPainter (калибровка по стр. 3 develop/word-export.pdf: 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); палитра темы — 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.2 (пакетыorg.apache.fop.*);Fop.Renderers.getRenderer()возвращает список (рендер выбирается по mimeapplication/pdf).docx2fo.xsltв репозитории нет — он в jardocx4j-export-fo. - Форк FOP вырезал
PageMaster.setupRegions(в jar нетlayoutmgr/PageMaster*/RegionXY):area.Pageстроит viewportregion-bodyкак page-area минус собственные margin'ы body,extentуregion-before/region-afterbody-регион не уменьшает — в.doc-ветке разводка body и колонтитулов только margin'амиregion-body(регрессияDocToPdfTest#legacyDoc_bodyClearsHeaderFooterRegions). Docx-ветку не касается: docx4j сам закладывает высоты колонтитулов в margin'ы мастера. - Страницы в валидаторе =
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. .doc:checkDocPageCountLightweight= кэшSummaryInformation.getPacket().getPageCount()(Word 97-2003 писал число страниц в OLE2-метаданные; явных разрывов из FIB не извлечь) — тот же stale-cache риск, что иdocProps/app.xml;0/отсутствие пакета → молча. FOP-конфиг.doc-ветки — строка сauto-detect="false"+resource://fonts/...(классыFOPFontProvider/FopConfParserpackage-private, JAXB-обходrendererFontsк ним не применим).- Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются
.notdef(GNU FreeSerif GPL — не добавляем намеренно). - Внимательно: комментарии в
WordPdfConverter/DocxOnOffNormalizerговорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).
Шрифты (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 (15 записей, ключи 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 — byte[], с лимитом/без, checkDocPageCountLightweight — OLE2-.doc, и validate(byte[], ConvertOptions) — полная цепочка размер → подпись контейнера (zip/OLE2) → страницы; без зависимости от docx4j — только POI для .doc), ConversionException, ValidationException (наследник — «вход некорректен»), WordPdfSettings (константы-дефолты), ConvertOptions (record: renderCharts, renderSmartArt, maxMb, maxPages) |
…/wordpdf/fonts/ |
BundledFonts (реестр/выгрузка TTF, families(), FALLBACK_FAMILY), BundledFontMapper (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук bundledFamily) |
…/wordpdf/internal/ |
5 байтовых нормализатора + FopFallbackFonts + DocToPdfRenderer (ветка .doc; классы public — вызываются из родительского пакета; публичные члены только normalize/declare/render) |
…/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/ |
12 закоммиченных фикстур: 11 .docx + legacy-doc.doc (OLE2, ветка .doc) |
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ |
REST API (10 классов): WordPdfApplication (единственный public), ConvertController, ConversionService (очередь), ApiExceptionHandler, ApiKeyFilter, OpenApiConfig (@SecurityScheme X-API-Key для springdoc) + 4 класса исключений |
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, non-root, HEALTHCHECK actuator); compose app+web+gateway: web-образ со своим HEALTHCHECK (wget /), в обоих compose depends_on web: condition: service_healthy (без health web gateway не стартует); прод-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; реальный прод .env — на прод-сервере (координаты: /home/pjandro/prod/java-word-pdf/DEPLOY.md, вне репо) |
.gitea/workflows/ |
Gitea Actions: pr.yml (PR checks), main.yml (тесты → images (docker build + push в Nexus) → deploy (pull) → autotests → rollback) |
корневой GITEA-vars.md |
инструкция владельца: Secrets/Variables, защита ветки, перезапуск — только имена переменных, без значений |
корневой prod-autotests/ |
прод-автотесты API (pytest + requests, 19 проверок): конфигурация стенда только env (WORDPDF_BASE_URL обязателен, WORDPDF_API_KEY/WORDPDF_MAX_PAGES/WORDPDF_MAX_MB/WORDPDF_SAMPLES_DIR факультативны) — прод-хостов/ключей в коде нет; окружение — mise (mise.toml: python 3.15 + автосоздаваемый .venv, в venv от uv pip досеивается ensurepip); прод-раннер вне git — /home/pjandro/prod/java-word-pdf/run-prod-tests.sh (знает прод-настройки: base URL, лимит 100 стр. (= Gitea Variable WORDPDF_MAX_PAGES), ключ из соседнего .env) |
develop/ (вне git) |
рабочие материалы и эталоны Word 365 (word.docx+word.pdf, word-export.*, convert.pdf, 1212.pdf, diff/) — ручное сравнение, не фикстуры, в тесты/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 → :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 и legacy-doc.doc НЕ генерируются — созданы вручную, не перезаписывать):
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 5.8.2 + podman-compose 1.6.0, бинарников docker/docker-compose на сервере нет); координаты сервера, каталог, restart-секвенция, ключ и гейты успешности — вне репо: /home/pjandro/prod/java-word-pdf/DEPLOY.md (обязательно прочитать перед любым деплоем/перезапуском; в том каталоге лежат архивные файлы старого стека 88.14 — restart.sh.old-88.14, старый compose/nginx — не поднимать). Единая точка входа с 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: $host и X-Forwarded-Prefix: /pdf-converter — из них springdoc собирает server-URL спека и swagger-config под префиксом (без X-Forwarded-Host server = https://app:8080, gateway шлёт приложению Host: app:8080); канонический URL документации https://pjandro.ru/pdf-converter/swagger-ui.html — открыт без ключа. Dev-стенд — из репо compose.dev.yml (проект wordpdf-dev, 9011:80 на все интерфейсы — вход по LAN-IP хоста, без 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, 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>; DOCKER_BUILDKIT=0 обязателен — daemon за
раннером podman, BuildKit-сессий нет; job-контейнеры видят podman-сокет хоста — настройка
раннера вне репо, см. DEPLOY.md), deploy (SSH на прод:
сохранить .rollback.env — image ID контейнеров app/web — затем
restart.sh --deploy в директории деплоя (Variable DEPLOY_DIR): login в реестр +
podman-compose pull + --force-recreate app web; 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, хранилище на ZFS tank (серверная часть, вне репо).
Правило: координаты прода и креды в коммитимые файлы не попадают — ни внутренние 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 (только имена, без значений).
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(compile в core —poi-scratchpad, ветка.doc; test —poi-ooxml, генератор фикстур), Spring Boot4.1.1(BOM-import), springdoc3.1.1; pluginManagement: compiler3.16.0, surefire3.6.0с-Djava.awt.headless=true, jar3.5.1. - Корневой
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).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), npm с закоммиченнымpackage-lock.json(npm ci); vite^8.3.0, React^19.2, TS~6.0(strictнигде не включён —npm run buildне является strict-гейтом), Tailwind^4.3, oxlint^1.81; podman-сборка web наnode:24-alpine. - 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,devнет; на origin висит остаточная смерженнаяdocs/regenerate-agents-md).
Testing & QA
- Гейт
maven-pmd-plugin3.28.0 (PMD 7.17) наverifyдля обоих модулей, rulesetpmd-ruleset.xml(codestyle без opinionated-правил + unused-правила + XPathLiteralFirstInEquals— строковый литерал слева вequals/equalsIgnoreCase;junit5TestPatternразрешает underscore-имена регрессий;includeTests=true— тесты сканируются). - 15 тестовых классов / 144
@Test(core 12/115, app 3/29). 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 таблицах). ВDocToPdfTestмаркер#НЕ проверяется: в.doc-ветке нетGlyphCoverageNormalizer, экзотические глифы легально остаются.notdef, а PDFBox «ремонтирует» подмножества установленных в системе шрифтов и извлекает#— текст/assertions только по Tinos/Carlito-ранам. - Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word (
PiePainterTestаспект h/w=0.585,assertRatioотклонение <0.06;Surface3dPainterTestassertRange±6 pt для центров силуэта +assertRatioдопуск 0.10 для геометрических отношений; shading — не допуск, а перцентильные коридоры яркости p5∈[0.74,0.90], median∈[0.90,1.10], p95∈[1.02,1.20]). - Фикстуры — закоммиченные
samples/*(12: 11.docx+legacy-doc.doc; в тестах не генерировать): 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),legacy-doc.doc(реальный Word 97-2003: 43 картинки, колонтитулы с PAGE-полем, кэшPages=12). - Юниты нормализаторов работают строками (
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_neitherDocxNorDoc↔inputNotAZip_rejectedBeforeRender),BundledFontsTest↔ruPlain_emDashEmbeddedNotHelvetica,ChartSpecTest↔автозаголовки, chart-пейнтеры↔chartsSmartArt_drawingsBecomeImages(+drawingToggles_offRemovesRasters/drawingToggles_chartsOffSmartArtOn),DocToPdfTest↔DocToPdfRenderer(legacyDoc_convertsToPdf— Tinos/Carlito без Helvetica + 43 картинки;legacyDoc_footersCarryPageNumbers— инъекция колонтитулов + PAGE;ole2Junk_rejected);noLoggingWarningInPdf— регрессияslf4j-simple,pdfTitle_comesFromParameter— регрессия PDF-title (юнит-партнёра нет). App-регрессии:requestLimitParams_areIgnored,nonPositiveLimits_failStartup,unknownPath_notFound,concurrentRequests_bothSucceed(гонка реестраPhysicalFonts),corruptNotAZip_rejected,junkInsideValidZip_conversionError,nonDocxFilename_rejected,oversizedOverCoreLimit_rejected,renderFlagsOff_convertsWithoutDrawings,cyrillicAndPathInFilename_sanitizedResponseName(RFC 5987 + path-traversal),docsOpenWithoutKey/forwardedPrefix_healthStaysOpen/forwardedPrefix_docsOpenWithoutKey(открытая документация + матч фильтра без forwarded-contextPath),legacyDoc_convertsToPdf(OLE2-развилка валидации ядра + заголовокX-Wordpdf-Degraded). - UI-тестов нет; гейт SPA —
npm run build(tsc -b) +npm run lint(oxlint,.oxlintrc.json: rules-of-hooks error, only-export-components warn).