feat(xlsx): REST + фронт + документация (шаг 8)
PR checks / web (pull_request) Successful in 39s
PR checks / java (pull_request) Successful in 1m37s

- 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:
Pjandro
2026-11-03 02:37:43 +00:00
parent 4a59662027
commit 733662770b
14 changed files with 182 additions and 36 deletions
+1 -1
View File
@@ -19,7 +19,7 @@
|`OfficeArt`|[MS-ODRAW] PICF @ fcDggInfo/lcbDggInfo (Table-поток), delay-поток = WordDocument; DggContainer → BStoreContainer(0xF004)/BStoreContainerDelay(0xF007)/инлайн → FBSE → BLIP: 0xF01A EMF / 0xF01B WMF / 0xF01C PICT / 0xF01D JPEG (=0xF02A) / 0xF01E PNG / 0xF01F DIB; PNG/JPEG дословно, DIB → ImageIO → PNG, EMF/WMF/PICT → пропуск + warn (EMF-рендера в Java2D нет)|
|`PrcData`|§2.9.210 PrcData в Data-потоке (`[cbGrpprl:2][grpprl]`, капа cb 0x3FA2, поля `next` нет): `resolve(data, grpprl)` разворачивает grpprl абзаца, чьи свойства Word вынес за FKP-страницу PAPX, — одиночный Prl `sprmPHugePapx` (0x6646; в grpprl GrpPrlAndIstd — единственный Prl при istd=0, §2.6.2) и `sprmPTableProps` (0x646B — цепочка продолжается в указанном PrcData). Оба указателя разворачиваются на своей позиции **без обрыва** текущего массива, не-спец-спрмы сохраняются (union): spec §2.6.2 велит хвост за PTableProps игнорировать, но Word пишет в нём легаси-зеркало (в `samples/ru-table-image.doc` — единственный `sprmTDefTable`, Appendix A <9>), а `sprmTInsert` из PrcData конвертер не читает — замещение ломало бы сетку; спец-спрмов нет → **тот же массив** (по ссылке); любой брак (ptr за Data, cb вне [1, 0x3FA2], цикл A→B→A — бюджет 32 PrcData) → останов без исключения, снисходительно (образец `Styles`/`Lists`). Подключается единственной точкой — `DocxBody.buildRange` (покрывает тело, колонтитуки, TTP-ветку и обычные huge-PAPX абзацы). Регрессия — `DocToDocxFormattingTest#hugePapxRowMark_closesRowWithGridFromPrcData` |
|`DocToDocx`|Оркестратор + вложенный `DocxBody`: текст → раны (CHPX+стилевой chpx-цепочка +chpx-цепочка символьного стиля по **sprmCIstd** (`Styles.charChain` — между стилевой цепочкой и прямыми, §2.4.6.5) → rPr (в т.ч. `w:highlight`/`w:shd`), прямой PAPX — после `PrcData.resolve` — +стилевая papx-цепочка (отступы через `Grpprl.Indents`, 80-варианты включительно; `sprmPChgTabsPapx`/`sprmPChgTabs` → `w:tabs`, у стилевого варианта радиус удаления из `rgdxaClose`) + sprmPIlfo/sprmPIlvl → pPr + `w:numPr` (между pageBreakBefore и tabs, CT_PPr §17.3.1.26; ilfo=0 перекрывает стилевой, ilvl=0x0C и неразрешённый numId → без numPr), base→derived→direct last-wins; флаги рана: vanish — мост фильтрует вывод рана (`w:vanish` в FO мёртв), caps/smallCaps — `Character.toUpperCase` в мосту (`w:caps`/`w:smallCaps` конвейер не читает, FOP без font-variant), rMarkIns/rMarkDel — ран оборачивается в `w:ins`/`w:del`+`w:delText` (шаблоны docx2fo рисуют правки — вид «Show Markup»), hpsPos → `w:position` (вендорный AUDIT-FIX → baseline-shift)), ¶ → `<w:p>`; TAB/0x0B → `w:tab`/`w:br`, 0x0E → `w:br type="column"` (конец колонки при sprmSCcolumns), 0x0C в ране → `w:br type="page"`, 0x0C в конце абзаца — **разрыв секции**: `sectPr` соответствующей `Sections.Section` (матчинг по конечному CP) в pPr этого абзаца, внутри таблицы деградирует в `w:br type="page"`; body-level `sectPr` — последняя секция; `w:type continuous` из sprmSBkc; `w:pgSz w:orient="landscape"` со сменой w/h местами, `w:pgNumType` (`w:start` при restart, `w:fmt` только для числовых nfc — общий маппинг `Lists.numFmt`), `w:cols` (evenly → `w:num`+`w:space`, иначе per-column `w:col`; неравные/неполные ширины → деградация в одноколонную), `w:titlePg` из `Section.titlePage` (после w:cols, CT_SectPrBase §17.2.3) — `DocxBody.sectPrXml`/`appendPgNumType`/`appendCols`; pPr: `w:shd` из sprmPShd/…80 перед `w:tabs` (CT_PPr §17.3.1.26), `w:keepNext`/`w:keepLines` перед `w:pageBreakBefore` (CT_PPr §17.3.1.26); 0x1E → U+2011, 0x1F → U+00AD, 0x02/0x03/0x04 (сноски) → пропуск; U+0001/U+0008 со sprmCPicLocation → DrawingML `pic` (общий путь с картинками и OLE-fallback; 0x08 — якорь плавающей картинки §2.9.267, переносится inline-приближением: PlcfSpa не читается, позиция/обтекание теряются); field-символы в основном тексте: инструкция скрыта, кэшированный результат после разделителя видим; **табличный автомат**: абзац с 0x07 без TTP закрывает ячейку, 0x07+sprmPFTtp — конец строки (`Tables.parse` по TAP → `w:tbl`/`w:tr`/`w:tc`, сам маркер не эмитится), sprmPFInTable открывает ячейку; без корректного TDefTable строка деградирует в плоские абзацы (прежнее поведение); сетка первой строки действует на всю таблицу как `tblGrid`, ширины/объединение ячеек каждой строки — из её собственного TDefTable (горизонтальное слияние → `w:gridSpan`)|
|`DocxWriter`|Мульти-частный zip: `[Content_Types].xml` (hdr/ftr/numbering/png/jpg), `_rels/.rels`, `word/document.xml` (посекционные sectPr + headerReference; tblPr таблиц: tblW → jc (из sprmTJc) → tblInd → tblBorders), `word/_rels/document.xml.rels`, `word/numbering.xml`, `word/headerN.xml`/`footerN.xml` (по одной на непустую историю секции), `word/media/imageN.(png|jpg)`; корневые namespaces w/r/wp/a/pic|
|`DocxPackageWriter` (в `internal/`, общий с мостом .xlsx)|Мульти-частный zip: `[Content_Types].xml` (hdr/ftr/numbering/png/jpg), `_rels/.rels`, `word/document.xml` (посекционные sectPr + headerReference; tblPr таблиц: tblW → jc (из sprmTJc) → tblInd → tblBorders), `word/_rels/document.xml.rels`, `word/numbering.xml`, `word/headerN.xml`/`footerN.xml` (по одной на непустую историю секции), `word/media/imageN.(png|jpg)`; корневые namespaces w/r/wp/a/pic/c|
## Остаток моста
+1 -1
View File
@@ -18,7 +18,7 @@
### Валидация входа и подсчёт страниц
Вход валидируется **до** `convertToStream`: `WordPdfValidator.validate(bytes, options)` (размер → подпись: zip `PK\x03\x04` или CFB `D0 CF 11 E0` → контейнер → страницы). Для `.doc` страницы считаются **по сырым байтам .doc, до конвертации**: `checkPageCountDoc` = `max(SummaryInfo PageCount, 1 + явные разрывы)`; явные — 0x0C в основном тексте + `sprmPFPageBreakBefore` из PAPX. Тот же метод — вход приложения. Скан выполняется ровно один раз по сырому входу, до аллокаций docx4j: правила 1–10 число учитываемых разрывов не увеличивают (правило 9 способно только убрать разрыв внутри скрытого рана — счёт по сырому входу остаётся верхней оценкой лимита).
Вход валидируется **до** `convertToStream`: `WordPdfValidator.validate(bytes, options)` (размер → подпись: zip `PK\x03\x04` или CFB `D0 CF 11 E0` → контейнер `checkOoxmlContainer` → `ContainerKind.DOCX|XLSX` по подстрокам `[Content_Types].xml` (маркеры — content-type'ы частей `wordprocessingml.document` / union-префикс `spreadsheetml.` (worksheet/sheet/sharedStrings/styles); DOCX проверяется первым — манифест с обоими маркерами трактуется как .docx; ни одного маркера → 400) → страницы). Для `.doc` страницы считаются **по сырым байтам .doc, до конвертации**: `checkPageCountDoc` = `max(SummaryInfo PageCount, 1 + явные разрывы)`; явные — 0x0C в основном тексте + `sprmPFPageBreakBefore` из PAPX. Для `.xlsx` — `checkPageCountXlsx` = двупроходная нижняя оценка `estimateXlsxPages`: проход 1 — `xl/workbook.xml` (видимые листы: r:id, state≠hidden/veryHidden) + `xl/_rels/workbook.xml.rels` (rId → target части, внешний/отсутствующий target — лист не учитывается), проход 2 — счёт `rowBreaks/brk` в целевых частях; страницы = число учитываемых листов + их разрывы; `docProps/app.xml` для книг не читается (Excel `<Pages>` не кэширует), геометрия `PrintLayout` — дело моста, оценка обязана быть ≤ фактических секций. Тот же метод — вход приложения. Скан выполняется ровно один раз по сырому входу, до аллокаций docx4j: правила 1–10 число учитываемых разрывов не увеличивают (правило 9 способно только убрать разрыв внутри скрытого рана — счёт по сырому входу остаётся верхней оценкой лимита).
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; explicit = межсекционные `w:sectPr` в body + `w:br type="page"` + `pageBreakBefore` (включая таблицы и `w:sdt`). Единственный путь — lightweight (StAX по zip, secure-ридер без DTD/external entities; `WordPdfValidator` не зависит от docx4j): атрибуты — по локальному имени (`attrLocal`, не по transitional-URI: иначе в strict-документе `w:br type="page"` не засчитываются); `sectPr` внутри `pPr` не считает, последнюю body-direct секцию не считает, `continuous`-секции не считает, в колонтитуках — только `w:br type="page"`, `pageBreakBefore` — только внутри `pPr` вне `sectPr` (truthy `val`: `null|true|1|on`). На не-zip молчит — подпись проверяет вызывающий. `checkPageCount` — один стриминговый проход `ZipInputStream` без буферизации частей (хелпер `noClose` глушит `close()` сканеров): потребление O(одной части) вместо O(суммы XML-частей).
+14 -6
View File
@@ -6,12 +6,13 @@
|---|---|
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | Публичный API: `WordPdfConverter` (`convert(byte[],String[,ConvertOptions])`), `WordPdfValidator` (`checkInput`/`checkPageCount`/`validate` — без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}`), `WordPdfSettings` (`MAX_INPUT_MB=5`, `MAX_PAGES=100`, защитные `MAX_DECOMPRESSED_MB=200`/`MAX_ZIP_ENTRIES=8192`, `ERROR_ON_*=false`), `ConvertOptions` (record) |
| `…/wordpdf/fonts/` | `BundledFonts` (реестр/выгрузка TTF), `BundledFontMapper` (алиасы, self-map, `DISPLAY_NAMES`, `bundledFamily`), `GlyphFont` (глиф-движок fontbox) |
| `…/wordpdf/internal/` | 11 нормализаторов + `DocxRewritePipeline` (один zip-проход правил 1–10, raw-копия неизменённых записей) + `LayoutPostRenderer` (кастомный `FORenderer`, post-FO padding-компенсация таблиц, шаг 4.25) + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка commons-compress, шаг 0). Классы `public` (иначе родительский пакет не вызвал бы), публичные члены наружу только `normalize`/`STEP`/`declare`/`DependencyGuard.check`/`LayoutPostRenderer.register`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)` |
| `…/wordpdf/internal/doc/` | Мост `.doc` → `.docx`: 18 классов (детали — `docs/agent/doc-bridge.md`) — `CfbReader`, `FibHeader`, `PieceTable`, `Grpprl`, `ChpxIndex`, `PapxIndex`, `Styles`, `Tables`, `Lists`, `Sections`, `FontTable`, `SummaryInfo`, `Headers`, `OfficeArt`, `PrcData`, `DocFile`, `DocxWriter`, `DocToDocx` (публичные `convert`/`countPages`; вложенный `DocxBody` — рендер текста и табличного автомата в XML) |
| `…/wordpdf/internal/` | 11 нормализаторов + `DocxRewritePipeline` (один zip-проход правил 1–10, raw-копия неизменённых записей) + `LayoutPostRenderer` (кастомный `FORenderer`, post-FO padding-компенсация таблиц, шаг 4.25) + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка commons-compress, шаг 0) + `DocxPackageWriter` (писатель мульти-частного docx-зипа для обоих мостов: `[Content_Types].xml`/rels по `Part(entry, contentType, relType, content)`, корневые namespaces с `xmlns:c`, `storyPart` для колонтитуков). Классы `public` (иначе родительский пакет не вызвал бы), публичные члены наружу только `normalize`/`STEP`/`declare`/`DependencyGuard.check`/`LayoutPostRenderer.register`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)` |
| `…/wordpdf/internal/doc/` | Мост `.doc` → `.docx`: 17 классов (детали — `docs/agent/doc-bridge.md`) — `CfbReader`, `FibHeader`, `PieceTable`, `Grpprl`, `ChpxIndex`, `PapxIndex`, `Styles`, `Tables`, `Lists`, `Sections`, `FontTable`, `SummaryInfo`, `Headers`, `OfficeArt`, `PrcData`, `DocFile`, `DocToDocx` (публичные `convert`/`countPages`; вложенный `DocxBody` — рендер текста и табличного автомата в XML); писатель зипа вынесен в `internal/DocxPackageWriter` (общий с мостом .xlsx) |
| `…/wordpdf/internal/xlsx/` | Мост `.xlsx` → `.docx`: 16 классов (детали — `docs/agent/xlsx-bridge.md`) — `XlsxPackage`, `WorkbookModel`, `SharedStrings`, `ThemeModel`, `StylesModel`, `ColorSpec`, `ColorResolver`, `NumberFormats`, `NumberText`, `Metrics`, `SheetModel`, `PrintLayout`, `SheetToTable`, `DrawingBridge`, `WarnOnce`, `XlsxToDocx` (публичный `convert(byte[], ConvertOptions)`) |
| `…/wordpdf/internal/chart/` |17 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer.run`)|
| `wordpdf-core/src/main/resources/fonts/` | 30 TTF + 3 лицензии — бинарные фикстуры, часть jar |
| `wordpdf-core/src/main/resources/xslt/` | `docx2fo.xslt` — вендорный XSL-FO-стилист (копия docx4j-export-fo + AUDIT-FIX-патчи), часть jar |
| `wordpdf-core/src/test/resources/samples/` | 25 закоммиченных фикстур: 13 `.docx` + 12 `.doc` (11 эталонов заказчика из `develop/doc/` с теми же базовыми именами + `doc-formats.doc`); `.docx` проходят `docs/standards/docx/validate-fixtures.py`, `.doc` — бинарные, XSD к ним неприменим |
| `wordpdf-core/src/test/resources/samples/` | 32 закоммиченных фикстур: 13 `.docx` + 12 `.doc` (11 эталонов заказчика из `develop/doc/` с теми же базовыми именами + `doc-formats.doc`) + 7 `.xlsx` (`xlsx-basic/numfmt/1904/page-limit/wide/fit-to-page/chart-image`, генерирует `SampleXlsxGenerator`, POI); `.docx` проходят `docs/standards/docx/validate-fixtures.py`, `.doc` — бинарные, XSD к ним неприменим |
| `wordpdf-core/src/test/resources/geom/` | `presetShapeDefinitions.xml` — копия приложения ECMA-376, синхрон таблицы `PresetGeometry` (только в тестах, в jar не попадает) |
| `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/` | REST API (10 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`, `OpenApiConfig` (`@SecurityScheme` X-API-Key) + 4 класса исключений |
| `wordpdf-web/src/` | SPA: `api.ts` (вся сеть), `components/` (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo) |
@@ -19,7 +20,7 @@
| `.env.example` | Шаблон env: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES` (пустое значение ломает binding long/int). Проду `.env` не нужен — ключ и лимиты подаёт job `deploy` из Gitea Secrets/Variables |
| `.gitea/workflows/` | Gitea Actions: `pr.yml` (`PR checks`), `main.yml` (тесты + coverage-сводка и комментарий в PR → `images-app`/`images-web` (build+push в Nexus) → deploy (рендер прод-конфигов + pull) → autotests → rollback) |
| `GITEA-vars.md` | Инструкция владельца: Secrets/Variables, защита ветки, перезапуск — только имена переменных, без значений |
| `prod-autotests/` | Прод-автотесты API (pytest + requests, 31 проверка): конфигурация стенда **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY`/`WORDPDF_MAX_PAGES`/`WORDPDF_MAX_MB`/`WORDPDF_SAMPLES_DIR` факультативны) — прод-хостов/ключей в коде нет |
| `prod-autotests/` | Прод-автотесты API (pytest + requests, 32 проверки): конфигурация стенда **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY`/`WORDPDF_MAX_PAGES`/`WORDPDF_MAX_MB`/`WORDPDF_SAMPLES_DIR` факультативны) — прод-хостов/ключей в коде нет |
| `docs/standards/` | Нормативная документация форматов Word/Excel, шесть каталогов + навигатор `README.md`: `ooxml/` — OOXML: PDF+md ECMA-376 Part 1 (5-е изд.), md [MS-OI29500]/[MS-ODRAWXML], полные наборы XSD `ooxml/schema/strict/` (21) + `ooxml/schema/transitional/` (26); `binary/` — общее OLE2-окружение .doc/.xls [MS-CFB]/[MS-OSHARED]/[MS-ODRAW]/[MS-OLEPS]/[MS-OFFCRYPTO]/[MS-OVBA]/[MS-WMF]/[MS-EMF]; `doc/` — [MS-DOC] (`ms-doc.md` + `ms-doc-full.md` — тот же текст с HTML packet diagram'ами и таблицами sprm §2.6.1–2.6.3, где `ms-doc.md` даёт `[TABLE]`); `docx/` — `validate-fixtures.py` (XSD-валидация `samples/*.docx`, lxml, ставится отдельно); `xls/` — [MS-XLS] (`ms-xls.md` + `ms-xls-full.md` — тот же приём `[TABLE]`); `xlsx/` — [MS-XLSX] (`ms-xlsx.md`); регенерация — README в каждом каталоге |
| `develop/` (вне git, gitignored) | Рабочие материалы и эталоны сравнения рендера — **не фикстуры**, в тесты/jar не подключать; пиксельные замеры зашиты числами в chart-тестах |
| `docs/agent/` | Глубокие справочники: `pipeline` / `doc-bridge` / `chart` / `render-limitations` / `testing` / `ci-cd` (когда читать — по имени файла) |
@@ -38,7 +39,7 @@
- `.ci/maven-settings.xml` — Maven-зеркало Nexus с URL из `${env.MAVEN_MIRROR_URL}` (общий файл CI-job'ов `java` и Containerfile; координаты стенда в репо не хранятся — Variable/build-arg).
- `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF.
- `gateway/nginx.conf` — единственный вход: `/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → `app:8080`, остальное → `web:80`; `client_max_body_size 100m` (без директивы upload режется HTML-413 шлюза вместо JSON-ошибки API); `proxy_read_timeout`/`proxy_send_timeout 300s` (дефолтные 60s рвут 2-минутные конвертации 504 раньше app-ного 504); `resolver 10.113.0.1` + `proxy_pass` через переменные (статический `proxy_pass` резолвит имя один раз при старте — gateway, поднявшийся раньше app, получал бы 502 до перезапуска).
- `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур; `ChartTypesDocxGenerator.java` — генератор `chart-types.docx`.
- `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур; `ChartTypesDocxGenerator.java` — генератор `chart-types.docx`; `SampleXlsxGenerator.java` — main()-утилита пересоздания 7 фикстур `samples/xlsx-*.xlsx` (POI XSSF); `internal/xlsx/XlsxTestZips.java` — конструктор синтетических .zip-книг для юнитов моста (не фикстура).
- `wordpdf-web/vite.local.config.ts` — легаси-одноразовщик (прокси `/api` → :8091), в `tsconfig.node.json` не включён; кандидат на удаление, не тиражировать паттерн. Корневые `javac.*.args` — мусор пробной компиляции (gitignored), тоже кандидат на удаление.
## Development Commands (детали)
@@ -62,6 +63,13 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples
```
Пересоздать 7 фикстур `.xlsx` (тот же classpath):
```bash
java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
ru.pjandro.wordpdf.SampleXlsxGenerator wordpdf-core/src/test/resources/samples
```
### Перевендоривание XSL-FO-стилиста
```bash
@@ -98,7 +106,7 @@ PMD: `failurePriority` в плагине не задан — на практик
- Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run`/`DependencyGuard.check` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`.
- Гейт JaCoCo `0.8.15`: `jacoco:check` (правило BUNDLE, LINE COVEREDRATIO `0.90` — обоих модулей; в `wordpdf-core/pom.xml` execution `check` переопределён и добавляет BRANCH COVEREDRATIO `0.85` — только для core) на `verify`; агент подключается в surefire через `argLine` = `@{argLine} -Djava.awt.headless=true` (свойство `argLine` в корневом pom по умолчанию пусто и перезаписывается `prepare-agent` — `mvn test -Djacoco.skip=true` без агента работоспособно); `report` и `check` оба на `verify`, report раньше — при провале порога отчёт уже на диске; отчёты `target/site/jacoco/` (html+xml, xml нужен CI-сводке). Плотность покрытия держат тесты, а не заглушки: промахи в основном недостижимые IOException/catch-ветки (`GlyphFont`, `BundledFonts`) и защитные ветви сканеров нормализаторов/валидатора.
- 57 тестовых класса / 886 теста (core 51/843 — из них 17 классов / 225 тестов в `internal/doc/`, `WordPdfConverterTest` 75 — включая блок аудита .docx 2026-11: правила 9–10, AUDIT-FIX-2 и пиннинг сносок/полей/titlePg/vMerge/sdt/txbx/OMML/highlight на синтетике через хелпер `docx(...)`; app 6/43: ConvertController 23 + ApiKeyFilter 8 + ConversionService 5 + ApiExceptionHandler 4 + ConvertLimits 2 + ConversionTimeout 1). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true`; только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`), тестовые классы package-private, зеркалят main-пакеты; только `@Test` + два `@BeforeAll` (warm-up шрифтов в `GlyphCoverageNormalizerTest` и `BundledFonts.init()` в `BundledFontsTest`) + `@AfterEach drainWorker` в `ConversionTimeoutTest` (дренировать отменённый FOP-рендер до следующего класса — гонка глобального `PhysicalFonts`).
- 75 тестовых класса / 1095 тестов (core 69/1051 — из них 17 классов / 225 тестов в `internal/doc/`, 15 классов / 189 тестов в `internal/xlsx/` + корневой `XlsxPdfConverterTest` 8 (PDF по фикстурам `samples/xlsx-*.xlsx`), `WordPdfConverterTest` 76 — включая блок аудита .docx 2026-11: правила 9–10, AUDIT-FIX-2 и пиннинг сносок/полей/titlePg/vMerge/sdt/txbx/OMML/highlight на синтетике через хелпер `docx(...)`; app 6/44: ConvertController 24 + ApiKeyFilter 8 + ConversionService 5 + ApiExceptionHandler 4 + ConvertLimits 2 + ConversionTimeout 1). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true`; только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`), тестовые классы package-private, зеркалят main-пакеты; только `@Test` + два `@BeforeAll` (warm-up шрифтов в `GlyphCoverageNormalizerTest` и `BundledFonts.init()` в `BundledFontsTest`) + `@AfterEach drainWorker` в `ConversionTimeoutTest` (дренировать отменённый FOP-рендер до следующего класса — гонка глобального `PhysicalFonts`).
- Фронт: Node `^20.19.0 || >=22.12.0` (engines vite/rolldown/oxlint из `package-lock.json` — в `package.json` секции `engines` нет), npm с закоммиченным `package-lock.json` (`npm ci`); vite `^8.3`, React `^19.2`, TS `~6.0` (**`strict` нигде не включён** — `npm run build` не является strict-гейтом), Tailwind `^4.3`, oxlint `^1.81`; сборка web-образа на `node:24-alpine`.
- Контейнеры (podman/buildah): `FROM` только FQDN (`docker.io/library/...` — short-name не резолвится без `unqualified-search-registries`); buildah подмешивает хостовые прокси-переменные в `RUN`/`HEALTHCHECK` — обнулять `HTTP_PROXY= http_proxy= …` **на самой команде** (ENV не перебивает). Chart-движку нужен только модуль `java.desktop` (Graphics2D, он внутри JRE); fontconfig и системные шрифты рантайму не нужны — текст рисуется глифами fontbox (`fonts/GlyphFont`), проверено на musl-стенде без libfontconfig/`/etc/fonts`.
+5 -3
View File
@@ -8,7 +8,7 @@
### Фикстуры
- Фикстуры — закоммиченные `samples/*.docx` + `samples/*.doc` (13 + 12; в тестах не генерировать; `.docx` все ECMA-conformant по `docs/standards/docx/validate-fixtures.py` — фикстура невалидна, правится фикстура, не код; `.doc` — эталоны заказчика, конвертируются мостом): core грузит classpath-ресурсом → `byte[]`, PDF для PDFBox — временный файл; app читает `/samples/…` из **test-jar core** (classifier `tests`) → `mvn -pl wordpdf-app` без `-am` не соберётся. In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]`; in-memory `.doc` — POIFS (`POIFSFileSystem`) вокруг крафтовых WordDocument/1Table/Data (`DocToDocxFormattingTest`). Ключевые: `too-many-pages` (150 явных разрывов → 151; `.doc`-пара — кэш PageCount=150 → 400 «не менее 151»), `stale-cache` (docx: кэш `<Pages>1</Pages>` + 110 `lastRenderedPageBreak` → 400; doc: кэш 5 → конвертируется — семантика запинена), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject; `.doc`-пара — 3 BLIP-fallback → 3 картинки), `ole-embedded` (осиротевший bin с ложным `Default bin→footer+xml` + настоящий `w:object` с честным `Override → oleObject` и VML-плейсхолдером `media/fallback.png` — ручная, генератором не перезаписывать; `.doc`-пара — OLE-fallback BLIP → 1 картинка), `chart-types` (14 графиков: 9 типов + ofPie-pie + lineChart stacked + `c:wireframe` + combo barChart+lineChart на вторичной `c:valAx` pos="r"; пересоздание — `ChartTypesDocxGenerator`; `.doc`-аналога нет), `doc-formats.doc` (2 страницы — лимит страниц на .doc-пути).
- Фикстуры — закоммиченные `samples/*.docx` + `samples/*.doc` + `samples/*.xlsx` (13 + 12 + 7; в тестах не генерировать; `.docx` все ECMA-conformant по `docs/standards/docx/validate-fixtures.py` — фикстура невалидна, правится фикстура, не код; `.doc` — эталоны заказчика, конвертируются мостом; `.xlsx` генерирует `SampleXlsxGenerator` (POI), их содержимое — контракт: тексты ячеек запинены, assertions только по целым словам широких колонок — узкие режутся переносом FOP): core грузит classpath-ресурсом → `byte[]`, PDF для PDFBox — временный файл; app читает `/samples/…` из **test-jar core** (classifier `tests`) → `mvn -pl wordpdf-app` без `-am` не соберётся. In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]`; in-memory `.doc` — POIFS (`POIFSFileSystem`) вокруг крафтовых WordDocument/1Table/Data (`DocToDocxFormattingTest`). Ключевые: `too-many-pages` (150 явных разрывов → 151; `.doc`-пара — кэш PageCount=150 → 400 «не менее 151»), `stale-cache` (docx: кэш `<Pages>1</Pages>` + 110 `lastRenderedPageBreak` → 400; doc: кэш 5 → конвертируется — семантика запинена), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject; `.doc`-пара — 3 BLIP-fallback → 3 картинки), `ole-embedded` (осиротевший bin с ложным `Default bin→footer+xml` + настоящий `w:object` с честным `Override → oleObject` и VML-плейсхолдером `media/fallback.png` — ручная, генератором не перезаписывать; `.doc`-пара — OLE-fallback BLIP → 1 картинка), `chart-types` (14 графиков: 9 типов + ofPie-pie + lineChart stacked + `c:wireframe` + combo barChart+lineChart на вторичной `c:valAx` pos="r"; пересоздание — `ChartTypesDocxGenerator`; `.doc`-аналога нет), `doc-formats.doc` (2 страницы — лимит страниц на .doc-пути).
### Юниты
@@ -16,9 +16,11 @@
- Юниты моста (`internal/doc/`): `CfbReaderTest` строит крафтовый CFB-байтстрим (сектор 512/mini 64: FAT/DIFAT/miniFAT/directory руками) и бьёт все guard-ветки (циклы FAT/DIFAT/MiniFAT, ссылки за файл, обрезанные потоки, root без mini stream, мусор в directory); `SummaryInfoTest` — крафтовый PropertySetStream (пинит **относительность offset от начала PropertySet**, реальные фикстуры её не различают); `PieceTableTest`/`ChpxIndexTest`/`PapxIndexTest` (в т.ч. `istdFor`: istd из UpxPapx, пустой grpprl ≠ null, bOffset=0 → дефолтные свойства при сохранённой границе)/`SectionsTest`/`FibHeaderTest` (пара fcStshf)/`GrpprlTest` (в т.ч. спец-длины: двухбайтовый cb у sprmTDefTable при operand >255 Б, у 0xC60D cb=0xFF — обрыв, у 0xC615 cb=0xFF — длина по формуле §2.9.182 (`scan_pChgTabsSentinel_lengthByFormula`))/`FontTableTest`/`HeadersTest`/`OfficeArtTest`/`PrcDataTest` — byte[]-конструкции in memory (`PrcDataTest`: разворачивание huge-PAPX/PTableProps на позиции указателя, union цепочки с легаси-зеркалом, guard'ы — cb-капа 0x3FA2, ptr за Data, цикл A→B→A); `StylesTest` — крафтовый STSH (LPStd/LPUpx): цепочка base→derived, цикл → пустая таблица, чужой stk/битый STSH нисходительны; `TablesTest` — крафтовый TAP: сетка TDefTable (XAS со знаком), границы Brc (cv fAuto) и Brc80 (ico, приоритет 0xD613), выравнивание sprmTJc/sprmTJc90 (u16, приоритет современного, 0 → null), деградация при битом TDefTable; `ListsTest` — крафтовые PlfLst/PlfLfo байтстримом (счёт LVL по fSimpleList 1/9, плейсхолдеры xst → `%{n+1}` и литеральный `%` → `%%`, MSONFC→ST_NumberFormat вкл. экзотика→decimal, ixchFollow→`w:suff`, grpprl уровня → `w:ind`/`w:rFonts`, LFOLVL fStartAt/fFormatting, обрыв LVL-массива, lsid без LSTF, нулевые lcb); `DocToDocxFormattingTest` — полный синтетический .doc через POIFS (крафтовые FIB/Clx/FKP-страницы: полные CHPX/PAPX-свойства, STSH-цепочка с переопределением и победой direct, spacing/tabs, таблица TTP+TDefTable+Brc с деградацией строки без сетки и многострочной ячейкой, колонтитук со стилевым jc, табы колонтитука из стиля sprmPChgTabs (`styleTabsChg_reachesFooterPart`/`styleTabsChgDel_removesStop`: прямой del с rgdxaClose вырезает stop стиля), таблица в odd footer со sprmTJc (`footerTable_jcCenterEmitted`: guard-¶ отдельным абзацем после строки, как в реальных Plcfhdd), знаки, поле в основном тексте, picLocation=0, 0Table, отсутствие табличного потока, списки: `listParagraphs_getNumPrAndNumberingPart` (sprmPIlfo/sprmPIlvl в PAPX → `w:numPr` + `word/numbering.xml` c `w:num`/Override/rels), `listCancelledByDirectZero_noNumPr` (ilfo стиля, перекрытый прямым 0), `ilvlSkipValue_noNumPr` (ilvl=0x0C), `missingListTables_degradeToPlain` (нулевые FIB-пары 73/74 — ни numbering-части, ни numPr)). Doc-регрессии конвертера — общие assert-хелперы docx-пар: `assertCyrillicAndStyles`/`assertPageNumbers`/`assertTableImage`/`assertOleObjectsRemoved`/`assertDrawingsBecomeImages`/`assertTooManyPages`/`assertExoticGlyphs` вызываются с `ru-plain.doc`/`page-numbers.doc`/`ru-table-image.doc`/`ole-embedded.doc`/`charts-smartart.doc`/`too-many-pages.doc`/`exotic-glyphs.doc` (тесты-пары называются по docx-имени, внутри зовут оба формата); `WordPdfValidatorTest#checkPageCountDoc_*` + `ConvertControllerTest` (`.doc` upload, `nonDocxFilename_rejected`).
- Юниты моста `.xlsx` (`internal/xlsx/`): синтетические книги — `XlsxTestZips` (литеральные XML в `ZipOutputStream`: workbook/sheet/rels/sst/styles/theme; лист обязан ссылаться на рисунок элементом `<drawing r:id>` в XML листа — `SheetModel` резолвит `drawingPath` по элементу, не по релсам); POI в юнитах моста не используется. PDF-слой — корневой `XlsxPdfConverterTest` по фикстурам (текст, `imageCount`/`distinctImageCount`, 422 `Kind.CHARTS`/`Kind.OLE`).
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); четыре контекста — `ConvertControllerTest` (пустой ключ), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest` (`@TestPropertySource` max-mb/max-pages), `ConversionTimeoutTest` (`@TestPropertySource` convert-timeout=1ms) — четыре разных набора свойств = четыре кэшированных контекста (отдельные классы, не `@Nested`: `@Nested` + `@TestPropertySource` не даёт отдельного контекста); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring-контекста (прямые юниты).
- UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint, `.oxlintrc.json`: rules-of-hooks error, only-export-components warn). Прод-автотесты (pytest 9.1.1 + requests 2.34.2, 31 проверка — 27 под маркером `needs_key` (SKIP без ключа; включая `.doc`-фикстуры обоих путей — растры/OLE и границы страниц), 4 открытых: health/SPA-root/swagger/spec; env-конфиг, `mise exec -- python -m pytest -q .` из `prod-autotests/`) гоняются CI после deploy против живого прода.
- UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint, `.oxlintrc.json`: rules-of-hooks error, only-export-components warn). Прод-автотесты (pytest 9.1.1 + requests 2.34.2, 32 проверка — 28 под маркером `needs_key` (SKIP без ключа; включая `.doc`/`.xlsx`-фикстуры обоих путей — растры/OLE и границы страниц), 4 открытых: health/SPA-root/swagger/spec; env-конфиг, `mise exec -- python -m pytest -q .` из `prod-autotests/`) гоняются CI после deploy против живого прода.
### Регрессивные записи, не выводимые из кода
@@ -28,4 +30,4 @@
- `vendoredXsltTracksJarCopy` — дрейф-гейт: вне AUDIT-FIX-регионов вендорный `docx2fo.xslt` обязан быть побайтно равен стилисту из jar'а docx4j-export-fo (при апгрейде docx4j — перевендорить и перенести патчи).
- Крафт POIFS (закоммиченных фикстур нет, крафт продублирован в `WordPdfConverterTest`): `ListsTest`+`DocToDocxFormattingTest#list*`↔`docLists_numberingAndBulletsRendered` (синтетический .doc со списками → PDF: `1.` `2.` `a)` `b)` `•`, ни одного `#`; фикстур со списками нет — крафт POIFS продублирован в `WordPdfConverterTest`), `PrcDataTest`+`DocToDocxFormattingTest#hugePapxRowMark_closesRowWithGridFromPrcData` (TTP-абзац с grpprl в PrcData Data-потока → `w:tbl`/`w:tr`/сетка из цепочки; фикстуры нет — `docTest.doc` заказчика не коммитим, крафт POIFS продублирован), `SectionsTest`+`HeadersTest`+`DocToDocxFormattingTest#twoSections*/sectionBreakInTable*`↔`docMultiSection_perSectionHeaders` (двухсекционный .doc → PDF: стр. 1 — ШАПКА-1+ПОДВАЛ-1, стр. 2 — ШАПКА-2 + унаследованный ПОДВАЛ-1, ни одной `#`; крафт POIFS продублирован в `WordPdfConverterTest`), `ChpxIndexTest#zeroOffset_defaultPropsBoundaryKept`+`DocToDocxFormattingTest#runFlags_*/keepNextKeepLines_*/sectLandscapePgNumCols_*/sectUnevenCols_*/cellVertAlign_*/drawnObject_*`+`SectionsTest#orientationPgNumColumns_applied/unevenColumns_perIndexWidths/restartWithoutStart_clampsToOne`+`TablesTest#vertAlign_*`↔`WordPdfConverterTest#docClassD_landscapeHiddenDelCaps/#docClassD_pageNumberRestartLowerRoman/#docClassD_twoColumnsBreak/#docClassD_drawnObjectBecomesImage` (закрытие пробелов класса D: vanish-фильтр/правки/caps/position/keep, landscape+pgNumType, колонки+column break, vAlign, 0x08→inline-картинка; фикстур нет — крафт POIFS продублирован в обоих тестовых классах).
- Синтетика через общий хелпер `docx(docXmlns, body, sect, rels, overrides, parts)`: AUDIT-FIX-2↔`movedRevision_textPrinted`/`bdoDir_textPrinted` (фикстур нет — синтетический docx через общий хелпер `docx(docXmlns, body, sect, rels, overrides, parts)`); пиннинг аудита .docx↔`footnote_rendersAtPageBottom`, `endnote_rendersAtDocumentEnd`, `docxHyperlink_uriAnnotation`, `pageRefField_liveNotCached` (кэш 9001/7777 заменён живым номером), `dateField_notStaleCache` (кэш 01.02.2003 заменён текущей датой), `titlePg_firstPageHeader`, `vMergeCell_spansRows`, `sdtContent_rendered`, `drawingTextBox_textPrinted`, `ommlMath_drawnAsVectors` (пиксели: +150 тёмных px@150dpi сверх текста), `highlightAndShading_backgroundDrawn` (жёлтые px >0 против baseline 0), аудит [MS-DOC] моста 2026-11: `GrpprlTest#tInsertOperand_skippedBySpra`/`tInsertOperand_truncated_aborts` (sprmTInsert — 4 байта, хвост TAP не рассинхронизирован), `TablesTest#cellPadding_*` + `DocToDocxFormattingTest#cellMargins_becomeTcMar` ↔ `WordPdfConverterTest#tableTcMar_textInsetLikeWord` (CSSA→w:tcMar, пайплайн красит поля ячейки как tblCellMar — текст на margin+padding), `StylesTest#characterStyle_stk3_chainViaCharChain`/`charChain_nonCharacterStk_empty` + `DocToDocxFormattingTest#charStyle_viaIstd_mergesUnderDirect` (sprmCIstd: символьная chpx-цепочка между стилевой и прямыми, direct wins), `DocToDocxFormattingTest#runHighlightAndShading_inRPr`/`runShadingPattern_degradesToBackFill`/`paraShd_inPPrBeforeJc` ↔ `docHighlightAndShading_yellowPixels` (Ico→ST_HighlightColor; w:shd в форме FOP val="clear"+fill; паттерн→cvBack), `SectionsTest#titlePage_flagFromSepx` + `DocToDocxFormattingTest#titlePage_emittedAfterCols` ↔ `docTitlePage_firstHeaderOnlyFirstPage` (sprmSFTitlePage + first-слоты Plcfhdd → headerReference type="first", первая страница — только first-шапка)..
- App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed`, `corruptNotAZip_rejected`, `plainZipNotDocx_rejected`, `junkInsideValidZip_conversionError` (500 на валидном .docx-контейнере с мусором), `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `drawingsAlwaysRendered`, `cyrillicAndPathInFilename_sanitizedResponseName`, `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey`, `dotSegmentOpenPrefix_rejected`, `errorFlagNotBoolean_rejected`, `methodNotSupportedReturns405`/`badContentTypeReturns415`.
- App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed`, `corruptNotAZip_rejected`, `plainZipNotDocx_rejected`, `junkInsideValidZip_conversionError` (500 на валидном .docx-контейнере с мусором), `nonDocxFilename_rejected`, `xlsxFile_convertsToPdf`, `oversizedOverCoreLimit_rejected`, `drawingsAlwaysRendered`, `cyrillicAndPathInFilename_sanitizedResponseName`, `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey`, `dotSegmentOpenPrefix_rejected`, `errorFlagNotBoolean_rejected`, `methodNotSupportedReturns405`/`badContentTypeReturns415`.
+77
View File
@@ -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`).