Замена wordpdf-cli на Spring Boot REST API: wordpdf-app, SPA wordpdf-web, docker-compose
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
## Project Overview
|
||||
|
||||
Конвертер `.docx` → `.pdf` на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 17, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-cli` (fat-jar через maven-shade). Единственный гейт перед `git push` — `mvn clean verify` (CI/lint в репозитории нет).
|
||||
Конвертер `.docx` → `.pdf` на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 21, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-app` (Spring Boot REST API); плюс `wordpdf-web` — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед `git push` — `mvn clean verify` (CI/lint в репозитории нет; SPA гейтуется `npm run build`).
|
||||
|
||||
## Architecture & Data Flow
|
||||
|
||||
@@ -21,16 +21,21 @@
|
||||
→ `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`.
|
||||
5. `finally`: `deleteEmbeddedFontTempFiles()` (в 17.x `OpcPackage.close()` нет).
|
||||
|
||||
### REST API (`wordpdf-app`)
|
||||
|
||||
- Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (очередь 16, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` (шаг 1 пайплайна), параллельные конвертации вырывают его друг у друга из-под рендера.
|
||||
- Разделение ошибок: валидация байтов до очереди (`WordPdfValidator.checkInput(byte[])` + проверка zip-подписи + `checkPageCountLightweight(byte[])`) → `ValidationException` → 400; ошибки ядра/рендера → `ConversionFailedException` → 500; очередь занята → 503; таймаут (`wordpdf.convert-timeout`, 2m) → 504. Граница: сломанный контейнер → 400, валидный zip с мусором внутри → 500.
|
||||
- Фронт ходит только на относительный `/api/...` — CORS не нужен (dev: vite-proxy → :8080; prod: nginx).
|
||||
|
||||
### Критические инварианты (нарушение = битый вывод)
|
||||
|
||||
- **`docx4j.convert.out.fo.gsubFeatures=false`** — ставится в статическом блоке `WordPdfConverter`. Иначе docx4j навешивает `fox:gsub-features` без объявления префикса → FO невалиден → `WordLayoutFixups` молча отказывается от всех фиксов → FOP падает на `docx4j-baseline`. Без фиксов нет колонок и колонок таблиц.
|
||||
- **`ServicesResourceTransformer` в maven-shade (`wordpdf-cli`) обязателен**: `META-INF/services/org.apache.fop.fo.ElementMapping` дублируется в `docx4j-fo-renderer-core` и `docx4j-export-fo`; без слияния FOP падает на `UnknownXMLObj cannot be cast to Root`. В fat-jar из тестов не видно — проверять `java -jar`.
|
||||
- **Не убирать shade-фильтры `META-INF/*.SF|*.DSA|*.RSA`** — подписанные jar ломают fat-jar.
|
||||
- **`slf4j-simple` обязателен**: без него docx4j пишет «TO HIDE THESE MESSAGES» прямо в выходной PDF (регрессия `noLoggingWarningInPdf`).
|
||||
- **`slf4j-simple` обязателен** в ядре: без него docx4j пишет «TO HIDE THESE MESSAGES» прямо в выходной PDF (регрессия `noLoggingWarningInPdf`). Приложение (`wordpdf-app`) исключает `slf4j-simple` из зависимости ядра — логи ведёт logback из Boot; предупреждение в PDF возникает только при полном отсутствии SLF4J-провайдера, `slf4j-simple.properties` из core остаётся инертным ресурсом.
|
||||
- **JAXB-обход обязан раскрывать `JAXBElement`** (иначе таблицы/раны молча пропускаются — оценка «1» вместо 121). Рекурсия через `ContentAccessor` из `org.docx4j.wml` (НЕ `org.docx4j.contentcontrol` — в 17.x его нет). Тип секции — `SectPr$Type.getVal()`; маркер — `R.LastRenderedPageBreak` (`CTLastRenderedPageBreak` в 17.x отсутствует).
|
||||
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.2 (пакеты `org.apache.fop.*`), умеет хинты `docx4j:baseline`/`docx4j:line-box`. `Fop.Renderers.getRenderer()` возвращает **список** — `FopFallbackFonts.rendererFonts` ищет `application/pdf`.
|
||||
- `docx2fo.xslt` в репозитория нет — он в jar `docx4j-export-fo`. `WordLayoutFixups` (включён по умолчанию в 17.x) постобработкой DOM FO даёт реальные колонки `w:cols/@w:num` и колонки таблиц; побочный эффект — авто-ширины колонок без `tblGrid`/`tcW` стали уже (слово может перенестись в ячейке).
|
||||
- Известный остаток эталона: U+2188 (ↈ) и U+218A (↊) — глифов нет ни в одном OFL-шрифте бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
|
||||
- **nginx `client_max_body_size 6m`** (`wordpdf-web/nginx.conf`) обязателен: без него upload > 1 МБ режется HTML-413 от nginx до бэкенда вместо JSON-ошибки API.
|
||||
|
||||
### Шрифты (30 TTF в `wordpdf-core/src/main/resources/fonts/`, SIL OFL)
|
||||
|
||||
@@ -56,7 +61,10 @@
|
||||
| `…/wordpdf/internal/chart/` | Java2D-рендер диаграмм/SmartArt в PNG |
|
||||
| `wordpdf-core/src/main/resources/fonts/` | 30 TTF + лицензии — бинарные фикстуры, часть jar |
|
||||
| `wordpdf-core/src/test/resources/samples/` | 11 закоммиченных `.docx`-фикстур (единственные фикстуры) |
|
||||
| `wordpdf-cli/src/main/java/…/cli/` | `WordPdfCli` (fat-jar) |
|
||||
| `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/` | REST API: `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler` |
|
||||
| `wordpdf-web/src/` | SPA (React+TS+Vite+Tailwind): компоненты в `components/`, вся сеть в `api.ts` |
|
||||
| корневые `Dockerfile`, `docker-compose.yml` | образ бэкенда (multi-stage, temurin-21); compose web+app |
|
||||
| `wordpdf-web/Dockerfile`, `wordpdf-web/nginx.conf` | образ SPA (node→nginx); прокси `/api`, `/swagger-ui`, `/v3/api-docs` |
|
||||
| `references/` | эталон Word 365 (`word.docx` + `word.pdf`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать |
|
||||
| `diff/`, корневые `word-export.*` | gitignored артефакты ручной калибровки |
|
||||
|
||||
@@ -64,14 +72,14 @@
|
||||
|
||||
```bash
|
||||
mvn clean verify # все модули + тесты — обязательный гейт перед push
|
||||
mvn -pl wordpdf-cli package # fat-jar (из корня); из каталога cli — только с -am
|
||||
java -jar wordpdf-cli/target/wordpdf-cli-1.0.0.jar in.docx [out.pdf]
|
||||
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
|
||||
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, POST /api/v1/convert
|
||||
npm run dev # (wordpdf-web/) SPA :5173, proxy /api → :8080
|
||||
docker compose up -d --build # всё вместе: SPA+nginx публикует :8080, app не публикуется
|
||||
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест
|
||||
```
|
||||
|
||||
CLI: 1 аргумент → PDF рядом с исходником; 2-й `.pdf` → явный выход; **два `.docx` = пакетная конвертация**. Коды возврата: 0 успех, 1 ошибка использования, 2 не сконвертирован хотя бы один файл.
|
||||
|
||||
`dependency-reduced-pom.xml` — артефакт shade, не коммитить.
|
||||
Compose: `web` проксирует `/api`, `/swagger-ui`, `/v3/api-docs` на `app` (DNS-имя в сети compose); бэкенд наружу не публикуется. `wordpdf.convert-timeout` переопределяется env `WORDPDF_CONVERT_TIMEOUT` (relaxed binding Boot).
|
||||
|
||||
Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` НЕ генерируется — исключение):
|
||||
|
||||
@@ -83,35 +91,35 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
|
||||
|
||||
## Code Conventions & Common Patterns
|
||||
|
||||
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе docx4j: `BundledFontMapper` (наследник `BestMatchingMapper`), `DrawMlColor` (палитра темы).
|
||||
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе: docx4j-классы `BundledFontMapper` (наследник `BestMatchingMapper`), `DrawMlColor` (палитра темы) и Spring-компоненты `wordpdf-app`.
|
||||
- Нормализаторы — единая сигнатура `public static byte[] normalize(byte[] docx) throws IOException` с флагом `changed`: нечего менять → вернуть **тот же массив** (`assertSame` в тестах); package-private хук `static String rewrite(String xml)` для юнит-тестов.
|
||||
- Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние `IOException`/`IllegalStateException` оборачиваются на границе. В chart — деградация вместо падения: неизвестный пресет → прямоугольник + лог.
|
||||
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же.
|
||||
- Константы UPPER_SNAKE с числовыми эталонными значениями (`CAMERA_DISTANCE`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/...`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`.
|
||||
- Внутренние API package-private; наружу из `internal` торчат только `normalize`/`declare`/`DrawingPreRenderer.run`.
|
||||
- `WordPdfCli.main` тонко обёртывает `public static int run(String[])` — CLI тестируется без `System.exit`.
|
||||
- В `wordpdf-app` всё package-private (контроллер, advice, service, исключения); в SPA вся сетевая логика только в `src/api.ts` — компоненты `fetch` не вызывают.
|
||||
|
||||
## Important Files
|
||||
|
||||
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures`.
|
||||
- `wordpdf-cli/pom.xml` — shade: Main-Class, `ServicesResourceTransformer`, фильтры подписей.
|
||||
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.0`, slf4j `2.0.17`, JUnit `5.12.2`, PDFBox `3.0.7` (test), POI `5.5.1` (test, только генератор фикстур); форки FOP/jeuclid приходят транзитивно с `docx4j-export-fo`, пинить не надо.
|
||||
- `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён из зависимости ядра.
|
||||
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox `3.0.8` (test), POI `5.5.1` (test, только генератор фикстур), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; форки FOP/jeuclid приходят транзитивно с `docx4j-export-fo`, пинить не надо.
|
||||
- `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF.
|
||||
- `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур (команда в javadoc).
|
||||
|
||||
## Runtime & Tooling Preferences
|
||||
|
||||
- Java 17 + Maven (обязательны; wrapper `mvnw` нет). UTF-8.
|
||||
- Java 21 + Maven (обязательны; wrapper `mvnw` нет). UTF-8. Фронт: Node.js ≥ 20.19 (Vite 7+), вне Maven-депа.
|
||||
- Только Maven (никакого Gradle/Ant); новые зависимости — latest stable, версии только в корневой `dependencyManagement`.
|
||||
- CI, линтеров, форматтеров, checkstyle — нет; проверка одна: `mvn clean verify`.
|
||||
- Fat-jar проверять только `java -jar` (тесты идут по classpath и shade-проблем не видят).
|
||||
- Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят).
|
||||
|
||||
## Testing & QA
|
||||
|
||||
- JUnit 5, surefire c `-Djava.awt.headless=true`; только `Assertions` (без Mockito/AssertJ), package-private тесты в mirror-пакетах.
|
||||
- JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire c `-Djava.awt.headless=true`; только `Assertions` (без Mockito/AssertJ, несмотря на test-классpath Boot), package-private тесты в mirror-пакетах.
|
||||
- **PDF сравнивается текстом, не растеризацией**: PDFBox `PDFTextStripper` для текста, override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страницы для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок. Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Пиксели — только в unit-тестах chart-пейнтеров (там сам код — Java2D); допуски 6–10%.
|
||||
- Текст нормализуется по пробелам (`tableImage_tableAndImage` — полное удаление пробелов: docx4j переносит слова в auto-fit таблицах).
|
||||
- Фикстуры — закоммиченные `samples/*.docx` (не генерировать в тестах); classpath → временный файл (`extractSample`/`extractToTemp`). In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]` (`WordPdfValidatorTest`).
|
||||
- Юниты нормализаторов работают строками (`rewrite`) и проверяют контракт «нечего менять → null / тот же массив» и неприкосновенность `[Content_Types].xml`.
|
||||
- Тесты `wordpdf-cli` берут фикстуры из test-jar core (classifier `tests`) → `-pl wordpdf-cli` без `-am` не соберётся; проверять коды возврата `WordPdfCli.run`.
|
||||
- Тесты `wordpdf-app` (`ConvertControllerTest`, MockMvc) берут фикстуры из test-jar core (classifier `tests`) → `-pl wordpdf-app` без `-am` не соберётся. Гейт SPA — `npm run build` (tsc -b); UI-тестов нет.
|
||||
- Каждый фикс бага docx4j/FOP сопровождается: байтовый нормализатор/pre-renderer + регрессионный тест с фикстурой + javadoc-ссылка. Проверенные пары: `DocxOnOffNormalizerTest`/`ruPlain_regularRunsUseRegularFont`, `FieldNormalizerTest`/`pageNumbers_recomputedNotCached`, `SymbolFontNormalizerTest`/`symbolFonts_bulletsAreNotHash`, `GlyphCoverageNormalizerTest`/`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`/`staleCachePageCountRejectedBeforeRender`, `BundledFontsTest`/`noLoggingWarningInPdf`, `Surface3dPainterTest`/`chartsSmartArt_drawingsBecomeImages`.
|
||||
|
||||
Reference in New Issue
Block a user