- ConvertController: расширение .xlsx, текст 400 «только .docx, .doc и .xlsx» (контракт с фронтом), @Operation — флаг errorOnSmartArt на .xlsx не срабатывает; safeBaseName срезает .xlsx - фронт: DropZone accept/подпись, подзаголовок App, api.ts фолбэк-имя режет .xlsx; web build+lint зелёные - app-тесты: xlsxFile_convertsToPdf (200, PDF, filename* Отчёт.pdf, текст доехал), nonDocxFilename_rejected — .xlsx в тексте, safeBaseName .XLSX - прод-автотест test_convert_xlsx (32 проверки) - docs: новая docs/agent/xlsx-bridge.md (классы, единицы, деградации, соглашения PrintLayout↔валидатора); AGENTS.md — роутинг входа, секция моста .xlsx, REST/фронт/счётчики (75 классов/1095 тестов, 32 фикстуры); pipeline.md (ContainerKind, estimateXlsxPages), repo-map.md (пакет, DocxPackageWriter, генераторы, пересоздание xlsx), testing.md, doc-bridge.md (DocxWriter → internal/DocxPackageWriter) Сквозная проверка java -jar + curl: xlsx→PDF 200 (filename* RFC5987), chart-fixture 200 с отрисованными PNG, errorOnCharts=true → 422 контрактный текст, .txt → 400 новый текст, .doc-регресс 200
14 KiB
Мост .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 <Pages> не кэширует, а нижняя оценка отсекает заведомо гигантские вход
дешевле полной геометрии 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 → индекс строк; <si> — обычный текст, <r>-раны с 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 |
атрибуты <color> → спецификация: 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 |
<v>-байты → 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, <v>, inlineStr is, формулы — значение из кэша <v>, отсутствующее <v> + 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.<ext> (байты как есть, тип по расширению 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 клампится к первой видимой единице — иначе рисунок уезжает за страницу.
- Числа форматируются по кэшированному
<v>(пере-вычисление формул не делается — формулы Excel не исполняются, значения берутся из файла; пустое<v>при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).