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

78 lines
14 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.
# Мост `.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`).