Хостовые Setup JDK/Maven/кеш~/.m2 и mvn на раннере убраны: полный mvn clean verify (тесты + PMD + JaCoCo) исполняется только в образе Containerfile.test (без libfontconfig и /etc/fonts). Отчёты JaCoCo извлекаются из образа docker create/cp (отсутствие отчёта — пустая сводка, не падение). mise verify остаётся сырым mvn без docker/podman.
28 KiB
Repository Guidelines
Роутер: правила, инварианты и команды — здесь; глубокие детали —
docs/agent/*.md, нормативные форматы —docs/standards/(ссылка с номером секции обязательна), пользовательская документация —README.md.
Project Overview
Конвертер .docx/.doc → .pdf на чистом Java: docx4j 17.3.2 → XSL-FO → форк Apache FOP, без LibreOffice/Aspose. Бинарный .doc (Word 97-2003) переносится мостом MS-DOC/MS-CFB (internal/doc) в in-memory .docx и идёт тем же конвейером. Java 17, только Maven.
| Модуль | Содержимое |
|---|---|
wordpdf-core |
библиотека: 61 Java-файл (6 — публичный API, 16 internal/, 18 internal/doc/, 18 internal/chart/, 3 fonts/) |
wordpdf-app |
REST API на Spring Boot 4.1.1: 11 классов, единственный public — WordPdfApplication |
wordpdf-web |
SPA (React 19 + TS + Vite + Tailwind), вне Maven-реактора, отдельный образ |
Единственный вход стека — gateway-контейнер nginx (:9010 prod-like compose.yml, :9011 dev compose.dev.yml), не 8080. Авторитетны этот файл, docs/agent/ и код. Полный путеводитель по каталогам, ключевым файлам и командам — docs/agent/repo-map.md.
Пайплайн WordPdfConverter.convert(byte[], String[, ConvertOptions])
Порядок шагов 0–7 фиксирован (convertToStream), местами менять нельзя. Вход роутируется по сигнатуре: PK\x03\x04 → docx-путь; D0 CF 11 E0 A1 B1 1A E1 (CFB, MS-CFB §2.2) → DocToDocx.convert → in-memory .docx → тот же конвейер (предикат — WordPdfValidator.isBinaryDoc). Валидация — до convertToStream: WordPdfValidator.validate(bytes, options) (размер → подпись zip/CFB → контейнер → страницы); для .doc — checkPageCountDoc по сырым байтам.
Порядок: шрифты (BundledFontMapper → BundledFonts.init → restrictToBundled) и правила 1–10 (DocxRewritePipeline.STEP) + OleObjectNormalizer — до WordprocessingMLPackage.load; FOSettings/FopFallbackFonts/LayoutPostRenderer — до setCustomXsltTemplates(VendoredXslt.TEMPLATES); Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL) — последним; finally → deleteEmbeddedFontTempFiles() + сброс имиджевых кешей общей FopFactory + BundledFonts.restrictToBundled() (реестр шрифтов возвращается в бандл-состояние: load() регистрирует встроенные шрифты документа в глобальном PhysicalFonts). Полная таблица шагов и подсчёт страниц — docs/agent/pipeline.md.
Нормализаторы (internal/DocxNormalizer)
Контракт: byte[] normalize(byte[]) throws IOException; нечего менять → вернуть тот же массив (assertSame). Порядок фиксирован: Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby. Правила 1–10 применяет DocxRewritePipeline.STEP одним zip-проходом (неизменённые записи копируются raw-сжатыми байтами); OleObjectNormalizer (правило 11) — лямбдой в WordPdfConverter.normalizers(). STEP выставляют 9 из 10 rewrite-нормализаторов (нет у RubyNormalizer), у OleObjectNormalizer её нет. Правила 1–11, guard'ы, номера секций и инвариант mc-preprocessor.xslt (собственный рерайт strict-URI ломать нельзя) — docs/agent/pipeline.md.
Мост .doc → .docx (internal/doc)
18 классов, 17 package-private; наружу — только DocToDocx (convert/countPages). Общий разбор — DocFile: CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table. Новых runtime-зависимостей нет (POI/POIFS — test-scope). Источники: [MS-DOC] (docs/standards/doc/), [MS-CFB]/[MS-OLEPS]/[MS-ODRAW] (docs/standards/binary/). Байтовые раскладки по классам — docs/agent/doc-bridge.md.
REST API (wordpdf-app, всё package-private кроме WordPdfApplication)
POST /api/v1/convert: multipart-поле file (.docx/.doc) + query/form-параметры errorOnCharts/errorOnSmartArt/errorOnOle (дефолт каждого — false), maxMb/maxPages (лимиты входа: переопределяют серверный дефолт в обе стороны; ≤ 0 → 400). Ответ — application/pdf, Content-Disposition: attachment; filename*=UTF-8''…; имя — ConversionService.safeBaseName. Тело ошибки — {"error": …}. Error-флаги на .doc не срабатывают (BLIP-плейсхолдеры → картинки). ApiExceptionHandler не видит ошибок фильтров — 401 пишет сам ApiKeyFilter.
- Коды: 400 —
ValidationException/BadRequestException/битые параметры; 401 —ApiKeyFilter; 404/405/415 — путь/метод/content-type; 413 — multipart; 422 —DrawingRejectedException(core-DrawingFoundException,Kind {CHARTS, SMARTART, OLE}); 500/503/504 —ConversionFailedException/ConversionRejectedException/ConversionTimeoutException. 500 отвечает фиксированный текст («Внутренняя ошибка конвертации») — сообщение ядра логируется, наружу не попадает. Полная карта —docs/agent/repo-map.md. - Текст 422 — контракт с фронтом: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты».
- Ключ:
X-API-Key↔wordpdf.api-key(пустое = выключено); без ключа открыты толькоOPEN_PREFIXES(/actuator/,/swagger-ui,/v3/api-docs), пути с точечными сегментами — никогда. - Очередь и лимиты: конвертации сериализованы однопоточным
ThreadPoolExecutor(QUEUE_CAPACITY = 16, переполнение → 503): ядро дополнительно сериализует конвертации мониторомWordPdfConverter.class(convert()безопасен из нескольких потоков); головой очереди на старте стоитwarmup(). До очереди — только дешёвый гейт размера (WordPdfValidator.checkInputна потоке Tomcat); полныйvalidate(контейнер/страницы — бюджеты распаковки и прочие пороги выводятся из лимитов входаmaxMb/maxPagesметодомWordPdfValidator.max*, крышек нет) выполняется внутри воркера ядром,ValidationExceptionизExecutionExceptionпробрасывается как 400. Лимиты входа:wordpdf.max-mb/max-pages— дефолт эндпоинта (литералы 5/100 в@Value; значение свойства ≤ 0 →IllegalStateExceptionна старте); параметры запросаmaxMb/maxPagesпереопределяют дефолт в обе стороны (≤ 0 → 400), верхнего потолка нет. - SPA: вся сеть в
wordpdf-web/src/api.ts; ключ вlocalStorage(wordpdf.api.key);ApiKeyGate— только еслиprobeApiKey()подтвердил требование ключа (признак открытого сервера — 405); base —VITE_BASE; DropZone.docx,.doc.
Chart/SmartArt-движок (internal/chart, 18 классов)
Нормативный источник — ECMA-376 (docs/standards/ooxml/: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D, XSD); поведение Word — ms-oi29500.md, ms-odrawxml.md. Калибровки (камера, PIE_DEPTH) меняются только с пиксельными тестами; невалидная фикстура правится, не код.
Java2D → PNG: ChartRenderer.DPI = 300, потолок MAX_PIXELS = 16_777_216 (fitDpi); лимиты ChartSpec.MAX_POINTS = 100_000, ChartRenderer.MAX_TICKS = 1000, DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000, суммарный бюджет chart-PNG на документ MAX_CHART_PNG_BYTES_TOTAL = 128 MiB (превышение — объект удалён + warn; тестовый шов run(pkg, options, maxPngBytesTotal)) — деградация «объект как есть / удалён + warn», не OOM; сам OutOfMemoryError при рендере — не деградация, а ConversionException (500: состояние кучи после OOM ненадёжно). Chart-PNG вставляются media-частями вручную (addChartMedia, /word/media/chart-*, без createImagePart); ChartImageHandler отключает «Compress Pictures» (CR-029) только для них. Пейнтеры, autoTitleDeleted, Combo, обходы JAXB — docs/agent/chart.md.
Критические инварианты (нарушение = битый вывод, не исключение)
docx4j.convert.out.fo.gsubFeatures=false— static-блокWordPdfConverter; иначе FO невалиден →WordLayoutFixupsмолча отказывает всем фиксам → FOP падает наdocx4j-baseline.docx4j.fonts.discoverPhysicalFonts.enabled=falseиdiscoverJarFonts.enabled=false— static-блок: иначеBestMatchingMapperсканирует системные шрифты и jar'ы classpath'а, аrestrictToBundled()всё найденное выбрасывает (~100–140 мс впустую на JVM).discoverJarFonts("fonts-symbol")свойством не гейтится — символ-шрифт регистрируется и снимается restrict'ом как раньше.- Единственный XSL-FO-стилист — вендорный
xslt/docx2fo.xslt(копия из docx4j-export-fo 17.3.2 + два AUDIT-FIX-патча:w:rPr/w:position→baseline-shift, Part 1 §17.3.2.24; AUDIT-FIX-2 —w:moveFrom/w:moveTo/w:bdo/w:dir, иначе их ловит catch-allmatch="*"и текст теряется). Дрейф-гейтvendoredXsltTracksJarCopy: вне AUDIT-FIX-регионов копия побайтно равна стилю из jar'а.setCustomXsltTemplatesпринимает предкомпилированныйTemplates. slf4j-simpleобязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессияnoLoggingWarningInPdf); приложение исключает его — логи ведёт logback.- FOP — форк
org.docx4j:docx4j-fo-renderer*2.11-docx4j.6 (транзитив отdocx4j-export-fo, в pom не пинится; пакетыorg.apache.fop.*).FopFallbackFontsберётw:rendererс mimeapplication/pdf, иначе первый со шрифтами. BundledFonts.init()идемпотентен, распаковывает TTF вwordpdf-fonts-*(deleteOnExit);dropNonBundled()чиститPhysicalFontsот всего, что вне бандла; ВСЕ синхронизированные методыBundledFonts(init/restrictToBundled/font) держат мониторWordPdfConverter.class(не собственный замок класса) — тот же, что сериализует конвертации, поэтому внешний вызов рядом с идущей конвертацией безопасен автоматически. Регрессия —WordPdfConverterTest#concurrentFontMutators_conversionsUnharmed.PhysicalFonts— глобальный и мутируемый → конвертации сериализуются мониторомWordPdfConverter.classвнутри ядра (общаяFopFactoryи сброс её image-кешей — под тем же монитором); приложение держит однопоточный воркер ради 503/timeout;warmup()идёт тем же потоком.- Страницы в валидаторе =
max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1); правила StAX-подсчёта —docs/agent/pipeline.md. - Не чинить:
jc="distribute",suff="tab"/lvlJc, метрика «single», кернинг,framePr,REF/SEQ/TOC-кэш, руби-надстрочница, U+2188/U+218A — доказательства вdocs/agent/render-limitations.md. - Комментарии в
WordPdfConverter/DocxOnOffNormalizerговорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).
Шрифты (30 TTF + 3 лицензии, SIL OFL, wordpdf-core/src/main/resources/fonts/)
9 семейств: 7 × 4 начертания (Carlito/Caladea/Arimo/Tinos/Cousine/DejaVu Sans/DejaVu Serif) + Noto Naskh Arabic / Noto Sans Armenian (только regular). BundledFontMapper.ALIASES: Calibri→Carlito, Calibri Light→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; self-map всех бандл-семейств, включая Noto; fallback — DejaVu Sans; виртуальный SYMBOL_FONT «Segoe UI Symbol» (U+2000–U+2EFF) → fallback до основного цикла. Новый шрифт = файл + запись в BundledFonts.ENTRIES (синхрон проверяет BundledFontsTest). GlyphFont читает TTF напрямую с classpath через fontbox, без java.awt.Font (нужен fontconfig на хосте). Публичный API и детали — docs/agent/repo-map.md.
Команды
Бутстрап: sh bootstrap.sh (Windows: powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1) — project-local mise в ./.mise/, дальше — ./mise.sh / .\mise.ps1.
./mise.sh run verify # = mvn clean verify: тесты + PMD + JaCoCo (гейт перед push)
mvn clean verify # то же; mvnw НЕТ — только системный Maven
./mise.sh run verify-nofontconfig # тот же полный verify в контейнере без fontconfig (именно так живёт CI)
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am: core test-jar
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
./mise.sh run web-install|web-build|web-lint|web-dev # npm ci | tsc -b && vite build | oxlint | vite :5173
podman-compose -f compose.dev.yml up -d --build --force-recreate # dev-стенд :9011, без ключа
./mise.sh run prod-tests # прод-автотесты в prod-autotests/
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD (lxml)
Задачи mise (9): verify, verify-nofontconfig, app-package, app-run, web-install, web-build, web-lint, web-dev, prod-tests.
«Запусти тестовый сервер» (термин пользователя) = полный dev-стенд, НЕ java -jar: podman-compose -f compose.dev.yml up -d --build --force-recreate, вход http://<LAN-IP хоста>:9011 без API-ключа; гейт — контейнеры healthy + корень SPA отвечает 200. --force-recreate обязателен: без него контейнеры остаются на старом образе.
Пересоздание фикстур и перевендоривание стилиста — docs/agent/repo-map.md. Деплой: прод — на пользовательском LAN-сервере; перед деплоем/перезапуском прочитать /home/pjandro/prod/java-word-pdf/DEPLOY.md; пуск — push в main или Run workflow, ручных скриптов нет (детали — docs/agent/ci-cd.md).
Code Conventions & Common Patterns
- Классы
final, приватный конструктор, толькоstatic(stateless, DI нет; конфигурация —Docx4jProperties+ classpath-ресурсы). Исключения — экземпляры по природе:BundledFontMapper,DrawMlColor, Spring-компонентыwordpdf-app. - В
internal/**классы package-private,public— только вызываемые извне пакета: вinternal—DocxNormalizer,DocxRewritePipeline(наружу толькоSTEP),OleObjectNormalizer(толькоnormalize(byte[], boolean)),FopFallbackFonts(declare),LayoutPostRenderer(register/render),DependencyGuard(check); вinternal/chart—DrawingPreRenderer(run) иChartImageHandler. Публичные члены наружу ничем шире этого не расширять;rewrite-хуки — package-private. Вwordpdf-appвсё package-private кромеWordPdfApplication; вinternal/docпубличен толькоDocToDocx. - Нормализаторы — единый контракт
internal/DocxNormalizer+ константаSTEP; порядок цепочки — см. «Нормализаторы», правятся толькоword/*.xml. - Ошибки публичного API — только
ConversionException extends RuntimeException(unchecked); внутренние исключения оборачиваются на границе. В chart — деградация вместо падения.ValidationException— собственностьWordPdfValidator; не оборачивать в общийConversionException. - DI в
wordpdf-app— конструкторная инъекция Spring; состояние сервисовprivate final. SPA: единственный источник состояния —useStateвApp.tsx, вся сеть — вapi.ts. - Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат:
Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx). - Константы UPPER_SNAKE с эталонными значениями (
PIE_DEPTH,DECOMPRESS_MB_PER_MAX_MB); начертанияV_REGULAR/V_BOLD/V_ITALIC/V_BOLD_ITALIC; модели —record; размеры в chart — в пунктах, растр ×DPI/72. - Логирование:
java.util.logging.Loggerв корневом пакете иinternal/, SLF4J — вinternal/chartиwordpdf-app. - Тестовые методы: регрессионные —
объект_условиечерез underscore (ruPlain_cyrillicAndStyles), юниты — camelCase (pageFieldBecomesFldSimple); оба стиля разрешает PMD-паттернjunit5TestPattern(^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$). - PMD (
pmd-ruleset.xml, executionpmd-checkнаverifyв обоих модулях,includeTests=true, валится нарушение любой приоритетности): полные исключения категории, кастомное XPath-правилоLiteralFirstInEqualsи настройки — в самом ruleset.
Runtime & Tooling
- Java 17 + Maven (обязательны; wrapper
mvnwНЕТ); UTF-8; только Maven — никаких Gradle/Ant. Инструменты (Java/Maven/Node/Python) ставит project-local mise (бинарь в.mise/, вне системы), версии пинятся в корневомmise.toml; ежедневный запуск —./mise.sh. - Версии зависимостей — только в корневом
pom.xml(properties + dependencyManagement), новые — latest stable; закреплённый список —docs/agent/repo-map.md. Maven-зависимости — через Nexusmaven-central: локально~/.m2/settings.xml(файл вне репо), CI/Containerfile —.ci/maven-settings.xml+MAVEN_MIRROR_URL. - Фронт: Node из engines vite/oxlint,
npm ciс закоммиченнымpackage-lock.json, TSstrictнигде не включён. Контейнеры (podman/buildah):FROMтолько FQDN, хостовые прокси-переменные обнулять на самой команде (RUN/HEALTHCHECK),DOCKER_BUILDKIT=0обязателен, fontconfig рантайму не нужен (глифы — fontbox). - Локальная проверка одна:
mvn clean verify(тесты + PMD + JaCoCo). Форматтеров и checkstyle для Java нет; статический линтер — PMD. Исполняемый jar проверять толькоjava -jar; нюансBundledFontsTest(file:-протокол classpath) —docs/agent/repo-map.md. - Git: origin
git.pjandro.ru:pjandro/java-word-pdf; защищённые ветки —main,master,dev. Все правки — через PR в дефолтную ветку; push — завершающим шагом задачи, только после./mise.sh run verify. - Прод-координаты и креды в коммитимые файлы не попадают (ни IP, ни хостов, ни пользователей, ни ключей): стенд — Gitea Actions Variables, креды — Secrets; workflow-файлы ссылаются только на
${{ vars.* }}/${{ secrets.* }}(список —GITEA-vars.md). Локальный.env(gitignored) — только дляcompose.yml.
CI/CD (Gitea Actions)
pr.yml (PR checks): job java (единственный полный mvn clean verify внутри образа Containerfile.test — без fontconfig, зеркало Nexus через build-arg) + извлечение jacoco.xml из образа (docker create/docker cp) + coverage-сводка и комментарий в PR, job web (npm ci → build → lint). main.yml: java/web → images-app/images-web (build+push в Nexus, теги prod + sha-<7>) → deploy (SSH, рендер прод-конфигов, гейты healthy) → autotests → rollback при провале. Нарратив — docs/agent/ci-cd.md.
Защита ветки main: required-контексты — PR checks / java (pull_request), PR checks / web (pull_request) (deploy/autotests в список не включать — на PR не бегут). Смена лимитов стенда = правка Variables, PR не нужен.
Testing & QA
- Гейты: PMD
maven-pmd-plugin3.28.0 (includeTests=true) и JaCoCo0.8.15(jacoco:checkнаverify) — LINE0.90(оба модуля), BRANCH0.85(только core); отчётreportраньшеcheck(target/site/jacoco/). Механика —docs/agent/repo-map.md. Плотность покрытия держат тесты, а не заглушки. - Стек: JUnit 6 (
org.junit.jupiter), толькоAssertions— Mockito/AssertJ не использовать; в app-тестах допустим inline-HamcrestcontainsStringвandExpect; тестовые классы package-private, зеркалят main-пакеты. Счётчики —docs/agent/testing.md. - PDF сравнивается текстом, не растеризацией: PDFBox 3,
PDFTextStripper; негативные маркеры —.notdef(#) иHelvetica; текст нормализуется по пробелам (norm). Пиксельные проверки — только в юнитах chart-пейнтеров (допускиassertRatio< 0.06 / < 0.10). Детали —docs/agent/repo-map.md. - Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары
XxxNormalizerTest↔тест-в-конвейеревоспроизводятся грепом по этим ссылкам; исключения —docs/agent/testing.md. - Фикстуры — только закоммиченные
samples/*.docx(13) +samples/*.doc(12), в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (assertSame) + неприкосновенность частей внеword/*.xml. - App-тесты:
@SpringBootTest+@AutoConfigureMockMvc(Boot 4:org.springframework.boot.webmvc.test.autoconfigure); четыре набора свойств = четыре контекста (отдельные классы, не@Nested);ConversionServiceTest/ApiExceptionHandlerTest— без Spring. Core-юниты Spring не поднимают; app-тесты проверяют только HTTP-код/заголовки/текст ошибки. Детали —docs/agent/testing.md. - Жизненный цикл: только
@Test; исключения — два@BeforeAll(прогрев шрифтов) и@AfterEach drainWorkerвConversionTimeoutTest. Ни@Nested, ни@ParameterizedTest, ни@Disabled, ниassertAll. - Идиомы загрузки фикстур: core — classloader без ведущего слэша, app — class-relative со слэшем (core test-jar). Синтетика: docx —
ZipOutputStream,.doc— крафтPOIFSFileSystem. - Сообщения ассертов — по-русски и с наблюдаемым значением; сравнение строк литерал-слева (
"%PDF".equals(...), PMDLiteralFirstInEquals); контракт идентичности —assertSame/assertNotSame. Общих test-util-классов нет: хелперы (norm,pdfText,assertRatio) намеренно продублированы. - Прод-автотесты: pytest + requests; под маркером
needs_keyбез ключа SKIP; конфигурация стенда только env (WORDPDF_BASE_URLобязателен). mvn testне запускает PMD и JaCoCo-гейты (оба наverify) — «зелёное» состояние проверяетсяmvn clean verify.mvn -pl wordpdf-appбез-amпадает: app зависит от core test-jar.