Files
java-word-pdf/AGENTS.md
T
Pjandro 8d5a19491e
PR checks / web (pull_request) Successful in 31s
PR checks / java (pull_request) Successful in 1m6s
Main: tests, deploy, autotests / web (push) Successful in 33s
Main: tests, deploy, autotests / java (push) Successful in 1m4s
Main: tests, deploy, autotests / images-web (push) Successful in 28s
Main: tests, deploy, autotests / images-app (push) Successful in 40s
Main: tests, deploy, autotests / deploy (push) Successful in 1m32s
Main: tests, deploy, autotests / autotests (push) Successful in 38s
Main: tests, deploy, autotests / rollback (push) Has been skipped
Мост .doc → .docx: горизонтальное объединение ячеек из сетки строки (gridSpan, §2.9.321)
TTP-абзац каждой строки несёт свой sprmTDefTable; автомат использовал только
сетку первой строки → объединённая ячейка получала tcW первой колонки и
рендерилась пол-width с лишней вертикальной чертой в строке. Теперь rowXml
строит tcW/gridSpan из собственной сетки строки, согласованной с tblGrid
(ECMA-376 §17.4.65); при невыровненных границах — прежняя индексная выдача.

Регрессия — WordPdfConverterTest#docMergedTableRow_fullWidthNotSplit,
юниты — DocToDocxFormattingTest#mergedRow_gridSpanAndWidth,
#misalignedRow_fallsBackToColumnWidths.
2026-10-31 23:25:13 +00:00

253 lines
98 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. Авторитетны этот файл и код.
## 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-проба `ZipArchiveInputStream.getNextEntry()` — совместимость commons-compress ≥ 1.25.0; иначе `ConversionException` с инструкцией вместо мутного `NoSuchMethodError` внутри docx4j |
| 1 | `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` | Конструктор маппера добавляет системные шрифты в глобальный реестр `PhysicalFonts`; `init()` вызывает `dropNonBundled()` **до** регистрации бандла (`addPhysicalFont` не перезаписывает занятый ключ — иначе системный Calibri ломает em-dash-fallback) |
| 2 | `DocxRewritePipeline.STEP` → `OleObjectNormalizer` → `WordprocessingMLPackage.load` | Один zip-проход переписывания XML-частей (правила 1–8, см. ниже) + условная OLE-вычистка (правило 9) |
| 2.5 | `WordPdfValidator.checkPageCount(normalizedBytes, maxPages)` | Lightweight-оценка страниц по zip, до рендера |
| 3 | `pkg.setFontMapper(mapper)` | Привязка шрифтов документа к физическим TTF |
| 3.5 | `DrawingPreRenderer.run(pkg, options)` | `c:chart`/`dgm:relIds` → PNG 300 dpi → `pic:pic` (docx2fo.xslt их не умеет) |
| 4 | `new FOSettings(pkg)` + `FopFallbackFonts.declare(foSettings)` | В FOP-конфиг добавляются **все** бандл-семейства: FOP встраивает только задекларированные |
| 4.25 | `LayoutPostRenderer.register(foSettings)` | Кастомный `FORenderer`: post-FO padding-компенсация таблиц (`start-indent` += `padding-left` первой ячейки), внутри — штатный `FORendererApacheFOP` |
| 4.5 | `foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES)` | Стилист — вендорный `xslt/docx2fo.xslt` (копия docx4j-export-fo + AUDIT-FIX-патч `w:rPr/w:position`→`baseline-shift`); `Templates` компилируется один раз — `getTemplates` кастит значение в `Templates` |
| 5 | `FORendererApacheFOP.getFopFactoryBuilder` + `getFOUserAgent` | Непустой `title` → заголовок PDF |
| 6 | `Docx4J.toFO(foSettings, os, FLAG_EXPORT_PREFER_XSL)` | XSL-FO → PDF |
| 7 | `finally` → `getFontTablePart().deleteEmbeddedFontTempFiles()` | В docx4j 17.x `OpcPackage.close()` нет — пакет в памяти |
Вход валидируется **до** `convertToStream`: `WordPdfValidator.validate(bytes, options)` (размер → подпись: zip `PK\x03\x04` или CFB `D0 CF 11 E0` → контейнер → страницы). Для `.doc` страницы считаются **по сырым байтам .doc, до конвертации**: `checkPageCountDoc` = `max(SummaryInfo PageCount, 1 + явные разрывы)`; явные — 0x0C в основном тексте + `sprmPFPageBreakBefore` из PAPX. Тот же метод — вход приложения.
### Мост `.doc` → `.docx` (`internal/doc`)
Нормативный источник — `docs/standards/doc/` ([MS-DOC], [MS-CFB], [MS-OLEPS], [MS-ODRAWXML]), ссылки — с номерами секций. Новых runtime-зависимостей нет (POI остаётся test-scope; POIFS — только в тестах для упаковки крафтовых CFB). Публичные точки: `DocToDocx.convert(byte[])` (вызывает `WordPdfConverter`) и `DocToDocx.countPages(byte[])` (вызывает `WordPdfValidator.checkPageCountDoc`); общий разбор — `DocFile` (CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table). Все классы package-private-члены, наружу только `DocToDocx`.
|Класс|Спецификация|
|---|---|
|`CfbReader`|[MS-CFB] заголовок (секторы 512/4096, mini 64), FAT/DIFAT (лимиты секторов + защита от циклов), miniFAT + mini stream из root, directory; любой брак (цикл, ссылка за файл, обрезанный поток, битый заголовок) → `ValidationException`|
|`FibHeader`|[MS-DOC §2.4.1/§2.6.1] FibBase (`fWhichTblStm` — бит 9 u16@10 → 1Table/0Table), FibRgLw97 (ccpText/ccpFtn/ccpHdd), пары FibRgFcLcb97: fcStshf=1, fcPlcfSed=6, fcPlcfHdd=11, fcPlcfBteChpx=12, fcPlcfBtePapx=13, fcSttbfFfn=15, fcClx=33, fcDggInfo=50, fcPlfLst=73, fcPlfLfo=74|
|`PieceTable`|§2.9.135 Clx/Pcdt: куски compressed (FC/2, байт + CP1252-карта 0x80–0x9F) и uncompressed (UTF-16LE); FC за потоком → `ValidationException`|
|`Grpprl`|§2.6.2 sprm'ы: CHPX — bold 0x0835, italic 0x0836, strike 0x0837, kul 0x2A3E, hps 0x4A43, hpsBi 0x4A61, ftc0 0x4A4F, ftc1 0x4A50, cv 0x6870 (4-й байт FF → auto), sprmCFSpec 0x0875, **sprmCPicLocation 0x6A03** (смещение BLIP в Data); PAPX — **sprmPHugePapx 0x6646**/**sprmPTableProps 0x646B** (указатели на PrcData в Data, разворачивает `PrcData.resolve`; `Grpprl.scan` сам их корректно пропускает по spra=3), jc 0x2461 (4→distribute, 5/7/8/9→both, 6 — игнор) и jc80 0x2403 (3/4/5 — justify-both с разной компрессией, distribute у jc80 нет), dxaLeft/dxaLeft1/dxaRight + 80-варианты 0x840F/0x8411/0x840E и sprmPNest 0x465F/sprmPNest80 0x4610 (XAS со знаком → hanging/firstLine; общий накопитель `Grpprl.Indents`: nest к своему dxaLeft, современное семейство вытесняет 80-е), pageBreakBefore 0x2407, InTable 0x2416, sprmPFTtp 0x2417, istd 0x8463, LSPD 0x6412 (dyaLine i16 + fMult), before/after 0xA413/0xA414, PChgTabs 0xC60D и **sprmPChgTabs 0xC615** (табы стиля; PChgTabsDelClose §2.9.182 — радиус удаления из rgdxaClose, XAS_plusOne), **ilvl 0x260A** (u8; 0x0C — «пропустить, не нумеровать»), **ilfo 0x460B** (i16: 0/0xF801 — списока нет, 1..0x07FE — 1-базированный индекс rgLfo, 0xF802..0xFFFF — отрицание индекса с сохранением отступов); TAP — **sprmTDefTable 0xD608**, sprmTTableBorders 0xD613, sprmTTableBorders80 0xD605, sprmTJc 0x548A / sprmTJc90 0x5400 (u16 0/1/2 → left/center/right, единый маппинг: FOP complex-script не поддерживает, RTL вне контура). Спец-длины операндов spra=6: у 0xD608 счётчик cb **двухбайтовый** («остаток+1», §2.9.321 — формула «1+первый байт» врёт при cb>255), у 0xC60D cb=0xFF — обрыв разбора; у 0xC615 cb=0xFF — длина 3 + 4·cTabsDel + 3·cTabsAdd по раскладке §2.9.182 (разбор продолжается)|
|`ChpxIndex`/`PapxIndex`|§2.4.6: PlcfBte (aFc n+1 + pn 22 бита) → FKP-страницы 512 Б по pn·512 (rgfc (n+1)×4, rgbx n×1/×13, crun/cpara — последний байт); Chpx = cb + grpprl; PapxInFkp: cb≠0 → GrpPrlAndIstd 2cb−1, cb=0 → cb′ → 2cb′ (внутри istd(2) + grpprl, grpprl может быть пустым — istd без прямых Prl); bOffset=0 → дефолт; **istd сохраняется** (`istdFor`, вне диапазона −1) — по нему `DocxBody` применяет цепочку `Styles`|
|`Styles`|§2.9.271 STSH по fcStshf: LPStshi (cbStshi, cstd, cbSTDBaseInFile) → LPStd на чётных границах → Std (stdf: sti/stk/istdBase/cupx + xstzName + LPUpx): stk=1 → UPX[0]=UpxPapx (istd(2)+grpprl), UPX[1]=UpxChpx. Цепочка base-first (предок раньше потомка, last-wins при скане); istdBase 0x0FFF — без предка, цикл — обрыв на MAX_CHAIN=16. Разбор **снисходительный** (образец FontTable): битый/отсутствующий STSH → пустая таблица, конвертация на прямых свойствах, без `ValidationException`|
|`Tables`|TAP TTP-абзаца (§2.6.3) → `Grid(colWidths, indent, bordersXml, tblJc)`: sprmTDefTable (§2.9.321, ncols 1..63, rgdxaCenter XAS со знаком — ширина = center[i+1]−center[i], первый center — сдвиг от поля); границы: sprmTTableBorders (§2.9.302, 6×Brc: cv fAuto, dptLineWidth 1/8pt, brcType §2.9.39) иначе sprmTTableBorders80 (§2.9.303, ico→цвет §2.9.171); brcType=0 не эмитится, ≥0x40 ширина ×8, sz<2 → 2; выравнивание: sprmTJc/sprmTJc90 (u16: 1→"center", 2→"right", прочее → null — элемент не эмитится), современный перекрывает 90-вариант (тот же приоритет, что у 0xD613 над 0xD605) → `w:jc` в tblPr (`openTable`; регрессия — WordPdfConverterTest#docFooterTableCentered_shiftedLikeWord). `null` (нет/битый TDefTable, неположительная ширина) → строка деградирует в плоские абзацы|
|`Lists`|§2.9.200/.201 PlfLst/PlfLfo → `word/numbering.xml`: PlfLst — cLst SHORT (2 Б) при `fc`, rgLstf с `fc+2` (§2.9.201, Figure 56); LSTF (28 Б, fSimpleList→1 LVL иначе 9, массив LVL приложен за `fc+lcb`) + LVL (LVLF 28 Б: iStartAt/nfc/jc/ixchFollow/cbGrpprl'ы; Xst: плейсхолдеры 0x00–0x08 → `%{n+1}`, литеральный `%` → `%%`) → `w:abstractNum` (MSONFC [MS-OSHARED §2.2.1.3] → ST_NumberFormat §17.18.59, экзотика CJK → decimal — нет глифов в бандле; ixchFollow 1/2 → `w:suff` space/nothing, 0=tab не эмитится; grpprlPapx уровня → `w:ind`, grpprlChpx → `w:rPr` rFonts/b/sz); LFO (lsid→первый LSTF) + LFOLVL (fStartAt → `w:startOverride`, fFormatting → полный `w:lvl`) → `w:num` (numId = 1-базированный ilfo). Снисходительно (образец `Styles`): битая таблица/обрыв LVL → пустой/неполный результат; `hasNum` — numId разрешается в валидный abstractNum, иначе абзацы деградируют в плоские|
|`Sections`|PlcfSed (§2.8.26): aCP n+1 + Sed n (12 Б) + Sepx (cb + секционные sprm) → `list()` — список record'ов `Section` (CP-диапазон, геометрия секции, `continuous` из sprmSBkc); невозрастающие aCP → `ValidationException`; финальный aCP реальные файлы пишут за ccpText (PLC покрывает весь текстовый поток) — конец последней секции клампится к ccpText; `pageWidth()`/`header()`/`footer()` — геометрия последней секции (полоса набора для правила 7), `continuousSectionEnds()` — вычитание из подсчёта страниц (последняя секция не считается)|
|`FontTable`|SttbfFfn (§2.9.147): индекс ftc → имя семейства в `w:rFonts`|
|`SummaryInfo`|[MS-OLEPS §2.2] PropertySet-поток `\x01SummaryInformation`; **offset'ы заголовка относительны начала PropertySet-потока** (`abs = Offset0 + offset`); PIDSI_PAGECOUNT=0x0E|
|`Headers`|Plcfhdd (§2.4.1): 6 разделителей + по 6 историй на секцию (even/odd/first × hdr/ftr); odd hdr/ftr **каждой** секции → своя часть `headerN.xml`/`footerN.xml` (нумерация независимая по типу) и `headerReference`/`footerReference` type="default" в её sectPr; пустая история `[x,x)` → части нет, docx4j наследует колонтитук предыдущей секции; guard-¶ отрезается; PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple` (та же семантика, что `FieldNormalizer` в docx-пути)|
|`OfficeArt`|[MS-ODRAW] PICF @ fcDggInfo/lcbDggInfo (Table-поток), delay-поток = WordDocument; DggContainer → BStoreContainer(0xF004)/BStoreContainerDelay(0xF007)/инлайн → FBSE → BLIP: 0xF01A EMF / 0xF01B WMF / 0xF01C PICT / 0xF01D JPEG (=0xF02A) / 0xF01E PNG / 0xF01F DIB; PNG/JPEG дословно, DIB → ImageIO → PNG, EMF/WMF/PICT → пропуск + warn (EMF-рендера в Java2D нет)|
|`PrcData`|§2.9.210 PrcData в Data-потоке (`[cbGrpprl:2][grpprl]`, капа cb 0x3FA2, поля `next` нет): `resolve(data, grpprl)` разворачивает grpprl абзаца, чьи свойства Word вынес за FKP-страницу PAPX, — одиночный Prl `sprmPHugePapx` (0x6646; в grpprl GrpPrlAndIstd — единственный Prl при istd=0, §2.6.2) и `sprmPTableProps` (0x646B — цепочка продолжается в указанном PrcData). Оба указателя разворачиваются на своей позиции **без обрыва** текущего массива, не-спец-спрмы сохраняются (union): spec §2.6.2 велит хвост за PTableProps игнорировать, но Word пишет в нём легаси-зеркало (в `samples/ru-table-image.doc` — единственный `sprmTDefTable`, Appendix A <9>), а `sprmTInsert` из PrcData конвертер не читает — замещение ломало бы сетку; спец-спрмов нет → **тот же массив** (по ссылке); любой брак (ptr за Data, cb вне [1, 0x3FA2], цикл A→B→A — бюджет 32 PrcData) → останов без исключения, снисходительно (образец `Styles`/`Lists`). Подключается единственной точкой — `DocxBody.buildRange` (покрывает тело, колонтитуки, TTP-ветку и обычные huge-PAPX абзацы). Регрессия — `DocToDocxFormattingTest#hugePapxRowMark_closesRowWithGridFromPrcData` |
|`DocToDocx`|Оркестратор + вложенный `DocxBody`: текст → раны (CHPX+стилевой chpx-цепочка → rPr, прямой PAPX — после `PrcData.resolve` — +стилевая papx-цепочка (отступы через `Grpprl.Indents`, 80-варианты включительно; `sprmPChgTabsPapx`/`sprmPChgTabs` → `w:tabs`, у стилевого варианта радиус удаления из `rgdxaClose`) + sprmPIlfo/sprmPIlvl → pPr + `w:numPr` (между pageBreakBefore и tabs, CT_PPr §17.3.1.26; ilfo=0 перекрывает стилевой, ilvl=0x0C и неразрешённый numId → без numPr), base→derived→direct last-wins), ¶ → `<w:p>`; TAB/0x0B → `w:tab`/`w:br`, 0x0C в ране → `w:br type="page"`, 0x0C в конце абзаца — **разрыв секции**: `sectPr` соответствующей `Sections.Section` (матчинг по конечному CP) в pPr этого абзаца, внутри таблицы деградирует в `w:br type="page"`; body-level `sectPr` — последняя секция; `w:type continuous` из sprmSBkc; 0x1E → U+2011, 0x1F → U+00AD, 0x02/0x03/0x04 (сноски) → пропуск; U+0001 со sprmCPicLocation → DrawingML `pic` (общий путь с картинками и OLE-fallback); field-символы в основном тексте: инструкция скрыта, кэшированный результат после разделителя видим; **табличный автомат**: абзац с 0x07 без TTP закрывает ячейку, 0x07+sprmPFTtp — конец строки (`Tables.parse` по TAP → `w:tbl`/`w:tr`/`w:tc`, сам маркер не эмитится), sprmPFInTable открывает ячейку; без корректного TDefTable строка деградирует в плоские абзацы (прежнее поведение); сетка первой строки действует на всю таблицу как `tblGrid`, ширины/объединение ячеек каждой строки — из её собственного TDefTable (горизонтальное слияние → `w:gridSpan`)|
|`DocxWriter`|Мульти-частный zip: `[Content_Types].xml` (hdr/ftr/numbering/png/jpg), `_rels/.rels`, `word/document.xml` (посекционные sectPr + headerReference; tblPr таблиц: tblW → jc (из sprmTJc) → tblInd → tblBorders), `word/_rels/document.xml.rels`, `word/numbering.xml`, `word/headerN.xml`/`footerN.xml` (по одной на непустую историю секции), `word/media/imageN.(png|jpg)`; корневые namespaces w/r/wp/a/pic|
Остаток моста (осознанный, вне контура): семантика рестартов списков не переносится (`fNoRestart`/`ilvlRestartLim` → `w:lvlRestart` — docx4j-Emulator применяет свой дефолт «рестарт на старшем уровне»), как и `fLegal`/`isLgl`, `dxaIndentSav` и `LfoData.cp`; `sprmPIlvl=0x0C` — абзац без numPr (не «в списке без номера»); AUTONUM-поля трактуются как обычные списки; отрицательный `sprmPIlfo` («сохранить отступы») — обычный numPr, отступы делает прямой `w:ind` абзаца; объединённые ячейки: вертикальное слияние (`vertMerge`) не переносится, горизонтальное — переносится собственной сеткой строки (TTP-абзац каждой строки несёт свой `sprmTDefTable`, §2.9.321 → `w:gridSpan`+суммарный `w:tcW`; регрессия — WordPdfConverterTest#docMergedTableRow_fullWidthNotSplit, юниты — DocToDocxFormattingTest#mergedRow_gridSpanAndWidth, #misalignedRow_fallsBackToColumnWidths), вложенные таблицы (sprmPFInnerTtp — разделитель ячейки/строки там ¶ 0x0D, не 0x07) и бордюры уровня ячейки (TC80/sprmTCellBorders) не переносятся — только сетка и строковые границы; строки, у которых сетка задана только `sprmTInsert` (в PrcData нет `sprmTDefTable`, а PAPX-зеркало отсутствует), деградируют в плоские абзацы (`sprmTInsert` конвертер не читает); `DocFile.countPages` (`PapxIndex.countPageBreakBefore`) цепочку PrcData не следует — свойства вне FKP в подсчёт страниц не попадают, 0x0C-разрывы считаются; сноски/концевые сноски/комментарии не рендерятся (метки ссылок пропускаются); чётные и first-page варианты колонтитуков не переносятся (переносится только odd → `type="default"`, FOP не различает чётность полос набора, `titlePg` не эмитится); разрыв секции в абзаце со sprmPFInTable деградирует в разрыв страницы (`w:sectPr` в `w:pPr` внутри `w:tc` невалиден); error-флаги `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` на `.doc` **не срабатывают** — диаграммы/SmartArt/OLE в бинарном формате существуют только как BLIP-плейсхолдеры, мост выдаёт их картинками (задокументировано в `@Operation`); `stale-cache.doc` конвертируется (кэш PageCount=5, концепта lastRenderedPageBreak в .doc нет) — семантика отличается от docx-фикстуры, запинено тестом.
### Нормализаторы (`internal/DocxNormalizer`)
Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame` в тестах). Восемь rewrite-нормализаторов выставляют константу `STEP` (`public static final DocxNormalizer`); у `OleObjectNormalizer` STEP **нет** — он подключается лямбдой в `WordPdfConverter.normalizers()`. Правила 1–8 применяет `internal/DocxRewritePipeline` — **один zip-проход**: к каждой записи `word/*.xml` рерайты цепляются в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix (каждое правило работает только содержимым одной части — по-частная цепочка эквивалентна последовательным полным проходам); до прохода из `word/document.xml` извлекается полоса набора (`TableIndentNormalizer.bandOf`, −1 — полосы нет), и `word/headerN.xml`/`footerN.xml` дополнительно прогоняются через `TableIndentNormalizer.rewritePart` с этой полосой; неизменённые записи переносятся raw-копией сжатых байтов (без inflate/deflate); нигде не поменялось → тот же массив. `OleObjectNormalizer` — второй условный проход (меняет части, а не XML). Индивидуальные `normalize()` восьми нормализаторов сохранены (контракт юнит-тестов), но `WordPdfConverter` их не вызывает — его `normalizers(options)` = `DocxRewritePipeline.STEP` + лямбда OLE. Порядок правил значим:
1. `StrictOoxmlNormalizer` — strict-OOXML → transitional: `a:`-проценты и `w14:fillToRect` → тысячные ×1000, текст `wp14:pctWidth`/`pctHeight`; элементы `w:start`/`w:end` → `w:left`/`w:right` (кроме `w:lvl/w:start` в numbering.xml); значения `w:val="start"/"end"` у `w:jc` и `w:tab` правятся **всегда** (docx4j `Justification.setXslFO` знает только left/center/right/both, для END `fo:text-align` не пишет вовсе — `jc="end"` рендерился по левому краю; Part 1 §17.3.1.13: `jc val="end"` — правовыравнивание в LTR, ST_Jc §17.18.44; RTL вне контура — FOP без complex-script). Strict-ность части определяется наличием `http://purl.oclc.org` (не «transitional-URI в документе» — mixed-документ трактуется по каждой части). **Guard сосуществования форм**: атрибут `w:start`/`w:end` не переименовывается, если в том же открывающем теге уже есть `w:left`/`w:right` (дубль атрибута ломает well-formedness — регрессии `indCoexistLeftStartUntouched`, `indCoexistForms_convertsNotRejected`); элементы `w:start`/`w:end` в strict-части переименовываются глобально, в transitional — только внутри `w:tcMar`/`w:tblCellMar` без одноимённого соседа (`maxOccurs=1` на left). Ничего не поменялось → `rewrite` вернул `null` → исходный массив (`StrictOoxmlNormalizerTest#transitionalCoexistReturnsOriginalArray`).
2. `DocxOnOffNormalizer` — `w:val="off"/"on"` → `"false"/"true"`; якорь по тегу, правится только атрибут `w:val`, текст между тегами не трогается.
3. `SymbolFontNormalizer` — PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans; переписывает `<w:sym>`, правит `w:lvl` в numbering.xml; 5 карт по 256 слотов (таблица `SymbolMapper` из docx4j 17.x).
4. `FieldNormalizer` — `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple` (кэш страниц в PDF не попадает); вложенные/битые поля пропускаются.
5. `InvisibleCharNormalizer` — вырезает из `w:t` U+0085, U+2028, U+2029, U+200E/200F, U+202A–202E, U+2060, U+FEFF (FOP делает из них переносы/пустые строки, Arimo/Tinos рисуют боксы). U+00A0/U+00AD/U+200B–U+200D **не** трогает.
6. `GlyphCoverageNormalizer` — режет раны по покрытию глифов и пишет семейство в `w:rFonts`, иначе FOP рисует «#». Покрытие — `GlyphFont` (fontbox, cmap) + BitSet-кэш, **не** docx4j `GlyphCheck` (плодит INFO-лог; `java.awt.Font` требовал fontconfig на хосте). Для serif-ран fallback ищется сначала в `SERIF_FAMILIES` (`dejavu serif`, `tinos`, `caladea`), затем в sans.
7. `TableIndentNormalizer` — свёртка `w:tblPr/w:jc` (center/right) с любым (в т.ч. отсутствующим/нулевым) `w:tblInd` в абсолютный `w:tblInd` с удалением `w:jc` (Word: tblInd — сдвиг от поля после центрирования, MS-OI29500 §2.1.155; docx4j при jc≠left игнорирует tblInd буквально — Part 1 §17.4.50, а центрированию пишет абсолютный start-indent **без** вычета cellMar, поверх которого padding-компенсация правила LayoutPostRenderer уводит текст на +padding — свёртка обязательна и при X=0): center → (W−T)/2+X, right → (W−T)+X, W — полоса набора (pgSz − pgMar left/right в transitional и `w:start`/`w:end` в strict; дефолты 11906/1440 — измеренное поведение docx4j, не ECMA-1800), T — Σ gridCol; пропускает несколько body-level `sectPr`, не-dxa `tblInd`, `tblPr` с `tblCellSpacing` без `tblInd` (нет корректной позиции вставки по CT_TblPrBase), `tblW pct`, нецелые gridCol. Кроме `rewrite`/`STEP` (document.xml, полоса из собственного sectPr) есть `rewritePart(part, xml, band)` — `word/headerN.xml`/`footerN.xml` с полосой из document.xml (в частях колонтитуков своего sectPr нет) и `bandOf(documentXml)` — экстрактор полосы (−1 — полосы нет). Регрессия — WordPdfConverterTest#tableIndentCentered_shiftedLikeWord, #headerTableIndent_centeredInHeader, #tableCenteredNoIndent_shiftedLikeWord.
8. `NumberingSuffixNormalizer` — `w:suff w:val="space"` → дописанный обычный пробел в конце следующего `w:lvlText` того же уровня (порядок CT_Lvl suff→lvlText, wml.xsd; Part 1 §17.3.1.28): docx4j разделитель не эмитит вовсе (дамп n4.fo); уже пробельный lvlText не дублируется; suff=tab — отдельный Class C-остаток (нужна per-item ширина), nothing совпадает с docx4j. Регрессия — WordPdfConverterTest#suffSpace_labelGetsSpace.
9. `OleObjectNormalizer` — принимает флаг `errorOnOle`. Два этапа: дешёвый детект по центральному каталогу zip (`ZipFile`; читаются только `[Content_Types].xml` и `word/*.xml` до первого `<w:object`; не-zip/нет центрального каталога → входной массив — прежняя снисходительность), переупаковка — только при находке. Детект OLE-бинарников — по `[Content_Types].xml`: тип `…oleObject` **или** ложный `+xml`-тип у `.bin` (XML в bin не бывает; `printerSettings` не трогается). Удаляются вместе с rels-ссылками (по типу, включая `TargetMode=External`) и Override удалённых частей. Элементы `<w:object>` из `word/*.xml` не выбрасываются, а заменяются статичным представлением — картинкой-плейсхолдером (ECMA-376 §15.2.10): `w:drawing` переиспользуется дословно, `v:imagedata r:id` → inline-DrawingML на ту же image-часть (размер из `style` `v:shape`, иначе `w:dxaOrig`/`w:dyaOrig` ×635), блоки с `w:control` и без плейсхолдера удаляются. OLE-бинарники никогда не читаются. При `errorOnOle=true` вместо вычистки — `DrawingFoundException(OLE)`. Лечит оба механизма падения docx4j: JAXB-разбор бинарника под ложным XML-типом («Content is not allowed in prolog» → NPE) и NPE `chunkType is null` в VML-сериализации `w:object`. Многочастный: публичный член только `normalize(byte[], boolean)`, `rewrite`-хука нет.
`mc-preprocessor.xslt` docx4j (в jar `docx4j-core`) перебивает strict-namespace'ы в transitional и конвертит `pt` в twips/half-points, но ветку перевода процентов в тысячные для namespace'ных атрибутов содержит с закомментированным `<xsl:value-of select="$cleanValue * 1000"/>` (для атрибутов без namespace — она активна), а `w:start`/`w:end` в `w:left`/`w:right` не маппит вовсе. Поэтому собственный рерайт URI ломать нельзя — он сломал бы pt-конверсию preprocessor'а (FOP получил бы «10pt»).
### 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''…`. Проверка `.docx`/`.doc`-расширения — в `ConvertController` (ошибочный текст 400 — контракт с фронтом); `ConversionService.safeBaseName` — единый источник имени для файла, заголовка ответа и PDF-title (срезает оба расширения; разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). Error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры → картинки, см. «Мост») — описано в `@Operation`.
| Ситуация | 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`.
- **Ключ доступа**: `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` и **не потокобезопасно**. `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` + текст зоны).
### 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`), а не догадки по исходникам LibreOffice/Word. Формулировки из стандарта при ссылке — с номером секции (§21.2.2.132 и т.п.). Эмпирические калибровки (камера, `PIE_DEPTH`) менять только вместе с пиксельными тестами. Фикстуры могут быть невалидны — код под фикстуру не правится, правится фикстура (после проверки по XSD/секции).
Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр × `DPI/72`, размеры в пунктах, EMU→pt `cx/12700.0`). Потолок растра `ChartRenderer.MAX_PIXELS = 16_777_216` (4096², 64 МБ ARGB): при превышении `fitDpi` uniform-но понижает эффективный dpi (геометрия в пунктах и безразмерные пропорции не меняются; 24″-график: 208 МБ → 64 МБ, dpi 300 → ≈171); `SmartArtRenderer` использует тот же `DPI`/`fitDpi`. `ChartSpec.parse` (`enum Type`: PIE, PIE3D, DOUGHNUT, BAR, BAR_HORIZONTAL, LINE, AREA, SURFACE3D, AREA3D, BAR3D, LINE3D, RADAR, SCATTER, BUBBLE, STOCK, OF_PIE, SURFACE, UNSUPPORTED). `c:autoTitleDeleted` (§21.2.2.7, `val` опущен — default true) применяется только при отсутствии `c:title` (MS-OI29500 §2.1.1431(a)) — явный заголовок показывается при любом флаге; при отсутствии `c:title` и `val=0` рисуется автозаголовок. Пустой/пробельный `c:title` (или `val=0` без `c:title`) — автозаголовок Office (MS-OI29500 §2.1.1561(a)): одиночный ряд с именем → имя ряда (любой тип графика), иначе `ChartSpec.AUTO_TITLE = "Название диаграммы"`; несколько абзацев `a:p` склеиваются `'\n'` (жёсткий перенос в `DrawMlText`). Регрессии — `ChartSpecTest#emptyTitleSingleSeriesBar_usesSeriesName`, `#deletedTitleWithText_stillShown`, `#deletedTitleValOmitted_stillShown`, `#multiSeriesDoughnut_placeholderNotSeriesName`, `#multiParagraphTitle_joinedWithNewlines`. Палитра `accent1..6` темы; легенда по умолчанию снизу; `overlay` (§21.2.2.132) рисуется поверх области построения, место не резервирует.
Пейнтеры: `CartesianPainter` (2-D line/bar/area; `c:grouping` stacked/percentStacked §21.2.2.76 — ряд рисуется накопленной суммой через `ChartRenderer.stackedCumulative`), `PiePainter` (`PIE_DEPTH = 0.22`, `PIE_FIT = 0.865`), `Surface3dPainter` (камера — регрессия `cameraMatchesWordReference`: `DEPTH_RATIO = 0.705`, `HEIGHT_RATIO = 0.664`, `GUTTER_LEFT/RIGHT = 0.1485`, `GUTTER_TOP = 0.116`, `GUTTER_BOTTOM = 0.146`, свет `LIGHT_X/Y/Z = 0.83/0.48/0.28`; `c:rAngAx=true` приоритетнее `c:perspective` (MS-OI29500 §2.1.1516(b)); `c:wireframe` §21.2.2.205 — только каркас), `ScatterPainter` (радиус пузыря sqrt при `c:sizeRepresents="area"` §21.2.2.128), `RadarPainter` (спицы от 12 часов), `StockPainter` (upDownBars обводятся контуром, дефолт чёрный 0.75pt), `OfPiePainter` (MS-OI29500 §2.1.1507(a), §2.1.1545(a)), `Surface2dPainter` (контурная карта §21.2.2.204, marching squares, изолинии по `c:bandFmts` §21.2.2.13/.14), `Cartesian3dPainter` (bar3D/line3D/area3D §21.2.2.19/.101/.122, `c:shape` §21.2.3.44), `SmartArtRenderer` (кэш `word/diagrams/drawing1.xml` через relationship `…/office/2007/relationships/diagramDrawing`; формы — `PresetGeometry` из `a:prstGeom`, семь пресетов дословно из `presetShapeDefinitions.xml`; оператор `?:` = «if x > 0 then y else z» (ISO/IEC 29500-1, **не** x != 0); углы в Arc2D — со знаком минус; текст — `DrawMlText`, шрифты через `BundledFontMapper.bundledFamily`; autofit только `normAutofit` §21.1.2.1.2/.3; `dgm:prSet/@phldrT` не рисуется).
Защитные лимиты против враждебного chart-XML: `ChartSpec.MAX_POINTS = 100_000` (`c:pt/@idx` §21.2.2.150/.151, `c:ptCount` §21.2.2.152 — ST_UnsignedInt без верхней границы; отказ `IllegalArgumentException` **до** предвыделения списка), `ChartRenderer.MAX_TICKS = 1000` (шаг ≤ 0/NaN/слишком мелкий в `axisBounds` заменяется `niceUnit` 1/2/5·10ⁿ), `DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000` (≈24″; при `cx/cy` вне капа объект **оставляется как есть** + warn, картинка не рендерится — регрессия `hugeExtentChart_removedNotOom`). Бросок перехватывает catch в `DrawingPreRenderer.renderChart` → штатная деградация «объект удалён + warn». Обход `pkg.getParts()` — только по **снимку** списка (`createImagePart` мутирует реестр → CME); rels частей — `part.getRelationshipsPart()`, **не** `getOwningRelationshipPart()`; обход XML обязан раскрывать `JAXBElement`.
**Combo** (Word «Комбинированная», §21.2.2.145): несколько групп в одном `c:plotArea` (`c:barChart` + `c:lineChart`/`c:areaChart`), каждая со своими `c:axId` (§21.2.2.9). `parse` привязывает группы по id осей: `Series.renderAs` (семейство отрисовки), `Series.grouping`, `Series.valAxis` + `ChartSpec.secondaryValAxis` (обычно `c:axPos="r"`); `spec.valAxis`/`catAxis` — first-wins. `CartesianPainter` рисует семейства в порядке BAR→AREA→LINE, каждая серия масштабируется по своей оси, вторичная ось — линия справа + подписи справа.
### Критические инварианты (нарушение = битый вывод, не исключение)
- `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 игнорирует). Дрейф-гейт `WordPdfConverterTest#vendoredXsltTracksJarCopy`: вне AUDIT-FIX-региона вендорная копия обязана быть побайтно равна стилисту из jar'а (сравнение с возвратом патч-региона к исходному вызову `createBlockForRPr`) — при апгрейде 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`, в конвейере используется вендорная копия (см. выше).
- Порядок инициализации шрифтов: `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` — **до** `load()`. `BundledFonts.init()` идемпотентен и `synchronized`, распаковывает TTF во временный каталог `wordpdf-fonts-*` (`deleteOnExit` на файлы и на каталог). `dropNonBundled()` чистит глобальный реестр `PhysicalFonts` от всего, что вне бандла.
- `PhysicalFonts` — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером.
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; explicit = межсекционные `w:sectPr` в body + `w:br type="page"` + `pageBreakBefore` (включая таблицы и `w:sdt`). Единственный путь — lightweight (StAX по zip, secure-ридер без DTD/external entities; `WordPdfValidator` не зависит от docx4j): атрибуты — по локальному имени (`attrLocal`, не по transitional-URI: иначе в strict-документе `w:br type="page"` не засчитываются); `sectPr` внутри `pPr` не считает, последнюю body-direct секцию не считает, `continuous`-секции не считает, в колонтитуках — только `w:br type="page"`, `pageBreakBefore` — только внутри `pPr` вне `sectPr` (truthy `val`: `null|true|1|on`). На не-zip молчит — подпись проверяет вызывающий. `checkPageCount` — один стриминговый проход `ZipInputStream` без буферизации частей (хелпер `noClose` глушит `close()` сканеров): потребление O(одной части) вместо O(суммы XML-частей).
- Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
- Аудит раскладки по ECMA-376 Part 1 (2026-10) — известные нечинимые ограничения FOP/docx4j (Java-слой): `w:jc="distribute"` рендерится как left — межсимвольного распределения в FOP нет (ST_Jc §17.18.44: distribute — межсимвольный разнос, justify только межсловный), последняя строка блока не растягивается, свойства `text-align-last` в форке нет (в docx4j-fo-renderer отсутствуют классы TextAlign*); `w:suff="tab"` и `w:lvlJc` игнорируются (numbering-лейбл всегда через hanging-tab; suff=space чинит правило 8, suff=nothing совпадает с docx4j — разделителя нет); абзац без `w:line` рендерится natural-высотой FOP 15.44pt@11pt, явный `lineRule="auto"` — 13.4277pt, два «single» в конвертере (13.4277 — канонический single по метрикам Carlito/Calibri 2500/2048 em; «Word ≈13.9pt» из первичного аудита не воспроизводится: обе величины считаются по метрикам шрифта, артефакты исходного замера не сохранились → пункт закрыт без правок); кернинг не применяется ни для одного бандл-семейства (замер: advance A→V = A→A — Carlito 6.369pt, DejaVu Sans 7.524pt@11pt): 22 TTF — GPOS-only, а legacy `kern`-таблица DejaVu Sans/Serif ключована glyph id, не совпадающими с cmap (2568/2727 пар без Unicode-маппинга, пары A→V нет) — латинский путь FOP (`TextLayoutManager`→`Font.hasKerning`) читает только legacy `kern` и такие пары отбрасывает; свойства `kerning` в форке нет, порог `w:kern` через FO не выражается. Word кернит только при явно заданном `w:kern` в иерархии стилей и при sz ≥ val (Part 1 §17.3.2.19; при отсутствии `w:kern` Office не кернит — MS-OI29500 §21.1.2.3.9a) — по умолчанию совпадает с нами, расходится только для документов с явно заданным `w:kern`. Починено веткой layout-class-c: левый padding ячейки (`LayoutPostRenderer`, шаг 4.25), `w:tblInd` при `w:jc`≠left (правило 7), `w:suff="space"` (правило 8).
- Внимание: комментарии в `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 до основного цикла. `DISPLAY_NAMES` — обратный маппинг lowercase→отображаемое имя для `documentFontName` (пишет `GlyphCoverageNormalizer` в `w:rFonts`). `BundledFontMapper.bundledFamily` — public-хук «имя шрифта из docx → бандл-семейство или fallback» (пользуется chart-движком). Публичный API `BundledFonts`: `families()`, `font/regular/bold/italic/boldItalic(family)`, `FALLBACK_FAMILY`. `GlyphFont` — глиф-движок на fontbox (метрики + растеризация глифов для chart-движка и покрытия глифов); читает TTF **напрямую из classpath** `fonts/<file>` (не из temp-каталога `BundledFonts`), кэш по `family/variant`, `of()` возвращает `null` для неизвестного семейства; `java.awt.Font` из рантайм-пути убран, AWT остаётся только как геометрия Graphics2D. Новый шрифт = файл + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`).
## 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/` | 9 нормализаторов + `DocxRewritePipeline` (один zip-проход правил 1–8, 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 классов (см. секцию «Мост») — `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/` |17 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer.run`)|
| `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 (10 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`, `OpenApiConfig` (`@SecurityScheme` X-API-Key) + 4 класса исключений |
| `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` — включён. `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, две категории: `docx/` — OOXML: PDF+md ECMA-376 Part 1 (5-е изд.), md [MS-OI29500]/[MS-ODRAWXML], полные наборы XSD `docx/schema/strict/` (21) + `docx/schema/transitional/` (26), `docx/validate-fixtures.py` — XSD-валидация `samples/*.docx` (lxml, ставится отдельно); `doc/` — бинарный .doc: md [MS-DOC] (`ms-doc.md` + `ms-doc-full.md` — тот же текст с HTML packet diagram'ами и таблицами sprm §2.6.1–2.6.3, где `ms-doc.md` даёт `[TABLE]`) + окружение [MS-CFB]/[MS-OSHARED]/[MS-ODRAW]/[MS-OLEPS]/[MS-OFFCRYPTO]/[MS-OVBA]/[MS-WMF]/[MS-EMF]; регенерация — README в каждой категории: `docx/README.md`, `doc/README.md` |
| `develop/` (вне git, gitignored) | Рабочие материалы и эталоны сравнения рендера — **не фикстуры**, в тесты/jar не подключать; пиксельные замеры зашиты числами в chart-тестах |
## 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)"`.
```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
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf
./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)
# Перевендорить 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-патч (w:rPr/w:position → baseline-shift, образец — комментарий в самом файле)
```
Задачи mise: `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` — все контейнеры (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.
Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` и `ole-embedded.docx` НЕ генерируются — созданы вручную, не перезаписывать; `chart-types.docx` — `ChartTypesDocxGenerator`):
```bash
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
```
Деплой. **Прод** — на пользовательском LAN-сервере (podman + podman-compose, docker-бинарников нет); координаты сервера и гейты успешности — вне репо: `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (обязательно прочитать перед любым деплоем/перезапуском). Прод-хост не хранит ни конфигураций, ни секретов: job `deploy` в `main.yml` рендерит `docker-compose.yml` и `nginx.conf` в директорию деплоя (значения — из Variables, API-ключ — из Secret `WORDPDF_API_KEY` через окружение деплоя, на диск не пишется), затем login/pull/`up -d --force-recreate app web`/гейты healthy+image/recreate gateway. Наследие `restart.sh` и `.env` деплой удаляет; единственное состояние на проде — `.rollback.env` (image ID для отката). Перезадеплой — push в `main` или Run workflow (`workflow_dispatch`), ручных скриптов нет. Наружный вход — `https://pjandro.ru/pdf-converter/`.
## Code Conventions & Common Patterns
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе: `BundledFontMapper` (`extends BestMatchingMapper`), обёртка цветов `DrawMlColor` (instance, но не наследник docx4j) и Spring-компоненты `wordpdf-app`.
- Нормализаторы — единый контракт `internal/DocxNormalizer` + константа `STEP`; цепочка `WordPdfConverter.normalizers()` = `DocxRewritePipeline.STEP` (правила 1–8 одним zip-проходом) + лямбда `OleObjectNormalizer`; нечего менять → **тот же массив**; package-private хук `static String rewrite(String xml)` для юнит-тестов (возвращает `null` при отсутствии изменений; есть у 8 из 9 — у многочастного `OleObjectNormalizer` нет); у `StrictOoxmlNormalizer` есть также `rewritePart(entryName, xml)` (per-part-логика, хук пайплайна); правятся только части `word/*.xml`.
- Ошибки публичного 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`/`DrawingPreRenderer.run`/`DependencyGuard.check` (`rewrite`, карты — package-private); в `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` — тесты тоже сканируются): `category/java/codestyle.xml` минус 14 opinionated-правил (`AtLeastOneConstructor`, `CallSuperInConstructor`, `CommentDefaultAccessModifier`, `ConfusingTernary`, `FieldDeclarationsShouldBeAtStartOfClass`, `LocalVariableCouldBeFinal`, `LongVariable`, `MethodArgumentCouldBeFinal`, `OnlyOneReturn`, `PrematureDeclaration`, `ShortMethodName`, `ShortVariable`, `UseExplicitTypes`, `UseUnderscoresInNumericLiterals`); `MethodNamingConventions` с `junit5TestPattern` и `TooManyStaticImports` (максимум 12) исключены из категории и переопределены ниже по своим настройкам; XPath-правило `LiteralFirstInEquals` (строковый литерал слева в `equals`/`equalsIgnoreCase`), unused-правила из `bestpractices.xml`, `ReturnEmptyCollectionRatherThanNull` (errorprone, priority 1), `AvoidLiteralsInIfCondition` (errorprone, priority 3), `EmptyCatchBlock` (errorprone, priority 2), `ForLoopCanBeForeach` (bestpractices, priority 2). `failurePriority` не задан — на практике `verify` валит нарушения любой приоритетности.
## 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), тоже кандидат на удаление.
## 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 `^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`.
- Локальная проверка одна: `mvn clean verify` (тесты + PMD + JaCoCo). Форматтеров и checkstyle для Java нет; статический линтер — PMD.
- Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят; `BundledFontsTest#listedFilesCoverAllTtfInResources` требует `file:`-протокол classpath — только surefire, не fat-jar).
- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`, `main`/`dev` защищены (правила глобального AGENTS.md; локально только `main`).
## CI/CD (Gitea Actions)
Два workflow. `.gitea/workflows/pr.yml` — `PR checks` (`pull_request` + `workflow_dispatch`): job `java` (temurin 17, кеш `~/.m2`, Maven 3.9.16 с dlcdn, `mvn -B -s .ci/maven-settings.xml clean verify` через зеркало Nexus `maven-central` (fail-closed проверка Variable `MAVEN_MIRROR_URL` первым шагом)) → `Coverage summary` (разбор `target/site/jacoco/jacoco.xml` python-сниппетом в step summary) → `Comment coverage on PR` (тот же текст комментарием; создаётся один раз, повторные push обновляют по маркеру `<!-- jacoco-coverage -->`; `continue-on-error`). job `web` (кеш `~/.npm`, `npm ci` → `build` → `lint`).
`.gitea/workflows/main.yml` — `Main: tests, deploy, autotests` (`push` в `main` + `workflow_dispatch`): те же `java`/`web` (байт-байт дубль — workflow-файлы самодостаточны, reusable-workflow не вводить) → `images-app`/`images-web` (build+push каждого Containerfile в Nexus-реестр `${{ vars.REGISTRY }}`, теги `prod` + immovable `sha-<7 символов GITHUB_SHA>`; app печётся с `--build-arg MAVEN_MIRROR_URL=…` (зеркало Nexus в Containerfile); web печётся с `--build-arg VITE_BASE=/pdf-converter/`; `DOCKER_BUILDKIT=0` обязателен — daemon за раннером podman, BuildKit-сессий нет; креды — вручную пишется `~/.docker/config.json`) → `deploy` (SSH на прод: рендер конфигов heredoc'ами в workspace раннера — appleboy/ssh-action непригоден, ломает heredoc; валидация PyYAML; прод-стек — подсеть `10.112.0.0/24` gw `10.112.0.1` (в репо-`compose.yml` — `10.113.0.0/24`, стенды разные), gateway биндится на `127.0.0.1:9010` + `$DEPLOY_HOST:9010`, `nginx.conf` — с `resolver 10.112.0.1`; сохранение `.rollback.env`; `login/pull/timeout 90 podman-compose up -d --force-recreate app web`; гейты healthy и image; gateway пересоздаётся последним; health-check) → `autotests` (venv + `prod-autotests/` против прода) → `rollback` (`if: failure()` — перерендер/перезалив прод-файлов тем же шагом, retag прежних image ID на `:prod`, `--force-recreate app web`, пересоздание gateway).
Артефактов покрытия нет намеренно: `upload-artifact@v4` Gitea не поддерживает, `@v3` на этом стенде зависает. HTML-отчёт — локально `target/site/jacoco/`, `web` (кеш `~/.npm`).
**Правило: координаты прода и креды в коммитимые файлы не попадают** — ни внутренние 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
- Гейт `maven-pmd-plugin` 3.28.0 на `verify` для обоих модулей, ruleset `pmd-ruleset.xml`, `includeTests=true`. Версия PMD-движка в pom не пинится (тянется плагином).
- Гейт 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`) и защитные ветви сканеров нормализаторов/валидатора.
- 55 тестовых класса / 799 `@Test` (core 49/756 — из них 17 классов / 189 тестов в `internal/doc/`, app 6/43: ConvertController 23 + ApiKeyFilter 8 + ConversionService 5 + ApiExceptionHandler 4 + 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`).
- **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 таблицах).
- Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров: безразмерные отношения к эталону Word (экспорт 300 dpi, числа зашиты в тесты), допуски `assertRatio` <0.06 (`PiePainterTest`, `CartesianPainterTest`) / <0.10 (`Surface3dPainterTest`, + `assertRange` ±6 pt для центров силуэта); пороги залитых px, перцентильные коридоры яркости, «серый» px — разброс каналов `GRAY_MAX_SPREAD=25`; исключение — структурная проверка чернил в `GlyphFontTest`. Эталонные файлы — `develop/`, вне git. Хелперы chart-тестов (`render`, `countColor`, `assertRatio`, `paint`) продублированы по классам — общего test-util нет.
- `GlyphFont` (fontbox): метрики пиксельно-метрически эквивалентны AWT (ascent/descent/leading/advance совпадают до 4-го знака, кернинг-дрейф 0.0000 — DejaVu Sans, Carlito). Приёмочный стенд без-fontconfig: контейнер без `libfontconfig.so.1*` и `/etc/fonts`, `mvn verify` + `java -jar` (до перехода на GlyphFont там падали `GlyphCoverageNormalizerTest` 12 / `CartesianPainterTest` 3 / `PiePainterTest` 2 / chart-тесты `WordPdfConverterTest` 4, chart-рендер молча деградировал). `GlyphFontTest` написан без единого `java.awt.Font` — обязан проходить на хосте без fontconfig.
- Фикстуры — закоммиченные `samples/*.docx` + `samples/*.doc` (13 + 12; в тестах не генерировать; `.docx` все ECMA-conformant по `docs/standards/docx/validate-fixtures.py` — фикстура невалидна, правится фикстура, не код; `.doc` — эталоны заказчика, конвертируются мостом): core грузит classpath-ресурсом → `byte[]`, PDF для PDFBox — временный файл; app читает `/samples/…` из **test-jar core** (classifier `tests`) → `mvn -pl wordpdf-app` без `-am` не соберётся. In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]`; in-memory `.doc` — POIFS (`POIFSFileSystem`) вокруг крафтовых WordDocument/1Table/Data (`DocToDocxFormattingTest`). Ключевые: `too-many-pages` (150 явных разрывов → 151; `.doc`-пара — кэш PageCount=150 → 400 «не менее 151»), `stale-cache` (docx: кэш `<Pages>1</Pages>` + 110 `lastRenderedPageBreak` → 400; doc: кэш 5 → конвертируется — семантика запинена), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject; `.doc`-пара — 3 BLIP-fallback → 3 картинки), `ole-embedded` (осиротевший bin с ложным `Default bin→footer+xml` + настоящий `w:object` с честным `Override → oleObject` и VML-плейсхолдером `media/fallback.png` — ручная, генератором не перезаписывать; `.doc`-пара — OLE-fallback BLIP → 1 картинка), `chart-types` (14 графиков: 9 типов + ofPie-pie + lineChart stacked + `c:wireframe` + combo barChart+lineChart на вторичной `c:valAx` pos="r"; пересоздание — `ChartTypesDocxGenerator`; `.doc`-аналога нет), `doc-formats.doc` (2 страницы — лимит страниц на .doc-пути).
- Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив» (`assertSame`) и неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`). Тесты бьют и в package-private API (`GlyphCoverageNormalizer.split(text, family)`, `ChartSpec.readTitle`). Исключение — `OleObjectNormalizerTest`: многочастный нормализатор без `rewrite`-хука, тесты только через `normalize` на in-memory zip.
- Юниты моста (`internal/doc/`): `CfbReaderTest` строит крафтовый CFB-байтстрим (сектор 512/mini 64: FAT/DIFAT/miniFAT/directory руками) и бьёт все guard-ветки (циклы FAT/DIFAT/MiniFAT, ссылки за файл, обрезанные потоки, root без mini stream, мусор в directory); `SummaryInfoTest` — крафтовый PropertySetStream (пинит **относительность offset от начала PropertySet**, реальные фикстуры её не различают); `PieceTableTest`/`ChpxIndexTest`/`PapxIndexTest` (в т.ч. `istdFor`: istd из UpxPapx, пустой grpprl ≠ null, bOffset=0 → нет записи)/`SectionsTest`/`FibHeaderTest` (пара fcStshf)/`GrpprlTest` (в т.ч. спец-длины: двухбайтовый cb у sprmTDefTable при operand >255 Б, у 0xC60D cb=0xFF — обрыв, у 0xC615 cb=0xFF — длина по формуле §2.9.182 (`scan_pChgTabsSentinel_lengthByFormula`))/`FontTableTest`/`HeadersTest`/`OfficeArtTest`/`PrcDataTest` — byte[]-конструкции in memory (`PrcDataTest`: разворачивание huge-PAPX/PTableProps на позиции указателя, union цепочки с легаси-зеркалом, guard'ы — cb-капа 0x3FA2, ptr за Data, цикл A→B→A); `StylesTest` — крафтовый STSH (LPStd/LPUpx): цепочка base→derived, цикл → пустая таблица, чужой stk/битый STSH нисходительны; `TablesTest` — крафтовый TAP: сетка TDefTable (XAS со знаком), границы Brc (cv fAuto) и Brc80 (ico, приоритет 0xD613), выравнивание sprmTJc/sprmTJc90 (u16, приоритет современного, 0 → null), деградация при битом TDefTable; `ListsTest` — крафтовые PlfLst/PlfLfo байтстримом (счёт LVL по fSimpleList 1/9, плейсхолдеры xst → `%{n+1}` и литеральный `%` → `%%`, MSONFC→ST_NumberFormat вкл. экзотика→decimal, ixchFollow→`w:suff`, grpprl уровня → `w:ind`/`w:rFonts`, LFOLVL fStartAt/fFormatting, обрыв LVL-массива, lsid без LSTF, нулевые lcb); `DocToDocxFormattingTest` — полный синтетический .doc через POIFS (крафтовые FIB/Clx/FKP-страницы: полные CHPX/PAPX-свойства, STSH-цепочка с переопределением и победой direct, spacing/tabs, таблица TTP+TDefTable+Brc с деградацией строки без сетки и многострочной ячейкой, колонтитук со стилевым jc, табы колонтитука из стиля sprmPChgTabs (`styleTabsChg_reachesFooterPart`/`styleTabsChgDel_removesStop`: прямой del с rgdxaClose вырезает stop стиля), таблица в odd footer со sprmTJc (`footerTable_jcCenterEmitted`: guard-¶ отдельным абзацем после строки, как в реальных Plcfhdd), знаки, поле в основном тексте, picLocation=0, 0Table, отсутствие табличного потока, списки: `listParagraphs_getNumPrAndNumberingPart` (sprmPIlfo/sprmPIlvl в PAPX → `w:numPr` + `word/numbering.xml` c `w:num`/Override/rels), `listCancelledByDirectZero_noNumPr` (ilfo стиля, перекрытый прямым 0), `ilvlSkipValue_noNumPr` (ilvl=0x0C), `missingListTables_degradeToPlain` (нулевые FIB-пары 73/74 — ни numbering-части, ни numPr)). Doc-регрессии конвертера — общие assert-хелперы docx-пар: `assertCyrillicAndStyles`/`assertPageNumbers`/`assertTableImage`/`assertOleObjectsRemoved`/`assertDrawingsBecomeImages`/`assertTooManyPages`/`assertExoticGlyphs` вызываются с `ru-plain.doc`/`page-numbers.doc`/`ru-table-image.doc`/`ole-embedded.doc`/`charts-smartart.doc`/`too-many-pages.doc`/`exotic-glyphs.doc` (тесты-пары называются по docx-имени, внутри зовут оба формата); `WordPdfValidatorTest#checkPageCountDoc_*` + `ConvertControllerTest` (`.doc` upload, `nonDocxFilename_rejected`).
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); три контекста — `ConvertControllerTest` (пустой ключ), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest`/`ConversionTimeoutTest` (`@TestPropertySource` — отдельные классы, не `@Nested`: `@Nested` + `@TestPropertySource` не даёт отдельного контекста).
- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight`; юниты `indCoexistLeftStartUntouched`/`tcMarCoexistKept`/`tcBordersElementsKeptTransitional`/`jcStartRenamedTransitional`/`tabStartRenamedTransitional`/`transitionalCoexistReturnsOriginalArray`), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `InvisibleCharNormalizerTest`↔`invisibleChars_noEmptyLines`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `OleObjectNormalizerTest`↔`oleObjects_removedAndConverted`/`drawingErrors_errorFlagRejectsOle` (+app `errorFlagOle_rejected`/`oleObjects_removedByDefault`; юниты `objectWithImagedata_placeholderKept`/`objectWithoutImage_removed`/`objectWithDrawing_reusedVerbatim`/`controlBlockRemoved`/`sizeFromDxaOrig`/`styleUnits_allConvertToEmu`/`objectWithoutBin_stillRewritten`/`externalOleLinkRelRemoved`), `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCount_limitBoundary` 99/100/101, `cachedPagesUnreadableFallsBackToZero`, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`, `validate_notAZip`/`validate_plainZipRejected`/`validate_xlsxRenamedRejected`/`validate_zipBombRejected`/`validate_tooManyEntriesRejected`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `PresetGeometryTest`↔`chartsSmartArt_drawingsBecomeImages` (`tableMatchesEcmaXml`), chart-пейнтеры↔`chartTypes_allTypesRenderAsImages`, `ChartSpecTest`↔автозаголовки/комбо/DoS (`hugePointIndex_rejectedNotOom`, `hugePtCount_rejectedNotOom`, `hugeCategoryIndex_rejectedNotOom`, `nonFiniteScalingBounds_dropped`, `overlayLegend_keepsPositionAndFlag`, `emptyTitleSingleSeriesBar_usesSeriesName`, `deletedTitleWithText_stillShown`, `deletedTitleValOmitted_stillShown`, `multiSeriesDoughnut_placeholderNotSeriesName`, `multiParagraphTitle_joinedWithNewlines`), `Surface3dPainterTest`↔`axisBounds_tinyMajorUnit_fallsBackToNiceUnit`/`axisBounds_zeroMajorUnit_fallsBackToNiceUnit`, `ChartRendererTest`↔`axisBounds_explicitHugeRange_reunitsToMaxTicks`/`axisBounds_infiniteSpan_fallsBackToData`/`stackedCumulative_*`/`stackedRange_coversNegativeSums`/`overlayLegend_drawnOverPlot`/`wireframeSurfaceLegend_hollowMarkers`, `DrawMlTextTest`↔`hugeWord_wrapsLinearly`/`fallbackFamilyAliasedToBundle`/`lineSpacingPct_compactsLines`, `DrawMlColorTest`↔`invalidSrgbHexFallsBackToOfficeDefault`, `SmartArtRendererTest`↔`normAutofitShrinksToFit`/`missingAutofitKeepsDeclaredSize`/`emptyTxBody_noPlaceholderInk`, `CartesianPainterTest`↔`stackedLine_seriesStackCumulatively`/`percentStackedLine_topSeriesFlatAtHundred`/`areaFill_closesToBaseline`/`combo_barsAndLineOnSecondary_bothDrawn`, `GlyphCoverageNormalizerTest`↔`multipleTextNodes_runLeftUntouched`/`nestedRunInTextBox_innerSplit`, `SymbolFontNormalizerTest`↔`nestedRunInTextBox_innerNormalized`, `WordPdfConverterTest`↔`noLoggingWarningInPdf`/`pdfTitle_comesFromParameter`/`hostileChartAxis_convertsNotHangs`/`hugeExtentChart_removedNotOom`/`chartWithoutExtent_errorFlagRejects`/`jcEndTransitional_rightAligned`/`rPrPosition_raisesBaseline`/`vendoredXsltTracksJarCopy` (аудит раскладки ECMA-376), `LayoutPostRendererTest`↔`tableCellPadding_textInsetLikeWord` (+`lineRuleAuto_wordSingleLinePitch` пинит метрический шаг «single» от псевдофиксов, `carlitoAutoBlock_untouched`), `TableIndentNormalizerTest`↔`tableIndentCentered_shiftedLikeWord` (+`rewritePart*`↔`headerTableIndent_centeredInHeader`, +`jcWithoutIndent_folded`/`rightWithoutIndent_folded`/`zeroIndent_folded`/`cellSpacingWithoutIndent_returnsNull`↔`tableCenteredNoIndent_shiftedLikeWord`), `NumberingSuffixNormalizerTest`↔`suffSpace_labelGetsSpace`, `ListsTest`+`DocToDocxFormattingTest#list*`↔`docLists_numberingAndBulletsRendered` (синтетический .doc со списками → PDF: `1.` `2.` `a)` `b)` `•`, ни одного `#`; фикстур со списками нет — крафт POIFS продублирован в `WordPdfConverterTest`), `PrcDataTest`+`DocToDocxFormattingTest#hugePapxRowMark_closesRowWithGridFromPrcData` (TTP-абзац с grpprl в PrcData Data-потока → `w:tbl`/`w:tr`/сетка из цепочки; фикстуры нет — `docTest.doc` заказчика не коммитим, крафт POIFS продублирован), `SectionsTest`+`HeadersTest`+`DocToDocxFormattingTest#twoSections*/sectionBreakInTable*`↔`docMultiSection_perSectionHeaders` (двухсекционный .doc → PDF: стр. 1 — ШАПКА-1+ПОДВАЛ-1, стр. 2 — ШАПКА-2 + унаследованный ПОДВАЛ-1, ни одной `#`; крафт POIFS продублирован в `WordPdfConverterTest`). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed`, `corruptNotAZip_rejected`, `plainZipNotDocx_rejected`, `junkInsideValidZip_conversionError` (500 на валидном .docx-контейнере с мусором), `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `drawingsAlwaysRendered`, `cyrillicAndPathInFilename_sanitizedResponseName`, `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey`, `dotSegmentOpenPrefix_rejected`, `errorFlagNotBoolean_rejected`, `methodNotSupportedReturns405`/`badContentTypeReturns415`.
- UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint, `.oxlintrc.json`: rules-of-hooks error, only-export-components warn). Прод-автотесты (pytest 9.1.1 + requests 2.34.2, 31 проверка — 27 под маркером `needs_key` (SKIP без ключа; включая `.doc`-фикстуры обоих путей — растры/OLE и границы страниц), 4 открытых: health/SPA-root/swagger/spec; env-конфиг, `mise exec -- python -m pytest -q .` из `prod-autotests/`) гоняются CI после deploy против живого прода.