de9995bba3
PR checks / web (pull_request) Successful in 43s
PR checks / java (pull_request) Successful in 1m51s
Main: tests, deploy, autotests / web (push) Successful in 58s
Main: tests, deploy, autotests / images-web (push) Successful in 31s
Main: tests, deploy, autotests / java (push) Successful in 1m38s
Main: tests, deploy, autotests / images-app (push) Successful in 49s
Main: tests, deploy, autotests / deploy (push) Failing after 2m46s
Main: tests, deploy, autotests / autotests (push) Has been skipped
Main: tests, deploy, autotests / rollback (push) Successful in 2m20s
DrawingPreRenderer.swapForPicture вставляет media-часть вручную (newPartForContentType → setBinaryData → rels.addPart, имена /word/media/chart-*): createImagePart писал temp-файл и декодировал PNG обратно ради mime/размеров, которые нам и так известны. ChartImageHandler (foSettings.setImageHandler) возвращает null из compressedVariant для chart-* — «Compress Pictures» не ресемплит и не декодирует наши 300-dpi растры; медиа документов остаются в штатном docx4j-режиме. Замер (25 фикстур × 6 прогонов): chart-types.docx 657→507 МБ alloc (тёплый), суммарно 11640→10604 МБ, прочие 23 файла ±0%; ретеншн не изменился (144 MiB после GC), temp-файлов 0. Регрессии: chartMedia_notDownsampled, DrawingPreRendererTest, ChartImageHandlerTest.
194 lines
32 KiB
Markdown
194 lines
32 KiB
Markdown
# 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`)
|
||
|
||
Нормативный источник — `docs/standards/doc/` ([MS-DOC], [MS-CFB], [MS-OLEPS], [MS-ODRAW]; [MS-ODRAWXML] лежит в `docs/standards/docx/`), ссылки — с номерами секций. Новых 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()`.
|
||
|
||
1. `StrictOoxmlNormalizer` — strict-OOXML → transitional (`w:start`/`w:end` → `w:left`/`w:right`, проценты ×1000, `jc val="end"`).
|
||
2. `DocxOnOffNormalizer` — `w:val="off"/"on"` → `"false"/"true"`.
|
||
3. `SymbolFontNormalizer` — PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans.
|
||
4. `FieldNormalizer` — `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`.
|
||
5. `InvisibleCharNormalizer` — вырезание невидимых/bidi-символов из `w:t`.
|
||
6. `GlyphCoverageNormalizer` — резка ранов по покрытию глифов, `w:rFonts` (иначе FOP рисует «#»).
|
||
7. `TableIndentNormalizer` — `w:jc` center/right + `w:tblInd` → абсолютный `w:tblInd`.
|
||
8. `NumberingSuffixNormalizer` — `w:suff="space"` → пробел в `w:lvlText`.
|
||
9. `HiddenTextNormalizer` — вырезание скрытых ранов (`w:vanish`), guard защищённого содержимого.
|
||
10. `RubyNormalizer` — руби: база → обычные раны, надстрочница вырезается.
|
||
11. `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/docx/`: графики §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-all `match="*"` и текст теряется; руби тут не чинится — схема 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-fo` 17.3.2, в pom не пинится; пакеты `org.apache.fop.*`). `w:renderers` в docx4j 17.x содержит несколько `w:renderer` (по mime) — `FopFallbackFonts` берёт тот, у которого mime `application/pdf`, иначе первый со шрифтами. Оригинал `docx2fo.xslt` — в jar `docx4j-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/` | нормативные спецификации OOXML/.doc + XSD + `validate-fixtures.py` |
|
||
| `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`.
|
||
|
||
```bash
|
||
./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`, execution `pmd-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 качает mise `2026.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`, TS `strict` нигде не включён. Контейнеры (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-plugin` 3.28.0 (`includeTests=true`) и JaCoCo `0.8.15` (`jacoco:check` на `verify`) — пороги LINE `0.90` (оба модуля), BRANCH `0.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-Hamcrest `org.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`.
|