# Мост `.xlsx` → `.docx` (`internal/xlsx`) Нормативный источник любых правок — ECMA-376 Part 1 (SpreadsheetML: книга/листы §18.2, стили §18.8, печать §18.3, рисунки/диаграммы §21), окружение OPC — §3, ссылки — с номерами секций; локальные копии спецификаций в `docs/standards/`. Runtime-зависимостей нет (StAX + `java.util.zip`; POI — test-scope, только генератор фикстур). Публичные точки наружу: `XlsxToDocx.convert` (вызывает `WordPdfConverter`), предикат формата — `WordPdfValidator.isSpreadsheet`; остальные классы package-private в `internal/xlsx`. Вход роутируется в `WordPdfConverter.convertToStream` по сигнатуре+содержимому: `PK\x03\x04` и в `[Content_Types].xml` объявлен `…/sheet` — это книга → `XlsxToDocx.convert(bytes, options)` → in-memory `.docx` → общий конвейер docx4j/FOP. Валидация до конвертации — `WordPdfValidator.validate`: контейнер (`checkOoxmlContainer` возвращает `ContainerKind.DOCX|XLSX` по маркерам `[Content_Types].xml`), для `XLSX` — `checkPageCountXlsx`: двупроходная нижняя оценка `estimateXlsxPages` (проход 1 — `xl/workbook.xml` + `xl/_rels/workbook.xml.rels`: видимые листы и targets частей; проход 2 — счётчик `rowBreaks/brk` в целевых частях; страницы = видимые листы ×1 + явные разрывы; `docProps/app.xml` для книг не читается — Excel `` не кэширует, а нижняя оценка отсекает заведомо гигантские вход дешевле полной геометрии `PrintLayout`). ## Классы |Класс|Семантика| |---|---| |`XlsxPackage`|zip книги в памяти: части по имени, `_rels` любого part'а (`Rel(id,type,target,external)`), `relTargetPath` (target резолвится от каталога part-источника, `../` включительно), `resolvePath`/`parentDir`/`relsPathOf`, `truthy`/`attr`, `newSecureReader()` (StAX без DTD/external-сущностей). Битый zip/rels → `ValidationException`| |`WorkbookModel`|`xl/workbook.xml`: `Sheet(name,state,partPath)` по `r:id` из rels книги; не-`visible` листы помечаются, в вывод не попадают; `date1904` из `workbookPr` (сдвиг дат на 1462 дня в `NumberFormats`)| |`SharedStrings`|`xl/sharedStrings.xml` → индекс строк; `` — обычный текст, ``-раны с `rPr` (b/i/u/strike/sz/color/vertAlign/rFonts) → `Run(text,RunStyle)`; `parseRst` переиспользуется для `is`-ячеек inlineStr; `siPh` — пропуск| |`ThemeModel`|`xl/theme/theme1.xml`: 12 clrScheme-тонов (`dk1/lt1/dk2/lt2/accent1-6/hlink/folHlink`) + шрифты (`majorFont`/`minorFont`, latin+ea+cs); заголовок по `name`/`name val`; `theme1.xml` переносится в `word/theme/` для штатного chart-движка| |`StylesModel`|`xl/styles.xml`: numFmts (кастомные `formatCode` поверх встроенных), fonts/fills/borders/cellXfs по индексам; `cellStyleXfs` как base-цепочка (`xfId`), `cellStyle`-имена не нужны; `alignment(horizontal/vertical/indent)`; `xfId`-наследование cellXf от cellStyleXf base-first| |`ColorSpec`|атрибуты `` → спецификация: `rgb` (RRGGBB/AARRGGBB, `auto`), `theme`+`tint`+`shade`, `indexed`, `auto`; парсинг — `fromColorElement(xr)`| |`ColorResolver`|`ColorSpec` → sRGB int: theme → тон `ThemeModel` (dk1/lt1 меняются местами с bg1/tx1 по ECMA-376 §18.3.1.43), tint/shade — логарифмическая модуляция светлоты HSL (калибровка ECMA-376 §18.3.1.83/.105), indexed: 0–63 фиксированная палитра Office, 64+ — `palette` из styles| |`NumberFormats`|формат-код → текст числа: секции `pos;neg;zero;text`; заполнители `0 # ?`, разделители тысяч (`,` до `,`-суффикса ×1000, `,,` ×1e6, масштаб `%`/`‰`), проценты, даты/время (`d/m/y/h/s`, `[]`-кумуляции), научный `E`, текст-литералы `"…"`/`\`, `@`, `General` — `NumberText.general`; `[…]`-секции (условия `[>5]`, цвета `[Red]`, `[$-…]`) вырезаются из кода — принятая деградация, печатаем без цвета/условия. Битый код → `General` + warn. Календарная эпоха 1900/1904 из `WorkbookModel`| |`NumberText`|``-байты → `double`/текст по типу ячейки (`str`/`s`/`inlineStr`/`e`/`b`/`d`); `general(double)` — кратчайшая десятичная репрезентация без `BigDecimal`-хвостов| |`Metrics`|метрики шрифта листа: MDW (средняя ширина `0` в Calibri 11 через `GlyphFont`/fontbox; fallback 7), ширина колонок chars→twips (`(chars − padding·MDW…)` по ECMA-376 §18.3.1.8: px = `round(((256·chars + round(14/MDW·256))/256)·MDW)`, twips = px·15), высоты строк (pt→twips), конвертеры `pxToTwips`/`pxToEmu`/`ptToTwips`/`inchesToTwips`. Пересчёт на метрику `normal`-шрифта книги| |`PrintLayout`|страница печати листа: `Page` (paperSize→twips по ECMA-376 §17.6.5, landscape, поля `pageMargins` дюймы→twips, дефолты Word/L Excel: 0.7/0.75/0.3), `Plan` — срезы: горизонтальные полосы строк по `rowBreaks`/высоте, внутри — вертикальные по `colBreaks`+ширинам и print area; `fitToPage` (`fitToWidth`/`fitToHeight` ≤ 0 = auto) — равномерный `widthScale` колонок (масштаб в `%` в `w:sectPr` не используется — FOP не исполняет, режем колонки уже); `sectPr(Page)` — pgSz/pgMar для секции docx| |`SheetModel`|лист целиком: `sheetData` (строки/ячейки: `r`/`s`/`t`, ``, inlineStr `is`, формулы — значение из кэша ``, отсутствующее `` + `t=str` → пусто), `cols` (диапазоны ширинок/hidden/стиль колонки), hidden-строки/колонки, `mergeCells`, `hyperlinks` (rel part'а → внешний target), `sheetPr.pageSetUpPr.fitToPage`, print area/breaks, `headerFooter` (не рендерится — деградация), `pageSetup`, `drawing r:id` → `drawingPath` (путь резолвится по rels part'а листа), `legacyDrawing`/`oleObjects`/`controls` → `olePresent`. `parseRef`/`parseRange` — A1-нотация| |`SheetToTable`|срез → XML-блоки: один `w:tbl` на полосу (сетка `w:tblGrid` из видимых колонок с `w:gridSpan` слияний, `w:tcW` фикс., границы из стиля, `w:tblLayout fixed`), пустые строки/колонки outside content — сжимаются в строки-заполнители минимальной высоты; `w:trPr/w:trHeight` из высоты строки; ячейка: `w:p` c `w:pPr/w:spacing` нулевым, `w:ind` из indent, `w:jc` по Excel-горизонтали (§18.8.1, distributed/distribute — деградация к left/center), содержимое: рань-цепочка (sst-раны с rPr поверх стиля ячейки, прямое форматирование побеждает; `w:vertAlign` прокидывается), число через `NumberFormats`, `w:hyperlink w:external`; слияния: `w:gridSpan` + `w:vMerge restart/continue`, невидимые части hidden-колонок в слиянии — clamp; вертикальный origin — первая видимая строка| |`DrawingBridge`|`xl/drawings/drawingN.xml` → позиции+эмитты: якоря `twoCellAnchor`/`oneCellAnchor`/`absoluteAnchor` (EMU-кумулятив по ширине/высоте колонок-строк через `Metrics`, hidden-единицы = 0; `xdr:ext` != `a:ext` — namespace-различение!), from-ячейка → anchor (hidden clamp к первой видимой); `xdr:pic` → media-часть `word/media/xlsx-imageN.` (байты как есть, тип по расширению blip-target) → `wp:inline`-рань внутри from-ячейки (clamped); `graphicFrame` c `c:chart` → `word/charts/xlsx-chartN.xml` `DocxPackageWriter.Part`'ом с `CHART_REL_TYPE`/`c:chartSpace` content-type (rels части создаёт писатель), в теле остаётся `graphicData` — штатный шаг 3.5 (`DrawingPreRenderer`) дорисовывает PNG 300 dpi и применяет `errorOnCharts`; SmartArt (`dgm:`), фигуры `sp`/`cxnSp`, внешние blip — пропуск + warn (`errorOnSmartArt` на .xlsx не срабатывает — контракт REST); `olePresent`/OLE-blip → warn, при `errorOnOle` — `DrawingFoundException(Kind.OLE)` → 422; `theme1.xml` → `word/theme/` по `theme`-rel книги (палитра chart-движку); потолок `MAX_EXTENT_EMU = 22_000_000` (как `DrawingPreRenderer`) — превысил → объект остаётся как есть| |`WarnOnce`|дедупликация warning'ов по шаблону (битая книга не тонет в логе)| |`XlsxToDocx`|оркестратор: `XlsxPackage` → `WorkbookModel` → `ThemeModel`/`StylesModel`/`SharedStrings` → на каждый видимый лист: `PrintLayout.plan` → блоки-срезы; между блоками — секционные разрывы (`w:pPr/w:sectPr` со `sectPr(Page)`), колонтитуки — деградация; финальный body-`sectPr` последнего листа; picture/chart/theme-части через `DocxPackageWriter` (части `word/media/*`, `word/charts/*`, `word/theme/*` + rels манифеста). `options.errorOnOle` бросает `DrawingFoundException` до сборки docx| ## Ключевые соглашения - Единицы: xlsx хранит ширины колонок в символах MDW, высоты строк в пунктах, поля в дюймах, EMU в рисунках; все конверсии — только через `Metrics` (`pxToTwips` = px·15, `ptToTwips` = pt·20, EMU/pt = 12700). Ошибка в коэффициенте = расползание сетки. - Скрытые строки/колонки не рендерятся, но их вклад в геометрию якорей/слияний обнуляется (hidden = 0 EMU/twips), anchor клампится к первой видимой единице — иначе рисунок уезжает за страницу. - Числа форматируются по кэшированному `` (пере-вычисление формул не делается — формулы Excel не исполняются, значения берутся из файла; пустое `` при `t=str` — пусто, не «#»). - `PrintLayout.plan` — источник геометрии секций моста; валидатор страниц (`estimateXlsxPages`) — независимая дешёвая нижняя оценка (листы + явные `rowBreaks`), она обязана быть ≤ числа секций моста, но не обязана совпадать — лимит `MAX_PAGES` отсекает заведомо гигантский вход до полной разметки. - Фикстуры генерирует `SampleXlsxGenerator` (test-класс, POI 5.5): 7 штук `samples/xlsx-*.xlsx` — basic/numfmt/1904/page-limit/wide/fit-to-page/chart-image; содержимое фикстуры — контракт (тесты пинят тексты ячеек, `norm` схлопывает пробелы; assertions — по целым словам широких колонок, узкие режутся переносом). ## Деградации (принятые, не чинить) - Колонтитуки `headerFooter`, повторяющиеся заголовки `printTitles` (`titlesOnly`/ row-and-column), `framePr`-фреймы, комментарии, `rPh`-фонетика, флаг `wrapText` (текст в ячейке переносится FOP по ширине колонки всегда) — пропуск. - Формат-коды с условиями `[<]`/цветами `[Red]`/локалями `[$-…]`: `[…]`-секции вырезаются, число печатается остатком кода без цвета и без проверки условия. - Fit-to-page реализован геометрическим сжатием ширины колонок (FOP игнорирует масштаб секции docx4j), `fitToHeight` > 0 — та же судьба: страницы по высоте не спрессовываются дополнительно. - `errorOnSmartArt` для .xlsx не срабатывает (SmartArt отбрасывается до порога детекта docx-пайплайна) — зафиксировано в `@Operation`. Регрессии: пары юнит↔конвейер — `XlsxPackageTest`…`PrintLayoutTest` ↔ `XlsxPdfConverterTest` (PDF-текст/imageCount по фикстурам `samples/xlsx-*.xlsx`).