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
This commit is contained in:
@@ -0,0 +1,77 @@
|
||||
# Мост `.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`).
|
||||
Reference in New Issue
Block a user