Files
java-word-pdf/docs/agent/xlsx-bridge.md
T
Pjandro 733662770b
PR checks / web (pull_request) Successful in 39s
PR checks / java (pull_request) Successful in 1m37s
feat(xlsx): REST + фронт + документация (шаг 8)
- 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
2026-11-03 02:37:43 +00:00

14 KiB
Raw Blame History

Мост .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).