Слияние docx4j 17.3.5 в wordpdf-core и форк FO-рендерера 2.11-docx4j.8 в реактор
PR checks / web (pull_request) Successful in 38s
PR checks / java (pull_request) Successful in 18m31s

- wordpdf-core/src/main/java впитаны исходники docx4j-core, -export-fo,
  -chart-render, -JAXB-ReferenceImpl, -copy, -generated-objects (17.3.5) +
  сгенерированная XJC JAXB-модель; ресурсы — тем же путём; артефакты группы
  org.docx4j из внешних репозиториев больше не подключаются
- vendor/fop: форк docx4j-fo-renderer 2.11-docx4j.8 (util/events/core/fop)
  собирается в реакторе вместо jar из Nexus
- docx2fo.xslt перевендорен со стилем 17.3.5, оба AUDIT-FIX-патча перенесены;
  дрейф-гейт vendoredXsltTracksJarCopy зелёный
- upstream-тесты docx4j перенесены в src/test/java/org (658 классов, вне гейта);
  execution upstream-docx4j-tests в профиле upstream-tests (./mise.sh run
  upstream-tests, в pr.yml non-blocking шаг): 3470 тестов, 3457 зелёных,
  13 красных — категории окружения/калибровки хоста и следствий слияния
  classpath задокументированы в docs/agent/testing.md
- surefire: провайдер SLF4J фиксируется коротким slf4j.provider по execution;
  перенесён upstream logback.xml (root=DEBUG без конфига ломает visitor-экспорт
  VML); upstream-форки пинят JDK JAXP-фабрики; PMD/JaCoCo исключают org/**
- wordpdf-app: без изменений кода (зависит от слитого ядра); тесты 44/44
- документация синхронизирована (AGENTS.md, README, docs/agent/*), mise task
  upstream-tests
This commit is contained in:
Pjandro
2026-11-08 02:54:49 +00:00
parent f41ac54072
commit 8529b6877b
10191 changed files with 1694473 additions and 75 deletions
+20 -6
View File
@@ -1,7 +1,9 @@
# java-word-pdf
Конвертация **.docx/.doc → PDF** на чистом Java: `docx4j` 17.3.2 + форк
`Apache FOP`, без LibreOffice/Aspose. Бинарный `.doc` (Word 97–2003) читается
Конвертация **.docx/.doc → PDF** на чистом Java: `docx4j` 17.3.5 (исходники
библиотеки слиты в `wordpdf-core`, отдельная зависимость от Maven Central не
нужна) + форк `Apache FOP` (собирается из исходников в `vendor/fop`), без
LibreOffice/Aspose. Бинарный `.doc` (Word 97–2003) читается
собственным мостом [MS-DOC]/[MS-CFB] и переносится в .docx в памяти — дальше
идёт тем же конвейером. Шрифты упакованы в jar — конвертация не зависит от
шрифтов, установленных в системе (работает «из коробки» на голом сервере).
@@ -27,6 +29,8 @@
```
java-word-pdf/
├── wordpdf-core/ библиотека: конвертер, мост .doc, шрифты, диаграммы
│ + слитый docx4j 17.3.5 (пакеты org.docx4j.*, org.pptx4j.*, org.xlsx4j.*)
├── vendor/fop/ форк FO-рендерера (docx4j-fo-renderer, Apache FOP 2.11 + патчи docx4j)
├── wordpdf-app/ REST API: POST /api/v1/convert (Spring Boot 4.1.1, Swagger UI)
└── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)
```
@@ -76,6 +80,7 @@ powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
|Задача|Содержание|
|---|---|
|`verify`|`mvn clean verify` — тесты + PMD + JaCoCo|
|`upstream-tests`|перенесённые upstream-тесты docx4j (`-Pupstream-tests`), не в гейте; десятки минут|
|`app-package`|исполняемый jar бэкенда|
|`app-run`|бэкенд на :8080, ключ выключен (после `app-package`)|
|`web-install`|`npm ci` в `wordpdf-web`|
@@ -95,10 +100,14 @@ powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
`./mise.sh exec -- …` (Windows: `.\mise.ps1 exec -- …`) либо после активации mise в шелле.
```bash
mvn clean verify # все модули + тесты
mvn clean verify # все модули + тесты (vendor/fop собирается в реакторе)
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
```
Первый `mvn` скачивает зависимости и собирает форк FOP; JAI (`javax.media:jai-core:1.1.3`,
только для компиляции форка) — бинарь в `vendor/fop/lib/`, устанавливается в локальный
Maven-репозиторий автоматически.
Результат: `wordpdf-app/target/wordpdf-app-<версия>.jar` (все зависимости
внутри). Для фронтенда — отдельные команды (вне Maven): `npm ci && npm run build`
в `wordpdf-web/` — по закоммиченному `package-lock.json` (то же делают задачи
@@ -307,10 +316,11 @@ Dev-режим без контейнеров: бэкенд `java -jar wordpdf-ap
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi
(`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
5. Экспорт в XSL-FO идёт вендорным стилем `xslt/docx2fo.xslt` (копия стилиста
docx4j-export-fo с AUDIT-FIX-патчами: `w:position` → `baseline-shift`,
docx4j-export-fo — база `org/docx4j/convert/out/fo/docx2fo.xslt` слитого
docx4j — с AUDIT-FIX-патчами: `w:position` → `baseline-shift`,
`w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir`), перед рендером `LayoutPostRenderer`
компенсирует расхождение docx4j↔Word по padding таблиц; `Apache FOP`
(форк `docx4j-fo-renderer`) рендерит PDF, встраивая подмножества шрифтов.
(форк `docx4j-fo-renderer`, `vendor/fop`) рендерит PDF, встраивая подмножества шрифтов.
## Ограничения
@@ -342,9 +352,13 @@ test-утилита `SampleDocxGenerator`) и проверяют извлечё
API (`wordpdf-app`) проверяется `MockMvc`-сквозняками (`ConvertControllerTest`)
на тех же фикстурах — ядро отдаёт их test-jar'ом.
В ядро перенесён upstream-набор тестов docx4j (658 классов, `src/test/java/org`) —
он не входит в гейт `verify` и прогоняется отдельно: `./mise.sh run upstream-tests`
(в CI — non-blocking шаг-отчёт в `pr.yml`).
## CI/CD и деплой
- Pull request → Gitea Actions (`pr.yml`): Java — `mvn clean verify` + сводка покрытия комментарием в PR; Web — `npm ci`, build, lint.
- Pull request → Gitea Actions (`pr.yml`): Java — `mvn clean verify` + non-blocking отчёт по upstream-набору docx4j + сводка покрытия комментарием в PR; Web — `npm ci`, build, lint.
- Push в `main` → `main.yml`: тесты → сборка и push образов `wordpdf-app`/`wordpdf-web` в реестр → deploy (job рендерит прод-конфиги, `podman-compose pull && up -d --force-recreate`, health-гейты, автооткат при провале) → prod-автотесты против живого стенда.
- Координаты прод-сервера и креды вне репозитория — Gitea Actions Variables/Secrets (настройка: `GITEA-vars.md`). Наружный вход стенда — путь `/pdf-converter/` за пользовательским nginx.
- Локальный прогон prod-автотестов (задача `prod-tests`: `pip install`