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
+26 -11
View File
@@ -2,7 +2,7 @@
## Project Overview
Конвертер `.docx`/`.doc` → `.pdf` на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Бинарный `.doc` (Word 97-2003) — собственный мост MS-DOC/MS-CFB `internal/doc` → in-memory `.docx` → тот же конвейер. Java 17, только Maven.
Конвертер `.docx`/`.doc`/`.xlsx` → `.pdf` на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Бинарный `.doc` (Word 97-2003) — собственный мост MS-DOC/MS-CFB `internal/doc` → in-memory `.docx` → тот же конвейер; `.xlsx` (SpreadsheetML) — собственный мост `internal/xlsx` → in-memory `.docx` → тот же конвейер. Java 17, только Maven.
Три независимых модуля:
@@ -16,7 +16,7 @@
### Пайплайн `WordPdfConverter.convert(byte[], String[, ConvertOptions])`
Порядок фиксирован, местами менять нельзя (`WordPdfConverter.convertToStream`). Вход роутируется по сигнатуре до входа в конвейер: `PK\x03\x04` → docx-путь, `D0 CF 11 E0 A1 B1 1A E1` (CFB, MS-CFB §2.2) → мост `DocToDocx.convert` → in-memory `.docx` → этот конвейер (`WordPdfValidator.isBinaryDoc` — единый предикат):
Порядок фиксирован, местами менять нельзя (`WordPdfConverter.convertToStream`). Вход роутируется по сигнатуре до входа в конвейер: `PK\x03\x04` + маркеры книги в `[Content_Types].xml` → мост `XlsxToDocx.convert` → in-memory `.docx` → этот конвейер, `D0 CF 11 E0 A1 B1 1A E1` (CFB, MS-CFB §2.2) → мост `DocToDocx.convert` → in-memory `.docx` → этот конвейер, иначе docx-путь (`WordPdfValidator.isBinaryDoc`/`isSpreadsheet` — единые предикаты):
| # | Шаг | Что делает |
|---|---|---|
@@ -31,11 +31,11 @@
| 5–6 | `getFopFactoryBuilder`/`getFOUserAgent` → `Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)` | XSL-FO → PDF; непустой `title` → заголовок PDF |
| 7 | `finally` → `deleteEmbeddedFontTempFiles()` | в docx4j 17.x `OpcPackage.close()` нет |
Полные обоснования шагов и правила подсчёта страниц — `docs/agent/pipeline.md`. Вход валидируется **до** `convertToStream`: `WordPdfValidator.validate(bytes, options)` (размер → подпись zip/CFB → контейнер → страницы); для `.doc` — `checkPageCountDoc` по сырым байтам до конвертации.
Полные обоснования шагов и правила подсчёта страниц — `docs/agent/pipeline.md`. Вход валидируется **до** `convertToStream`: `WordPdfValidator.validate(bytes, options)` (размер → подпись zip/CFB → контейнер `ContainerKind.DOCX|XLSX` → страницы); для `.doc` — `checkPageCountDoc` по сырым байтам до конвертации, для `.xlsx` — `checkPageCountXlsx` (двупроходная нижняя оценка: видимые листы + явные `rowBreaks/brk`, `docProps/app.xml` для книг не читается).
### Мост `.doc` → `.docx` (`internal/doc`)
Нормативный источник — [MS-DOC] в `docs/standards/doc/`, общее OLE-окружение ([MS-CFB], [MS-OLEPS], [MS-ODRAW]) в `docs/standards/binary/`, [MS-ODRAWXML] в `docs/standards/ooxml/`, ссылки — с номерами секций. Новых runtime-зависимостей нет (POI/POIFS — test-scope). Публичные точки: `DocToDocx.convert(byte[])` (вызывает `WordPdfConverter`) и `DocToDocx.countPages(byte[])` (вызывает `WordPdfValidator.checkPageCountDoc`); общий разбор — `DocFile` (CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table). 16 из 18 классов package-private; наружу — `DocToDocx` и `CfbReader`.
Нормативный источник — [MS-DOC] в `docs/standards/doc/`, общее OLE-окружение ([MS-CFB], [MS-OLEPS], [MS-ODRAW]) в `docs/standards/binary/`, [MS-ODRAWXML] в `docs/standards/ooxml/`, ссылки — с номерами секций. Новых runtime-зависимостей нет (POI/POIFS — test-scope). Публичные точки: `DocToDocx.convert(byte[])` (вызывает `WordPdfConverter`) и `DocToDocx.countPages(byte[])` (вызывает `WordPdfValidator.checkPageCountDoc`); общий разбор — `DocFile` (CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table). 15 из 17 классов package-private; наружу — `DocToDocx` и `CfbReader`; писатель зипа вынесен в `internal/DocxPackageWriter` (общий с мостом `.xlsx`: `Part(entry, contentType, relType, content)`, `NAMESPACES` — корневые включая `xmlns:c`, `write(bodyXml, parts, hyperlinkTargets)`, `storyPart`).
|Класс|Семантика (полные байтовые раскладки — `docs/agent/doc-bridge.md`)|
|---|---|
@@ -44,10 +44,25 @@
|`Styles`, `FontTable`, `Lists`|STSH-цепочки base-first, символьные stk=3 → `charChain` (§2.9.271) + ftc→`w:rFonts` (§2.9.147) + PlfLst/PlfLfo → `word/numbering.xml` (§2.9.200/.201)|
|`Tables`, `Sections`, `Headers`|TAP → сетка/границы/`w:jc`/vAlign/`w:tcMar` (§2.6.3; битый TDefTable → плоские абзацы) + секции (PlcfSed §2.8.26: continuous/landscape/колонтитуки/колонки/titlePage) + Plcfhdd → `headerN.xml`/`footerN.xml`|
|`SummaryInfo`, `OfficeArt`|кэш PageCount [MS-OLEPS] (offset'ы относительны начала PropertySet) + BLIP → PNG/JPEG/DIB, EMF/WMF/PICT → пропуск + warn|
|`DocToDocx`, `DocxWriter`|оркестратор + `DocxBody` (раны/pPr/табличный автомат 0x07/TTP → docx-XML) + мульти-частный zip (document/numbering/hdr/ftr/media)|
|`DocToDocx`|оркестратор + `DocxBody` (раны/pPr/табличный автомат 0x07/TTP → docx-XML); мульти-частный zip (document/numbering/hdr/ftr/media) — через `internal/DocxPackageWriter`|
Перечень остатков моста — `docs/agent/doc-bridge.md`.
### Мост `.xlsx` → `.docx` (`internal/xlsx`)
Нормативный источник — ECMA-376 Part 1 (SpreadsheetML: §18 книга/стили/печать, §21 рисунки/диаграммы, §3 OPC) в `docs/standards/ooxml/`, ссылки — с номерами секций. Новых runtime-зависимостей нет (StAX + `java.util.zip`; POI — test-scope, генератор фикстур). Публичные точки: `XlsxToDocx.convert(byte[], ConvertOptions)` (вызывает `WordPdfConverter`), всё остальное — package-private `internal/xlsx`. 16 классов:
|Класс|Семантика (полные раскладки и калибровки — `docs/agent/xlsx-bridge.md`)|
|---|---|
|`XlsxPackage`, `WorkbookModel`, `SharedStrings`|zip книги в памяти: части, `_rels` любого part'а с резолвом `../`; листы (`name/state/partPath`, hidden/veryHidden не рендерятся), `date1904`; sst с rich-ранами (`rPr` → `RunStyle`)|
|`ThemeModel`, `StylesModel`, `ColorSpec`, `ColorResolver`|clrScheme/шрифты темы + перенос `theme1.xml` в `word/theme/`; numFmts/fonts/fills/borders/cellXfs с base-цепочкой `cellStyleXfs`; цвет: rgb/theme+tint+shade (лог-модуляция светлоты)/indexed+palette → sRGB|
|`NumberFormats`, `NumberText`|формат-коды: секции, `0 # ?`, тысячныe/процентные масштабы, даты/время (эпоха 1900/1904), научный, литералы; `[…]` (условия/цвета/локали) — вырезание (деградация); битый код → `General`+warn|
|`Metrics`|MDW по бандл-метрике (`GlyphFont`), chars↔px↔twips (ECMA-376 §18.3.1.8), pt/inches→twips, px→EMU|
|`SheetModel`, `PrintLayout`, `SheetToTable`|лист: ячейки (кэш значений формул, inlineStr), cols/hidden, merges, гиперссылки, print area/breaks, `drawing r:id`, `olePresent`; страница печати (paper/landscape/поля, срезы полос по разрывам+высоте/ширине, fitToPage = геометрическое сжатие ширины колонок) + `sectPr(Page)`; срез → фикс-таблица `w:tbl` (сетка, gridSpan/vMerge, trHeight, jc по Excel-горизонтали, раны sst поверх стиля, числа через `NumberFormats`, гиперссылки)|
|`DrawingBridge`, `WarnOnce`, `XlsxToDocx`|якоря xdr (two/one/absoluteCell, EMU-кумулятив через `Metrics`, hidden=0, clamp) → `wp:inline` в from-ячейку; `xdr:pic` → `word/media/xlsx-imageN`; `c:chart` → `word/charts/xlsx-chartN.xml` — дорисовывает штатный шаг 3.5 (ловит `errorOnCharts`); SmartArt/фигуры — пропуск+warn (`errorOnSmartArt` на .xlsx не срабатывает); OLE → warn/422 по флагу; оркестратор: секция docx на каждый срез, финальный body-`sectPr`, части через `DocxPackageWriter`|
Перечень деградаций — `docs/agent/xlsx-bridge.md`.
### Нормализаторы (`internal/DocxNormalizer`)
Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame` в тестах). Порядок фиксирован: Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby; правила 1–10 применяет `DocxRewritePipeline.STEP` одним zip-проходом (механика zip-прохода — `docs/agent/pipeline.md`), `OleObjectNormalizer` подключается лямбдой в `WordPdfConverter.normalizers()`.
@@ -68,7 +83,7 @@
### REST API (`wordpdf-app`, всё package-private кроме `WordPdfApplication`)
Единственный эндпоинт `POST /api/v1/convert`: multipart-поле `file` + факультативные query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолты — `WordPdfSettings.ERROR_ON_*`). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Имя файла — `ConversionService.safeBaseName`; расширение `.docx`/`.doc` проверяет `ConvertController` (текст ошибки 400 — контракт с фронтом). Error-флаги диаграмм/SmartArt/OLE на `.doc` **не срабатывают** (BLIP-плейсхолдеры → картинки) — описано в `@Operation`. Полный текст — `docs/agent/repo-map.md`.
Единственный эндпоинт `POST /api/v1/convert`: multipart-поле `file` + факультативные query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолты — `WordPdfSettings.ERROR_ON_*`). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Имя файла — `ConversionService.safeBaseName`; расширение `.docx`/`.doc`/`.xlsx` проверяет `ConvertController` (текст ошибки 400 — контракт с фронтом). Error-флаги диаграмм/SmartArt/OLE на `.doc` **не срабатывают** (BLIP-плейсхолдеры → картинки); на `.xlsx` `errorOnSmartArt` не срабатывает (SmartArt отбрасывается мостом), `errorOnCharts`/`errorOnOle` работают — описано в `@Operation`. Полный текст — `docs/agent/repo-map.md`.
| Ситуация | HTTP | Класс |
|---|---|---|
@@ -85,7 +100,7 @@
- **Ключ доступа**: `X-API-Key` ↔ `wordpdf.api-key` (пустое = выключено); без ключа открыты только `OPEN_PREFIXES`, пути с точечными сегментами — никогда. Механика `ApiKeyFilter` — `docs/agent/repo-map.md`.
- **Очередь и лимиты**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (переполнение → 503) — ядро мутирует глобальный `PhysicalFonts` и **не потокобезопасно**; лимиты входа — только конфигурация сервера (`wordpdf.max-mb`/`max-pages`, SpEL-дефолты из `WordPdfSettings`; ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются, в `application.properties` не объявлены). Подробности — `docs/agent/repo-map.md`.
- **SPA**: вся сеть в `wordpdf-web/src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), экран `ApiKeyGate` показывается только когда `probeApiKey()` подтвердил требование ключа; base — `VITE_BASE` (дефолт `/`, CORS не нужен); три error-флага (дефолт — выключены), DropZone `.docx,.doc`. Полный текст — `docs/agent/repo-map.md`.
- **SPA**: вся сеть в `wordpdf-web/src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), экран `ApiKeyGate` показывается только когда `probeApiKey()` подтвердил требование ключа; base — `VITE_BASE` (дефолт `/`, CORS не нужен); три error-флага (дефолт — выключены), DropZone `.docx,.doc,.xlsx`. Полный текст — `docs/agent/repo-map.md`.
### Chart/SmartArt-движок (`internal/chart`)
@@ -117,9 +132,9 @@ chart-PNG вставляются media-частями вручную (`DrawingPr
| Путь | Назначение |
|---|---|
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | публичный API; `fonts/` (бандл+глиф-движок), `internal/` (нормализаторы, пайплайн), `internal/doc/` (мост), `internal/chart/` (диаграммы) |
|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API; `fonts/` (бандл+глиф-движок), `internal/` (нормализаторы, пайплайн), `internal/doc/` (мост .doc), `internal/xlsx/` (мост .xlsx), `internal/chart/` (диаграммы)|
| `wordpdf-core/src/main/resources/` | `fonts/` (30 TTF), `xslt/docx2fo.xslt` (вендорный стилист), `slf4j-simple.properties` |
| `wordpdf-core/src/test/resources/` | `samples/` (25 закоммиченных фикстур: 13 `.docx` + 12 `.doc`), `geom/` (`presetShapeDefinitions.xml`, тесты) |
|`wordpdf-core/src/test/resources/`|`samples/` (32 закоммиченных фикстур: 13 `.docx` + 12 `.doc` + 7 `.xlsx`), `geom/` (`presetShapeDefinitions.xml`, тесты)|
| `wordpdf-app/` | REST API (10 классов, public только `WordPdfApplication`) |
| `wordpdf-web/` | SPA: `src/api.ts` (вся сеть) + компоненты |
| корневые `Containerfile`, `compose.yml`, `compose.dev.yml`, `gateway/nginx.conf` | контейнеры; единственный вход — gateway (`:9010`/`:9011`) |
@@ -185,9 +200,9 @@ python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources
## Testing & QA
- Гейты: PMD `maven-pmd-plugin` 3.28.0 (`includeTests=true`) и JaCoCo `0.8.15` (`jacoco:check` на `verify`) — пороги LINE `0.90` (оба модуля), BRANCH `0.85` (core); отчёт `report` раньше `check` (при провале порога отчёт уже на диске). Механика `argLine`/`prepare-agent`/`jacoco.skip` — `docs/agent/repo-map.md`. Плотность покрытия держат тесты, а не заглушки.
- Счётчики: 57 тестовых класса / 886 теста (core 51/843, app 6/43; разбивка — `docs/agent/repo-map.md`). JUnit 6, только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты.
- Счётчики: 75 тестовых класса / 1095 тестов (core 69/1051, app 6/44; разбивка — `docs/agent/repo-map.md`). JUnit 6, только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты.
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` (пер-странично), `processTextPosition` для шрифта символа, обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`), счётчик картинок (`imageCount`/`distinctImageCount` — SMask игнорируется). Негативные маркеры: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`).
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары `XxxNormalizerTest`↔`тест-в-конвейере` воспроизводятся грепом по этим ссылкам; исключения (крафт POIFS, синтетика, app-регрессии) — `docs/agent/testing.md`.
- Фикстуры — только закоммиченные `samples/*.docx` + `samples/*.doc`, в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (`assertSame`) + неприкосновенность частей вне `word/*.xml`.
- Фикстуры — только закоммиченные `samples/*.docx` + `samples/*.doc` + `samples/*.xlsx`, в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (`assertSame`) + неприкосновенность частей вне `word/*.xml`.
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc`; четыре набора свойств = четыре кэшированных контекста (отдельные классы, не `@Nested`); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring-контекста.
- Справочник: фикстуры и их смысл, юниты моста/нормализаторов/app, пиксели и стенд без fontconfig, регрессивные записи без javadoc-ссылок — `docs/agent/testing.md`.