Пересобран корневой 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) зелёные.
27 KiB
Извлечение из AGENTS.md; читать при навигации по репо, деплое и работе с REST/шрифтами — полный «путеводитель», вынесенный из AGENTS.md дословно. Авторитетно наравне с AGENTS.md.
Key Directories (полная таблица)
| Путь | Назначение |
|---|---|
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ |
Публичный API: WordPdfConverter (convert(byte[],String[,ConvertOptions])), WordPdfValidator (checkInput/checkPageCount/validate — без зависимости от docx4j), ConversionException, ValidationException (наследник — «вход некорректен»), DrawingFoundException (enum Kind {CHARTS, SMARTART, OLE}), WordPdfSettings (MAX_INPUT_MB=5, MAX_PAGES=100, защитные MAX_DECOMPRESSED_MB=200/MAX_ZIP_ENTRIES=8192, ERROR_ON_*=false), ConvertOptions (record) |
…/wordpdf/fonts/ |
BundledFonts (реестр/выгрузка TTF), BundledFontMapper (алиасы, self-map, DISPLAY_NAMES, bundledFamily), GlyphFont (глиф-движок fontbox) |
…/wordpdf/internal/ |
11 нормализаторов + DocxRewritePipeline (один zip-проход правил 1–10, raw-копия неизменённых записей) + LayoutPostRenderer (кастомный FORenderer, post-FO padding-компенсация таблиц, шаг 4.25) + интерфейс DocxNormalizer + FopFallbackFonts + DependencyGuard (проверка commons-compress, шаг 0). Классы public (иначе родительский пакет не вызвал бы), публичные члены наружу только normalize/STEP/declare/DependencyGuard.check/LayoutPostRenderer.register; OleObjectNormalizer — многочастный, публичный normalize(byte[], boolean), бросает DrawingFoundException(OLE) |
…/wordpdf/internal/doc/ |
Мост .doc → .docx: 18 классов (детали — docs/agent/doc-bridge.md) — CfbReader, FibHeader, PieceTable, Grpprl, ChpxIndex, PapxIndex, Styles, Tables, Lists, Sections, FontTable, SummaryInfo, Headers, OfficeArt, PrcData, DocFile, DocxWriter, DocToDocx (публичные convert/countPages; вложенный DocxBody — рендер текста и табличного автомата в XML) |
…/wordpdf/internal/chart/ |
18 классов Java2D-рендера диаграмм/SmartArt в PNG (public: DrawingPreRenderer.run и ChartImageHandler — второй инстанцируется из WordPdfConverter) |
wordpdf-core/src/main/resources/fonts/ |
30 TTF + 3 лицензии — бинарные фикстуры, часть jar |
wordpdf-core/src/main/resources/xslt/ |
docx2fo.xslt — вендорный XSL-FO-стилист (копия docx4j-export-fo + AUDIT-FIX-патчи), часть jar |
wordpdf-core/src/test/resources/samples/ |
25 закоммиченных фикстур: 13 .docx + 12 .doc (11 эталонов заказчика из develop/doc/ с теми же базовыми именами + doc-formats.doc); .docx проходят docs/standards/docx/validate-fixtures.py, .doc — бинарные, XSD к ним неприменим |
wordpdf-core/src/test/resources/geom/ |
presetShapeDefinitions.xml — копия приложения ECMA-376, синхрон таблицы PresetGeometry (только в тестах, в jar не попадает) |
wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ |
REST API (11 классов): WordPdfApplication (единственный public), ConvertController, ConversionService (очередь), ApiExceptionHandler, ApiKeyFilter, OpenApiConfig (@SecurityScheme X-API-Key) + 5 классов исключений (BadRequest, DrawingRejected, ConversionFailed, ConversionRejected, ConversionTimeout) |
wordpdf-web/src/ |
SPA: api.ts (вся сеть), components/ (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo) |
корневые Containerfile, compose.yml, compose.dev.yml, gateway/nginx.conf |
Образ бэкенда (multi-stage maven:3.9-eclipse-temurin-17 → eclipse-temurin:17-jre-alpine, non-root uid 10001, -XX:MaxRAMPercentage=70, HEALTHCHECK — busybox wget); compose app+web+gateway (mem_limit: 2g app, подсеть 10.113.0.0/24 gw 10.113.0.1, x-podman.name_separator_compat); прод-compose не в репо — его рендерит job deploy; в репо-compose.yml springdoc выключен env (SPRINGDOC_API_DOCS_ENABLED=false, SPRINGDOC_SWAGGER_UI_ENABLED=false), в compose.dev.yml springdoc-переменных нет вовсе — включён по умолчанию (не отключается). wordpdf-web/Containerfile — node:24-alpine → nginx:alpine, ARG VITE_BASE=/ (прод-CI печёт /pdf-converter/); репозиторный wordpdf-web/nginx.conf в образ не копируется (SPA одностраничная, без клиентского роутинга — SPA-fallback не нужен) |
.env.example |
Шаблон env: WORDPDF_API_KEY (openssl rand -hex 32), закомментированные WORDPDF_MAX_MB/WORDPDF_MAX_PAGES (пустое значение ломает binding long/int). Проду .env не нужен — ключ и лимиты подаёт job deploy из Gitea Secrets/Variables |
.gitea/workflows/ |
Gitea Actions: pr.yml (PR checks), main.yml (тесты + coverage-сводка и комментарий в PR → images-app/images-web (build+push в Nexus) → deploy (рендер прод-конфигов + pull) → autotests → rollback) |
GITEA-vars.md |
Инструкция владельца: Secrets/Variables, защита ветки, перезапуск — только имена переменных, без значений |
prod-autotests/ |
Прод-автотесты API (pytest + requests, 31 проверка): конфигурация стенда только env (WORDPDF_BASE_URL обязателен, WORDPDF_API_KEY/WORDPDF_MAX_PAGES/WORDPDF_MAX_MB/WORDPDF_SAMPLES_DIR факультативны) — прод-хостов/ключей в коде нет |
docs/standards/ |
Нормативная документация форматов Word/Excel, восемь каталогов + навигатор README.md: ooxml/ — OOXML: PDF+md ECMA-376 Part 1 (5-е изд.), md [MS-OI29500]/[MS-ODRAWXML], полные наборы XSD ooxml/schema/strict/ (21) + ooxml/schema/transitional/ (26); binary/ — общее OLE2-окружение .doc/.xls [MS-CFB]/[MS-OSHARED]/[MS-ODRAW]/[MS-OLEPS]/[MS-OFFCRYPTO]/[MS-OVBA]/[MS-WMF]/[MS-EMF]; doc/ — [MS-DOC] (ms-doc.md + ms-doc-full.md — тот же текст с HTML packet diagram'ами и таблицами sprm §2.6.1–2.6.3, где ms-doc.md даёт [TABLE]); docx/ — validate-fixtures.py (XSD-валидация samples/*.docx, lxml, ставится отдельно); xls/ — [MS-XLS] (ms-xls.md + ms-xls-full.md — тот же приём [TABLE]); xlsx/ — [MS-XLSX] (ms-xlsx.md); регенерация — README в каждом каталоге |
develop/ (вне git, gitignored) |
Рабочие материалы и эталоны сравнения рендера — не фикстуры, в тесты/jar не подключать; пиксельные замеры зашиты числами в chart-тестах |
docs/agent/ |
Глубокие справочники: pipeline / doc-bridge / chart / render-limitations / testing / ci-cd / repo-map (когда читать — по имени файла) |
Important Files (полностью)
wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java— точка входа библиотеки + static-блокgsubFeatures+normalizers(options)(порядок цепочки).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,ERROR_ON_* = false); рантайм-конфигурации в ядре нет.wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/chart/DrawingPreRenderer.java— замена диаграмм/SmartArt на PNG; владеетMAX_EXTENT_EMUи деградацией при падении рендера.wordpdf-app/src/main/resources/application.properties— multipart 100MB (max-file-size/max-request-size+file-size-threshold=2MB— части крупнее 2 МБ на диск, не в память; в тон gatewayclient_max_body_size 100m),wordpdf.convert-timeout=2m, пустойwordpdf.api-key,server.forward-headers-strategy=framework(префикс прод-прокси для springdoc) +springdoc.swagger-ui.persist-authorization=true;wordpdf.max-mb/max-pagesздесь намеренно нет.wordpdf-app/pom.xml—spring-boot-maven-pluginс явной executionrepackage(в 4.1.1 сам не связывается, jar останется тонким);slf4j-simpleисключён;spring-boot-starter-webmvc(Boot 4: переименован из starter-web) +spring-boot-starter-actuator(нужен HEALTHCHECK контейнера/actuator/health); тест-зависимости:spring-boot-webmvc-test(в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.wordpdf-core/pom.xml—maven-jar-pluginexecutiontest-jar(публикует фикстуры для app); JaCoCo executioncheckпереопределён (LINE 0.90 + BRANCH 0.85).- Корневой
pom.xml— все версии зависимостей (в модулях версии не объявлять): docx4j17.3.2, commons-compress1.28.0, slf4j2.0.20, JUnit6.1.3, PDFBox/fontbox3.0.8(fontbox— compile в core: глиф-движокGlyphFont;pdfbox— test в обоих модулях; commons-logging исключён, мост —jcl-over-slf4j), 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, PMD3.28.0, JaCoCo0.8.15; пустой дефолт<argLine>(для-Djacoco.skip=true). pmd-ruleset.xml— ruleset PMD (см. Code Conventions)..ci/maven-settings.xml— Maven-зеркало Nexus с URL из${env.MAVEN_MIRROR_URL}(общий файл CI-job'овjavaи Containerfile; координаты стенда в репо не хранятся — Variable/build-arg).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);proxy_read_timeout/proxy_send_timeout 300s(дефолтные 60s рвут 2-минутные конвертации 504 раньше app-ного 504);resolver 10.113.0.1+proxy_passчерез переменные (статическийproxy_passрезолвит имя один раз при старте — gateway, поднявшийся раньше app, получал бы 502 до перезапуска).wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java— main()-утилита пересоздания фикстур;ChartTypesDocxGenerator.java— генераторchart-types.docx.wordpdf-web/vite.local.config.ts— легаси-одноразовщик (прокси/api→ :8091), вtsconfig.node.jsonне включён; кандидат на удаление, не тиражировать паттерн. Корневыеjavac.*.args— мусор пробной компиляции (gitignored), тоже кандидат на удаление.
Development Commands (детали)
Бутстрап toolchain: sh bootstrap.sh (Windows: powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1) — ставит project-local mise в ./.mise/ (gitignored, в систему ничего не ставится) и инструменты из корневого mise.toml. Дальше — через ./mise.sh / .\mise.ps1 (Windows) либо eval "$(./.mise/bin/mise activate bash)".
Точечный запуск одного теста:
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf
Пересоздание фикстур
Пересоздать 10 фикстур (POI, test scope; charts-smartart.docx и ole-embedded.docx НЕ генерируются — созданы вручную, не перезаписывать; chart-types.docx — ChartTypesDocxGenerator):
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
Перевендоривание XSL-FO-стилиста
# Перевендорить XSL-FO-стилист после апгрейда docx4j (этого потребует гейт vendoredXsltTracksJarCopy):
unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-export-fo-<версия>.jar \
org/docx4j/convert/out/fo/docx2fo.xslt > wordpdf-core/src/main/resources/xslt/docx2fo.xslt
# затем перенести AUDIT-FIX-патчи (position → baseline-shift; AUDIT-FIX-2 move/bdo/dir — образец в комментарии самого файла)
Задачи mise: verify, app-package, app-run, web-install, web-build, web-lint, web-dev, prod-tests. Venv прод-автотестов prod-autotests/.venv mise создаёт сам ([env] в mise.toml).
«Запусти тестовый сервер» (полный текст)
«Запусти тестовый сервер» (термин пользователя) = полный dev-стенд, НЕ java -jar: podman-compose -f compose.dev.yml up -d --build --force-recreate — все контейнеры (app+web+gateway) с полной пересборкой образов. Обязательные свойства после запуска: фронт доступен без API-ключа (compose.dev.yml не задаёт WORDPDF_API_KEY → wordpdf.api-key пуст → ApiKeyFilter прозрачен) и с других ПК сети — вход http://<LAN-IP хоста>:9011 (hostname -I на хосте), не localhost. Проверить: podman-compose -f compose.dev.yml ps (контейнеры healthy) и curl -s -o /dev/null -w '%{http_code}' http://<LAN-IP>:9011/ = 200.
REST API (детали bullet'ов)
Единственный эндпоинт POST /api/v1/convert: multipart-поле file + факультативные query/form-параметры errorOnCharts/errorOnSmartArt/errorOnOle (дефолт каждого — WordPdfSettings.ERROR_ON_*). Ответ — application/pdf, Content-Disposition: attachment; filename*=UTF-8''…. Проверка .docx/.doc-расширения — в ConvertController (ошибочный текст 400 — контракт с фронтом); ConversionService.safeBaseName — единый источник имени для файла, заголовка ответа и PDF-title (срезает оба расширения; разрешены [\p{L}\p{N} ._-], пустое → document). Error-флаги диаграмм/SmartArt/OLE на .doc не срабатывают (BLIP-плейсхолдеры → картинки, см. «Мост») — описано в @Operation.
-
Ключ доступа:
ApiKeyFilterсверяет заголовокX-API-Key(ApiKeyFilter.HEADER) со свойствомwordpdf.api-key(envWORDPDF_API_KEY, сравнениеMessageDigest.isEqual). Пустое свойство = аутентификация выключена (devjava -jar, тесты). Без ключа открытыOPEN_PREFIXES=/actuator/,/swagger-ui,/v3/api-docs— матч по пути без forwarded-contextPath (getRequestURI()минусgetContextPath(); иначе подX-Forwarded-PrefixHEALTHCHECK получил бы 401). Пути с точечными сегментами (../%2e) открытыми не считаются никогда. -
Очередь: конвертации сериализованы однопоточным
ThreadPoolExecutor(ConversionService.QUEUE_CAPACITY = 16, переполнение → 503): ядро мутирует глобальный реестрPhysicalFontsи не потокобезопасно. Головой очереди конструктор ставитWordPdfConverter.warmup()— прогрев ядра минимальным in-code docx + растром (~1,5–2,5 с, Future никто не забирает, warmup не бросает): первый реальный запрос после деплоя — за прогретым ядром (замер 2026-11: 0,13 с против 1,74 с наmain), запросы периода прогрева ждут в очереди штатно.future.cancel(true)при таймауте не останавливает FOP мгновенно — осознанный компромисс. -
Лимиты входа задаёт только конфигурация сервера:
wordpdf.max-mb/wordpdf.max-pages(envWORDPDF_MAX_MB/WORDPDF_MAX_PAGES),@ValueвConvertControllerс дефолтом-SpEL изWordPdfSettings(5 МБ / 100); значение ≤ 0 →IllegalStateExceptionна старте; параметрами запроса не переопределяются. Ключи вapplication.propertiesне объявлены — пустое значение затенит SpEL-дефолт. -
SPA: вся сеть в
wordpdf-web/src/api.ts(компонентыfetchне вызывают); ключ вlocalStorage(wordpdf.api.key), при 401 очищается, экранApiKeyGate(UnauthorizedError— наследникApiError, проверяется раньше); гейт показывается только когдаprobeApiKey()(GET /api/v1/convert → 401) подтвердил требование ключа. Запросы на${import.meta.env.BASE_URL}api/...(vitebaseизVITE_BASE, дефолт/) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx под префиксом/pdf-converter/). Три переключателя error-флагов в форме («Диаграммы», «SmartArt», «OLE-объекты», дефолт — все выключены). DropZone принимает.docx,.doc(accept+ текст зоны).
Детали конвенций, рантайма и гейтов
- PDF сравнивается текстом, не растеризацией: PDFBox 3 (
Loader.loadPDF) —PDFTextStripper(пер-страничноsetStartPage/setEndPage), overrideprocessTextPositionдля шрифта конкретного символа (fontNameOf), обход ресурсов страниц для встроенных шрифтов (EAAAAA+Carlito-Bold) и счётчик картинок (imageCount/distinctImageCount— SMask игнорируется). Негативные маркеры:assertFalse(text.contains("#"))(.notdef),assertFalse(font.startsWith("Helvetica")). Текст нормализуется по пробелам (norm); вtableImage_tableAndImage— полное удаление пробелов (docx4j переносит слова в auto-fit таблицах).
PMD: failurePriority в плагине не задан — на практике verify валит нарушение любой приоритетности; перечень исключённых правил в AGENTS.md не дублируется — единственный источник pmd-ruleset.xml.
-
Нормализаторы — единый контракт
internal/DocxNormalizer+ константаSTEP; цепочкаWordPdfConverter.normalizers()=DocxRewritePipeline.STEP(правила 1–10 одним zip-проходом) + лямбдаOleObjectNormalizer; нечего менять → тот же массив; package-private хукstatic String rewrite(String xml)для юнит-тестов (возвращаетnullпри отсутствии изменений; есть у 10 из 11 — у многочастногоOleObjectNormalizerнет); уStrictOoxmlNormalizerесть такжеrewritePart(entryName, xml), уTableIndentNormalizer—rewritePart(name, xml, band)(per-part-логика, хуки пайплайна); правятся только частиword/*.xml. -
Классы в
internal—public(иначе родительский пакет не вызвал бы), но публичные члены наружу толькоnormalize/STEP/declare/DrawingPreRenderer.run/DependencyGuard.check(rewrite, карты — package-private); вwordpdf-appвсё package-private кромеWordPdfApplication. -
Гейт JaCoCo
0.8.15:jacoco:check(правило BUNDLE, LINE COVEREDRATIO0.90— обоих модулей; вwordpdf-core/pom.xmlexecutioncheckпереопределён и добавляет BRANCH COVEREDRATIO0.85— только для core) наverify; агент подключается в surefire черезargLine=@{argLine} -Djava.awt.headless=true(свойствоargLineв корневом pom по умолчанию пусто и перезаписываетсяprepare-agent—mvn test -Djacoco.skip=trueбез агента работоспособно);reportиcheckоба наverify, report раньше — при провале порога отчёт уже на диске; отчётыtarget/site/jacoco/(html+xml, xml нужен CI-сводке). Плотность покрытия держат тесты, а не заглушки: промахи в основном недостижимые IOException/catch-ветки (GlyphFont,BundledFonts) и защитные ветви сканеров нормализаторов/валидатора. -
59 тестовых классов / 893 теста (core 53/849 — из них 17 классов / 225 тестов в
internal/doc/, 17 классов / 271 тест вinternal/chart/,WordPdfConverterTest77 — включая блок аудита .docx 2026-11: правила 9–10, AUDIT-FIX-2 и пиннинг сносок/полей/titlePg/vMerge/sdt/txbx/OMML/highlight на синтетике через хелперdocx(...); app 6/44: ConvertController 23 + ApiKeyFilter 8 + ConversionService 5 + ApiExceptionHandler 5 + ConvertLimits 2 + ConversionTimeout 1). JUnit 6 (org.junit.jupiter:junit-jupiter), surefire 3.6.0 с-Djava.awt.headless=true; толькоAssertions(Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrestorg.hamcrest.Matchers.containsStringвandExpect), тестовые классы package-private, зеркалят main-пакеты; только@Test+ два@BeforeAll(warm-up шрифтов вGlyphCoverageNormalizerTestиBundledFonts.init()вBundledFontsTest) +@AfterEach drainWorkerвConversionTimeoutTest(дренировать отменённый FOP-рендер до следующего класса — гонка глобальногоPhysicalFonts). -
Фронт: Node
^20.19.0 || >=22.12.0(engines vite/rolldown/oxlint изpackage-lock.json— вpackage.jsonсекцииenginesнет), npm с закоммиченнымpackage-lock.json(npm ci); vite^8.3, React^19.2, TS~6.0(strictнигде не включён —npm run buildне является strict-гейтом), Tailwind^4.3, oxlint^1.81; сборка web-образа наnode:24-alpine. -
Контейнеры (podman/buildah):
FROMтолько FQDN (docker.io/library/...— short-name не резолвится безunqualified-search-registries); buildah подмешивает хостовые прокси-переменные вRUN/HEALTHCHECK— обнулятьHTTP_PROXY= http_proxy= …на самой команде (ENV не перебивает). Chart-движку нужен только модульjava.desktop(Graphics2D, он внутри JRE); fontconfig и системные шрифты рантайму не нужны — текст рисуется глифами fontbox (fonts/GlyphFont), проверено на musl-стенде без libfontconfig//etc/fonts. -
Исполняемый jar бэкенда проверять только
java -jar(тесты идут по classpath и repackage-специфику не видят;BundledFontsTest#listedFilesCoverAllTtfInResourcesтребуетfile:-протокол classpath — только surefire, не fat-jar).
Шрифты (детали)
DISPLAY_NAMES — обратный маппинг lowercase→отображаемое имя для documentFontName (пишет GlyphCoverageNormalizer в w:rFonts). BundledFontMapper.bundledFamily — public-хук «имя шрифта из docx → бандл-семейство или fallback» (пользуется chart-движком). GlyphFont — глиф-движок на fontbox (метрики + растеризация глифов для chart-движка и покрытия глифов); читает TTF напрямую из classpath fonts/<file> (не из temp-каталога BundledFonts), кэш по family/variant, of() возвращает null для неизвестного семейства; java.awt.Font из рантайм-пути убран, AWT остаётся только как геометрия Graphics2D.