33 KiB
Repository Guidelines
Project Overview
Конвертер .docx/.doc → .pdf на чистом Java (docx4j 17.3.2 + форк 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 → Apache FOP), шрифты и chart/SmartArt-движок внутри.wordpdf-app— REST API (Spring Boot 4.1.1), единственныйpublic-класс —WordPdfApplication.wordpdf-web— SPA (React 19 + TS + Vite + Tailwind), собирается npm, деплоится отдельно от Maven.
Вход стека — gateway-контейнер nginx (:9010 prod-like compose / :9011 dev), не 8080. Авторитетны этот файл, docs/agent/ и код.
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 |
| 1 | BundledFontMapper → BundledFonts.init() → restrictToBundled() |
инициализация шрифтов — инвариант |
| 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 | FOSettings + FopFallbackFonts.declare |
в FOP-конфиг — все бандл-семейства |
| 4.25 | LayoutPostRenderer.register |
кастомный FORenderer: post-FO padding-компенсация таблиц |
| 4.5 | 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() нет |
Полные обоснования шагов и правила подсчёта страниц — docs/agent/pipeline.md. Вход валидируется до convertToStream: WordPdfValidator.validate(bytes, options) (размер → подпись zip/CFB → контейнер → страницы); для .doc — checkPageCountDoc по сырым байтам до конвертации.
Мост .doc → .docx (internal/doc)
Нормативный источник — [MS-DOC] в docs/standards/doc/, общее OLE-окружение ([MS-CFB], [MS-OLEPS], [MS-ODRAW]) в docs/standards/binary/, [MS-ODRAWXML] в docs/standards/ooxml/, ссылки — с номерами секций. Новых runtime-зависимостей нет (POI/POIFS — test-scope). Публичные точки: DocToDocx.convert(byte[]) (вызывает WordPdfConverter) и DocToDocx.countPages(byte[]) (вызывает WordPdfValidator.checkPageCountDoc); общий разбор — 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], любой брак → ValidationException) + 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) |
Перечень остатков моста — docs/agent/doc-bridge.md.
Нормализаторы (internal/DocxNormalizer)
Контракт: byte[] normalize(byte[]) throws IOException; нечего менять → вернуть тот же массив (assertSame в тестах). Порядок фиксирован: Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby; правила 1–10 применяет DocxRewritePipeline.STEP одним zip-проходом (механика zip-прохода — docs/agent/pipeline.md), OleObjectNormalizer подключается лямбдой в WordPdfConverter.normalizers().
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 (ломать собственный рерайт URI нельзя) — docs/agent/pipeline.md.
REST API (wordpdf-app, всё package-private кроме WordPdfApplication)
Единственный эндпоинт POST /api/v1/convert: multipart-поле file + факультативные query/form-параметры errorOnCharts/errorOnSmartArt/errorOnOle (дефолты — WordPdfSettings.ERROR_ON_*). Ответ — application/pdf, Content-Disposition: attachment; filename*=UTF-8''…. Имя файла — ConversionService.safeBaseName; расширение .docx/.doc проверяет ConvertController (текст ошибки 400 — контракт с фронтом). Error-флаги диаграмм/SmartArt/OLE на .doc не срабатывают (BLIP-плейсхолдеры → картинки) — описано в @Operation. Полный текст — docs/agent/repo-map.md.
| Ситуация | HTTP | Класс |
|---|---|---|
| Некорректный вход (размер, подпись zip/CFB, контейнер, страницы) | 400 | ValidationException (наследник ConversionException) |
| 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, пути с точечными сегментами — никогда. МеханикаApiKeyFilter—docs/agent/repo-map.md. - Очередь и лимиты: конвертации сериализованы однопоточным
ThreadPoolExecutor(переполнение → 503) — ядро мутирует глобальныйPhysicalFontsи не потокобезопасно; лимиты входа — только конфигурация сервера (wordpdf.max-mb/max-pages, SpEL-дефолты изWordPdfSettings; ≤ 0 →IllegalStateExceptionна старте; параметрами запроса не переопределяются, вapplication.propertiesне объявлены). Подробности —docs/agent/repo-map.md. - SPA: вся сеть в
wordpdf-web/src/api.ts(компонентыfetchне вызывают); ключ вlocalStorage(wordpdf.api.key), экранApiKeyGateпоказывается только когдаprobeApiKey()подтвердил требование ключа; base —VITE_BASE(дефолт/, CORS не нужен); три error-флага (дефолт — выключены), DropZone.docx,.doc. Полный текст —docs/agent/repo-map.md.
Chart/SmartArt-движок (internal/chart)
Нормативный источник любых правок — 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) только для них — медиа документов остаются в штатном docx4j-режиме.
Пейнтеры со всеми калибровками, autoTitleDeleted/автозаголовки, Combo-семантика, защитные обходы JAXB — docs/agent/chart.md.
Критические инварианты (нарушение = битый вывод, не исключение)
docx4j.convert.out.fo.gsubFeatures=false— static-блокWordPdfConverter. Иначе FO невалиден →WordLayoutFixupsмолча отказывает всем фиксам → FOP падает наdocx4j-baseline.- Единственный 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 — docx4j position игнорирует; AUDIT-FIX-2 — шаблоныw:moveFrom/w:moveTo/w:bdo/w:dir(plain-text passthrough, move-правки не раскрашиваются, bidi — принятая деградация), иначе их ловит catch-allmatch="*"и текст теряется; руби тут не чинится — схема docx4j не биндитw:rubyBase/w:rt, их разбирает правило 10 в байтах). Дрейф-гейтWordPdfConverterTest#vendoredXsltTracksJarCopy: вне AUDIT-FIX-регионов вендорная копия обязана быть побайтно равна стилисту из jar'а (сравнение с возвратом AUDIT-FIX-региона к исходному вызовуcreateBlockForRPrи удалением региона AUDIT-FIX-2) — при апгрейде docx4j перевендорить и перенести патчи.setCustomXsltTemplatesпринимает предкомпилированныйTemplates(getTemplatesкастит 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-fo17.3.2, в pom не пинится; пакетыorg.apache.fop.*).w:renderersв docx4j 17.x содержит несколькоw:renderer(по mime) —FopFallbackFontsберёт тот, у которого mimeapplication/pdf, иначе первый со шрифтами. Оригиналdocx2fo.xslt— в jardocx4j-export-fo, в конвейере используется вендорная копия (bullet «Единственный XSL-FO-стилист»). - Порядок инициализации шрифтов:
new BundledFontMapper()→BundledFonts.init()→restrictToBundled()— доload().BundledFonts.init()идемпотентен иsynchronized, распаковывает TTF во временный каталогwordpdf-fonts-*(deleteOnExitна файлы и на каталог).dropNonBundled()чистит глобальный реестрPhysicalFontsот всего, что вне бандла. PhysicalFonts— глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером.- Страницы в валидаторе =
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/)
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). Детали (DISPLAY_NAMES, bundledFamily, GlyphFont на fontbox) — docs/agent/repo-map.md.
Key Directories
| Путь | Назначение |
|---|---|
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ |
публичный API; fonts/ (бандл+глиф-движок), internal/ (нормализаторы, пайплайн), internal/doc/ (мост), internal/chart/ (диаграммы) |
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, тесты) |
wordpdf-app/ |
REST API (10 классов, public только WordPdfApplication) |
wordpdf-web/ |
SPA: src/api.ts (вся сеть) + компоненты |
корневые 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/ |
нормативные спецификации форматов Word/Excel (навигатор — README.md): ooxml/ (ECMA-376 + XSD + MS-OI29500/MS-ODRAWXML), binary/ (OLE2-окружение), doc/ ([MS-DOC]), docx/ (валидатор фикстур), xls/ ([MS-XLS]), xlsx/ ([MS-XLSX]) |
docs/agent/ |
глубокие справочники (когда читать — по имени файла) |
prod-autotests/ |
прод-автотесты (pytest, конфиг только env) |
Полная таблица (.env.example, GITEA-vars.md, develop/ — рабочие материалы, не фикстуры) и «Important Files» — docs/agent/repo-map.md.
Development Commands
Бутстрап toolchain: sh bootstrap.sh (Windows: bootstrap.ps1) — project-local mise в ./.mise/ (в систему ничего не ставится), дальше — ./mise.sh / .\mise.ps1. Полный текст — docs/agent/repo-map.md.
./mise.sh run verify # = mvn clean verify: тесты + PMD + гейты JaCoCo (обязательный гейт перед push)
mvn clean verify # то же самое; mvnw НЕТ — только системный Maven
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда (-am обязателен: app берёт test-jar core)
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 ОБЯЗАТЕЛЕН: без него podman-compose пересобирает образ, но контейнеры оставляет на старом (проверено: свежий image, а в app крутится jar прошлой сборки)
./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: verify, app-package, app-run, web-* (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(instance, но не наследник docx4j) и Spring-компонентыwordpdf-app. - Нормализаторы — единый контракт
internal/DocxNormalizer+ константаSTEP; порядок цепочки — см. «Нормализаторы», правятся толькоword/*.xml, package-private хукrewrite(nullпри отсутствии изменений). Полный текст —docs/agent/repo-map.md. - Ошибки публичного API — только
ConversionException extends RuntimeException; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения. - Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат:
Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx) — новый фикс оформлять так же. - Константы UPPER_SNAKE с числовыми эталонными значениями (
PIE_DEPTH,MAX_PAGES); начертанияV_REGULAR/V_BOLD/...; модели —record; размеры в chart — в пунктах, растр ×DPI/72. - Классы в
internal—public(иначе родительский пакет не вызвал бы), публичные члены наружу ограничены (normalize/STEP/declare/run/check/register, перечни —docs/agent/repo-map.md); вwordpdf-appвсё package-private кромеWordPdfApplication. - Тестовые методы: регрессионные —
объект_условиечерез 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— тесты тоже сканируются, валится нарушение любой приоритетности): полные исключения категории и настройки правил — в самом ruleset.
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,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. - Зависимости Maven — через зеркало Nexus
maven-central: локально~/.m2/settings.xml(литеральный URL, файл вне репо), CI/Containerfile —.ci/maven-settings.xml+MAVEN_MIRROR_URL(Variable / build-arg). - Фронт: Node из engines vite/rolldown/oxlint,
npm ciс закоммиченнымpackage-lock.json, TSstrictнигде не включён. Контейнеры (podman/buildah):FROMтолько FQDN, хостовые прокси-переменные обнулять на самой команде (RUN/HEALTHCHECK), fontconfig рантайму не нужен (глифы — fontbox). Полные bullet'ы —docs/agent/repo-map.md. - Локальная проверка одна:
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/devзащищены (правила глобального AGENTS.md; локально толькоmain). - Push всегда в конце задачи:
git push(и следующий за ним PR) — завершающий шаг, только когда вся реализация готова и обязательные гейты пройдены (./mise.sh run verify). Промежуточные push запрещены; коммиты в ходе работы — по правилам глобального AGENTS.md.
CI/CD (Gitea Actions)
pr.yml (PR checks): job java (mvn clean verify через зеркало Nexus) + coverage-комментарий в PR, job web (npm ci → build → lint). main.yml: java/web → образы images-app/images-web в Nexus → deploy (SSH, рендер прод-конфигов, гейты healthy) → autotests → rollback при провале. Нарратив job'ов и деплоя — docs/agent/ci-cd.md.
Правило: координаты прода и креды в коммитимые файлы не попадают — ни внутренние IP, ни SSH-пользователи/логины, ни хосты, ни директория деплоя, ни ключи/токены/пароли. Координаты стенда — 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.* }}. Смена лимитов = правка Variables, PR не нужен. Защита ветки main: required-контексты PR checks / java (pull_request), PR checks / web (pull_request) (deploy/autotests в список НЕ включать — на PR не бегут, мерж блокировался бы навсегда).
Testing & QA
- Гейты: PMD
maven-pmd-plugin3.28.0 (includeTests=true) и JaCoCo0.8.15(jacoco:checkнаverify) — пороги LINE0.90(оба модуля), BRANCH0.85(core); отчётreportраньшеcheck(при провале порога отчёт уже на диске). МеханикаargLine/prepare-agent/jacoco.skip—docs/agent/repo-map.md. Плотность покрытия держат тесты, а не заглушки. - Счётчики: 57 тестовых класса / 886 теста (core 51/843, app 6/43; разбивка —
docs/agent/repo-map.md). JUnit 6, только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). - Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары
XxxNormalizerTest↔тест-в-конвейеревоспроизводятся грепом по этим ссылкам; исключения (крафт POIFS, синтетика, app-регрессии) —docs/agent/testing.md. - Фикстуры — только закоммиченные
samples/*.docx+samples/*.doc, в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (assertSame) + неприкосновенность частей внеword/*.xml. - App-тесты:
@SpringBootTest+@AutoConfigureMockMvc; четыре набора свойств = четыре кэшированных контекста (отдельные классы, не@Nested);ConversionServiceTest/ApiExceptionHandlerTest— без Spring-контекста. - Справочник: фикстуры и их смысл, юниты моста/нормализаторов/app, пиксели и стенд без fontconfig, регрессивные записи без javadoc-ссылок —
docs/agent/testing.md.