Пересобран корневой AGENTS.md по результатам параллельного исследования (core src, tests, build/config, app/web/docs). Сохранены все разделы и инварианты, добавлены точные счётчики и недостающие детали, полезные AI-ассистенту (идиомы загрузки фикстур по модулям, жизненный цикл тестов, правила PMD/JaCoCo, карта HTTP-контракта). Исправлен фактический дрейф в соседних справках (docs/agent/* объявлены авторитетными наравне с AGENTS.md): - счётчики тестов: 891 → 893 (core 848 → 849, app 43 → 44; ApiExceptionHandlerTest = 5); - internal/chart: 17 → 18 классов, public ещё и ChartImageHandler; - wordpdf-app: 10 → 11 классов (5 классов исключений); - константа STEP: 8 → 9 из 10 rewrite-нормализаторов (есть у HiddenTextNormalizer); - docs/standards: шесть → восемь каталогов; в перечне docs/agent добавлен repo-map. Проверено: mvn clean verify — 893 теста, PMD (includeTests) и гейты JaCoCo (LINE 0.90 обоих модулей, BRANCH 0.85 core) зелёные.
41 KiB
Repository Guidelines
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— библиотека конвертации: docx4j → XSL-FO → FOP; бандл шрифтов, chart/SmartArt-движок, мост.doc. 62 Java-файла: 7 в корневом пакете (публичный 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-реактора, собирается npm и деплоится отдельным образом.
Единственный вход стека — gateway-контейнер nginx (:9010 prod-like compose.yml, :9011 dev compose.dev.yml), не 8080. Авторитетны этот файл, docs/agent/ и код; решения о форматах — по спецификациям из docs/standards/ (ссылка на секцию обязательна).
Architecture & Data Flow
Пайплайн WordPdfConverter.convert(byte[], String[, ConvertOptions])
Порядок фиксирован, местами менять нельзя (WordPdfConverter.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).
| # | Шаг | Что делает |
|---|---|---|
| 0 | DependencyGuard.check() |
API-проба commons-compress ≥ 1.25.0, иначе ConversionException с инструкцией |
| 1 | new BundledFontMapper() → BundledFonts.init() → restrictToBundled() |
инициализация шрифтов — инвариант (объяснение в docs/agent/pipeline.md) |
| 2 | DocxRewritePipeline.STEP → OleObjectNormalizer → WordprocessingMLPackage.load |
один zip-проход правил 1–10 + условная OLE-вычистка (правило 11) |
| 3 | pkg.setFontMapper(mapper) |
привязка шрифтов документа к бандл-TTF |
| 3.5 | DrawingPreRenderer.run(pkg, options) |
c:chart/dgm:relIds → PNG 300 dpi → pic:pic |
| 4 | new FOSettings(pkg) + FopFallbackFonts.declare |
в FOP-конфиг — все бандл-семейства |
| 4.25 | LayoutPostRenderer.register |
кастомный FORenderer: post-FO padding-компенсация таблиц |
| 4.5 | foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES) |
вендорный xslt/docx2fo.xslt с AUDIT-FIX-патчами (инвариант) |
| 5–6 | getFopFactoryBuilder/getFOUserAgent → Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL) |
XSL-FO → PDF; непустой title → заголовок PDF |
| 7 | finally → deleteEmbeddedFontTempFiles() |
в docx4j 17.x OpcPackage.close() нет |
Вход валидируется до convertToStream: WordPdfValidator.validate(bytes, options) (размер → подпись zip/CFB → контейнер → страницы). Для .doc — checkPageCountDoc по сырым байтам (MS-DOC), до конвертации. Полные обоснования шагов и правила подсчёта страниц — docs/agent/pipeline.md.
Мост .doc → .docx (internal/doc, 18 классов)
Нормативный источник — [MS-DOC] в docs/standards/doc/, общее OLE-окружение ([MS-CFB], [MS-OLEPS], [MS-ODRAW]) — docs/standards/binary/. Новых runtime-зависимостей нет (POI/POIFS — test-scope). Публичные точки: DocToDocx.convert(byte[]) и DocToDocx.countPages(byte[]); общий разбор — DocFile (CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table). 16 из 18 классов package-private; наружу — DocToDocx и CfbReader.
| Класс | Семантика (полные байтовые раскладки — docs/agent/doc-bridge.md) |
|---|---|
CfbReader, FibHeader, PieceTable |
CFB ([MS-CFB], любой брак → ConversionException) + FIB (§2.4.1: fWhichTblStm, пары fc*) + текст §2.9.135 (compressed CP1252 / UTF-16LE) |
Grpprl, ChpxIndex, PapxIndex, PrcData |
sprm'ы CHPX/PAPX/TAP/Sepx (§2.6.2) + FKP-индексы (§2.4.6; bOffset=0 — дефолт с сохранением границы рана) + разворот grpprl вне FKP (§2.9.210) |
Styles, FontTable, Lists |
STSH-цепочки base-first, символьные stk=3 → charChain (§2.9.271) + ftc→w:rFonts (§2.9.147) + PlfLst/PlfLfo → word/numbering.xml (§2.9.200/.201) |
Tables, Sections, Headers |
TAP → сетка/границы/w:jc/vAlign/w:tcMar (§2.6.3; битый TDefTable → плоские абзацы) + секции (PlcfSed §2.8.26: continuous/landscape/колонтитулы/колонки/titlePage) + Plcfhdd → headerN.xml/footerN.xml |
SummaryInfo, OfficeArt |
кэш PageCount [MS-OLEPS] (offset'ы относительны начала PropertySet) + BLIP → PNG/JPEG/DIB; EMF/WMF/PICT → пропуск + warn |
DocToDocx, DocxWriter |
оркестратор + DocxBody (раны/pPr/табличный автомат 0x07/TTP → docx-XML) + мульти-частный zip (document/numbering/hdr/ftr/media) |
Нормализаторы (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 её нет вовсе.
StrictOoxmlNormalizer— strict-OOXML → transitional (w:start/w:end→w:left/w:right, проценты ×1000,jc val="end").DocxOnOffNormalizer—w:val="off"/"on"→"false"/"true".SymbolFontNormalizer— PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans.FieldNormalizer—fldCharPAGE/NUMPAGES/SECTIONPAGES →w:fldSimple.InvisibleCharNormalizer— вырезание невидимых/bidi-символов изw:t.GlyphCoverageNormalizer— резка ранов по покрытию глифов,w:rFonts(иначе FOP рисует «#»).TableIndentNormalizer—w:jccenter/right +w:tblInd→ абсолютныйw:tblInd.NumberingSuffixNormalizer—w:suff="space"→ пробел вw:lvlText.HiddenTextNormalizer— вырезание скрытых ранов (w:vanish), guard защищённого содержимого.RubyNormalizer— руби: база → обычные раны, надстрочница вырезается.OleObjectNormalizer— OLE-бинарники вычищаются,<w:object>→ плейсхолдер-картинка;errorOnOle→ 422.
Полные правила с номерами секций, guard'ами и инвариантом про mc-preprocessor.xslt (собственный рерайт strict-URI ломать нельзя) — docs/agent/pipeline.md.
REST API (wordpdf-app, всё package-private кроме WordPdfApplication)
Единственный эндпоинт POST /api/v1/convert: multipart-поле file (.docx/.doc) + факультативные query/form-параметры errorOnCharts/errorOnSmartArt/errorOnOle (дефолты — WordPdfSettings.ERROR_ON_*). Ответ — application/pdf, Content-Disposition: attachment; filename*=UTF-8''…; имя — ConversionService.safeBaseName. Error-флаги диаграмм/SmartArt/OLE на .doc не срабатывают (BLIP-плейсхолдеры → картинки) — описано в @Operation. Полный текст — docs/agent/repo-map.md.
| Ситуация | HTTP | Класс |
|---|---|---|
| Некорректный вход (размер, подпись zip/CFB, контейнер, страницы) | 400 | ValidationException (наследник ConversionException) |
| Ошибка уровня запроса (нет файла, чужое расширение, размер, нечитаемая часть) | 400 | BadRequestException |
| Error-флаг на диаграммы/SmartArt/OLE | 422 | DrawingRejectedException (core-DrawingFoundException, Kind {CHARTS, SMARTART, OLE}) |
| Ошибка ядра/рендера | 500 | ConversionFailedException |
| Очередь переполнена | 503 | ConversionRejectedException |
Дольше wordpdf.convert-timeout (2m) |
504 | ConversionTimeoutException |
| Превышен multipart-лимит | 413 | MaxUploadSizeExceededException |
| Неизвестный путь / метод / content-type | 404 / 405 / 415 | NoResourceFoundException / HttpRequestMethodNotSupportedException / HttpMediaTypeNotSupportedException |
| Битый error-флаг, нет части/параметра | 400 | MethodArgumentTypeMismatchException, MissingServletRequestPartException, MissingServletRequestParameterException |
Тело ошибки — {"error": …}. Текст 422 — контракт с фронтом, показывается дословно: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты». ApiExceptionHandler не видит ошибок фильтров — 401 пишет сам ApiKeyFilter.
- Ключ доступа:
X-API-Key↔wordpdf.api-key(пустое = выключено); без ключа открыты толькоOPEN_PREFIXES(/actuator/,/swagger-ui,/v3/api-docs), пути с точечными сегментами — никогда. МеханикаApiKeyFilter—docs/agent/repo-map.md. - Очередь и лимиты: конвертации сериализованы однопоточным
ThreadPoolExecutor(QUEUE_CAPACITY = 16, переполнение → 503) — ядро мутирует глобальныйPhysicalFontsи не потокобезопасно; головой очереди на старте стоитWordPdfConverter.warmup(); лимиты входа — только конфигурация сервера (wordpdf.max-mb/max-pages, SpEL-дефолты изWordPdfSettings; ≤ 0 →IllegalStateExceptionна старте; параметрами запроса не переопределяются, вapplication.propertiesнамеренно не объявлены). - SPA: вся сеть в
wordpdf-web/src/api.ts(компонентыfetchне вызывают); ключ вlocalStorage(wordpdf.api.key), экранApiKeyGateпоказывается только когдаprobeApiKey()подтвердил требование ключа (признак открытого сервера — 405, не 200/404); base —VITE_BASE(дефолт/, CORS не нужен); три error-флага (дефолт — выключены), DropZone.docx,.doc.
Chart/SmartArt-движок (internal/chart, 18 классов)
Нормативный источник правок — ECMA-376 (docs/standards/ooxml/: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D, XSD schema/strict//schema/transitional/); поведение Word — ms-oi29500.md, ms-odrawxml.md. Эмпирические калибровки (камера, PIE_DEPTH) менять только вместе с пиксельными тестами; фикстура невалидна — правится фикстура, не код.
Java2D → PNG: ChartRenderer.DPI = 300, потолок растра MAX_PIXELS = 16_777_216 (fitDpi понижает эффективный dpi). Защитные лимиты: ChartSpec.MAX_POINTS = 100_000, ChartRenderer.MAX_TICKS = 1000, DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000 — деградация «объект остаётся как есть / удалён + warn», не OOM.
chart-PNG вставляются media-частями вручную (DrawingPreRenderer.addChartMedia, имена /word/media/chart-*, без docx4j-decode'а createImagePart); ChartImageHandler отключает docx4j «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иdocx4j.fonts.discoverJarFonts.enabled=false— static-блокWordPdfConverter:BestMatchingMapper(static) сканирует системные шрифты и jar'ы classpath'а, аBundledFonts.restrictToBundled()перед каждой конвертацией всё найденное выбрасывает (~100–140 мс впустую на JVM).discoverJarFonts("fonts-symbol")свойством не гейтится — символ-шрифт регистрируется и снимается restrict'ом как раньше.- Единственный XSL-FO-стилист — вендорный
wordpdf-core/src/main/resources/xslt/docx2fo.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="*"и текст теряется). Дрейф-гейтWordPdfConverterTest#vendoredXsltTracksJarCopy: вне AUDIT-FIX-регионов вендорная копия обязана быть побайтно равна стилю из jar'а — при апгрейде docx4j перевендорить и перенести патчи.setCustomXsltTemplatesпринимает предкомпилированныйTemplates(каст Object→Templates, поток кидает CCE). 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, иначе первый со шрифтами. - Порядок инициализации шрифтов:
new BundledFontMapper()→BundledFonts.init()→restrictToBundled()— доload().init()идемпотентен иsynchronized, распаковывает TTF во временный каталогwordpdf-fonts-*(deleteOnExitна файлы и каталог);dropNonBundled()чистит глобальный реестрPhysicalFontsот всего, что вне бандла. PhysicalFonts— глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером.warmup()обязан идти тем же сериализующим потоком.- Страницы в валидаторе =
max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1); детальные правила StAX-подсчёта (attrLocal,continuous, колонтитуки, стриминговый проход) —docs/agent/pipeline.md. - Не чинить (невозможности FOP/docx4j и ограничения эталона):
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 (ключи lowercase): 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 до основного цикла. Публичный API BundledFonts: families(), font/regular/bold/italic/boldItalic(family), FALLBACK_FAMILY. Новый шрифт = файл + запись в BundledFonts.ENTRIES (синхрон проверяет BundledFontsTest). GlyphFont читает TTF напрямую с classpath через fontbox — без java.awt.Font (нужен fontconfig на хосте).
Key Directories
| Путь | Назначение |
|---|---|
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ |
публичный API: WordPdfConverter, WordPdfValidator, WordPdfSettings, ConvertOptions, ConversionException/ValidationException/DrawingFoundException |
…/wordpdf/fonts/ |
BundledFonts (реестр/выгрузка TTF), BundledFontMapper (алиасы, self-map), GlyphFont (глиф-движок fontbox) |
…/wordpdf/internal/ |
11 нормализаторов + DocxRewritePipeline (zip-проход правил 1–10) + OleObjectNormalizer + LayoutPostRenderer + FopFallbackFonts + DependencyGuard + интерфейс DocxNormalizer |
…/wordpdf/internal/doc/ |
мост .doc → .docx (18 классов, детали — docs/agent/doc-bridge.md) |
…/wordpdf/internal/chart/ |
18 классов Java2D-рендера диаграмм/SmartArt в PNG (public: DrawingPreRenderer.run, ChartImageHandler) |
wordpdf-core/src/main/resources/ |
fonts/ (30 TTF), xslt/docx2fo.xslt (вендорный стилист), slf4j-simple.properties |
wordpdf-core/src/test/resources/ |
samples/ (25 закоммиченных фикстур: 13 .docx + 12 .doc), geom/presetShapeDefinitions.xml (ECMA-376, только в тестах) |
wordpdf-app/ |
REST API (11 классов, public только WordPdfApplication) |
wordpdf-web/ |
SPA: src/api.ts (вся сеть) + src/components/ (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo) |
корневые Containerfile, compose.yml, compose.dev.yml, gateway/nginx.conf |
контейнеры; единственный вход — gateway (:9010/:9011) |
.gitea/workflows/ |
Gitea Actions (pr.yml, main.yml) — нарратив job'ов docs/agent/ci-cd.md |
docs/standards/ |
нормативные спецификации (навигатор — README.md): ooxml/ (ECMA-376 + XSD + MS-OI29500/MS-ODRAWXML), binary/ (OLE2-окружение), doc/ ([MS-DOC]), docx/ (валидатор фикстур), xls/, xlsx/, ppt/, pptx/ |
docs/agent/ |
глубокие справочники: pipeline, doc-bridge, chart, render-limitations, testing, ci-cd, repo-map (когда читать — по имени файла) |
prod-autotests/ |
прод-автотесты (pytest, конфиг только env) |
develop/ |
рабочие материалы и эталоны рендера (gitignored) — не фикстуры, в тесты/jar не подключать |
Development Commands
Бутстрап toolchain: 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
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # app-тест (-am обязателен: app берёт test-jar core)
mvn -pl wordpdf-app -am package # исполняемый jar бкенда (-am обязателен)
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-стенд: http://<LAN-IP хоста>:9011, без ключа, springdoc вкл; --force-recreate ОБЯЗАТЕЛЕН — без него пересобирается образ, а контейнеры остаются на старом
./mise.sh run prod-tests # прод-автотесты: pip install + pytest -q . в prod-autotests/
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD-валидация фикстур (lxml)
Задачи mise (8): verify, 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.
Пересоздание фикстур (POI) и перевендоривание стилиста после апгрейда docx4j — команды в docs/agent/repo-map.md.
Деплой. Прод — на пользовательском LAN-сервере; перед любым деплоем/перезапуском прочитать /home/pjandro/prod/java-word-pdf/DEPLOY.md. Передёдплой — push в main или Run workflow (workflow_dispatch), ручных скриптов нет. Детали (рендер прод-конфигов job'ом deploy, гейты, откат) — docs/agent/ci-cd.md.
Code Conventions & Common Patterns
- Классы
final, приватный конструктор, толькоstatic(stateless, DI нет; конфигурация —Docx4jProperties+ classpath-ресурсы). Исключения — экземпляры по природе:BundledFontMapper(extends BestMatchingMapper),DrawMlColor, Spring-компонентыwordpdf-app. - В
internal/**классыpublic(иначе родительский пакет не вызвал бы), но публичные члены наружу ограничены:normalize/STEP/declare/run/check/register;rewrite-хуки — package-private. Вwordpdf-appвсё package-private кромеWordPdfApplication. Вinternal/docпубличны толькоDocToDocxиCfbReader. - Нормализаторы — единый контракт
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,MAX_PAGES); начертания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,checkInput_bytesOverLimit,noKey_rejected); чистые юниты — camelCase (pageFieldBecomesFldSimple,splitsRunForUncoveredGlyph); оба стиля разрешает PMD-паттернjunit5TestPattern(^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$). - PMD (
pmd-ruleset.xml, executionpmd-checkнаverifyв обоих модулях,includeTests=true— тесты тоже сканируются, валится нарушение любой приоритетности): полные исключения категории, кастомный XPath-правилоLiteralFirstInEqualsи настройки правил — в самом ruleset.
Important Files
| Файл | Роль |
|---|---|
wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java |
точка входа библиотеки + static-блок (gsubFeatures, отключение discovery шрифтов) + normalizers(options) (порядок цепочки) + VendoredXslt |
wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java |
валидация входа и lightweight-подсчёт страниц (StAX, без docx4j) |
wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java |
все дефолты ядра (MAX_INPUT_MB = 5, MAX_PAGES = 100, MAX_DECOMPRESSED_MB = 200, MAX_ZIP_ENTRIES = 8192, ERROR_ON_* = false); runtime-конфигурации в ядре нет |
wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/DocxRewritePipeline.java |
единственный zip-проход правил 1–10; порядок вызовов rewrite/rewritePart зафиксирован здесь |
wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/doc/DocToDocx.java |
оркестратор моста .doc (convert/countPages) + вложенный DocxBody |
wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/chart/DrawingPreRenderer.java |
замена диаграмм/SmartArt на PNG; владеет MAX_EXTENT_EMU и деградацией при падении рендера |
wordpdf-core/src/main/resources/xslt/docx2fo.xslt |
единственный XSL-FO-стилист (вендорная копия + AUDIT-FIX-патчи) |
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConvertController.java |
HTTP-слой: presence/расширение/размер → ConvertOptions → ConversionService |
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java |
однопоточная очередь конвертаций + таймаут + прогрев ядра |
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiExceptionHandler.java |
исключение → HTTP-код + {"error": …} (здесь же карта 400/404/405/413/415/422/500/503/504) |
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiKeyFilter.java |
аутентификация X-API-Key; 401 пишет сам |
wordpdf-app/src/main/resources/application.properties |
multipart 100MB (file-size-threshold=2MB — крупные части на диск), wordpdf.convert-timeout=2m, пустой wordpdf.api-key, server.forward-headers-strategy=framework; wordpdf.max-mb/max-pages намеренно отсутствуют |
wordpdf-web/src/api.ts |
весь сетевой слой SPA, хранение ключа, типы ошибок |
pom.xml (корень) |
все версии зависимостей и плагинов (в модулях версии не объявлять) |
pmd-ruleset.xml |
ruleset PMD (код-стиль + unused + NPE-safe equals) |
mise.toml |
версии инструментов и 8 задач |
.ci/maven-settings.xml |
Maven-зеркало Nexus; URL из ${env.MAVEN_MIRROR_URL} (координаты стенда в репо не хранятся) |
Containerfile, wordpdf-web/Containerfile |
multi-stage образы бекенда и SPA |
gateway/nginx.conf |
единственный вход: /api/, /swagger-ui, /v3/api-docs, /actuator → app:8080, остальное → web:80 |
wordpdf-core/src/test/java/.../SampleDocxGenerator.java, ChartTypesDocxGenerator.java |
утилиты пересоздания фикстур (main()) |
Runtime & Tooling Preferences
- Java 17 + Maven (обязательны; wrapper
mvnwНЕТ — только системный Maven); UTF-8. Только Maven — никаких Gradle/Ant. Java/Maven/Node/Python ставит project-local mise (бинарь в.mise/, вне системы), версии пинятся в корневомmise.toml(java = temurin-17,maven = 3.9.16— ровно как в CI,node = 24,python = 3.15), ежедневный запуск —./mise.sh/.\mise.ps1. Bootstrap качает mise2026.10.19→./.mise/bin, затемmise trust→mise install→mise run web-install. - Версии зависимостей — только в корневом
pom.xml(properties + dependencyManagement); новые зависимости — latest stable. Закреплено: docx4j17.3.2, commons-compress1.28.0, slf4j2.0.20, Spring Boot4.1.1, springdoc3.1.1, JUnit6.1.3, PDFBox/fontbox3.0.8, POI5.5.1(test), JaCoCo0.8.15; плагины: compiler3.16.0, surefire3.6.0(-Djava.awt.headless=true), jar3.5.1, PMD3.28.0. - Зависимости Maven — через зеркало Nexus
maven-central: локально~/.m2/settings.xml(литеральный URL, файл вне репо), CI/Containerfile —.ci/maven-settings.xml+MAVEN_MIRROR_URL(Variable / build-arg). - Фронт: 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— тесты идут по classpath и repackage-специфику не видят; нюансBundledFontsTest(file:-протокол classpath) —docs/agent/repo-map.md. - Git: origin
git.pjandro.ru:pjandro/java-word-pdf; защищённые ветки —main,master,dev(локально в репо обычно толькоmain+ feature-ветки в работе). Все правки — через PR в дефолтную ветку; push — завершающим шагом задачи, только после./mise.sh run verify. - Прод-координаты и креды в коммитимые файлы не попадают (ни IP, ни хостов, ни пользователей, ни ключей): стенд — Gitea Actions Variables (
DEPLOY_HOST,DEPLOY_USER,DEPLOY_DIR,WORDPDF_BASE_URL,WORDPDF_MAX_PAGES,WORDPDF_MAX_MB,REGISTRY,PIP_INDEX_URL,MAVEN_MIRROR_URL), креды — Secrets (DEPLOY_SSH_KEY,DEPLOY_KNOWN_HOSTS,WORDPDF_API_KEY,REGISTRY_USER,REGISTRY_PASSWORD); workflow-файлы ссылаются только на${{ vars.* }}/${{ secrets.* }}. Локальный.env(gitignored) — только дляcompose.yml.
CI/CD (Gitea Actions)
pr.yml (PR checks): job java (mvn -B -s .ci/maven-settings.xml clean verify через зеркало Nexus) + 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 при провале. Нарратив job'ов и деплоя — 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/). МеханикаargLine/prepare-agent/jacoco.skip—docs/agent/repo-map.md. Плотность покрытия держат тесты, а не заглушки. - Счётчики: 59 тестовых классов / 893 теста (core 53/849 — из них
internal/doc/17 классов / 225 тестов,internal/chart/17 / 271,WordPdfConverterTest77; app 6/44: ConvertController 23 + ApiKeyFilter 8 + ConversionService 5 + ApiExceptionHandler 5 + ConvertLimits 2 + ConversionTimeout 1). JUnit 6 (org.junit.jupiter), толькоAssertions— Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrestorg.hamcrest.Matchers.containsStringвandExpect; тестовые классы package-private, зеркалят main-пакеты. - PDF сравнивается текстом, не растеризацией: PDFBox 3 (
Loader.loadPDF) —PDFTextStripper(пер-странично),processTextPositionдля шрифта символа, обход ресурсов страниц для встроенных шрифтов (EAAAAA+Carlito-Bold), счётчик картинок (imageCount/distinctImageCount— SMask игнорируется). Негативные маркеры:assertFalse(text.contains("#"))(.notdef),assertFalse(font.startsWith("Helvetica")). Текст нормализуется по пробелам (norm). Пиксельные проверки — только в юнитах chart-пейнтеров (допускиassertRatio< 0.06 / < 0.10, числа зашиты в тесты). - Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары
XxxNormalizerTest↔тест-в-конвейеревоспроизводятся грепом по этим ссылкам; исключения (крафт POIFS, синтетика, app-регрессии) —docs/agent/testing.md. - Фикстуры — только закоммиченные
samples/*.docx(13) +samples/*.doc(12), в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (assertSame) + неприкосновенность частей внеword/*.xml([Content_Types].xml). - App-тесты:
@SpringBootTest+@AutoConfigureMockMvc(Boot 4:org.springframework.boot.webmvc.test.autoconfigure); четыре набора свойств = четыре кэшированных контекста (отдельные классы, не@Nested—@Nested+@TestPropertySourceне даёт отдельного контекста);ConversionServiceTest/ApiExceptionHandlerTest— без Spring-контекста. Core-юниты Spring не поднимают; app-тесты не переигрывают семантику конвейера — только HTTP-код/заголовки/текст ошибки. - Жизненный цикл: только
@Test+ два@BeforeAll(прогрев шрифтов вBundledFontsTest,GlyphCoverageNormalizerTest) +@AfterEach drainWorkerвConversionTimeoutTest(дренировать отменённый FOP-рендер — гонка глобальногоPhysicalFonts). Ни@Nested, ни@ParameterizedTest, ни@Disabled, ниassertAll. - Идиомы загрузки фикстур различаются по модулю: core — classloader без ведущего слэша (
getResourceAsStream("samples/" + name)), app — class-relative со слэшем (getResourceAsStream("/samples/ru-plain.docx"), ресурсы из core test-jar). Синтетика, когда фикстуры нет: docx —ZipOutputStreamпо строковому XML,.doc— крафтPOIFSFileSystem. - Сообщения ассертов — по-русски и с наблюдаемым значением (
assertTrue(cond, "нет «Привет, мир!»: " + text)); сравнение строк литерал-слева ("%PDF".equals(...), правило PMDLiteralFirstInEquals); контракт идентичности —assertSame/assertNotSame. Общих test-util-классов в репо нет: хелперы (norm,pdfText,assertRatio) намеренно продублированы по тест-классам. - Прод-автотесты: pytest 9.1.1 + requests 2.34.2, 31 проверка (4 открытых + 27 под маркером
needs_key→ SKIP без ключа); конфигурация стенда только env (WORDPDF_BASE_URLобязателен — без него набор падает, а не подставляет дефолт;WORDPDF_API_KEY/WORDPDF_MAX_PAGES/WORDPDF_MAX_MB/WORDPDF_SAMPLES_DIR— факультативны). mvn testне запускает PMD и JaCoCo-гейты (оба наverify) — «зелёное» состояние проверяетсяmvn clean verify.mvn -pl wordpdf-appбез-amпадает: app зависит от core test-jar.- Справочник: фикстуры и их смысл, юниты моста/нормализаторов/app, пиксели и стенд без fontconfig, регрессивные записи без javadoc-ссылок —
docs/agent/testing.md.