Files
java-word-pdf/AGENTS.md
T
2026-10-14 20:49:51 +00:00

23 KiB
Raw Blame History

Repository Guidelines

Project Overview

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

Architecture & Data Flow

Пайплайн WordPdfConverter.convertToStream (порядок фиксирован, менять местами нельзя)

  1. new BundledFontMapper() → BundledFonts.init() → BundledFonts.restrictToBundled(). Конструктор маппера каждый раз добавляет системные шрифты в реестр PhysicalFonts; ключ реестра — имя шрифта, addPhysicalFont(URI) не перезаписывает занятый → init() вызывает dropNonBundled() до регистрации и load().
  2. Нормализация байтов docx до JAXB-загрузки (цепочка byte[] → byte[], порядок значим): DocxOnOffNormalizer (w:val="off"/"on" → false/true) → SymbolFontNormalizer (PUA U+F0xx Symbol/Wingdings/Webdings → Unicode + DejaVu Sans; таблица SymbolMapper сгенерирована) → FieldNormalizer (fldChar PAGE/NUMPAGES/SECTIONPAGES → w:fldSimple, иначе во всех колонтитулах один закэшированный номер) → GlyphCoverageNormalizer (режет ран по покрытию глифов, пишет семейство в w:rFonts, иначе FOP рисует «#»).
  3. WordprocessingMLPackage.load → WordPdfValidator.checkPageCount(pkg, maxPages) — до рендера.
  4. pkg.setFontMapper(mapper) → DrawingPreRenderer.run(pkg, options) (шаг 3.5: c:chart/dgm:relIds docx2fo.xslt не умеет — свой Java2D-движок internal/chart/* рендерит в PNG 300 dpi и подменяет на pic:pic; объект, выключенный в ConvertOptions, пропускается до рендера и остаётся в docx).
  5. new FOSettings(pkg) + FopFallbackFonts.declare (декларирует все бандл-семейства — FOP встраивает только задекларированные) → FORendererApacheFOP/FOUserAgent (непустой title → заголовок PDF) → Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL).
  6. finally: deleteEmbeddedFontTempFiles() (в 17.x OpcPackage.close() нет).

REST API (wordpdf-app, все классы package-private)

  • Единственный эндпоинт POST /api/v1/convert (multipart-поле file, факультативные renderCharts/renderSmartArt — query или form) → application/pdf, Content-Disposition: attachment; filename*=UTF-8''….
  • Конвертации сериализованы однопоточным ThreadPoolExecutor (ConversionService.QUEUE_CAPACITY = 16, переполнение → 503): ядро мутирует глобальный реестр PhysicalFonts.
  • Ошибки (ApiExceptionHandler, тело {"error": …}): ValidationException → 400; ConversionFailedException → 500; ConversionRejectedException → 503; ConversionTimeoutException (wordpdf.convert-timeout, 2m) → 504; MaxUploadSizeExceededException → 413; неизвестный путь → 404; catch-all → 500 (подробности только в лог). Граница: сломанный контейнер (не zip / размер / страницы) → 400, валидный zip с мусором внутри → 500. Валидация до очереди: checkInput → zip-магик PK\x03\x04 → checkPageCountLightweight (порядок значим).
  • Ключ доступа: ApiKeyFilter сверяет заголовок X-API-Key со свойством wordpdf.api-key (env WORDPDF_API_KEY, сравнение MessageDigest.isEqual). Пустое свойство = аутентификация выключена (dev java -jar, тесты). /actuator/** открыт (HEALTHCHECK). 401 пишет сам фильтр (ApiExceptionHandler ошибок фильтров не видит). Прод compose выключает springdoc env'ами — документация с валидным ключом даёт 404.
  • Лимиты входа задаёт только конфигурация сервера: wordpdf.max-bytes/wordpdf.max-pages (env WORDPDF_MAX_BYTES/WORDPDF_MAX_PAGES), @Value в ConvertController с дефолтом-SpEL из WordPdfSettings (20 MiB / 1000); значение ≤ 0 → падение на старте; параметрами запроса не переопределяются. Ключи в application.properties не объявлены — пустое значение затенит SpEL-дефолт.
  • SPA: вся сеть в src/api.ts (компоненты fetch не вызывают); ключ в localStorage (wordpdf.api.key), при 401 очищается, экран ApiKeyGate; запросы на ${import.meta.env.BASE_URL}api/... (vite base из VITE_BASE, дефолт /) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом /pdf-converter/).

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

Java2D → PNG 300 dpi (ChartRenderer.DPI = 300). ChartSpec.parse (enum Type: PIE/PIE3D/DOUGHNUT/BAR/BAR_HORIZONTAL/LINE/AREA/SURFACE3D/UNSUPPORTED; пустой c:title + autoTitleDeleted="0" → автозаголовок Chart Title) → ChartRenderer (осевые «круглые» шаги 1/2/5·10ⁿ как Word) → пейнтеры CartesianPainter/PiePainter/Surface3dPainter (калибровка по стр. 3 develop/word-export.pdf: CAMERA_DISTANCE=2.36, DEPTH_RATIO=0.705, HEIGHT_RATIO=0.664, свет (0.83,0.48,0.28)); SmartArtRenderer рисует кэш разложенной схемы word/diagrams/drawing1.xml; палитра темы — DrawMlColor. Калибровочные константы менять только вместе с Surface3dPainterTest/PiePainterTest. Обход pkg.getParts() — только по снимку списка (createImagePart мутирует реестр → CME); rels частей — part.getRelationshipsPart(), не getOwningRelationshipPart(); обход XML обязан раскрывать JAXBElement; при падении рендера — gd.getAny().clear() + warn (деградация, не падение).

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

  • 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() возвращает список. docx2fo.xslt в репозитория нет — он в jar docx4j-export-fo.
  • Страницы в валидаторе = max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1); lightweight-путь (StAX по zip, без docx4j) на не-zip молчит — подпись проверяет вызывающий. Расхождение lightweight↔JAXB допустимо только в завышение.
  • Известный остаток эталона: 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/)

Алиасы MS→open-source в BundledFontMapper.ALIASES: Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans; виртуальный «Segoe UI Symbol» для U+2000–U+2EFF → fallback. Noto Naskh Arabic / Noto Sans Armenian — только regular, в маппер не регистрируются (покрытие подбирает PhysicalFonts-реестр). Новый шрифт = файл + запись в BundledFonts.ENTRIES (синхрон проверяет BundledFontsTest).

Key Directories

Путь Назначение
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ публичный API: WordPdfConverter, WordPdfValidator, ConversionException, WordPdfSettings (константы-дефолты), ConvertOptions (record: renderCharts, renderSmartArt, maxBytes, maxPages)
…/wordpdf/fonts/ BundledFonts (реестр/выгрузка TTF), BundledFontMapper (алиасы MS→open-source)
…/wordpdf/internal/ 4 байтовых нормализатора + FopFallbackFonts
…/wordpdf/internal/chart/ Java2D-рендер диаграмм/SmartArt в PNG
wordpdf-core/src/main/resources/fonts/ 30 TTF + лицензии — бинарные фикстуры, часть jar
wordpdf-core/src/test/resources/samples/ 11 закоммиченных .docx-фикстур (единственные фикстуры)
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ REST API: WordPdfApplication, ConvertController, ConversionService (очередь), ApiExceptionHandler, ApiKeyFilter
wordpdf-web/src/ SPA (React 19 + TS + Vite + Tailwind): компоненты в components/, вся сеть в api.ts
корневые Dockerfile, docker-compose.yml, docker-compose.dev.yml, gateway/nginx.conf образ бэкенда (multi-stage, temurin-21); compose app+web+gateway
корневой .env.example шаблон env: WORDPDF_API_KEY (openssl rand -hex 32), закомментированные WORDPDF_MAX_BYTES/WORDPDF_MAX_PAGES; реальный прод .env — в PROD-DIR/
develop/ (вне git) рабочие материалы и эталоны Word 365 (word.docx+word.pdf, word-export.*, 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

Деплой. Прод — каталог PROD-DIR (вне репо; проект wordpdf-prod, образы *:prod, build-context'ы указывают в репозиторий → пересборка берёт рабочее дерево, незакоммиченные правки поедут в прод): gateway только на PROD-HOST:9010 (LAN), ключ — .env прод-каталога (fail-closed ${WORDPDF_API_KEY:?…}), springdoc выключен env'ами, SPA собрана с VITE_BASE=/pdf-converter/, свой nginx.conf = репозиторный + proxy_read_timeout 300s (дефолтные 60 с рвут длинные конвертации). Наружный вход https://pjandro.ru/pdf-converter/ (внешний nginx PROD-HOST). Dev-стенд — из репо docker-compose.dev.yml (проект wordpdf-dev, :9011, пустой ключ). Репозиторный docker-compose.yml — третий вариант (проект wordpdf, 9010:80 на все интерфейсы, VITE_BASE не передаётся). Перезапуск прода — ./restart.sh в прод-каталоге: без флага restart app web → гейт healthy app (до 120 с) → restart gateway; --build — up -d --build. Gateway всегда последним (nginx кэширует DNS бэкендов — иначе 502). Гейт успешности: docker compose ps (3× healthy) + curl http://PROD-HOST:9010/actuator/health → UP. Запуск по просьбе пользователя = прод-стек; dev/java -jar/npm run dev — внутренняя отладка.

Code Conventions & Common Patterns

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

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_BYTES 20 MiB, MAX_PAGES 1000, RENDER_CHARTS/SMARTART); рантайм-конфигурации в ядре нет.
  • wordpdf-app/src/main/resources/application.properties — multipart 100MB (в тон gateway client_max_body_size 100m), wordpdf.convert-timeout=2m, пустой wordpdf.api-key; wordpdf.max-bytes/max-pages здесь намеренно нет.
  • wordpdf-app/pom.xml — spring-boot-maven-plugin с явной execution repackage (в 4.1.1 сам не связывается, jar останется тонким); slf4j-simple исключён; тест-зависимости: spring-boot-webmvc-test (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.
  • wordpdf-core/pom.xml — maven-jar-plugin execution test-jar (публикует фикстуры для app).
  • Корневой pom.xml — все версии зависимостей (в модулях версии не объявлять): docx4j 17.3.2, slf4j 2.0.20, JUnit 6.1.3, PDFBox 3.0.8 (test), POI 5.5.1 (test, только генератор фикстур), Spring Boot 4.1.1 (BOM-import), springdoc 3.1.1; surefire с -Djava.awt.headless=true.
  • 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-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java — main()-утилита пересоздания фикстур.

Runtime & Tooling Preferences

  • Java 21 + Maven (обязательны; wrapper mvnw нет); UTF-8. Только Maven — никакого Gradle/Ant.
  • Версии зависимостей — только в корневом pom.xml (properties + dependencyManagement); новые зависимости — latest stable.
  • Фронт: Node ≥ 20.19 (фактически vite ^8.3.0, React ^19.2, TS ~6.0, Tailwind ^4.3, oxlint; docker-сборка на node:24-alpine), npm с закоммиченным package-lock.json (npm ci).
  • CI, линтеров, форматтеров, checkstyle для Java — нет; проверка одна: mvn clean verify.
  • Исполняемый jar бэкенда проверять только java -jar (тесты идут по classpath и repackage-специфику не видят).
  • Git: origin git.pjandro.ru:pjandro/java-word-pdf, рабочие ветки main/dev защищены (правила глобального AGENTS.md).

Testing & QA

  • JUnit 6 (org.junit.jupiter:junit-jupiter), surefire 3.6.0 с -Djava.awt.headless=true в argLine; только Assertions (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest org.hamcrest.Matchers.containsString в andExpect); тестовые классы package-private, зеркалят main-пакеты; только @Test (+ @BeforeAll где нужен warm-up шрифтов).
  • PDF сравнивается текстом, не растеризацией: PDFBox 3 (Loader.loadPDF) — PDFTextStripper для текста (пер-странично setStartPage/setEndPage), override processTextPosition для шрифта конкретного символа (fontNameOf), обход ресурсов страниц для встроенных шрифтов (EAAAAA+Carlito-Bold) и счётчика картинок (imageCount). Негативные маркеры — регрессии: assertFalse(text.contains("#")) (.notdef), assertFalse(font.startsWith("Helvetica")). Текст нормализуется по пробелам (norm); в tableImage_tableAndImage — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах).
  • Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word.
  • Фикстуры — закоммиченные samples/*.docx (11; в тестах не генерировать): core грузит classpath-ресурсом → byte[], PDF для PDFBox — временный файл; app читает /samples/… из test-jar core (classifier tests) → mvn -pl wordpdf-app без -am не соберётся. In-memory docx — ZipOutputStream из литеральных XML или POI в byte[].
  • Юниты нормализаторов работают строками (rewrite) + zip'ами из ZipOutputStream; обязательные контракты: «нечего менять → тот же массив (assertSame)» и неприкосновенность частей вне word/*.xml ([Content_Types].xml).
  • App-тесты: @SpringBootTest + @AutoConfigureMockMvc (Boot 4: org.springframework.boot.webmvc.test.autoconfigure); три контекста — ConvertControllerTest (пустой ключ), ApiKeyFilterTest (properties = "wordpdf.api-key=…"), ConvertLimitsTest (@TestPropertySource с лимитами — отдельный класс, не @Nested).
  • Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой + javadoc-ссылка): DocxOnOffNormalizerTest↔ruPlain_regularRunsUseRegularFont, SymbolFontNormalizerTest↔symbolFonts_bulletsAreNotHash, FieldNormalizerTest↔pageNumbers_recomputedNotCached, GlyphCoverageNormalizerTest↔exoticGlyphs_drawnNotHash, WordPdfValidatorTest↔staleCachePageCountRejectedBeforeRender, BundledFontsTest↔ruPlain_emDashEmbeddedNotHelvetica, chart-пейнтеры↔chartsSmartArt_drawingsBecomeImages (+drawingToggles_*); noLoggingWarningInPdf — регрессия slf4j-simple (юнит-партнёра нет). App-регрессии: requestLimitParams_areIgnored, nonPositiveLimits_failStartup, unknownPath_notFound, concurrentRequests_bothSucceed (гонка реестра PhysicalFonts).
  • UI-тестов нет; гейт SPA — npm run build (tsc -b) + npm run lint (oxlint).