Files
java-word-pdf/docs/agent/repo-map.md
T
Pjandro 3dd770c542
PR checks / web (pull_request) Successful in 38s
PR checks / java (pull_request) Failing after 1m56s
docs: AGENTS.md — сводный репозиторный гайд по фактам дерева
Пересобран корневой 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) зелёные.
2026-11-07 03:19:01 +00:00

27 KiB
Raw Blame History

Извлечение из 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 МБ на диск, не в память; в тон gateway client_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 с явной execution repackage (в 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-plugin execution test-jar (публикует фикстуры для app); JaCoCo execution check переопределён (LINE 0.90 + BRANCH 0.85).
  • Корневой pom.xml — все версии зависимостей (в модулях версии не объявлять): docx4j 17.3.2, commons-compress 1.28.0, slf4j 2.0.20, JUnit 6.1.3, PDFBox/fontbox 3.0.8 (fontbox — compile в core: глиф-движок GlyphFont; pdfbox — test в обоих модулях; commons-logging исключён, мост — jcl-over-slf4j), POI 5.5.1 (test), Spring Boot 4.1.1 (BOM-import), springdoc 3.1.1; pluginManagement: compiler 3.16.0, surefire 3.6.0 с -Djava.awt.headless=true, jar 3.5.1, PMD 3.28.0, JaCoCo 0.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 (env WORDPDF_API_KEY, сравнение MessageDigest.isEqual). Пустое свойство = аутентификация выключена (dev java -jar, тесты). Без ключа открыты OPEN_PREFIXES = /actuator/, /swagger-ui, /v3/api-docs — матч по пути без forwarded-contextPath (getRequestURI() минус getContextPath(); иначе под X-Forwarded-Prefix HEALTHCHECK получил бы 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 (env WORDPDF_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/... (vite base из 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), override processTextPosition для шрифта конкретного символа (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 COVEREDRATIO 0.90 — обоих модулей; в wordpdf-core/pom.xml execution check переопределён и добавляет BRANCH COVEREDRATIO 0.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/, WordPdfConverterTest 77 — включая блок аудита .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-Hamcrest org.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.