Прод (наружный nginx срезает /pdf-converter/): springdoc генерировал абсолютные URL от корня хоста — пути до /v3/api-docs и swagger-ui битые. server.forward-headers-strategy=framework + X-Forwarded-* (добавляет наружный nginx) дают server https://pjandro.ru/pdf-converter и configUrl с префиксом; 'native'-клапан Tomcat X-Forwarded-Prefix не понимает. ApiKeyFilter: матч по пути без forwarded-contextPath (под префиксным заголовком getRequestURI() включает префикс — HEALTHCHECK получил бы 401) + открытые без ключа /swagger-ui* и /v3/api-docs* (браузер не может положить ключ в заголовок при загрузке UI; /api/** под ключом). OpenApiConfig: @SecurityScheme X-API-Key — кнопка Authorize в UI, @SecurityRequirement на convert — «Try it out» с ключом. springdoc.swagger-ui.persist-authorization=true. Регрессии: ApiKeyFilterTest#docsOpenWithoutKey, #forwardedPrefix_healthStaysOpen, #forwardedPrefix_docsOpenWithoutKey (вместо удалённого openApiRequiresKey). AGENTS.md синхронизирован.
35 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), НЕ 8080. README устарел шире Docker-секции: лимиты (пишет 5 МБ/100 стр./6 МБ multipart — фактически 20 MiB/1000/100 MB), порты («всё на :8080» — фактически gateway :9010/:9011), API-ключ вообще не упомянут; плюс «фикстуры генерируются POI» (они закоммичены, POI только в генераторе) и Swagger UI без оговорки, что в проде она открыта без ключа, — авторитет этот файл.
Architecture & Data Flow
Пайплайн WordPdfConverter.convert(byte[], String[, ConvertOptions]) (порядок фиксирован, менять местами нельзя)
Наружу checkInput(bytes, maxBytes) вызывается до приватного 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(pkg, maxPages)— до рендера.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, факультативныеrenderCharts/renderSmartArt— query или form) →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;ConversionFailedException→ 500;ConversionRejectedException→ 503;ConversionTimeoutException(wordpdf.convert-timeout, 2m) → 504;MaxUploadSizeExceededException→ 413;MissingServletRequestPartException/MissingServletRequestParameterException→ 400;NoResourceFoundException(неизвестный путь) → 404; catch-all → 500 (подробности только в лог). Четыре app-исключения (ValidationException,ConversionFailedException,ConversionRejectedException,ConversionTimeoutException) — package-private, несут семантику 400/500/503/504. Граница: сломанный контейнер (не zip / размер / страницы) → 400, валидный zip с мусором внутри → 500. Валидация до очереди:checkInput→ zip-магикPK\x03\x04→checkPageCountLightweight(порядок значим). - Ключ доступа:
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-bytes/wordpdf.max-pages(envWORDPDF_MAX_BYTES/WORDPDF_MAX_PAGES),@ValueвConvertControllerс дефолтом-SpEL изWordPdfSettings(20 MiB / 1000); значение ≤ 0 →IllegalStateExceptionна старте; параметрами запроса не переопределяются. Ключи вapplication.propertiesне объявлены — пустое значение затенит SpEL-дефолт. - SPA: вся сеть в
src/api.ts(компонентыfetchне вызывают); ключ вlocalStorage(wordpdf.api.key), при 401 очищается, экранApiKeyGate(UnauthorizedError— наследникApiError, проверяется раньше); запросы на${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. - Страницы в валидаторе =
max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1); explicit = межсекционныеsectPrв body +w:br type="page"+pageBreakBefore(рекурсивно, включая таблицы иw:sdt). Lightweight-путь (StAX по zip, secure-ридер без DTD/external entities): атрибуты — по локальному имени (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 молчит — подпись проверяет вызывающий. Расхождение lightweight↔JAXB допустимо только в завышение.pageCountOfpackage-private намеренно (тесты); при провале JAXB-разбора (getJaxbElement()→ null) бросаетConversionException, а не NPE. - Известный остаток эталона: 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/checkPageCountLightweight/checkPageCount — byte[] или pkg, с лимитом/без), ConversionException, WordPdfSettings (константы-дефолты), ConvertOptions (record: renderCharts, renderSmartArt, maxBytes, 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) + 4 класса исключений |
wordpdf-web/src/ |
SPA (React 19 + TS + Vite + Tailwind): api.ts (вся сеть), components/ (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo) |
корневые Dockerfile, docker-compose.yml, docker-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_BYTES:-20971520/WORDPDF_MAX_PAGES:-1000 |
корневой .env.example |
шаблон env: WORDPDF_API_KEY (openssl rand -hex 32), закомментированные WORDPDF_MAX_BYTES/WORDPDF_MAX_PAGES; реальный прод .env — на прод-сервере (координаты: /home/pjandro/prod/java-word-pdf/DEPLOY.md, вне репо) |
develop/ (вне git) |
рабочие материалы и эталоны Word 365 (word.docx+word.pdf, word-export.*, convert.pdf, 1212.pdf, diff/) — ручное сравнение, не фикстуры, в тесты/jar не подключать |
Development Commands
mvn clean verify # все модули + тесты — обязательный гейт перед 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)
docker compose -f docker-compose.dev.yml up -d --build # dev-стенд: http://127.0.0.1:9011, без ключа, 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-сервере; координаты сервера, каталог, 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 (пробрасывает флаги удалённому скрипту: --build — пересборка образов из origin/main + перезапуск; без флага — restart контейнеров; предупреждает о не запушенном в main). В прод попадает только запушенное в main — рабочее дерево на сборку не влияет. Наружный вход https://pjandro.ru/pdf-converter/ (префикс срезает наружный nginx прод-хоста, не репозиторный gateway-конф; прод-копия gateway-конфа дополнительно содержит proxy_read_timeout 300s — в репо её нет, дефолтные 60s рвут 2-минутные конвертации). Тот же наружный 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-стенд — из репо docker-compose.dev.yml (проект wordpdf-dev, 127.0.0.1:9011:80, без env → ключ пуст, springdoc вкл). Репозиторный docker-compose.yml — третий вариант (проект wordpdf, 9010:80 на все интерфейсы, WORDPDF_API_KEY fail-closed без .env — up упадёт, VITE_BASE — build-arg wordpdf-web/Dockerfile — репо-compose НЕ передаёт: compose build без arg даёт base / и битые ассеты под префиксом, прод передаёт arg по DEPLOY.md). Запуск по просьбе пользователя = прод-стек; dev/java -jar/npm run dev — внутренняя отладка.
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_BYTES20 MiB,MAX_PAGES1000,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-bytes/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(нужен Docker 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. 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; docker-сборка web наnode:24-alpine. - CI, линтеров, форматтеров, checkstyle для Java — нет; проверка одна:
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
- 14 тестовых классов / 126
@Test(core 11/104, app 3/22). 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-пейнтеров, допуски 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/*.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),pageCountOf,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(+checkPageCountLightweight_agreesWithJaxbPath99/100/101,pageCount_breaksInsideTablesAreCounted,pageCount_continuousSectionsNotCountedLightweight),BundledFontsTest↔ruPlain_emDashEmbeddedNotHelvetica,ChartSpecTest↔автозаголовки, chart-пейнтеры↔chartsSmartArt_drawingsBecomeImages(+drawingToggles_offRemovesRasters/drawingToggles_chartsOffSmartArtOn);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). - UI-тестов нет; гейт SPA —
npm run build(tsc -b) +npm run lint(oxlint,.oxlintrc.json: rules-of-hooks error, only-export-components warn).