Compare commits
35 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| b558fe1c30 | |||
| 187938c4db | |||
| 0e9266450c | |||
| b3511f8b74 | |||
| ae7c8b755a | |||
| fca253b9f5 | |||
| e308db47da | |||
| f3ff218686 | |||
| 202e4ca97e | |||
| fa45b7a8be | |||
| 1c8f6e1516 | |||
| 9d4661be3f | |||
| 67f8636b0c | |||
| 08c68305be | |||
| f7304094ec | |||
| e6a8b86583 | |||
| d44eac683a | |||
| aaad5d2bb0 | |||
| 334e6a9006 | |||
| 72cc717056 | |||
| 0b2dda8caa | |||
| d8eda0a2e4 | |||
| e9abcd38c8 | |||
| 5631c9e0c0 | |||
| 13ca7425a3 | |||
| af5d09e001 | |||
| 8a8e8a9f84 | |||
| 41b4f89e74 | |||
| 8b16d64059 | |||
| 638e28c653 | |||
| d8353aab61 | |||
| 8d2fa3dad9 | |||
| 2116ec43a4 | |||
| bc98a12421 | |||
| 8061a2fbe7 |
+32
-23
@@ -20,28 +20,29 @@ jobs:
|
|||||||
exit 1
|
exit 1
|
||||||
}
|
}
|
||||||
|
|
||||||
- name: Setup JDK 17
|
- name: Build and test without fontconfig (PMD+JaCoCo included)
|
||||||
uses: actions/setup-java@v5
|
|
||||||
with:
|
|
||||||
java-version: '17'
|
|
||||||
distribution: 'temurin'
|
|
||||||
|
|
||||||
- name: Cache Maven repository
|
|
||||||
uses: actions/cache@v4
|
|
||||||
with:
|
|
||||||
path: ~/.m2/repository
|
|
||||||
key: maven-${{ hashFiles('pom.xml', 'wordpdf-core/pom.xml', 'wordpdf-app/pom.xml') }}
|
|
||||||
restore-keys: maven-
|
|
||||||
|
|
||||||
- name: Setup Maven 3.9.16
|
|
||||||
run: |
|
|
||||||
curl -fsSL https://dlcdn.apache.org/maven/maven-3/3.9.16/binaries/apache-maven-3.9.16-bin.tar.gz | tar xz -C /opt
|
|
||||||
echo "/opt/apache-maven-3.9.16/bin" >> "$GITHUB_PATH"
|
|
||||||
|
|
||||||
- name: Build and test (PMD gate included)
|
|
||||||
env:
|
env:
|
||||||
MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
|
MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
|
||||||
run: mvn -B -s .ci/maven-settings.xml clean verify
|
run: |
|
||||||
|
DOCKER_BUILDKIT=0 docker build \
|
||||||
|
-f Containerfile.test \
|
||||||
|
--build-arg MAVEN_MIRROR_URL="$MAVEN_MIRROR_URL" \
|
||||||
|
-t wordpdf-verify:ci \
|
||||||
|
.
|
||||||
|
|
||||||
|
- name: Extract JaCoCo reports
|
||||||
|
if: always()
|
||||||
|
run: |
|
||||||
|
id=$(docker create wordpdf-verify:ci 2>/dev/null) || {
|
||||||
|
echo "образ не собран — сводка покрытия будет пустой"
|
||||||
|
exit 0
|
||||||
|
}
|
||||||
|
mkdir -p wordpdf-core/target/site/jacoco wordpdf-app/target/site/jacoco
|
||||||
|
docker cp "$id:/build/wordpdf-core/target/site/jacoco/jacoco.xml" \
|
||||||
|
wordpdf-core/target/site/jacoco/jacoco.xml || true
|
||||||
|
docker cp "$id:/build/wordpdf-app/target/site/jacoco/jacoco.xml" \
|
||||||
|
wordpdf-app/target/site/jacoco/jacoco.xml || true
|
||||||
|
docker rm "$id" >/dev/null
|
||||||
|
|
||||||
- name: Coverage summary
|
- name: Coverage summary
|
||||||
if: always()
|
if: always()
|
||||||
@@ -262,9 +263,9 @@ jobs:
|
|||||||
# не крушит стек бесконечным crash-loop. Синтаксис on-failure:N podman
|
# не крушит стек бесконечным crash-loop. Синтаксис on-failure:N podman
|
||||||
# переваривает и применяет (проверено: maxtries=N, после исчерпания exited).
|
# переваривает и применяет (проверено: maxtries=N, после исчерпания exited).
|
||||||
restart: on-failure:5
|
restart: on-failure:5
|
||||||
# heap вписан в лимит (-XX:MaxRAMPercentage=70 в ENTRYPOINT образа);
|
# фиксированный heap -Xms2g -Xmx2g в ENTRYPOINT образа, лимит 3g —
|
||||||
# паритет с repo compose.yml
|
# запас под metaspace/потоки/native; паритет с repo compose.yml
|
||||||
mem_limit: 2g
|
mem_limit: 3g
|
||||||
# healthcheck дублируется в compose, а не только в Containerfile: podman
|
# healthcheck дублируется в compose, а не только в Containerfile: podman
|
||||||
# выгружает образы в OCI, где HEALTHCHECK теряется, а gateway в depends_on
|
# выгружает образы в OCI, где HEALTHCHECK теряется, а gateway в depends_on
|
||||||
# ждал бы healthy вечно. wget, не curl: alpine-jre образ curl не содержит.
|
# ждал бы healthy вечно. wget, не curl: alpine-jre образ curl не содержит.
|
||||||
@@ -329,6 +330,14 @@ jobs:
|
|||||||
resolver 10.112.0.1 valid=10s ipv6=off;
|
resolver 10.112.0.1 valid=10s ipv6=off;
|
||||||
set \$upstream_app http://app:8080;
|
set \$upstream_app http://app:8080;
|
||||||
set \$upstream_web http://web:80;
|
set \$upstream_web http://web:80;
|
||||||
|
# X-Forwarded-* переписываются безусловно: клиент не должен иметь
|
||||||
|
# возможности подсунуть бэкенду подставной "реальный IP/схема/хост"
|
||||||
|
# (Spring ForwardedHeaderFilter доверяет этим заголовкам).
|
||||||
|
# X-Forwarded-Prefix не трогаем: его проставляет внешний nginx,
|
||||||
|
# на нём держится корректный base у swagger-ui за прокси.
|
||||||
|
proxy_set_header X-Forwarded-For \$remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-Proto \$scheme;
|
||||||
|
proxy_set_header X-Forwarded-Host \$host;
|
||||||
location /api/ {
|
location /api/ {
|
||||||
# в proxy_pass нет path-части, поэтому URI передаётся как есть
|
# в proxy_pass нет path-части, поэтому URI передаётся как есть
|
||||||
proxy_pass \$upstream_app;
|
proxy_pass \$upstream_app;
|
||||||
|
|||||||
+46
-20
@@ -19,28 +19,29 @@ jobs:
|
|||||||
exit 1
|
exit 1
|
||||||
}
|
}
|
||||||
|
|
||||||
- name: Setup JDK 17
|
- name: Build and test without fontconfig (PMD+JaCoCo included)
|
||||||
uses: actions/setup-java@v5
|
|
||||||
with:
|
|
||||||
java-version: '17'
|
|
||||||
distribution: 'temurin'
|
|
||||||
|
|
||||||
- name: Cache Maven repository
|
|
||||||
uses: actions/cache@v4
|
|
||||||
with:
|
|
||||||
path: ~/.m2/repository
|
|
||||||
key: maven-${{ hashFiles('pom.xml', 'wordpdf-core/pom.xml', 'wordpdf-app/pom.xml') }}
|
|
||||||
restore-keys: maven-
|
|
||||||
|
|
||||||
- name: Setup Maven 3.9.16
|
|
||||||
run: |
|
|
||||||
curl -fsSL https://dlcdn.apache.org/maven/maven-3/3.9.16/binaries/apache-maven-3.9.16-bin.tar.gz | tar xz -C /opt
|
|
||||||
echo "/opt/apache-maven-3.9.16/bin" >> "$GITHUB_PATH"
|
|
||||||
|
|
||||||
- name: Build and test (PMD gate included)
|
|
||||||
env:
|
env:
|
||||||
MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
|
MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
|
||||||
run: mvn -B -s .ci/maven-settings.xml clean verify
|
run: |
|
||||||
|
DOCKER_BUILDKIT=0 docker build \
|
||||||
|
-f Containerfile.test \
|
||||||
|
--build-arg MAVEN_MIRROR_URL="$MAVEN_MIRROR_URL" \
|
||||||
|
-t wordpdf-verify:ci \
|
||||||
|
.
|
||||||
|
|
||||||
|
- name: Extract JaCoCo reports
|
||||||
|
if: always()
|
||||||
|
run: |
|
||||||
|
id=$(docker create wordpdf-verify:ci 2>/dev/null) || {
|
||||||
|
echo "образ не собран — сводка покрытия будет пустой"
|
||||||
|
exit 0
|
||||||
|
}
|
||||||
|
mkdir -p wordpdf-core/target/site/jacoco wordpdf-app/target/site/jacoco
|
||||||
|
docker cp "$id:/build/wordpdf-core/target/site/jacoco/jacoco.xml" \
|
||||||
|
wordpdf-core/target/site/jacoco/jacoco.xml || true
|
||||||
|
docker cp "$id:/build/wordpdf-app/target/site/jacoco/jacoco.xml" \
|
||||||
|
wordpdf-app/target/site/jacoco/jacoco.xml || true
|
||||||
|
docker rm "$id" >/dev/null
|
||||||
|
|
||||||
- name: Coverage summary
|
- name: Coverage summary
|
||||||
if: always()
|
if: always()
|
||||||
@@ -103,6 +104,31 @@ jobs:
|
|||||||
f"{base}/{existing}" if existing else base, {"body": body})
|
f"{base}/{existing}" if existing else base, {"body": body})
|
||||||
PY
|
PY
|
||||||
|
|
||||||
|
macos-sim:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v5
|
||||||
|
|
||||||
|
- name: Check maven mirror var
|
||||||
|
env:
|
||||||
|
MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
|
||||||
|
run: |
|
||||||
|
[ -n "$MAVEN_MIRROR_URL" ] || {
|
||||||
|
echo "Задайте Actions Variable MAVEN_MIRROR_URL — см. GITEA-vars.md" >&2
|
||||||
|
exit 1
|
||||||
|
}
|
||||||
|
|
||||||
|
- name: Tests under macOS emulation (-Dos.name)
|
||||||
|
env:
|
||||||
|
MAVEN_MIRROR_URL: ${{ vars.MAVEN_MIRROR_URL }}
|
||||||
|
run: |
|
||||||
|
DOCKER_BUILDKIT=0 docker build \
|
||||||
|
-f Containerfile.test \
|
||||||
|
--build-arg MAVEN_MIRROR_URL="$MAVEN_MIRROR_URL" \
|
||||||
|
--build-arg "SUREFIRE_OS_NAME=Mac OS X" \
|
||||||
|
-t wordpdf-verify:macos-sim \
|
||||||
|
.
|
||||||
|
|
||||||
web:
|
web:
|
||||||
runs-on: ubuntu-latest
|
runs-on: ubuntu-latest
|
||||||
steps:
|
steps:
|
||||||
|
|||||||
@@ -44,3 +44,8 @@ DEPLOY.md
|
|||||||
# Mise: локальный бинарь mise (bootstrap.sh / bootstrap.ps1)
|
# Mise: локальный бинарь mise (bootstrap.sh / bootstrap.ps1)
|
||||||
/.mise/
|
/.mise/
|
||||||
|
|
||||||
|
# Сайт документации: сборка, venv, копия javadoc
|
||||||
|
site/
|
||||||
|
docs/.venv/
|
||||||
|
docs/apidocs/
|
||||||
|
|
||||||
|
|||||||
@@ -1,128 +1,130 @@
|
|||||||
# Repository Guidelines
|
# Repository Guidelines
|
||||||
|
|
||||||
> Роутер: правила, инварианты и команды — здесь; глубокие детали — `docs/agent/*.md`, нормативные форматы — `docs/standards/` (ссылка с номером секции обязательна), пользовательская документация — `README.md`.
|
> Роутер: правила, инварианты и команды — здесь; глубокие детали — `docs/agent/*.md` (pipeline, doc-bridge, chart, testing, ci-cd, repo-map, render-limitations — каждый авторитетен наравне с этим файлом), нормативные форматы — `docs/standards/` (навигатор — `docs/standards/README.md`, ссылка на спецификацию — с номером секции).
|
||||||
|
|
||||||
## Project Overview
|
## Project Overview
|
||||||
|
|
||||||
Конвертер `.docx`/`.doc` → `.pdf` на чистом Java: docx4j 17.3.2 → XSL-FO → форк Apache FOP, без LibreOffice/Aspose. Бинарный `.doc` (Word 97-2003) переносится мостом MS-DOC/MS-CFB (`internal/doc`) в in-memory `.docx` и идёт тем же конвейером. Java 17, только Maven.
|
Конвертер `.docx`/`.doc` → `.pdf` на чистом Java: docx4j 17.3.2 → XSL-FO → форк Apache FOP (`org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 — транзитив от `docx4j-export-fo`), без LibreOffice/Aspose. Бинарный `.doc` (Word 97-2003) переносится мостом MS-DOC/MS-CFB (`internal/doc`) в in-memory `.docx` и идёт тем же конвейером. Maven-мультимодуль `ru.pjandro:java-word-pdf:1.0.0`: `wordpdf-core` (библиотека), `wordpdf-app` (REST на Spring Boot 4.1.1); вне Maven-реактора — SPA `wordpdf-web` (React 19.2 + TS ~6.0 + Vite 8.3 + oxlint + Tailwind v4.3, npm; strict-режим TS намеренно не включён — сборка не strict-гейт) и pytest-автотесты `prod-autotests/`. Java 17, только Maven.
|
||||||
|
|
||||||
| Модуль | Содержимое |
|
## Architecture & Data Flow
|
||||||
|
|
||||||
|
Единственный вход стека — gateway-контейнер nginx (`:9010` prod-like `compose.yml`, `:9011` dev `compose.dev.yml`), **не** 8080. Реальный прод-стек (`docker-compose.yml` + прод `nginx.conf`) рендерит CI-job `deploy` — копий на хосте/в репо не заводить. Наружный прод-вход — `https://pjandro.ru/pdf-converter/` (образ web собирается с `VITE_BASE=/pdf-converter/` — bake в job `images-web`, не в compose).
|
||||||
|
|
||||||
|
**Пайплайн** `WordPdfConverter.convert(byte[] docxBytes, String title, ConvertOptions)` → `convertToStream` (публичная сигнатура единственная, 2-аргументной перегрузки **нет**); порядок шагов фиксирован:
|
||||||
|
|
||||||
|
0. `DependencyGuard.check()` (commons-compress ≥ 1.25.0 API-проба);
|
||||||
|
1. шрифты: `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` — строго в этом порядке, до `load()`;
|
||||||
|
2. нормализаторы (`DocxRewritePipeline.STEP` + лямбда `OleObjectNormalizer`) → `WordprocessingMLPackage.load`;
|
||||||
|
3. `setFontMapper`; 3.5 `DrawingPreRenderer.run` (chart/SmartArt/OMML-формулы → PNG; error-флаги бросаются здесь) — **обязателен до `FOSettings`**, иначе FOP молча теряет диаграммы;
|
||||||
|
4. `FOSettings` + `ChartImageHandler` + `FopFallbackFonts.declare`; 4.25 `LayoutPostRenderer.register`; 4.5 `setCustomXsltTemplates(VendoredXslt.TEMPLATES)`;
|
||||||
|
5. общая `FopFactory` (DCL на мониторе `WordPdfConverter.class`);
|
||||||
|
6. `Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)` — последним;
|
||||||
|
7. `finally`: сброс temp-шрифтов (`FontTablePart.deleteEmbeddedFontTempFiles()`), `resetSharedImageCaches()` (иначе ~1,5 ГБ за 30 конвертаций), `restrictToBundled()` (иначе встроенные в предыдущий docx шрифты травят реестр).
|
||||||
|
|
||||||
|
`WordPdfValidator.validate` вызывается в `convert()` **до** монитора (параллельно); при `options == null` бросает `ValidationException` сам `convert()`. Вход роутируется по сигнатуре: `PK\x03\x04` → docx; `D0 CF 11 E0 A1 B1 1A E1` (CFB) → `DocToDocx.convert`. Для `.doc` страницы считаются по сырым байтам. Пороги валидатора в `WordPdfConverter` объявлены compile-time literals (javac инлайнит, static-блок конвертера не дёргается).
|
||||||
|
|
||||||
|
**Слои ядра** (`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`):
|
||||||
|
- публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConvertOptions` (record `errorOnCharts/errorOnSmartArt/errorOnOle/maxMb/maxPages` — порядок полей фиксирован), `ConversionException` + `ValidationException` + `Charts/SmartArt/OleFoundException`; `warmup()` — идемпотентный прогрев (никогда не бросает), решает вызывающий;
|
||||||
|
- `internal/`: контракт нормализатора — `byte[] normalize(byte[])`, нечего менять → **тот же массив** (`assertSame`); правила 1–11 идут одним zip-проходом `DocxRewritePipeline.STEP` в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→MathFallback→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby (порядок в javadoc `WordPdfConverter.normalizers` устарел — не доверять), `OleObjectNormalizer` — 12-й, отдельным байтовым проходом (не zip); неизменённые записи копируются raw-сжатыми байтами; наружу только `DocxNormalizer`, `DocxRewritePipeline.STEP`, `OleObjectNormalizer`, `FopFallbackFonts`, `LayoutPostRenderer`, `DependencyGuard`;
|
||||||
|
- `internal/doc`: мост `.doc`→`.docx`, 18 top-level классов (17 package-private + `DocToDocx`) + вложенный `DocxBody`, наружу только `DocToDocx.convert/countPages`; любая бита/шифрованный/Word 6-95 входов → `ConversionException`; раскладки — `docs/agent/doc-bridge.md`;
|
||||||
|
- `internal/chart`: Java2D → PNG (`ChartRenderer.DPI = 300`, `MAX_PIXELS` 4096² — `fitDpi` понижает dpi; `MAX_POINTS` 100 000, бюджет chart/math-PNG на документ 128 MiB); формулы OMML — собственный растер `MathModel` (разбор §22.1 в дерево боксов, `SUPPORTED` — единый список конструкций) + `MathRenderer` (без AWT/JEuclid, только бандл через `GlyphFont`); модель **деградации**: битая chart-часть/превышение бюджета → объект удалён + warn; неподдерживаемая/битая формула → **текст** (конкатенация `m:t`) + warn; `wp:extent` вне диапазона/ноль → объект **остаётся** + warn (FOP молча потеряет); `OutOfMemoryError` — не деградация, а `ConversionException` (500);
|
||||||
|
- `fonts/GlyphFont`: метрика/глифы через fontbox напрямую, **без** `java.awt.Font` (fontconfig хосту не нужен).
|
||||||
|
|
||||||
|
**Concurrency-инвариант**: `PhysicalFonts` — глобальный мутируемый реестр → все конвертации сериализованы монитором `WordPdfConverter.class` (convert, warmup, DCL-фабрика, мутации `BundledFonts`, `BundledFonts.font()`). Приложение дополнительно держит однопоточный `ThreadPoolExecutor` (очередь 16 → 503, `wordpdf.convert-timeout=2m` → 504), головой очереди стоит `warmup()`; `WordPdfValidator.checkInput` выполняется синхронно до очереди.
|
||||||
|
|
||||||
|
**REST** (`wordpdf-app`, всё package-private кроме `WordPdfApplication`): `POST /api/v1/convert` (multipart `file` + `errorOnCharts/errorOnSmartArt/errorOnOle`, `maxMb/maxPages` переопределяют серверный дефолт в обе стороны, ≤ 0 → 400; `file.getBytes()` — только после проверки размера; имя файла из `Content-Disposition`, UTF-8 + `.pdf`). Коды: 400 валидация/битые параметры, 401 `ApiKeyFilter` (`X-API-Key` ↔ `wordpdf.api-key`, пусто = выключено, сравнение `MessageDigest.isEqual`; открытые префиксы `/actuator/` (со слэшем!), `/swagger-ui`, `/v3/api-docs`; dot-segment (`..`, `%2e`) заставляет требовать ключ даже на открытых; Advice фильтров не видит — 401 пишет сам), 413 multipart, **422** отказ по графике (`DrawingRejectedException`, фиксированные тексты CHARTS/SMART_ART/OLE — контракт с фронтом), 500 `ConversionFailedException` (текст ядра только в лог, наружу фиксированный), 503 переполнение очереди, 504 timeout; тело ошибки — `{"error": …}` (`record ApiError`). Полная карта, включая 404/405/415, — `docs/agent/repo-map.md`. На `.doc` error-флаги не срабатывают (OLE-вложения — U+0001, мост деградирует в картинки); при снятом флаге `.docx`-OLE теряет data-части, **но сохраняет плейсхолдер-картинку**.
|
||||||
|
|
||||||
|
**SPA** (`wordpdf-web/src`): вся сеть — единственная точка `api.ts` (ровно 2 `fetch`: `convertDocx`, `probeApiKey()` — 401=required / иначе open; ключ в localStorage `wordpdf.api.key`, при 401 стирается; имя файла из `Content-Disposition filename*=utf-8''`); единственный источник состояния — `useState` в `components/App.tsx` (+ `useRef` для `AbortController`/blob-URL), store-библиотек нет; лимиты на клиенте не задаются — только сервер.
|
||||||
|
|
||||||
|
### Критические инварианты (нарушение = битый вывод, не исключение)
|
||||||
|
|
||||||
|
- Static-блок `WordPdfConverter`: `docx4j.convert.out.fo.gsubFeatures=false` (иначе `WordLayoutFixups` отказывает всем фиксам → FOP падает), `docx4j.fonts.discoverPhysicalFonts.enabled=false`, `discoverJarFonts.enabled=false` — не удалять.
|
||||||
|
- Единственный XSL-FO-стилист — вендорный `wordpdf-core/src/main/resources/xslt/docx2fo.xslt` (копия из docx4j-export-fo 17.3.2 + AUDIT-FIX-патчи); обновление docx4j = ручной перенос патчей; дрейф-гейт `vendoredXsltTracksJarCopy`; команда ре-вендоринга — `docs/agent/repo-map.md`.
|
||||||
|
- `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF; в app исключён (logback). Fontbox логируется commons-logging — единственный мост `jcl-over-slf4j`; `commons-logging` исключён из pdfbox/fontbox в dependencyManagement.
|
||||||
|
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 (транзитив от `docx4j-export-fo`, в pom не пинится); `jeuclid-fop`/`jeuclid-core` исключены из `docx4j-export-fo` в core-pom (тянут AWT/fontconfig); расхождения с upstream-доками FOP нормальны; `lineRule=auto` не «чинить».
|
||||||
|
- Chart-media префикс `/word/media/chart-*` — константа `DrawingPreRenderer.CHART_MEDIA_URI_PREFIX` (package-private), пакетный контракт с `ChartImageHandler` (отключение пересжатия); переименование молча вернёт мыльный ресемпл.
|
||||||
|
- Стоп-лист «не чинить» (до любой попытки починить расхождение с Word — `docs/agent/render-limitations.md`): `jc="distribute"`, `suff="tab"`/`lvlJc`, кернинг, `framePr`, `REF`/`SEQ`/`TOC`-кэш, руби-надстрочница, `ptab`, U+2188/U+218A (GPL-шрифты не добавляем).
|
||||||
|
|
||||||
|
## Key Directories
|
||||||
|
|
||||||
|
|Каталог|Назначение|
|
||||||
|---|---|
|
|---|---|
|
||||||
| `wordpdf-core` | библиотека: 62 Java-файла (7 — публичный API, 16 `internal/`, 18 `internal/doc/`, 18 `internal/chart/`, 3 `fonts/`) |
|
|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API + `internal/` (нормализаторы) + `internal/doc/` (мост) + `internal/chart/` (рендер) + `fonts/`|
|
||||||
| `wordpdf-app` | REST API на Spring Boot 4.1.1: 11 классов, единственный `public` — `WordPdfApplication` |
|
|`wordpdf-core/src/main/resources/`|`fonts/` (30 TTF + лицензии OFL/Bitstream-Vera/Noto), `xslt/docx2fo.xslt`, `slf4j-simple.properties`|
|
||||||
| `wordpdf-web` | SPA (React 19 + TS + Vite + Tailwind), вне Maven-реактора, отдельный образ |
|
|`wordpdf-core/src/test/resources/samples/`|фикстуры: 13 `.docx` + 12 `.doc` (закоммичены, билдятся в test-jar для app; у app своего `src/test/resources` **нет**)|
|
||||||
|
|`wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/`|REST-слой (11 классов)|
|
||||||
|
|`wordpdf-web/src/`|SPA: `api.ts` (вся сеть), `components/` (`App.tsx` — состояние, `ApiKeyGate`, `DropZone`, `PdfPreview`, `StatusMessage`, `Logo`)|
|
||||||
|
|`prod-autotests/`|pytest-проверки живого стенда (31: 4 открытые + 27 `needs_key`)|
|
||||||
|
|`docs/agent/` · `docs/standards/`|справочники поведения · закоммиченные спецификации (ECMA-376, MS-DOC/CFB/ODRAW…, навигатор — `docs/standards/README.md`)|
|
||||||
|
|`gateway/nginx.conf`|прод-like шлюз (`client_max_body_size 100m`, таймауты 300 с, `resolver` привязан literal-ом к шлюзу сети)|
|
||||||
|
|`develop/`|вне git (gitignored): эталоны Word — **не фикстуры**, в тесты/jar не подключать|
|
||||||
|
|
||||||
Единственный вход стека — gateway-контейнер nginx (`:9010` prod-like `compose.yml`, `:9011` dev `compose.dev.yml`), **не** 8080. Авторитетны этот файл, `docs/agent/` и код. Полный путеводитель по каталогам, ключевым файлам и командам — `docs/agent/repo-map.md`.
|
## Development Commands
|
||||||
|
|
||||||
## Пайплайн `WordPdfConverter.convert(byte[], String[, ConvertOptions])`
|
Бутстрап: `sh bootstrap.sh` (Windows: `powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1`) — project-local mise 2026.10.19 в `./.mise/` + `mise install` + `npm ci` web; дальше всё через `./mise.sh` / `.\mise.ps1` (тонкие exec-обёртки; инструменты — в `~/.local/share/mise`).
|
||||||
|
|
||||||
Порядок шагов 0–7 фиксирован (`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`). Валидация — **до** `convertToStream`: `WordPdfValidator.validate(bytes, options)` (размер → подпись zip/CFB → контейнер → страницы); для `.doc` — `checkPageCountDoc` по сырым байтам.
|
|
||||||
|
|
||||||
Порядок: шрифты (`BundledFontMapper` → `BundledFonts.init` → `restrictToBundled`) и правила 1–10 (`DocxRewritePipeline.STEP`) + `OleObjectNormalizer` — до `WordprocessingMLPackage.load`; `FOSettings`/`FopFallbackFonts`/`LayoutPostRenderer` — до `setCustomXsltTemplates(VendoredXslt.TEMPLATES)`; `Docx4J.toFO(…, FLAG_EXPORT_PREFER_XSL)` — последним; `finally` → `deleteEmbeddedFontTempFiles()`. Полная таблица шагов и подсчёт страниц — `docs/agent/pipeline.md`.
|
|
||||||
|
|
||||||
## Нормализаторы (`internal/DocxNormalizer`)
|
|
||||||
|
|
||||||
Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame`). Порядок фиксирован: Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby. Правила 1–10 применяет `DocxRewritePipeline.STEP` одним zip-проходом (неизменённые записи копируются raw-сжатыми байтами); `OleObjectNormalizer` (правило 11) — лямбдой в `WordPdfConverter.normalizers()`. `STEP` выставляют 9 из 10 rewrite-нормализаторов (нет у `RubyNormalizer`), у `OleObjectNormalizer` её нет. Правила 1–11, guard'ы, номера секций и инвариант `mc-preprocessor.xslt` (собственный рерайт strict-URI ломать нельзя) — `docs/agent/pipeline.md`.
|
|
||||||
|
|
||||||
## Мост `.doc` → `.docx` (`internal/doc`)
|
|
||||||
|
|
||||||
18 классов, 16 package-private; наружу — `DocToDocx` (`convert`/`countPages`) и `CfbReader`. Общий разбор — `DocFile`: CFB → потоки WordDocument / 0Table|1Table / Data + FIB + piece table. Новых runtime-зависимостей нет (POI/POIFS — test-scope). Источники: [MS-DOC] (`docs/standards/doc/`), [MS-CFB]/[MS-OLEPS]/[MS-ODRAW] (`docs/standards/binary/`). Байтовые раскладки по классам — `docs/agent/doc-bridge.md`.
|
|
||||||
|
|
||||||
## REST API (`wordpdf-app`, всё package-private кроме `WordPdfApplication`)
|
|
||||||
|
|
||||||
`POST /api/v1/convert`: multipart-поле `file` (`.docx`/`.doc`) + query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолты — `WordPdfSettings.ERROR_ON_*`). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`; имя — `ConversionService.safeBaseName`. Тело ошибки — `{"error": …}`. Error-флаги на `.doc` **не срабатывают** (BLIP-плейсхолдеры → картинки). `ApiExceptionHandler` не видит ошибок фильтров — 401 пишет сам `ApiKeyFilter`.
|
|
||||||
|
|
||||||
- **Коды**: 400 — `ValidationException`/`BadRequestException`/битые параметры; 401 — `ApiKeyFilter`; 404/405/415 — путь/метод/content-type; 413 — multipart; **422** — `DrawingRejectedException` (core-`DrawingFoundException`, `Kind {CHARTS, SMARTART, OLE}`); 500/503/504 — `ConversionFailedException`/`ConversionRejectedException`/`ConversionTimeoutException`. Полная карта — `docs/agent/repo-map.md`.
|
|
||||||
- **Текст 422** — контракт с фронтом: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты».
|
|
||||||
- **Ключ**: `X-API-Key` ↔ `wordpdf.api-key` (пустое = выключено); без ключа открыты только `OPEN_PREFIXES` (`/actuator/`, `/swagger-ui`, `/v3/api-docs`), пути с точечными сегментами — никогда.
|
|
||||||
- **Очередь и лимиты**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`QUEUE_CAPACITY = 16`, переполнение → 503) — ядро не потокобезопасно; головой очереди на старте стоит `warmup()`. Лимиты входа — только конфигурация сервера (`wordpdf.max-mb`/`max-pages`, дефолты из `WordPdfSettings`; ≤ 0 → `IllegalStateException`; параметрами запроса не переопределяются).
|
|
||||||
- **SPA**: вся сеть в `wordpdf-web/src/api.ts`; ключ в `localStorage` (`wordpdf.api.key`); `ApiKeyGate` — только если `probeApiKey()` подтвердил требование ключа (признак открытого сервера — **405**); base — `VITE_BASE`; DropZone `.docx,.doc`.
|
|
||||||
|
|
||||||
## Chart/SmartArt-движок (`internal/chart`, 18 классов)
|
|
||||||
|
|
||||||
Нормативный источник — ECMA-376 (`docs/standards/ooxml/`: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D, XSD); поведение Word — `ms-oi29500.md`, `ms-odrawxml.md`. Калибровки (камера, `PIE_DEPTH`) меняются только с пиксельными тестами; невалидная фикстура правится, не код.
|
|
||||||
|
|
||||||
Java2D → PNG: `ChartRenderer.DPI = 300`, потолок `MAX_PIXELS = 16_777_216` (`fitDpi`); лимиты `ChartSpec.MAX_POINTS = 100_000`, `ChartRenderer.MAX_TICKS = 1000`, `DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000` — деградация «объект как есть / удалён + warn», не OOM. Chart-PNG вставляются media-частями вручную (`addChartMedia`, `/word/media/chart-*`, без `createImagePart`); `ChartImageHandler` отключает «Compress Pictures» (CR-029) только для них. Пейнтеры, `autoTitleDeleted`, Combo, обходы JAXB — `docs/agent/chart.md`.
|
|
||||||
|
|
||||||
## Критические инварианты (нарушение = битый вывод, не исключение)
|
|
||||||
|
|
||||||
- `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`; иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам → FOP падает на `docx4j-baseline`.
|
|
||||||
- `docx4j.fonts.discoverPhysicalFonts.enabled=false` и `discoverJarFonts.enabled=false` — static-блок: иначе `BestMatchingMapper` сканирует системные шрифты и jar'ы classpath'а, а `restrictToBundled()` всё найденное выбрасывает (~100–140 мс впустую на JVM). `discoverJarFonts("fonts-symbol")` свойством не гейтится — символ-шрифт регистрируется и снимается restrict'ом как раньше.
|
|
||||||
- Единственный XSL-FO-стилист — вендорный `xslt/docx2fo.xslt` (копия из docx4j-export-fo 17.3.2 + два AUDIT-FIX-патча: `w:rPr/w:position` → `baseline-shift`, Part 1 §17.3.2.24; AUDIT-FIX-2 — `w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir`, иначе их ловит catch-all `match="*"` и текст теряется). Дрейф-гейт `vendoredXsltTracksJarCopy`: вне AUDIT-FIX-регионов копия побайтно равна стилю из jar'а. `setCustomXsltTemplates` принимает предкомпилированный `Templates`.
|
|
||||||
- `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия `noLoggingWarningInPdf`); приложение исключает его — логи ведёт logback.
|
|
||||||
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 (транзитив от `docx4j-export-fo`, в pom не пинится; пакеты `org.apache.fop.*`). `FopFallbackFonts` берёт `w:renderer` с mime `application/pdf`, иначе первый со шрифтами.
|
|
||||||
- `BundledFonts.init()` идемпотентен и `synchronized`, распаковывает TTF в `wordpdf-fonts-*` (`deleteOnExit`); `dropNonBundled()` чистит `PhysicalFonts` от всего, что вне бандла.
|
|
||||||
- `PhysicalFonts` — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером; `warmup()` идёт тем же потоком.
|
|
||||||
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; правила StAX-подсчёта — `docs/agent/pipeline.md`.
|
|
||||||
- Не чинить: `jc="distribute"`, `suff="tab"`/`lvlJc`, метрика «single», кернинг, `framePr`, `REF`/`SEQ`/`TOC`-кэш, руби-надстрочница, U+2188/U+218A — доказательства в `docs/agent/render-limitations.md`.
|
|
||||||
- Комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).
|
|
||||||
|
|
||||||
## Шрифты (30 TTF + 3 лицензии, SIL OFL, `wordpdf-core/src/main/resources/fonts/`)
|
|
||||||
|
|
||||||
9 семейств: 7 × 4 начертания (Carlito/Caladea/Arimo/Tinos/Cousine/DejaVu Sans/DejaVu Serif) + Noto Naskh Arabic / Noto Sans Armenian (только regular). `BundledFontMapper.ALIASES`: Calibri→Carlito, Calibri Light→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; **self-map** всех бандл-семейств, включая Noto; fallback — DejaVu Sans; виртуальный `SYMBOL_FONT` «Segoe UI Symbol» (U+2000–U+2EFF) → fallback до основного цикла. Новый шрифт = файл + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`). `GlyphFont` читает TTF напрямую с classpath через fontbox, **без** `java.awt.Font` (нужен fontconfig на хосте). Публичный API и детали — `docs/agent/repo-map.md`.
|
|
||||||
|
|
||||||
## Команды
|
|
||||||
|
|
||||||
Бутстрап: `sh bootstrap.sh` (Windows: `powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1`) — project-local mise в `./.mise/`, дальше — `./mise.sh` / `.\mise.ps1`.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./mise.sh run verify # = mvn clean verify: тесты + PMD + JaCoCo (гейт перед push)
|
./mise.sh run verify # = mvn clean verify: тесты + PMD + JaCoCo (гейт перед push)
|
||||||
mvn clean verify # то же; mvnw НЕТ — только системный Maven
|
./mise.sh run verify-nofontconfig # тот же verify в контейнерах без fontconfig (как CI)
|
||||||
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест
|
mvn test -Djacoco.skip=true # работает: пустой <argLine> по умолчанию в корневом pom
|
||||||
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am: core test-jar
|
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
|
||||||
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
|
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am обязателен: core test-jar
|
||||||
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен
|
./mise.sh run app-package && ./mise.sh run app-run # jar :8080, ключ выключен
|
||||||
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
||||||
./mise.sh run web-install|web-build|web-lint|web-dev # npm ci | tsc -b && vite build | oxlint | vite :5173
|
./mise.sh run web-install|web-build|web-lint|web-dev # npm ci | tsc -b && vite build | oxlint | vite :5173
|
||||||
podman-compose -f compose.dev.yml up -d --build --force-recreate # dev-стенд :9011, без ключа
|
./mise.sh run mem-bench # membench.sh + core MemoryBench (MB_LABEL, --scenario suite|big|all, --dir develop/)
|
||||||
./mise.sh run prod-tests # прод-автотесты в prod-autotests/
|
podman-compose -f compose.dev.yml up -d --build --force-recreate # dev-стенд :9011, без ключа
|
||||||
|
podman-compose up -d --build # prod-like стенд :9010 — fail-closed: нужен .env с WORDPDF_API_KEY (шаблон .env.example)
|
||||||
|
./mise.sh run prod-tests # pytest; обязателен WORDPDF_BASE_URL
|
||||||
|
./mise.sh run docs-install|docs-serve|docs-build|docs-javadoc|docs-deploy # сайт документации (MkDocs Material): venv+pip | preview :8000 | strict-сборка в site/ | javadoc core | публикация в ~/srv/wordpdf-docs (юнит wordpdf-docs.service, :9012)
|
||||||
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD (lxml)
|
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD (lxml)
|
||||||
```
|
```
|
||||||
|
|
||||||
Задачи mise (8): `verify`, `app-package`, `app-run`, `web-install`, `web-build`, `web-lint`, `web-dev`, `prod-tests`.
|
- «Запусти тестовый сервер» (термин пользователя) = dev-стенд выше, **не** `java -jar`; вход — `http://<LAN-IP>:9011` (`hostname -I`); гейт готовности — контейнеры healthy (`podman-compose -f compose.dev.yml ps`) + корень SPA 200; `--force-recreate` обязателен.
|
||||||
|
- `mvn test` PMD и проверки JaCoCo **не** запускает (оба на `verify`; сам агент JaCoCo подключается и на `test` — execution `prepare-agent` на `initialize`); `mvn -pl wordpdf-app` без `-am` падает (зависимость от core test-jar).
|
||||||
**«Запусти тестовый сервер» (термин пользователя)** = полный dev-стенд, НЕ `java -jar`: `podman-compose -f compose.dev.yml up -d --build --force-recreate`, вход `http://<LAN-IP хоста>:9011` без API-ключа; гейт — контейнеры healthy + корень SPA отвечает 200. `--force-recreate` обязателен: без него контейнеры остаются на старом образе.
|
- Деплой — push в `main` → Gitea Actions (детали — `docs/agent/ci-cd.md`); **перед деплоем/перезапуском прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md`** (вне репо); ручных скриптов нет.
|
||||||
|
|
||||||
Пересоздание фикстур и перевендоривание стилиста — `docs/agent/repo-map.md`. Деплой: **прод** — на пользовательском LAN-сервере; **перед деплоем/перезапуском прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md`**; пуск — push в `main` или Run workflow, ручных скриптов нет (детали — `docs/agent/ci-cd.md`).
|
|
||||||
|
|
||||||
## Code Conventions & Common Patterns
|
## Code Conventions & Common Patterns
|
||||||
|
|
||||||
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе: `BundledFontMapper`, `DrawMlColor`, Spring-компоненты `wordpdf-app`.
|
- Классы `final`, приватный конструктор, только `static` (stateless, DI в ядре нет). Исключения-экземпляры: `BundledFontMapper`, Spring-компоненты app. В `internal/**` классы package-private; `public` — только вызываемые извне пакета, контракт не расширять.
|
||||||
- В `internal/**` классы `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу ограничены: `normalize`/`STEP`/`declare`/`run`/`check`/`register`; `rewrite`-хуки — package-private. В `wordpdf-app` всё package-private кроме `WordPdfApplication`; в `internal/doc` публичны только `DocToDocx` и `CfbReader`.
|
- Ошибки публичного API — только `ConversionException extends RuntimeException`; `ValidationException` не оборачивать; в chart — деградация вместо падения; текст 500 наружу фиксированный (сообщения ядра логируются, не отдаются).
|
||||||
- Нормализаторы — единый контракт `internal/DocxNormalizer` + константа `STEP`; порядок цепочки — см. «Нормализаторы», правятся только `word/*.xml`.
|
- Javadoc на русском: «зачем» со ссылкой на секцию спецификации (§17.3.2.24, [MS-DOC] §2.6.1…) + что сломается без шага + регрессия в формате `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx` (по этой строке грепом восстанавливаются пары «нормализатор-тест ↔ тест-в-конвейере»).
|
||||||
- Ошибки публичного API — только `ConversionException extends RuntimeException` (unchecked); внутренние исключения оборачиваются на границе. В chart — деградация вместо падения. `ValidationException` — собственность `WordPdfValidator`; не оборачивать в общий `ConversionException`.
|
- Логирование по пакетам: `java.util.logging` — корневой пакет и `internal/` (`WordPdfConverter`, `OleObjectNormalizer`, `DocToDocx`); SLF4J — `internal/chart` (`ChartRenderer`, `DrawingPreRenderer`) и `wordpdf-app`; остальное молчит.
|
||||||
- DI в `wordpdf-app` — конструкторная инъекция Spring; состояние сервисов `private final`. SPA: единственный источник состояния — `useState` в `App.tsx`, вся сеть — в `api.ts`.
|
- Модели — `record` (`ConvertOptions`, `BundledFonts.Entry`, `MathRenderer.MathImage`, `ApiError`); константы UPPER_SNAKE с javadoc-обоснованием числа; holder-идиомы для ленивой инициализации (`VendoredXslt.TEMPLATES`); DCL+caches (`sharedFopFactory`, `GlyphFont.CACHE`); compile-time literals там, где важен инлайн (`WordPdfConverter` ↔ `WordPdfValidator`).
|
||||||
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`).
|
- Шрифты: новый шрифт = файл в `resources/fonts/` + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`); алиасы — `BundledFontAliases.ALIASES` (Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine, …; вынесено из `BundledFontMapper`, чтобы обращение к статикам не инициировало ungated-скан `BestMatchingMapper.<clinit>`), fallback — DejaVu Sans.
|
||||||
- Константы UPPER_SNAKE с эталонными значениями (`PIE_DEPTH`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/V_ITALIC/V_BOLD_ITALIC`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`.
|
- PMD (`pmd-ruleset.xml`, execution `pmd-check` на `verify`, `includeTests=true`, валит любой приоритет): правила не перенастраивать, подавления (`@SuppressWarnings("PMD…")`, `// NOPMD`) запрещены — нарушения чинятся кодом.
|
||||||
- Логирование: `java.util.logging.Logger` в корневом пакете и `internal/`, SLF4J — в `internal/chart` и `wordpdf-app`.
|
- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`; защищённые `main`/`master`/`dev`; все правки — через PR в дефолтную ветку; push — только после `./mise.sh run verify`. Прод-координаты и креды в репо не попадают (Gitea Variables/Secrets — `GITEA-vars.md`; прод-ключ — только Gitea Secret; локальный `.env` gitignored, только для prod-like стенда).
|
||||||
- Тестовые методы: регрессионные — `объект_условие` через underscore (`ruPlain_cyrillicAndStyles`), юниты — camelCase (`pageFieldBecomesFldSimple`); оба стиля разрешает PMD-паттерн `junit5TestPattern` (`^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$`).
|
|
||||||
- PMD (`pmd-ruleset.xml`, execution `pmd-check` на `verify` в обоих модулях, `includeTests=true`, валится нарушение любой приоритетности): полные исключения категории, кастомное XPath-правило `LiteralFirstInEquals` и настройки — в самом ruleset.
|
|
||||||
|
|
||||||
## Runtime & Tooling
|
## Important Files
|
||||||
|
|
||||||
- Java 17 + Maven (обязательны; wrapper `mvnw` НЕТ); UTF-8; только Maven — никаких Gradle/Ant. Инструменты (Java/Maven/Node/Python) ставит project-local mise (бинарь в `.mise/`, вне системы), версии пинятся в корневом `mise.toml`; ежедневный запуск — `./mise.sh`.
|
|Файл|Что держать в голове|
|
||||||
- Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement), новые — latest stable; закреплённый список — `docs/agent/repo-map.md`. Maven-зависимости — через Nexus `maven-central`: локально `~/.m2/settings.xml` (файл вне репо), CI/Containerfile — `.ci/maven-settings.xml` + `MAVEN_MIRROR_URL`.
|
|---|---|
|
||||||
- Фронт: Node из engines vite/oxlint, `npm ci` с закоммиченным `package-lock.json`, TS `strict` нигде не включён. Контейнеры (podman/buildah): `FROM` только FQDN, хостовые прокси-переменные обнулять на самой команде (`RUN`/`HEALTHCHECK`), `DOCKER_BUILDKIT=0` обязателен, fontconfig рантайму не нужен (глифы — fontbox).
|
|`pom.xml` (корень)|единственное место версий (properties + dependencyManagement): docx4j 17.3.2, commons-compress 1.28.0, slf4j 2.0.20, Boot 4.1.1 BOM, springdoc 3.1.1, JUnit 6.1.3, PDFBox/fontbox 3.0.8, POI 5.5.1 (test), JaCoCo 0.8.15, PMD-плагин 3.21.2; там же плагины: compiler 3.16.0, surefire 3.6.0 (`-Djava.awt.headless=true`), jar 3.5.1; пустой `<argLine/>` — ради `-Djacoco.skip=true`|
|
||||||
- Локальная проверка одна: `mvn clean verify` (тесты + PMD + JaCoCo). Форматтеров и checkstyle для Java нет; статический линтер — PMD. Исполняемый jar проверять только `java -jar`; нюанс `BundledFontsTest` (`file:`-протокол classpath) — `docs/agent/repo-map.md`.
|
|`wordpdf-core/src/main/java/.../WordPdfConverter.java`|весь конвейер, static-блок sysprops, пороги-константы, монитор сериализации|
|
||||||
- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`; защищённые ветки — `main`, `master`, `dev`. Все правки — через PR в дефолтную ветку; push — завершающим шагом задачи, только после `./mise.sh run verify`.
|
|`wordpdf-app/src/main/resources/application.properties`|multipart 100MB/100MB (зеркалит nginx `client_max_body_size`) + `file-size-threshold=2MB` (сброс больших частей на диск — защита от OOM), `convert-timeout=2m`, `api-key=` (пусто = auth off), `forward-headers-strategy=framework`; `wordpdf.max-mb`/`max-pages` здесь **не объявлять намеренно** — пустое значение затенит `@Value`-дефолты 5/100 (≤ 0 на старте → `IllegalStateException`)|
|
||||||
- Прод-координаты и креды в коммитимые файлы **не попадают** (ни IP, ни хостов, ни пользователей, ни ключей): стенд — Gitea Actions Variables, креды — Secrets; workflow-файлы ссылаются только на `${{ vars.* }}`/`${{ secrets.* }}` (список — `GITEA-vars.md`). Локальный `.env` (gitignored) — только для `compose.yml`.
|
|`wordpdf-core/pom.xml` / `wordpdf-app/pom.xml`|execution `test-jar`; BRANCH-гейт 0.85 (только core); exclusions: jeuclid (core), `slf4j-simple` (app); Boot-4 имена: `spring-boot-starter-webmvc` (не `-web`), отдельный `spring-boot-webmvc-test`; `repackage` привязан явно|
|
||||||
|
|`Containerfile` / `Containerfile.test` / `compose*.yml` / `gateway/nginx.conf`|прод-образ (heap 2G, mem_limit 3G, wget-healthcheck, FQDN FROM, non-root 10001, обнуление прокси на команде) / CI-гейт без fontconfig (Debian-база — alpine amd64-only; `SUREFIRE_OS_NAME` для macos-sim) / стенды :9010–:9011 / шлюз. Нюанс: repo `compose.yml` (prod-like) гасит springdoc env-ами и требует `.env`-ключ, а реальный прод из CI-рендера держит swagger открытым (`test_swagger_ui_open_without_key`) — не путать|
|
||||||
|
|`.gitea/workflows/pr.yml`, `main.yml`, `.ci/maven-settings.xml`|CI: jobs `java`/`web` в обоих — идентичные шаги, в `pr.yml` дополнительно `macos-sim` (те же тесты с `--build-arg SUREFIRE_OS_NAME="Mac OS X"`, только на PR, не required-гейт); `main.yml`: `images-* → deploy → autotests (+ rollback при failure)`; Maven в CI живёт в контейнере `maven:3.9-eclipse-temurin-17`; зеркало `${env.MAVEN_MIRROR_URL}`, `mirrorOf="*"`|
|
||||||
|
|`wordpdf-web/src/api.ts`, `vite.config.ts`|вся сеть SPA; `base` — только через env `VITE_BASE` (в прод-образ запекается `--build-arg VITE_BASE=/pdf-converter/` в job `images-web`)|
|
||||||
|
|`mise.toml`, `GITEA-vars.md`|пины инструментов и все таски / полный список Secrets+Variables CI и настройка branch protection|
|
||||||
|
|
||||||
## CI/CD (Gitea Actions)
|
## Runtime/Tooling Preferences
|
||||||
|
|
||||||
`pr.yml` (`PR checks`): job `java` (`mvn -B -s .ci/maven-settings.xml clean verify` через Nexus) + coverage-сводка и комментарий в PR, job `web` (`npm ci` → build → lint). `main.yml`: `java`/`web` → `images-app`/`images-web` (build+push в Nexus, теги `prod` + `sha-<7>`) → `deploy` (SSH, рендер прод-конфигов, гейты healthy) → `autotests` → `rollback` при провале. Нарратив — `docs/agent/ci-cd.md`.
|
- Java 17 temurin + Maven 3.9.16 + Node 24 + Python 3.15 — пинины в `mise.toml`, всё через project-local mise (`./.mise/bin/mise`, вне системы); `mvnw` **нет** (`.mvn/` — пустой) — только Maven из mise. UTF-8.
|
||||||
|
- Только Maven (никаких Gradle/Ant). Версии зависимостей/плагинов — только в корневом `pom.xml`; FOP-форк отдельно не пинить; `commons-compress` не завышать (привязан к docx4j 17.3.2); `<repositories>` в pom не добавлять (зеркало — через settings).
|
||||||
Защита ветки `main`: required-контексты — **`PR checks / java (pull_request)`**, **`PR checks / web (pull_request)`** (deploy/autotests в список не включать — на PR не бегут). Смена лимитов стенда = правка Variables, PR не нужен.
|
- Веб: только npm (`package-lock.json` закоммичен; никаких pnpm/yarn); линтер — oxlint (не eslint).
|
||||||
|
- Контейнеры: podman/buildah; `FROM` только FQDN; хостовые прокси-переменные обнулять на самой команде в `RUN`/`HEALTHCHECK`; `DOCKER_BUILDKIT=0` (CI); healthcheck через wget, не curl; fontconfig рантайму не нужен (глифы — fontbox); alpine-теги maven/temurin amd64-only — тестовый образ на Debian-базе.
|
||||||
|
- Сеть: наружу публикуется только gateway (9010/9011); 8080/80 наружу не выставлять; подсети compose зафиксированы (nginx `resolver` привязан literal-ом к шлюзу сети — 10.113.0.1 стенды / 10.112.0.1 прод).
|
||||||
|
- Прод-стек (`docker-compose.yml`, `nginx.conf`) рендерится job'ом `deploy` из Variables — копий на хосте/в репо не заводить; required-контексты защиты `main` (по `GITEA-vars.md`) — буквально `PR checks / java (pull_request)`, `PR checks / web (pull_request)`; `macos-sim`, deploy/autotests — не required.
|
||||||
|
|
||||||
## Testing & QA
|
## 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` (`target/site/jacoco/`). Механика — `docs/agent/repo-map.md`. Плотность покрытия держат тесты, а не заглушки.
|
- Гейты на `verify`: PMD (движок 6.55.0 — default внутри maven-pmd-plugin 3.21.2, отдельно в pom не пинится; осознанный откат — ruleset использует удалённые в PMD 7 `*MustUseBraces`; подавлений в коде нет и быть не должно) + JaCoCo: LINE ≥ 0.90 оба модуля, BRANCH ≥ 0.85 только core; при провале отчёт уже в `target/site/jacoco/` (`report` привязан до `check`). CI-эквивалент — `./mise.sh run verify-nofontconfig`.
|
||||||
- Стек: JUnit 6 (`org.junit.jupiter`), только `Assertions` — Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `containsString` в `andExpect`; тестовые классы package-private, зеркалят main-пакеты. Счётчики — `docs/agent/testing.md`.
|
- Стек: JUnit 6 (`org.junit.jupiter`), **только `Assertions`** — Mockito/AssertJ запрещены и в pom их нет; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` (полностью квалифицирован, без импортов) в `andExpect`; app не объявляет junit сам — только через `spring-boot-starter-test`. Тестовые классы package-private, зеркалят main-пакеты; только `@Test` (исключения: два `@BeforeAll` прогрева шрифтов и `@AfterEach drainWorker` в `ConversionTimeoutTest`); ни `@Nested`, ни `@ParameterizedTest`, ни `@Disabled`, ни `assertAll`.
|
||||||
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3, `PDFTextStripper`; негативные маркеры — `.notdef` (`#`) и `Helvetica`; текст нормализуется по пробелам (`norm`). Пиксельные проверки — только в юнитах chart-пейнтеров (допуски `assertRatio` < 0.06 / < 0.10). Детали — `docs/agent/repo-map.md`.
|
- Именование: регрессионные — `объект_условие` (`pageNumbers_recomputedNotCached`), юниты — camelCase (`pageFieldBecomesFldSimple`).
|
||||||
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест; в javadoc фикса — ссылка «Регрессия — Test#имя, фикстура samples/…». Пары `XxxNormalizerTest`↔`тест-в-конвейере` воспроизводятся грепом по этим ссылкам; исключения — `docs/agent/testing.md`.
|
- **PDF сравнивается текстом**: PDFBox 3 `PDFTextStripper` (`norm` схлопывает пробелы; негативные маркеры — `#`/`.notdef` и `Helvetica`; приём `fontNameOf` — имя шрифта символа, живёт только в `WordPdfConverterTest`). Пиксели — только юниты chart-пейнтеров (`assertRatio` < 0.06 / < 0.10, эталонные числа Word-рендеров 300 dpi захардкожены). Тестовых утилит нет — хелперы намеренно дублируются в классах. Сообщения ассертов — по-русски с наблюдаемым значением; литерал слева (`"%PDF".equals(…)`).
|
||||||
- Фикстуры — только закоммиченные `samples/*.docx` (13) + `samples/*.doc` (12), в тестах не генерировать; контракт нормализаторов «нечего менять → тот же массив» (`assertSame`) + неприкосновенность частей вне `word/*.xml`.
|
- Фикстуры — только закоммиченные `samples/*.docx`/`*.doc`, в тестах не генерировать; XSD-невалидная фикстура правится, не код. Синтетика в памяти разрешена: docx — `ZipOutputStream` из литеральных XML, `.doc` — крафт `POIFSFileSystem`. Пересоздание — одноразовые `SampleDocxGenerator`/`ChartTypesDocxGenerator` (POI test-scope, команда — `docs/agent/repo-map.md`); `charts-smartart.docx` и `ole-embedded.docx` сделаны руками — **никогда не перезаписывать** (все 12 `.doc` — эталоны заказчика, не вывод генераторов).
|
||||||
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); четыре набора свойств = четыре контекста (отдельные классы, не `@Nested`); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring. Core-юниты Spring **не поднимают**; app-тесты проверяют только HTTP-код/заголовки/текст ошибки. Детали — `docs/agent/testing.md`.
|
- Идиома загрузки (ловушка): **core** — classloader без ведущего слэша (`getResourceAsStream("samples/…")`); **app** — class-relative со слэшем (`"/samples/…"`, ресурсы из core test-jar).
|
||||||
- Жизненный цикл: только `@Test`; исключения — два `@BeforeAll` (прогрев шрифтов) и `@AfterEach drainWorker` в `ConversionTimeoutTest`. Ни `@Nested`, ни `@ParameterizedTest`, ни `@Disabled`, ни `assertAll`.
|
- App-тесты: 4 набора свойств = 4 Spring-контекста (`ConvertControllerTest` пинует пустой `wordpdf.api-key=`; `ApiKeyFilterTest`; `ConvertLimitsTest`; `ConversionTimeoutTest`); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring; проверяют только HTTP-код/заголовки/текст ошибки; core-юниты Spring не поднимают. Ловушка: mise инжектирует корневой `.env` в окружение задач — ambient `WORDPDF_API_KEY` взорвёт 401 все MockMvc-тесты, если ключ не запинен свойствами контекста.
|
||||||
- Идиомы загрузки фикстур: **core** — classloader без ведущего слэша, **app** — class-relative со слэшем (core test-jar). Синтетика: docx — `ZipOutputStream`, `.doc` — крафт `POIFSFileSystem`.
|
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест + javadoc-ссылка. Счётчики (2026-11): 63 класса / 1005 тестов (core 57/957, app 6/48); детали — `docs/agent/testing.md`.
|
||||||
- Сообщения ассертов — по-русски и с наблюдаемым значением; сравнение строк литерал-слева (`"%PDF".equals(...)`, PMD `LiteralFirstInEquals`); контракт идентичности — `assertSame`/`assertNotSame`. Общих test-util-классов нет: хелперы (`norm`, `pdfText`, `assertRatio`) намеренно продублированы.
|
- Прод-автотесты: pytest 9.1.1 + requests 2.34.2 (timeout `(10,180)` — больше серверных 2m), конфигурация **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY` факультативен → `needs_key`-декоратор `skipif` (немаркированный marker — маркеры не регистрируются) даёт SKIP, `WORDPDF_MAX_MB`/`MAX_PAGES` — ожидаемые лимиты стенда 5/100, `WORDPDF_SAMPLES_DIR` — путь к фикстурам); запуск `./mise.sh run prod-tests` либо job `autotests` в CI.
|
||||||
- Прод-автотесты: pytest + requests; под маркером `needs_key` без ключа SKIP; конфигурация стенда **только env** (`WORDPDF_BASE_URL` обязателен).
|
|
||||||
- `mvn test` **не** запускает PMD и JaCoCo-гейты (оба на `verify`) — «зелёное» состояние проверяется `mvn clean verify`. `mvn -pl wordpdf-app` без `-am` падает: app зависит от core test-jar.
|
|
||||||
|
|||||||
+1
-1
@@ -37,5 +37,5 @@ USER app
|
|||||||
EXPOSE 8080
|
EXPOSE 8080
|
||||||
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=5 \
|
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=5 \
|
||||||
CMD HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= wget -qO /dev/null http://127.0.0.1:8080/actuator/health || exit 1
|
CMD HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= wget -qO /dev/null http://127.0.0.1:8080/actuator/health || exit 1
|
||||||
ENTRYPOINT ["java", "-Djava.awt.headless=true", "-XX:MaxRAMPercentage=70", "-jar", "/app/app.jar"]
|
ENTRYPOINT ["java", "-Djava.awt.headless=true", "-Xms2g", "-Xmx2g", "-jar", "/app/app.jar"]
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,60 @@
|
|||||||
|
# Тестовый образ «без fontconfig»: единственный полный прогон mvn clean verify
|
||||||
|
# (тесты + PMD + JaCoCo) там, где AWT-менеджер шрифтов недоступен (нет
|
||||||
|
# libfontconfig и /etc/fonts). В CI хостовый mvn не запускается вовсе — набор
|
||||||
|
# тестов никогда не исполняется на хосте с fontconfig. Локально сырой
|
||||||
|
# `mvn clean verify` (mise-задача verify) — хост-гейт без docker/podman.
|
||||||
|
# База — maven:3.9-eclipse-temurin-17, а не alpine: alpine-теги maven/temurin
|
||||||
|
# публикуются только под amd64, на arm64-хосте образ не собрать.
|
||||||
|
FROM docker.io/library/maven:3.9-eclipse-temurin-17
|
||||||
|
WORKDIR /build
|
||||||
|
# Удаляем fontconfig и системные шрифты; проверяем, что удалить удалось.
|
||||||
|
RUN set -eux; \
|
||||||
|
rm -rf /etc/fonts /usr/share/fonts /var/cache/fontconfig; \
|
||||||
|
find /usr/lib /lib -name 'libfontconfig.so*' -delete 2>/dev/null || true; \
|
||||||
|
if [ -e /etc/fonts ] || find /usr/lib /lib -name 'libfontconfig.so*' | grep -q .; then \
|
||||||
|
echo 'fontconfig остался в тестовом образе' >&2; exit 1; fi
|
||||||
|
# Жёсткий гейт: проба ядра (та же, что в MathMlSupport) обязана падать.
|
||||||
|
RUN set -eux; mkdir -p /tmp/probe; \
|
||||||
|
printf '%s\n' \
|
||||||
|
'public class Probe {' \
|
||||||
|
' public static void main(String[] a) {' \
|
||||||
|
' try {' \
|
||||||
|
' java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment()' \
|
||||||
|
' .getAvailableFontFamilyNames();' \
|
||||||
|
' System.exit(0);' \
|
||||||
|
' } catch (Throwable t) {' \
|
||||||
|
' System.exit(1);' \
|
||||||
|
' }' \
|
||||||
|
' }' \
|
||||||
|
'}' > /tmp/probe/Probe.java; \
|
||||||
|
javac -d /tmp/probe /tmp/probe/Probe.java; \
|
||||||
|
if java -Djava.awt.headless=true -cp /tmp/probe Probe; then \
|
||||||
|
echo 'AWT-шрифты доступны: fontconfig не удалён' >&2; exit 1; fi; \
|
||||||
|
echo 'fontconfig отсутствует: AWT-шрифты недоступны (ожидаемо)'; \
|
||||||
|
rm -rf /tmp/probe
|
||||||
|
# Зеркало Nexus (в CI приходит --build-arg MAVEN_MIRROR_URL из Gitea Variable).
|
||||||
|
ARG MAVEN_MIRROR_URL=
|
||||||
|
ENV MAVEN_MIRROR_URL=${MAVEN_MIRROR_URL}
|
||||||
|
COPY .ci/maven-settings.xml /tmp/ci-maven-settings.xml
|
||||||
|
RUN if [ -n "$MAVEN_MIRROR_URL" ]; then mkdir -p /root/.m2 && cp /tmp/ci-maven-settings.xml /root/.m2/settings.xml; fi
|
||||||
|
COPY pom.xml .
|
||||||
|
COPY wordpdf-core/pom.xml wordpdf-core/
|
||||||
|
COPY wordpdf-app/pom.xml wordpdf-app/
|
||||||
|
RUN HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= mvn -B -q dependency:go-offline
|
||||||
|
COPY . .
|
||||||
|
# Эмуляция чужой ОС в fork-нутом surefire-JVM: пусто (дефолт) — прежнее
|
||||||
|
# поведение (одна команда mvn, байт-в-байт как раньше); job `macos-sim` передаёт
|
||||||
|
# "Mac OS X" (docx4j PhysicalFonts читает os.name и уходит в
|
||||||
|
# MicrosoftFontsRegistry.getMsFonts()).
|
||||||
|
# Флаг на команде mvn попадает и в саму Maven-JVM: в Linux-JDK нет
|
||||||
|
# jdk/net/MacOSXSocketOptions, и первая же сетевая загрузка (surefire-провайдер,
|
||||||
|
# optional-зависимости, PMD-скин — всё, что НЕ закрыто dependency:go-offline)
|
||||||
|
# упала бы AssertionError на создании сокета. Поэтому при непустом флаге первым
|
||||||
|
# проходит полный verify БЕЗ флага — он догревает локальный репозиторий до нуля
|
||||||
|
# загрузок, и второй verify с флагом уже не открывает сокетов вовсе. Пустой флаг
|
||||||
|
# = один verify, прежний путь.
|
||||||
|
ARG SUREFIRE_OS_NAME=
|
||||||
|
RUN echo "SUREFIRE_OS_NAME=[${SUREFIRE_OS_NAME}]" && \
|
||||||
|
HTTP_PROXY= http_proxy= HTTPS_PROXY= https_proxy= \
|
||||||
|
sh -c '[ -z "$SUREFIRE_OS_NAME" ] || mvn -B -q clean verify || exit 1; \
|
||||||
|
exec mvn -B clean verify ${SUREFIRE_OS_NAME:+-Dos.name="$SUREFIRE_OS_NAME"}'
|
||||||
@@ -6,22 +6,6 @@
|
|||||||
идёт тем же конвейером. Шрифты упакованы в jar — конвертация не зависит от
|
идёт тем же конвейером. Шрифты упакованы в jar — конвертация не зависит от
|
||||||
шрифтов, установленных в системе (работает «из коробки» на голом сервере).
|
шрифтов, установленных в системе (работает «из коробки» на голом сервере).
|
||||||
|
|
||||||
## Возможности
|
|
||||||
|
|
||||||
- Поддержка RU/EN: кириллица и латиница встраиваются в PDF (embedded-подмножества).
|
|
||||||
- Самодостаточность: TTF выгружаются из jar в временный каталог и регистрируются
|
|
||||||
в docx4j/FOP.
|
|
||||||
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
|
|
||||||
(см. «Шрифты» ниже).
|
|
||||||
- Диаграммы и SmartArt растеризуются в PNG собственным Java2D-движком — без Word/LibreOffice.
|
|
||||||
- Бинарный `.doc` (Word 97–2003): текст, стили, таблицы, списки, колонтитуки,
|
|
||||||
картинки — собственный мост `internal/doc` без внешних зависимостей;
|
|
||||||
error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры
|
|
||||||
уже растры → вставляются картинками; EMF/WMF/PICT пропускаются с warn).
|
|
||||||
- OLE-внедрения вычищаются перед загрузкой; картинка-плейсхолдер из документа сохраняется.
|
|
||||||
- Клиентская библиотека (`wordpdf-core`), REST API (`wordpdf-app`, Spring Boot)
|
|
||||||
и веб-интерфейс (`wordpdf-web`, React SPA).
|
|
||||||
|
|
||||||
## Структура
|
## Структура
|
||||||
|
|
||||||
```
|
```
|
||||||
@@ -31,327 +15,56 @@ java-word-pdf/
|
|||||||
└── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)
|
└── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)
|
||||||
```
|
```
|
||||||
|
|
||||||
Ключевые классы (`wordpdf-core`):
|
## Быстрый старт
|
||||||
|
|
||||||
|Класс|Назначение|
|
Первая настройка — project-local mise (ставит temurin-17, maven 3.9.16, node 24,
|
||||||
|---|---|
|
python 3.15 в кеш mise, в систему ничего не идёт) + `npm ci` SPA:
|
||||||
|`ru.pjandro.wordpdf.WordPdfConverter`|публичный API: `convert(byte[], String[, ConvertOptions])` — .docx/.doc по сигнатуре байтов, байты PDF на выходе; `warmup()` — прогрев ядра|
|
|
||||||
|`ru.pjandro.wordpdf.WordPdfValidator`|валидация входа и lightweight-оценка страниц без рендера (`checkInput`/`checkPageCount`/`checkPageCountDoc`/`isBinaryDoc`/`validate`)|
|
|
||||||
|`ru.pjandro.wordpdf.ConvertOptions`|опции конвертации (record `errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages`; `ConvertOptions.defaults()`)|
|
|
||||||
|`ru.pjandro.wordpdf.ConversionException`|ошибки конвертации; подтипы `ValidationException` (некорректный вход) и `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}`)|
|
|
||||||
|`ru.pjandro.wordpdf.fonts.BundledFonts`|выгрузка TTF из jar и регистрация в docx4j|
|
|
||||||
|`ru.pjandro.wordpdf.fonts.BundledFontMapper`|маппинг имён шрифтов документа → TTF|
|
|
||||||
|`ru.pjandro.wordpdf.internal.DocxRewritePipeline`|правила 1–10 нормализации XML-частей одним zip-проходом (+ `OleObjectNormalizer`, правило 11)|
|
|
||||||
|`ru.pjandro.wordpdf.internal.doc.DocToDocx`|мост бинарного `.doc` → in-memory `.docx` (`convert`/`countPages`)|
|
|
||||||
|`ru.pjandro.wordpdf.internal.FopFallbackFonts`|декларация fallback-семейства в FOP-конфиге|
|
|
||||||
|`ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer`|диаграммы/SmartArt → PNG до XSL-FO|
|
|
||||||
|
|
||||||
## Инструменты проекта (mise)
|
|
||||||
|
|
||||||
Java, Maven, Node и Python для разработки ставит project-local mise: сам бинарь —
|
|
||||||
в `./.mise/bin` (gitignored), кеш инструментов — в user-директории mise, в систему
|
|
||||||
ничего не устанавливается. Версии зафиксированы в корневом `mise.toml`
|
|
||||||
(temurin-17, maven 3.9.16, node 24, python 3.15).
|
|
||||||
|
|
||||||
Первая настройка — скачивает mise, ставит инструменты и делает `npm ci` SPA:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
sh bootstrap.sh # Linux / macOS
|
sh bootstrap.sh # Linux / macOS
|
||||||
```
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
|
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
|
||||||
```
|
```
|
||||||
|
|
||||||
Дальше команды — через обёртку `./mise.sh` (Linux/macOS) или `.\mise.ps1` (Windows):
|
Дальше всё через обёртку `./mise.sh` (Windows: `.\mise.ps1`):
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./mise.sh run verify # полный гейт перед push: тесты + PMD + JaCoCo
|
./mise.sh run verify # полный гейт перед push: тесты + PMD + JaCoCo
|
||||||
./mise.sh exec -- mvn -v # любая команда с инструментами проекта в PATH
|
./mise.sh run app-package && ./mise.sh run app-run # бэкенд на :8080, ключ выключен
|
||||||
./mise.sh tasks # список задач с описаниями
|
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
||||||
```
|
```
|
||||||
|
|
||||||
Задачи проекта (`./mise.sh run <задача>`):
|
Стенды на контейнерах (podman), наружный вход — только nginx-gateway:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32
|
||||||
|
podman-compose up -d --build # prod-like :9010 (fail-closed: без ключа не встанет)
|
||||||
|
podman-compose -f compose.dev.yml up -d --build --force-recreate # dev :9011, без ключа
|
||||||
|
```
|
||||||
|
|
||||||
|
## Задачи проекта (`./mise.sh run <задача>`)
|
||||||
|
|
||||||
|Задача|Содержание|
|
|Задача|Содержание|
|
||||||
|---|---|
|
|---|---|
|
||||||
|`verify`|`mvn clean verify` — тесты + PMD + JaCoCo|
|
|`verify`|`mvn clean verify` — тесты + PMD + JaCoCo|
|
||||||
|`app-package`|исполняемый jar бэкенда|
|
|`verify-nofontconfig`|тот же verify в контейнере без fontconfig (гейт CI; требует podman/docker)|
|
||||||
|`app-run`|бэкенд на :8080, ключ выключен (после `app-package`)|
|
|`mem-bench`|замер памяти конвейера (TSV пиков + JFR)|
|
||||||
|`web-install`|`npm ci` в `wordpdf-web`|
|
|`app-package` / `app-run`|исполняемый jar бэкенда / бэкенд на :8080|
|
||||||
|`web-build`|гейт SPA: `tsc -b && vite build`|
|
|`web-install` / `web-build` / `web-lint` / `web-dev`|SPA: `npm ci` / гейт `tsc -b && vite build` / oxlint / :5173|
|
||||||
|`web-lint`|oxlint|
|
|
||||||
|`web-dev`|SPA на :5173, vite-proxy на :8080|
|
|
||||||
|`prod-tests`|прод-автотесты; обязателен `WORDPDF_BASE_URL`, факультативно `WORDPDF_API_KEY`|
|
|`prod-tests`|прод-автотесты; обязателен `WORDPDF_BASE_URL`, факультативно `WORDPDF_API_KEY`|
|
||||||
|
|`docs-install` / `docs-serve` / `docs-build`|сайт документации: venv+pip / preview :8000 / strict-сборка в `site/`|
|
||||||
|
|`docs-javadoc` / `docs-deploy`|javadoc core / публикация сайта на rpi (:9012)|
|
||||||
|
|
||||||
Альтернатива обёртке — активировать mise в шелле и работать напрямую
|
Альтернатива обёртке — активировать mise в шелле и работать напрямую
|
||||||
(`mvn`, `npm`, `python`): `eval "$(./.mise/bin/mise activate bash)"`.
|
(`mvn`, `npm`, `python`): `eval "$(./.mise/bin/mise activate bash)"`.
|
||||||
|
|
||||||
## Сборка
|
## Документация
|
||||||
|
|
||||||
Требуется **Java 17** и **Maven** (бэкенд), **Node.js `^20.19.0 || >=22.12.0`**
|
- **Сайт документации** (пользователю / REST API / библиотека / архитектура /
|
||||||
(engines Vite 8; mise ставит Node 24) — всё это ставит project-local mise
|
разработчику / эксплуатация): `http://192.168.88.23:9012/`
|
||||||
(см. «Инструменты проекта (mise)» выше). Команды ниже запускайте через
|
— исходники в `docs/`, публикация `./mise.sh run docs-deploy`,
|
||||||
`./mise.sh exec -- …` (Windows: `.\mise.ps1 exec -- …`) либо после активации mise в шелле.
|
javadoc — там же по `/apidocs/`.
|
||||||
|
- Веб-конвертер (прод): `https://pjandro.ru/pdf-converter/`.
|
||||||
```bash
|
- Внутренние справочники для правки кода — `docs/agent/` (pipeline, doc-bridge,
|
||||||
mvn clean verify # все модули + тесты
|
chart, render-limitations, testing, ci-cd, repo-map), нормативные спецификации
|
||||||
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
|
форматов — `docs/standards/`.
|
||||||
```
|
- Правила репозитория — `AGENTS.md`.
|
||||||
|
|
||||||
Результат: `wordpdf-app/target/wordpdf-app-<версия>.jar` (все зависимости
|
|
||||||
внутри). Для фронтенда — отдельные команды (вне Maven): `npm ci && npm run build`
|
|
||||||
в `wordpdf-web/` — по закоммиченному `package-lock.json` (то же делают задачи
|
|
||||||
mise `web-install`/`web-build`; результат — статика в `wordpdf-web/dist/`).
|
|
||||||
|
|
||||||
## Использование
|
|
||||||
|
|
||||||
### REST API
|
|
||||||
|
|
||||||
```bash
|
|
||||||
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
|
|
||||||
curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \
|
|
||||||
http://localhost:8080/api/v1/convert -o doc.pdf
|
|
||||||
```
|
|
||||||
|
|
||||||
`POST /api/v1/convert` принимает multipart-поле `file` (.docx или .doc) и синхронно
|
|
||||||
возвращает байты PDF (`application/pdf`, `Content-Disposition: attachment;
|
|
||||||
filename*=UTF-8''…` — имя файла санитизировано, кириллица разрешена).
|
|
||||||
|
|
||||||
**Ключ доступа.** Заголовок `X-API-Key` сверяется со свойством `wordpdf.api-key`
|
|
||||||
(env `WORDPDF_API_KEY`); пустое свойство — аутентификация выключена (`java -jar`,
|
|
||||||
dev-стенд). Без ключа открыты `/actuator/`, `/swagger-ui`, `/v3/api-docs`; без ключа
|
|
||||||
или с неверным — 401 `{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}`.
|
|
||||||
|
|
||||||
**Факультативные query/form-параметры** `errorOnCharts`/`errorOnSmartArt`/`errorOnOle`
|
|
||||||
(Boolean, дефолт `false`): при `true` соответствующие объекты в документе отменяют
|
|
||||||
конвертацию с 422. Диаграммы/SmartArt конвертируются в растры всегда; OLE-объекты
|
|
||||||
при `errorOnOle=false` тихо удаляются.
|
|
||||||
|
|
||||||
**Лимиты входа** задаёт только конфигурация сервера: `wordpdf.max-mb`/`wordpdf.max-pages`
|
|
||||||
(env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`, дефолты 5 МБ / 100 страниц); параметрами
|
|
||||||
запроса не переопределяются.
|
|
||||||
|
|
||||||
|Код|Смысл|
|
|
||||||
|---|---|
|
|
||||||
|200|PDF в теле ответа|
|
|
||||||
|400|некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше `wordpdf.max-mb` / больше `wordpdf.max-pages` страниц), отсутствующая часть `file`, некорректное значение error-флага|
|
|
||||||
|401|нет или неверен `X-API-Key`|
|
|
||||||
|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)|
|
|
||||||
|405|не-POST|
|
|
||||||
|413|тело запроса больше контейнерного лимита multipart (100 МБ; авторитетный лимит входа — `wordpdf.max-mb`, он даёт 400 раньше)|
|
|
||||||
|415|не-multipart тело|
|
|
||||||
|422|сработал error-флаг: в документе найдены диаграммы / SmartArt / OLE-объекты|
|
|
||||||
|500|ошибка ядра/рендера|
|
|
||||||
|503|очередь конвертации (16 мест) переполнена — повторить позже|
|
|
||||||
|504|конвертация дольше `wordpdf.convert-timeout` (по умолчанию 2m)|
|
|
||||||
|
|
||||||
Ошибки — JSON `{"error": "..."}`. Конвертации сериализуются одним воркером: ядро
|
|
||||||
мутирует глобальный реестр шрифтов; головой очереди на старте стоит `warmup()` —
|
|
||||||
первый запрос после деплоя идёт за прогретым ядром (~0,1–0,4 с вместо 1,4–1,9 с).
|
|
||||||
Интерактивная документация: Swagger UI —
|
|
||||||
`/swagger-ui.html`, OpenAPI — `/v3/api-docs` (доступны на `java -jar` и dev-стенде;
|
|
||||||
в compose-стеке springdoc выключён: `SPRINGDOC_API_DOCS_ENABLED=false`,
|
|
||||||
`SPRINGDOC_SWAGGER_UI_ENABLED=false`).
|
|
||||||
|
|
||||||
### Библиотека
|
|
||||||
|
|
||||||
```java
|
|
||||||
import ru.pjandro.wordpdf.WordPdfConverter;
|
|
||||||
import ru.pjandro.wordpdf.ConvertOptions;
|
|
||||||
import java.nio.file.Files;
|
|
||||||
import java.nio.file.Path;
|
|
||||||
|
|
||||||
byte[] docx = Files.readAllBytes(Path.of("doc.docx"));
|
|
||||||
byte[] pdf = WordPdfConverter.convert(docx, "doc"); // заголовок PDF
|
|
||||||
// с опциями: errorOnCharts/errorOnSmartArt/errorOnOle, лимиты МБ/страниц
|
|
||||||
pdf = WordPdfConverter.convert(docx, "doc", new ConvertOptions(true, false, false, 5, 100));
|
|
||||||
Files.write(Path.of("out.pdf"), pdf);
|
|
||||||
```
|
|
||||||
|
|
||||||
Ошибки валидации (содержимое не `.docx`/не `.doc` по сигнатуре, размер больше
|
|
||||||
5 МБ, страниц больше ста, зашифрованный `.doc`) бросают `ValidationException`
|
|
||||||
(подтип `ConversionException`). Формат определяется по сигнатуре байтов:
|
|
||||||
`PK\x03\x04` → .docx-путь, CFB-подпись `D0 CF 11 E0 A1 B1 1A E1` → мост → тот же
|
|
||||||
конвейер. Те же проверки без рендера доступны отдельно:
|
|
||||||
`WordPdfValidator.validate(bytes, options)`.
|
|
||||||
Работа с файлами — забота вызывающего: ядро пути не принимает.
|
|
||||||
|
|
||||||
#### Зависимость commons-compress (интеграция в чужой проект)
|
|
||||||
|
|
||||||
Ядру (через docx4j) нужен `org.apache.commons:commons-compress >= 1.25.0`,
|
|
||||||
рекомендована `1.28.0` — версию закрепляет POM ядра. Симптом старой версии в
|
|
||||||
classpath потребителя — `NoSuchMethodError:
|
|
||||||
org.apache.commons.compress.archivers.zip.ZipArchiveEntry
|
|
||||||
org.apache.commons.compress.archivers.zip.ZipArchiveInputStream.getNextEntry()`.
|
|
||||||
До входа в docx4j теперь срабатывает guard: `ConversionException` с текстом,
|
|
||||||
объясняющим, какую версию закрепить.
|
|
||||||
|
|
||||||
**Maven.** BOM (например, Spring Boot 3.x) пинит свою версию commons-compress,
|
|
||||||
а `dependencyManagement` потребителя перекрывает транзитивные версии
|
|
||||||
(«nearest wins») — закреплять нужно именно в нём:
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<dependencyManagement>
|
|
||||||
<dependencies>
|
|
||||||
<dependency>
|
|
||||||
<groupId>org.apache.commons</groupId>
|
|
||||||
<artifactId>commons-compress</artifactId>
|
|
||||||
<version>1.28.0</version>
|
|
||||||
</dependency>
|
|
||||||
</dependencies>
|
|
||||||
</dependencyManagement>
|
|
||||||
```
|
|
||||||
|
|
||||||
Диагностика: `mvn dependency:tree -Dincludes=org.apache.commons:commons-compress`.
|
|
||||||
|
|
||||||
**Gradle.** По умолчанию Gradle выбирает максимальную версию и конфликт
|
|
||||||
разрешает сам — guard не сработает и не нужен. Понижает версию только явный
|
|
||||||
`constraints` / `platform` / `resolutionStrategy`: уберите понижение либо
|
|
||||||
закрепите нужную версию:
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
dependencies {
|
|
||||||
constraints {
|
|
||||||
implementation("org.apache.commons:commons-compress:1.28.0")
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
(либо `resolutionStrategy.force("org.apache.commons:commons-compress:1.28.0")`).
|
|
||||||
Диагностика: `gradle dependencies --configuration runtimeClasspath`.
|
|
||||||
|
|
||||||
### Веб-интерфейс и контейнеры (podman)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32
|
|
||||||
podman-compose up -d --build
|
|
||||||
```
|
|
||||||
|
|
||||||
Наружный вход — nginx-контейнер `gateway` на `http://localhost:9010/` (контейнер
|
|
||||||
`app` наружу не публикуется). Файл `compose.yml` fail-closed: без `WORDPDF_API_KEY`
|
|
||||||
в `.env` стек не поднимется. Маршруты gateway: `/api/`, `/swagger-ui`,
|
|
||||||
`/v3/api-docs`, `/actuator` → `app:8080` (таймауты прокси 300s,
|
|
||||||
`client_max_body_size 100m`), остальное → `web` — чистая статика SPA.
|
|
||||||
|
|
||||||
Dev-стенд без ключа, с включённым springdoc:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
podman-compose -f compose.dev.yml up -d --build --force-recreate # http://<LAN-IP>:9011
|
|
||||||
```
|
|
||||||
|
|
||||||
(`--force-recreate` обязателен: без него podman-compose пересоберёт образ, но
|
|
||||||
контейнеры оставит на старом — будет крутиться jar прошлой сборки)
|
|
||||||
|
|
||||||
Dev-режим без контейнеров: бэкенд `java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar`
|
|
||||||
(порт 8080, ключ выключен) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173`
|
|
||||||
(Vite проксирует `/api`, `/swagger-ui`, `/v3/api-docs` на 8080, CORS не нужен).
|
|
||||||
|
|
||||||
## Шрифты
|
|
||||||
|
|
||||||
В `wordpdf-core/src/main/resources/fonts/` упакованы 30 TTF: 7 текстовых
|
|
||||||
семейств по 4 начертания плюс два покрывающих шрифта (только regular):
|
|
||||||
|
|
||||||
| Семейство | Аналог MS-шрифта |
|
|
||||||
|---|---|
|
|
||||||
| Carlito | Calibri |
|
|
||||||
| Caladea | Cambria |
|
|
||||||
| Arimo | Arial |
|
|
||||||
| Tinos | Times New Roman |
|
|
||||||
| Cousine | Courier New |
|
|
||||||
| DejaVu Sans / DejaVu Serif | fallback |
|
|
||||||
| Noto Naskh Arabic | арабские дополнения U+07B1–U+08FF |
|
|
||||||
| Noto Sans Armenian | армянские знаки Unicode 16 |
|
|
||||||
|
|
||||||
`BundledFontMapper` подставляет метрически совместимые аналоги при конвертации
|
|
||||||
(`Calibri → Carlito` и т.д.). Нераспознанные шрифты и символы, не найденные в
|
|
||||||
шрифте ранa (em-dash «—», кавычки, U+2000–U+2EFF), падают в **DejaVu Sans**
|
|
||||||
(гарантированная кириллица). Знак, которого нет ни в шрифте ранa, ни там, куда
|
|
||||||
его отправил docx4j, ищет себе место сам: `GlyphCoverageNormalizer` режет такой
|
|
||||||
ран и для каждой части назначает покрывающее семейство — serif-раны в
|
|
||||||
**DejaVu Serif**, sans — в **DejaVu Sans**, экзотика — в Noto. Все шрифты
|
|
||||||
встраиваются в PDF как подмножества.
|
|
||||||
|
|
||||||
### Лицензии шрифтов
|
|
||||||
|
|
||||||
- Arimo, Cousine, Tinos, Carlito, Caladea — **SIL OFL 1.1**
|
|
||||||
(см. `fonts/FONT-LICENSE.txt`).
|
|
||||||
- DejaVu Sans / DejaVu Serif — **SIL OFL 1.1 / Bitstream Vera**
|
|
||||||
(см. `fonts/DejaVu-LICENSE.txt`).
|
|
||||||
- Noto Naskh Arabic, Noto Sans Armenian — **SIL OFL 1.1**
|
|
||||||
(см. `fonts/Noto-LICENSE.txt`).
|
|
||||||
|
|
||||||
## Как это работает
|
|
||||||
|
|
||||||
```
|
|
||||||
.docx/.doc ──> валидация входа ──> (.doc: мост → .docx в памяти)
|
|
||||||
──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
|
|
||||||
──> диаграммы → PNG ──> XSL-FO (вендорный XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Вход проверяется до рендера: размер → сигнатура (zip PK или CFB) → (.docx:
|
|
||||||
контейнер и страницы lightweight-StAX по zip; .doc: страницы по чистому
|
|
||||||
бинарному документу мостом) — `WordPdfValidator`, без зависимости от docx4j.
|
|
||||||
2. XML-части переписывает `DocxRewritePipeline` одним zip-проходом — десять
|
|
||||||
правил (порядок значим): strict→transitional (`w:start`/`w:end`, проценты),
|
|
||||||
`on/off` → `true/false` (иначе docx4j теряет значение, и regular-раны
|
|
||||||
рендерились жирным курсивом), маркеры Symbol/Wingdings → Unicode (вместо «#»),
|
|
||||||
поля `PAGE`/`NUMPAGES` → `w:fldSimple` (пересчитываются, а не печатают кэш
|
|
||||||
из docx), невидимые символы, раны со знаками вне их шрифта (резка по покрытию
|
|
||||||
глифов), `w:jc` center/right + `w:tblInd` → абсолютный отступ таблицы,
|
|
||||||
`w:suff="space"` → пробел в номере списка, скрытые раны (`w:vanish`), руби
|
|
||||||
(надстрочница вырезается). Затем вычищаются OLE-объекты (правило 11,
|
|
||||||
`OleObjectNormalizer`, картинка-плейсхолдер сохраняется).
|
|
||||||
3. Документ загружается в `WordprocessingMLPackage`, привязывается
|
|
||||||
`BundledFontMapper`.
|
|
||||||
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi
|
|
||||||
(`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
|
|
||||||
5. Экспорт в XSL-FO идёт вендорным стилем `xslt/docx2fo.xslt` (копия стилиста
|
|
||||||
docx4j-export-fo с AUDIT-FIX-патчами: `w:position` → `baseline-shift`,
|
|
||||||
`w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir`), перед рендером `LayoutPostRenderer`
|
|
||||||
компенсирует расхождение docx4j↔Word по padding таблиц; `Apache FOP`
|
|
||||||
(форк `docx4j-fo-renderer`) рендерит PDF, встраивая подмножества шрифтов.
|
|
||||||
|
|
||||||
## Ограничения
|
|
||||||
|
|
||||||
- Это **не** pixel-perfect рендер Word: раскладка, поля и некоторые эффекты
|
|
||||||
приближённые (ограничения FOP/docx4j, а не «мы что-то упустили»).
|
|
||||||
- Символы U+2000–U+2EFF (em-dash и т.п.) берутся из шрифта ранa, если в нём
|
|
||||||
есть глиф, иначе — из fallback-семейства DejaVu.
|
|
||||||
- Знаков, которых нет ни в одном шрифте бандла, это не касается: вместо них
|
|
||||||
остаётся `.notdef`. В эталонном экспорте Word (`develop/`, вне git) таких два — U+2188 (ↈ)
|
|
||||||
и U+218A (↊), они есть только в GNU FreeSerif под GPL, а бандл держится
|
|
||||||
целиком на SIL OFL.
|
|
||||||
- Поддержка таблиц/изображений — базовая (через docx4j/FOP).
|
|
||||||
- Часть расхождений с Word — неустранимые невозможности FOP/docx4j
|
|
||||||
(`jc="distribute"`, `suff="tab"`, кернинг, `framePr`, кэш `REF`/`SEQ`/`TOC`,
|
|
||||||
надстрочница руби) — полный перечень с доказательствами:
|
|
||||||
`docs/agent/render-limitations.md`.
|
|
||||||
- На `.doc` error-флаги диаграмм/SmartArt/OLE не срабатывают: BLIP-плейсхолдеры
|
|
||||||
бинарного формата — уже растры, они вставляются картинками; EMF/WMF/PICT
|
|
||||||
пропускаются с warn.
|
|
||||||
|
|
||||||
## Тесты
|
|
||||||
|
|
||||||
Тесты используют 25 закоммиченных фикстур (13 `.docx` + 12 `.doc`) из
|
|
||||||
`wordpdf-core/src/test/resources/samples/` (в тестах не генерируются; пересоздание —
|
|
||||||
test-утилита `SampleDocxGenerator`) и проверяют извлечённый PDFBox'ом текст и
|
|
||||||
встраивание шрифтов. Запуск: `mvn test`; полный гейт перед push —
|
|
||||||
`./mise.sh run verify` (тесты + PMD + JaCoCo).
|
|
||||||
|
|
||||||
API (`wordpdf-app`) проверяется `MockMvc`-сквозняками (`ConvertControllerTest`)
|
|
||||||
на тех же фикстурах — ядро отдаёт их test-jar'ом.
|
|
||||||
|
|
||||||
## CI/CD и деплой
|
|
||||||
|
|
||||||
- Pull request → Gitea Actions (`pr.yml`): Java — `mvn clean verify` + сводка покрытия комментарием в 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`
|
|
||||||
зависимостей + `pytest -q .` в `prod-autotests/`):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
WORDPDF_BASE_URL=<стенд> WORDPDF_API_KEY=<ключ> ./mise.sh run prod-tests
|
|
||||||
```
|
|
||||||
|
|
||||||
31 проверка; без ключа 27 требующих его пропускаются.
|
|
||||||
|
|||||||
+3
-2
@@ -15,8 +15,9 @@ services:
|
|||||||
app:
|
app:
|
||||||
build: .
|
build: .
|
||||||
restart: unless-stopped
|
restart: unless-stopped
|
||||||
# Паритет с compose.yml: heap вписан в лимит (-XX:MaxRAMPercentage=70).
|
# Паритет с compose.yml: фиксированный heap -Xms2g -Xmx2g в ENTRYPOINT,
|
||||||
mem_limit: 2g
|
# лимит 3g — запас под metaspace/потоки/native.
|
||||||
|
mem_limit: 3g
|
||||||
# Дублирует HEALTHCHECK из Containerfile: podman выгружает образы в OCI,
|
# Дублирует HEALTHCHECK из Containerfile: podman выгружает образы в OCI,
|
||||||
# где поля healthcheck нет — без явного healthcheck depends_on
|
# где поля healthcheck нет — без явного healthcheck depends_on
|
||||||
# service_healthy ждал бы healthy вечно. Прокси обнуляем на команде.
|
# service_healthy ждал бы healthy вечно. Прокси обнуляем на команде.
|
||||||
|
|||||||
+4
-3
@@ -7,9 +7,10 @@ services:
|
|||||||
app:
|
app:
|
||||||
build: .
|
build: .
|
||||||
restart: unless-stopped
|
restart: unless-stopped
|
||||||
# Heap вписываем в лимит контейнера (-XX:MaxRAMPercentage=70 в ENTRYPOINT);
|
# Фиксированный heap -Xms2g -Xmx2g в ENTRYPOINT образа; лимит 3g — запас
|
||||||
# вход 16×5 МБ очередь + FOP-рендер в 2 ГБ помещаются.
|
# под metaspace/потоки/native. Вход 16×5 МБ + FOP-рендер в 2 ГБ heap
|
||||||
mem_limit: 2g
|
# помещаются.
|
||||||
|
mem_limit: 3g
|
||||||
# Дублирует HEALTHCHECK из Containerfile: podman выгружает образы в OCI,
|
# Дублирует HEALTHCHECK из Containerfile: podman выгружает образы в OCI,
|
||||||
# где поля healthcheck нет — без явного healthcheck depends_on
|
# где поля healthcheck нет — без явного healthcheck depends_on
|
||||||
# service_healthy ждал бы healthy вечно. Прокси обнуляем на команде.
|
# service_healthy ждал бы healthy вечно. Прокси обнуляем на команде.
|
||||||
|
|||||||
@@ -0,0 +1,190 @@
|
|||||||
|
# Потребление памяти при конвертации doc/docx → pdf: аудит и результаты апгрейда (2026-11)
|
||||||
|
|
||||||
|
Харнес: `MemoryBench` (`wordpdf-core/src/test/java/ru/pjandro/wordpdf/MemoryBench.java`, test-scope) +
|
||||||
|
`membench.sh` + `./mise.sh run mem-bench`. Числа ниже получены на них; методология и ограничения — §1.
|
||||||
|
|
||||||
|
## 1. Методология измерения
|
||||||
|
|
||||||
|
JVM: temurin 17.0.21, флаги харнеса `-Xms64m -Xmx2g -XX:+UseG1GC -XX:+HeapDumpOnOutOfMemoryError`
|
||||||
|
+ JFR `settings=profile` + `-Xlog:gc*=info,gc+heap=debug`. Машина — рабочая станция (amd64), не прод-контейнер.
|
||||||
|
|
||||||
|
Метрики на конвертацию (TSV-строки вывода харнеса):
|
||||||
|
|
||||||
|
|Метрика|Как снята|Смысл|
|
||||||
|
|---|---|---|
|
||||||
|
|`peak`|`MemoryPoolMXBean.getPeakUsage()` по хип-пулам с `reset()` перед каждой конвертацией|высокая вода кучи за конвертацию (включает невозвращённый мусор young-поколения — это мера запроса памяти, не live-сета)|
|
||||||
|
|`used`|сумма `getUsage().getUsed()` сразу после конвертации|куча «как есть» до ближайшего GC|
|
||||||
|
|`allocated-estimate`|GC-лог: выметенный Eden + humongous между паузами|честная оценка аллокаций (JFR-веса для этого не годятся — см. ограничения)|
|
||||||
|
|`max-live-after-gc`|GC-лог: максимум `M->M(after)` по паузам|живая куча после GC (включает конвертацию, идущую в момент паузы)|
|
||||||
|
|`VmHWM`|`/proc/self/status`|пик резидентной памяти процесса (куча + Metaspace + стеки + JFR-буферы)|
|
||||||
|
|`top-frames`/`app-sites`|агрегация `jdk.ObjectAllocationSample` из JFR|профиль аллокаций (относительная доля; веса — оценка сэмплера)|
|
||||||
|
|
||||||
|
Сценарии: `suite` — все 25 фикстур `samples/` (13 `.docx` + 12 `.doc`) циклами; `big` — синтетический
|
||||||
|
документ: `document.xml` фикстуры `ru-plain.docx` с повтором секции ×400 (≈1,6 МБ XML после
|
||||||
|
распаковки, ≈6000 строк контента, PDF ≈50 КБ/конвертация — много контента при малом in-put,
|
||||||
|
именно он и нагружает конвейер, а не байты входа).
|
||||||
|
|
||||||
|
Ограничения (важно для повторного прочтения чисел):
|
||||||
|
|
||||||
|
- **шум ±30% на фикстуру** между прогонами (старт нового JVM на сценарий, G1 растягивает young по
|
||||||
|
ходу прогона); сравнимы только суммарные/медианные агрегаты одного метода на одном железе;
|
||||||
|
- `peak` включает мусор: документ с большим churn даёт большой peak при малом live-сете;
|
||||||
|
- веса JFR `ObjectAllocationSample` (profile, period=20ms) — оценка сэмплера; абсолют — только GC-лог;
|
||||||
|
- фикстуры малы (вход ≤182 КБ, PDF в среднем 385 КБ): кандидаты, экономящие единицы мегабайт,
|
||||||
|
на них неотличимы от шума — это учитывалось в гейтах (§4).
|
||||||
|
|
||||||
|
Воспроизведение: `MB_LABEL=run ./mise.sh run mem-bench --scenario all --loops 20 | tee target/mem-run.txt`;
|
||||||
|
матрица флагов — через env `MB_JAVA_OPTS` (флаги идут после дефолтных и переопределяют их).
|
||||||
|
|
||||||
|
## 2. Baseline (до правок)
|
||||||
|
|
||||||
|
`MB_LABEL=before ./mise.sh run mem-bench --scenario all --loops 20` (JVM 17.0.21, пик 2026-11-17):
|
||||||
|
|
||||||
|
|Фикстура|n|peak p50, МБ|peak max, МБ|used avg, МБ|
|
||||||
|
|---|---|---|---|---|
|
||||||
|
|chart-types.docx|20|641|934|398|
|
||||||
|
|charts-smartart.doc|20|457|630|321|
|
||||||
|
|charts-smartart.docx|20|471|751|299|
|
||||||
|
|doc-formats.doc|20|261|783|326|
|
||||||
|
|en-plain.doc|20|302|819|273|
|
||||||
|
|en-plain.docx|20|278|855|298|
|
||||||
|
|exotic-glyphs.doc|20|328|907|325|
|
||||||
|
|exotic-glyphs.docx|20|312|950|287|
|
||||||
|
|ole-embedded.doc|20|298|540|238|
|
||||||
|
|ole-embedded.docx|20|269|574|222|
|
||||||
|
|page-numbers.doc|20|234|598|257|
|
||||||
|
|page-numbers.docx|20|272|558|266|
|
||||||
|
|ru-en-mixed.doc|20|300|453|293|
|
||||||
|
|ru-en-mixed.docx|20|344|528|298|
|
||||||
|
|ru-plain.doc|20|344|572|256|
|
||||||
|
|ru-plain.docx|20|281|455|274|
|
||||||
|
|ru-table-image.doc|20|331|462|267|
|
||||||
|
|ru-table-image.docx|20|299|522|263|
|
||||||
|
|ru-times.doc|20|275|561|275|
|
||||||
|
|ru-times.docx|20|251|580|256|
|
||||||
|
|stale-cache.doc|20|307|511|264|
|
||||||
|
|stale-cache.docx|20|323|525|269|
|
||||||
|
|symbol-bullets.docx|20|335|459|310|
|
||||||
|
|too-many-pages.doc|20|405|599|265|
|
||||||
|
|too-many-pages.docx|20|327|724|288|
|
||||||
|
|big (синтетика ×400)|5|924|976|360|
|
||||||
|
|
||||||
|
Итоги прогона: `allocated-estimate=36069MB` (≈71 МБ churn на конвертацию при медианном peak 300 МБ),
|
||||||
|
`max-live-after-gc=504MB`, паузы 536 шт./4815 мс; `VmHWM` процесса: 1,34 ГБ после suite-части,
|
||||||
|
1,56 ГБ после big-части (`-Xmx2g` доступен, куча растягивается под churn).
|
||||||
|
|
||||||
|
Главный вывод baseline: **память уходит не в копии документа, а в churn конвейера**. Вход 2,6–182 КБ
|
||||||
|
при peak 224–641 МБ — отношение долей порядка сотен. Профиль аллокаций (JFR, alloc-total —
|
||||||
|
оценка сэмплера 26,3 МБ взвешенных):
|
||||||
|
|
||||||
|
- доли приложения в топ-кадрах: `DocxRewritePipeline.normalize` — 0,44%, `WordPdfConverter.convert` —
|
||||||
|
0,36%, `GlyphFont.draw` — 0,10%; все остальные кадры `ru.pjandro.*` — ниже 0,1% (гейты §4);
|
||||||
|
- остальное — библиотеки: JAXB-андмаршалинг docx4j через DOM (`DOMScanner.visit/scan`,
|
||||||
|
`SAXOutput.getQName`, `NamespaceContextImpl.put`, `SAX2DOMEx.startElement`, `ClassFactory.create0`),
|
||||||
|
Xalan/XSLT, FOP (таблицы OpenType: `OTFAdvancedTypographicTableReader`, `OpenFont.readHorizontalMetrics`),
|
||||||
|
commons-io `IOUtils.byteArray`, `Arrays.copyOf`, `Throwable.fillInStackTrace` (docx4j использует
|
||||||
|
исключения как control flow — «Package field null» и т.п.);
|
||||||
|
- ~~JEuclid (`Parser.parseStreamSourceAsOdf`) — OMML-формулы на хосте с fontconfig (в CI/контейнере
|
||||||
|
иначе: MathFallback)~~ — **удалён из класса путей** (2026-11): jeuclid исключён exclusion'ом из
|
||||||
|
`docx4j-export-fo`, формулы рисует собственный `MathRenderer` (PNG, только бандл-шрифты);
|
||||||
|
`MathFallbackNormalizer` теперь деградирует в текст только конструкции вне `MathModel.SUPPORTED`.
|
||||||
|
|
||||||
|
## 3. Что нашли при чтении кода (архитектурные находки)
|
||||||
|
|
||||||
|
1. **FO материалзуется как `String`.** Форк `FORendererApacheFOP.convert(FODocumentHandler,
|
||||||
|
FOConverterContext, String)` (javap docx4j-export-fo 17.3.2) принимает весь выход XSLT одной
|
||||||
|
строкой UTF-16: для FO-документа это ≈2 байта/символ и FO в разы больше исходного XML.
|
||||||
|
Убрать можно только правкой форка (`templates.transform` стримом в FOP-парсер) — вне рамок
|
||||||
|
репозитория; фиделити-риск высокий. Дорожная карта.
|
||||||
|
2. **`disableFontCache()` в форке вызывается безусловно в 3 местах** (javap `FORendererApacheFOP`:
|
||||||
|
`FontManager.disableFontCache`), один участок защищён `Fop.isUseCache()` из fop.xconf
|
||||||
|
(по умолчанию кеш выключен) → таблицы шрифтов перечитываются на каждый рендер (видно в топ-кадрах).
|
||||||
|
Потенциальный рычаг (churn+CPU), но включение кеша влияет на сабзеттинг/метрики — только с
|
||||||
|
фиделити-прогоном, в форк/конфиг. Дорожная карта.
|
||||||
|
3. **`WordprocessingMLPackage` в docx4j 17.3.2 не имеет `close()`/`dispose()`** (javap пакета
|
||||||
|
`openpackaging.packages`/`parts` — только `setJaxbElement`/`unmarshal`): «освободить пакет явно»
|
||||||
|
API не даёт; пакет — локальная переменная `convertToStream` и умирает вместе со стеком.
|
||||||
|
4. **Валидатор делает два полных стриминговых прохода** по байтам входа (`checkPageCount` +
|
||||||
|
`checkDocxContainer`/`validate`): CPU, память O(8 КБ буферов) — на peak не влияет (§4, гейт E).
|
||||||
|
5. **Мост `.doc` уже отпускает потоки** (`releaseStreams`), но `DocxWriter.write` держит одновременно
|
||||||
|
`bodyXml`+`parts`+`hyperlinks` до `toByteArray()`; на фикстурах доля моста в аллокациях <0,15% —
|
||||||
|
не рычаг при текущих документах (§4, гейт C).
|
||||||
|
|
||||||
|
## 4. Кандидаты оптимизаций и гейты
|
||||||
|
|
||||||
|
Гейт: кандидат остаётся, только если после правки suite-сумма peak или big-peak улучшились ≥3%
|
||||||
|
(для «всегдашнего» A — плюс отсутствие регрессии); для B/C/E — плюс доля ≥5% в app-sites JFR.
|
||||||
|
Прогоны «до/после» — идентичной методикой, один и тот же компьютер, подряд.
|
||||||
|
|
||||||
|
|Кандидат|Доля в аллокациях (гейт 5%)|Замер после (гейт 3%)|Итог|
|
||||||
|
|---|---|---|---|
|
||||||
|
|A. Чанковый буфер PDF вместо `ByteArrayOutputStream`|—|`allocated` +0,7% (шум), сумма peak **+7,2% (хуже)**|отклонён, откачен|
|
||||||
|
|B. Needle-гейт декода в `DocxRewritePipeline`|`normalize` 0,44%|—|отклонён до правки|
|
||||||
|
|C. Ранний отпуск `bodyXml`/`parts`/`hyperlinks` в `DocxWriter.write`|кадров моста в топ-15 нет (<0,15%)|—|отклонён до правки|
|
||||||
|
|D. Явный release пакета docx4j|API отсутствует (§3.3)|—|нереализуем|
|
||||||
|
|E. Один проход валидатора|кадров валидатора в топ-15 нет (<0,1%)|—|отклонён до правки (плюс риск порядка ошибок — контракт 400-кодов)|
|
||||||
|
|
||||||
|
**Почему A отклонён измерением, хотя «в теории» экономит.** Реализация (`PdfOutputChunks`,
|
||||||
|
чанки вместо удваивающегося `byte[]`) протестирована на эквивалентность байтов и прогнана полным
|
||||||
|
бенчем (25 фикстур ×20 + big ×5, тот же метод):
|
||||||
|
|
||||||
|
- PDF фикстур в среднем 385 КБ: для них `PdfOutputChunks` с фиксированным чанком выделяет больше,
|
||||||
|
чем рост `ByteArrayOutputStream` от `Math.max(1<<16, docxBytes.length)` — сумма peak выросла на 7,2%;
|
||||||
|
- микробенч на 24 МБ (одноразовый `PeakProof`, куча 2г): peak 76 МБ у чанков против 61 МБ у BAOS —
|
||||||
|
чанк 1 МиБ на G1 humongous (регион 1 МиБ → 2 региона на чанк, отсюда ×2), чанк 256 КиБ уходит в
|
||||||
|
young и при подсчёте `peak` платит растянутым Eden; live-минимум чанков (P+P против 2–3P у BAOS)
|
||||||
|
выигрывает только на PDF десятки мегабайт, каких в фикстурах нет;
|
||||||
|
- вердикт гейта: не улучшено → откачен, конвейер остался на `ByteArrayOutputStream`.
|
||||||
|
|
||||||
|
**Итог по правкам ядра: ни один кандидат не прошёл гейт.** Это не «нечего улучшать», а «у текущих
|
||||||
|
документов память тратят библиотеки» (JAXB-via-DOM, XSLT, FOP-шрифты — §2; JEuclid больше
|
||||||
|
не потребитель — исключён из зависимостей): точечными
|
||||||
|
правками репозитория их не сократить, а правки библиотек/форка (FO-стриминг, font cache) —
|
||||||
|
отдельные задачи с фиделити-гейтом. Практический рычаг «потреблять меньше» прямо сейчас — размеры
|
||||||
|
кучи и GC (§5).
|
||||||
|
|
||||||
|
## 5. Матрица флагов JVM (итог: что ставить в прод)
|
||||||
|
|
||||||
|
Один и тот же прогон (`--scenario all --loops 5 --big-loops 2`), меняются только флаги
|
||||||
|
(`MB_JAVA_OPTS` поверх дефолта харнеса; для смены GC нужен и `-XX:-UseG1GC` — иначе старт падает
|
||||||
|
с «Multiple garbage collectors selected»). ВМ не кончалась ни на одном наборе, OOM'а нет нигде,
|
||||||
|
включая big-сценарий:
|
||||||
|
|
||||||
|
|Набор|VmHWM suite, МБ|VmHWM +big, МБ|max-live, МБ|Паузы (шт/мс)|Вывод|
|
||||||
|
|---|---|---|---|---|---|
|
||||||
|
|f1 — G1, `-Xmx2g` (дефолт харнеса; прод-Containerfile как раз `2G`/`mem_limit 3G`)|931|1337|575|159 / 1724|работает, но куча ×2,6 к реальной потребности|
|
||||||
|
|f2 — G1, `-Xmx768m`|802|902|451|183 / 1865|**рекомендуемый**: RSS ≤0,9 ГБ с JFR-буферами, запас к max-live 1,7×|
|
||||||
|
|f3 — G1, `-Xmx512m`|818|843|416|199 / 1877|работает, но max-live 416 из 512 — малый запас на chart-тяжёлые документы|
|
||||||
|
|f4 — Serial, `-Xmx512m`|748|748|482|126 / 4453|работает; паузы ×2,6 против G1|
|
||||||
|
|f5 — Serial, `-Xmx384m`|628|634|359|150 / 5803|максимальная плотность (RSS 0,63 ГБ); паузы ×3,4, max-live 359 из 384 — впритык|
|
||||||
|
|
||||||
|
`allocated-estimate` у Serial-прогонов — 0: awk-агрегатор GC-лога понимает G1-формат (регионы),
|
||||||
|
для Serial аллокации считаются по другому шаблону — на вывод матрицы не влияет.
|
||||||
|
|
||||||
|
Рекомендация прод-стеку (рендерится job'ом `deploy` из Gitea Variables — менять их, не репо):
|
||||||
|
|
||||||
|
1. Heap: `-Xmx768m` (f2) вместо `2G`; `mem_limit` — `1g` вместо `3G`. FopFactory/XSLT-кеш перманентны,
|
||||||
|
их размер от кучи не зависит; 451 МБ max-live — это ~3 конвертации chart-тяжёлых документов в полёте
|
||||||
|
(а конвертации сериализованы монитором — реально одна).
|
||||||
|
2. G1 оставить (~13 мс пауз на конвертацию против ~40 мс у Serial; при конвертациях 1–4 с это не
|
||||||
|
критично, но G1 при 768m ещё и ровнее ведёт humongous-аллокации растров чартов).
|
||||||
|
3. Плотность выше f2 (Serial 384m) достижима, но запас <7% к max-live на 384m — для прод-вариабельности
|
||||||
|
документов неприемлемо.
|
||||||
|
|
||||||
|
## 6. Итог апгрейда
|
||||||
|
|
||||||
|
- Ядро не изменено: ни один кандидат (A–E, §4) не прошёл замерный гейт; экономия памяти на текущих
|
||||||
|
документах лежит не в коде репозитория, а внутри JAXB/XSLT/FOP (§2–3). Правки форка
|
||||||
|
(FO-стриминг, font cache) — зафиксированные дорожные пункты с фиделити-гейтом.
|
||||||
|
- Практический эффект «потреблять меньше» — профиль кучи: `2G/3G → 768m/1g` (в ~3 раза меньше
|
||||||
|
резидентной памяти на стенде) без потери проходимости всех сценариев, включая big.
|
||||||
|
- Инфраструктура измерений осталась в репо: `MemoryBench` + `membench.sh` + `./mise.sh run mem-bench`
|
||||||
|
— любой следующий раунд начинается с baseline за 10 минут.
|
||||||
|
|
||||||
|
## 7. Как читать этот документ дальше
|
||||||
|
|
||||||
|
- Перепроверить числа: §1 (команды) — прогон ~10 мин, артефакты в `target/` и `wordpdf-core/target/membench-*.jfr`.
|
||||||
|
- Перед новым «починить память»: сначала топ-кадры собственного прогона — доли приложения ≤0,4% означают,
|
||||||
|
что чинить нужно библиотеки, а не `WordPdfConverter`.
|
||||||
|
- Стоп-лист § «не чинить» из `docs/agent/render-limitations.md` остаётся в силе: экономия памяти
|
||||||
|
не должна менять выход PDF (фиделити-тесты — единственный арбитр).
|
||||||
+1
-1
@@ -4,7 +4,7 @@
|
|||||||
|
|
||||||
Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр × `DPI/72`, размеры в пунктах, EMU→pt `cx/12700.0`). Потолок растра `ChartRenderer.MAX_PIXELS = 16_777_216` (4096², 64 МБ ARGB): при превышении `fitDpi` uniform-но понижает эффективный dpi (геометрия в пунктах и безразмерные пропорции не меняются; 24″-график: 208 МБ → 64 МБ, dpi 300 → ≈171); `SmartArtRenderer` использует тот же `DPI`/`fitDpi`. `ChartSpec.parse` (`enum Type`: PIE, PIE3D, DOUGHNUT, BAR, BAR_HORIZONTAL, LINE, AREA, SURFACE3D, AREA3D, BAR3D, LINE3D, RADAR, SCATTER, BUBBLE, STOCK, OF_PIE, SURFACE, UNSUPPORTED). `c:autoTitleDeleted` (§21.2.2.7, `val` опущен — default true) применяется только при отсутствии `c:title` (MS-OI29500 §2.1.1431(a)) — явный заголовок показывается при любом флаге; при отсутствии `c:title` и `val=0` рисуется автозаголовок. Пустой/пробельный `c:title` (или `val=0` без `c:title`) — автозаголовок Office (MS-OI29500 §2.1.1561(a)): одиночный ряд с именем → имя ряда (любой тип графика), иначе `ChartSpec.AUTO_TITLE = "Название диаграммы"`; несколько абзацев `a:p` склеиваются `'\n'` (жёсткий перенос в `DrawMlText`). Регрессии — `ChartSpecTest#emptyTitleSingleSeriesBar_usesSeriesName`, `#deletedTitleWithText_stillShown`, `#deletedTitleValOmitted_stillShown`, `#multiSeriesDoughnut_placeholderNotSeriesName`, `#multiParagraphTitle_joinedWithNewlines`. Палитра `accent1..6` темы; легенда по умолчанию снизу; `overlay` (§21.2.2.132) рисуется поверх области построения, место не резервирует.
|
Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр × `DPI/72`, размеры в пунктах, EMU→pt `cx/12700.0`). Потолок растра `ChartRenderer.MAX_PIXELS = 16_777_216` (4096², 64 МБ ARGB): при превышении `fitDpi` uniform-но понижает эффективный dpi (геометрия в пунктах и безразмерные пропорции не меняются; 24″-график: 208 МБ → 64 МБ, dpi 300 → ≈171); `SmartArtRenderer` использует тот же `DPI`/`fitDpi`. `ChartSpec.parse` (`enum Type`: PIE, PIE3D, DOUGHNUT, BAR, BAR_HORIZONTAL, LINE, AREA, SURFACE3D, AREA3D, BAR3D, LINE3D, RADAR, SCATTER, BUBBLE, STOCK, OF_PIE, SURFACE, UNSUPPORTED). `c:autoTitleDeleted` (§21.2.2.7, `val` опущен — default true) применяется только при отсутствии `c:title` (MS-OI29500 §2.1.1431(a)) — явный заголовок показывается при любом флаге; при отсутствии `c:title` и `val=0` рисуется автозаголовок. Пустой/пробельный `c:title` (или `val=0` без `c:title`) — автозаголовок Office (MS-OI29500 §2.1.1561(a)): одиночный ряд с именем → имя ряда (любой тип графика), иначе `ChartSpec.AUTO_TITLE = "Название диаграммы"`; несколько абзацев `a:p` склеиваются `'\n'` (жёсткий перенос в `DrawMlText`). Регрессии — `ChartSpecTest#emptyTitleSingleSeriesBar_usesSeriesName`, `#deletedTitleWithText_stillShown`, `#deletedTitleValOmitted_stillShown`, `#multiSeriesDoughnut_placeholderNotSeriesName`, `#multiParagraphTitle_joinedWithNewlines`. Палитра `accent1..6` темы; легенда по умолчанию снизу; `overlay` (§21.2.2.132) рисуется поверх области построения, место не резервирует.
|
||||||
|
|
||||||
Пейнтеры: `CartesianPainter` (2-D line/bar/area; `c:grouping` stacked/percentStacked §21.2.2.76 — ряд рисуется накопленной суммой через `ChartRenderer.stackedCumulative`), `PiePainter` (`PIE_DEPTH = 0.22`, `PIE_FIT = 0.865`), `Surface3dPainter` (камера — регрессия `cameraMatchesWordReference`: `DEPTH_RATIO = 0.705`, `HEIGHT_RATIO = 0.664`, `GUTTER_LEFT/RIGHT = 0.1485`, `GUTTER_TOP = 0.116`, `GUTTER_BOTTOM = 0.146`, свет `LIGHT_X/Y/Z = 0.83/0.48/0.28`; `c:rAngAx=true` приоритетнее `c:perspective` (MS-OI29500 §2.1.1516(b)); `c:wireframe` §21.2.2.205 — только каркас), `ScatterPainter` (радиус пузыря sqrt при `c:sizeRepresents="area"` §21.2.2.128), `RadarPainter` (спицы от 12 часов), `StockPainter` (upDownBars обводятся контуром, дефолт чёрный 0.75pt), `OfPiePainter` (MS-OI29500 §2.1.1507(a), §2.1.1545(a)), `Surface2dPainter` (контурная карта §21.2.2.204, marching squares, изолинии по `c:bandFmts` §21.2.2.13/.14), `Cartesian3dPainter` (bar3D/line3D/area3D §21.2.2.19/.101/.122, `c:shape` §21.2.3.44), `SmartArtRenderer` (кэш `word/diagrams/drawing1.xml` через relationship `…/office/2007/relationships/diagramDrawing`; формы — `PresetGeometry` из `a:prstGeom`, семь пресетов дословно из `presetShapeDefinitions.xml`; оператор `?:` = «if x > 0 then y else z» (ISO/IEC 29500-1, **не** x != 0); углы в Arc2D — со знаком минус; текст — `DrawMlText`, шрифты через `BundledFontMapper.bundledFamily`; autofit только `normAutofit` §21.1.2.1.2/.3; `dgm:prSet/@phldrT` не рисуется).
|
Пейнтеры: `CartesianPainter` (2-D line/bar/area; `c:grouping` stacked/percentStacked §21.2.2.76 — ряд рисуется накопленной суммой через `ChartRenderer.stackedCumulative`), `PiePainter` (`PIE_DEPTH = 0.22`, `PIE_FIT = 0.865`), `Surface3dPainter` (камера — регрессия `cameraMatchesWordReference`: `DEPTH_RATIO = 0.705`, `HEIGHT_RATIO = 0.664`, `GUTTER_LEFT/RIGHT = 0.1485`, `GUTTER_TOP = 0.116`, `GUTTER_BOTTOM = 0.146`, свет `LIGHT_X/Y/Z = 0.83/0.48/0.28`; `c:rAngAx=true` приоритетнее `c:perspective` (MS-OI29500 §2.1.1516(b)); `c:wireframe` §21.2.2.205 — только каркас), `ScatterPainter` (радиус пузыря sqrt при `c:sizeRepresents="area"` §21.2.2.128), `RadarPainter` (спицы от 12 часов), `StockPainter` (upDownBars обводятся контуром, дефолт чёрный 0.75pt), `OfPiePainter` (MS-OI29500 §2.1.1507(a), §2.1.1545(a)), `Surface2dPainter` (контурная карта §21.2.2.204, marching squares, изолинии по `c:bandFmts` §21.2.2.13/.14), `Cartesian3dPainter` (bar3D/line3D/area3D §21.2.2.19/.101/.122, `c:shape` §21.2.3.44), `SmartArtRenderer` (кэш `word/diagrams/drawing1.xml` через relationship `…/office/2007/relationships/diagramDrawing`; формы — `PresetGeometry` из `a:prstGeom`, семь пресетов дословно из `presetShapeDefinitions.xml`; оператор `?:` = «if x > 0 then y else z» (ISO/IEC 29500-1, **не** x != 0); углы в Arc2D — со знаком минус; текст — `DrawMlText`, шрифты через `BundledFontAliases.bundledFamily`; autofit только `normAutofit` §21.1.2.1.2/.3; `dgm:prSet/@phldrT` не рисуется).
|
||||||
|
|
||||||
Защитные лимиты против враждебного chart-XML: `ChartSpec.MAX_POINTS = 100_000` (`c:pt/@idx` §21.2.2.150/.151, `c:ptCount` §21.2.2.152 — ST_UnsignedInt без верхней границы; отказ `IllegalArgumentException` **до** предвыделения списка), `ChartRenderer.MAX_TICKS = 1000` (шаг ≤ 0/NaN/слишком мелкий в `axisBounds` заменяется `niceUnit` 1/2/5·10ⁿ), `DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000` (≈24″; при `cx/cy` вне капа объект **оставляется как есть** + warn, картинка не рендерится — регрессия `hugeExtentChart_removedNotOom`). Бросок перехватывает catch в `DrawingPreRenderer.renderChart` → штатная деградация «объект удалён + warn». Обход `pkg.getParts()` — только по **снимку** списка (вставка media-частей `addChartMedia→addPart→loadPart` мутирует реестр → CME); rels частей — `part.getRelationshipsPart()`, **не** `getOwningRelationshipPart()`; обход XML обязан раскрывать `JAXBElement`.
|
Защитные лимиты против враждебного chart-XML: `ChartSpec.MAX_POINTS = 100_000` (`c:pt/@idx` §21.2.2.150/.151, `c:ptCount` §21.2.2.152 — ST_UnsignedInt без верхней границы; отказ `IllegalArgumentException` **до** предвыделения списка), `ChartRenderer.MAX_TICKS = 1000` (шаг ≤ 0/NaN/слишком мелкий в `axisBounds` заменяется `niceUnit` 1/2/5·10ⁿ), `DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000` (≈24″; при `cx/cy` вне капа объект **оставляется как есть** + warn, картинка не рендерится — регрессия `hugeExtentChart_removedNotOom`). Бросок перехватывает catch в `DrawingPreRenderer.renderChart` → штатная деградация «объект удалён + warn». Обход `pkg.getParts()` — только по **снимку** списка (вставка media-частей `addChartMedia→addPart→loadPart` мутирует реестр → CME); rels частей — `part.getRelationshipsPart()`, **не** `getOwningRelationshipPart()`; обход XML обязан раскрывать `JAXBElement`.
|
||||||
|
|
||||||
|
|||||||
+1
-1
@@ -6,7 +6,7 @@
|
|||||||
|
|
||||||
### Job'ы workflow'ов
|
### Job'ы workflow'ов
|
||||||
|
|
||||||
Два workflow. `.gitea/workflows/pr.yml` — `PR checks` (`pull_request` + `workflow_dispatch`): job `java` (temurin 17, кеш `~/.m2`, Maven 3.9.16 с dlcdn, `mvn -B -s .ci/maven-settings.xml clean verify` через зеркало Nexus `maven-central` (fail-closed проверка Variable `MAVEN_MIRROR_URL` первым шагом)) → `Coverage summary` (разбор `target/site/jacoco/jacoco.xml` python-сниппетом в step summary) → `Comment coverage on PR` (тот же текст комментарием; создаётся один раз, повторные push обновляют по маркеру `<!-- jacoco-coverage -->`; `continue-on-error`). job `web` (кеш `~/.npm`, `npm ci` → `build` → `lint`; `setup-node` **нет** — нода берётся с раннера).
|
Два workflow. `.gitea/workflows/pr.yml` — `PR checks` (`pull_request` + `workflow_dispatch`): job `java` (fail-closed проверка Variable `MAVEN_MIRROR_URL` первым шагом → единственный прогон `mvn -B clean verify` внутри образа `Containerfile.test` — без fontconfig, набор тестов никогда не исполняется на хосте с fontconfig; `DOCKER_BUILDKIT=0` обязателен — daemon за раннером podman, BuildKit-сессий нет; зеркало Nexus приходит `--build-arg` → извлечение двух `jacoco.xml` из образа `wordpdf-verify:ci` шагами `docker create`/`docker cp || true` — при непрошедшей сборке пустая сводка, тесты не затронуты) → `Coverage summary` (разбор извлечённого `target/site/jacoco/jacoco.xml` python-сниппетом в step summary) → `Comment coverage on PR` (тот же текст комментарием; создаётся один раз, повторные push обновляют по маркеру `<!-- jacoco-coverage -->`; `continue-on-error`). job `macos-sim` — тот же образ `Containerfile.test`, собранный с `--build-arg SUREFIRE_OS_NAME="Mac OS X"` (эмуляция macOS: единственный хост-зависимый код — docx4j `PhysicalFonts`, читающий `os.name`; внутри образа набор исполняется дважды — сначала `verify` без флага догревает локальный репозиторий до нуля загрузок, затем `verify` с флагом, т.к. Linux-JVM с `os.name=Mac OS X` падает AssertionError на первом же сетевом сокете; шагов JaCoCo/комментария нет — дублировали бы `java`), в `main.yml` отсутствует намеренно. job `web` (кеш `~/.npm`, `npm ci` → `build` → `lint`; `setup-node` **нет** — нода берётся с раннера).
|
||||||
|
|
||||||
`.gitea/workflows/main.yml` — `Main: tests, deploy, autotests` (`push` в `main` + `workflow_dispatch`): те же `java`/`web` (байт-байт дубль — workflow-файлы самодостаточны, reusable-workflow не вводить) → `images-app`/`images-web` (build+push каждого Containerfile в Nexus-реестр `${{ vars.REGISTRY }}`, теги `prod` + immovable `sha-<7 символов GITHUB_SHA>`; app печётся с `--build-arg MAVEN_MIRROR_URL=…` (зеркало Nexus в Containerfile); web печётся с `--build-arg VITE_BASE=/pdf-converter/`; `DOCKER_BUILDKIT=0` обязателен — daemon за раннером podman, BuildKit-сессий нет; креды — вручную пишется `~/.docker/config.json`) → `deploy` (SSH на прод: рендер конфигов heredoc'ами в workspace раннера — appleboy/ssh-action непригоден, ломает heredoc; валидация PyYAML; прод-стек — подсеть `10.112.0.0/24` gw `10.112.0.1` (в репо-`compose.yml` — `10.113.0.0/24`, стенды разные), gateway биндится на `127.0.0.1:9010` + `$DEPLOY_HOST:9010`, `nginx.conf` — с `resolver 10.112.0.1`; сохранение `.rollback.env`; `login/pull/timeout 90 podman-compose up -d --force-recreate app web`; гейты healthy и image; gateway пересоздаётся последним; health-check) → `autotests` (venv + `prod-autotests/` против прода) → `rollback` (`if: failure()` — перерендер/перезалив прод-файлов тем же шагом, retag прежних image ID на `:prod`, `--force-recreate app web`, пересоздание gateway).
|
`.gitea/workflows/main.yml` — `Main: tests, deploy, autotests` (`push` в `main` + `workflow_dispatch`): те же `java`/`web` (байт-байт дубль — workflow-файлы самодостаточны, reusable-workflow не вводить) → `images-app`/`images-web` (build+push каждого Containerfile в Nexus-реестр `${{ vars.REGISTRY }}`, теги `prod` + immovable `sha-<7 символов GITHUB_SHA>`; app печётся с `--build-arg MAVEN_MIRROR_URL=…` (зеркало Nexus в Containerfile); web печётся с `--build-arg VITE_BASE=/pdf-converter/`; `DOCKER_BUILDKIT=0` обязателен — daemon за раннером podman, BuildKit-сессий нет; креды — вручную пишется `~/.docker/config.json`) → `deploy` (SSH на прод: рендер конфигов heredoc'ами в workspace раннера — appleboy/ssh-action непригоден, ломает heredoc; валидация PyYAML; прод-стек — подсеть `10.112.0.0/24` gw `10.112.0.1` (в репо-`compose.yml` — `10.113.0.0/24`, стенды разные), gateway биндится на `127.0.0.1:9010` + `$DEPLOY_HOST:9010`, `nginx.conf` — с `resolver 10.112.0.1`; сохранение `.rollback.env`; `login/pull/timeout 90 podman-compose up -d --force-recreate app web`; гейты healthy и image; gateway пересоздаётся последним; health-check) → `autotests` (venv + `prod-autotests/` против прода) → `rollback` (`if: failure()` — перерендер/перезалив прод-файлов тем же шагом, retag прежних image ID на `:prod`, `--force-recreate app web`, пересоздание gateway).
|
||||||
|
|
||||||
|
|||||||
+13
-13
File diff suppressed because one or more lines are too long
+16
-13
@@ -6,40 +6,43 @@
|
|||||||
|---|---|---|
|
|---|---|---|
|
||||||
| 0 | `DependencyGuard.check()` | API-проба `ZipArchiveInputStream.getNextEntry()` — совместимость commons-compress ≥ 1.25.0; иначе `ConversionException` с инструкцией вместо мутного `NoSuchMethodError` внутри docx4j |
|
| 0 | `DependencyGuard.check()` | API-проба `ZipArchiveInputStream.getNextEntry()` — совместимость commons-compress ≥ 1.25.0; иначе `ConversionException` с инструкцией вместо мутного `NoSuchMethodError` внутри docx4j |
|
||||||
| 1 | `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` | Конструктор маппера (static `BestMatchingMapper`) регистрирует в `PhysicalFonts` только symbol-шрифты из `docx4j-export-fo-fonts-symbol` (сканы системы и jar'ов отключены в static-блоке `WordPdfConverter` гейт-свойствами — всё найденное всё равно выбрасывает `restrictToBundled()`); `init()` вызывает `dropNonBundled()` **до** регистрации бандла, `restrictToBundled()` оставляет реестр = бандл + встроенные в docx. Порядок `init()` после конструктора — инвариант: `addPhysicalFont` не перезаписывает занятый ключ (иначе системный Calibri ломает em-dash-fallback) |
|
| 1 | `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` | Конструктор маппера (static `BestMatchingMapper`) регистрирует в `PhysicalFonts` только symbol-шрифты из `docx4j-export-fo-fonts-symbol` (сканы системы и jar'ов отключены в static-блоке `WordPdfConverter` гейт-свойствами — всё найденное всё равно выбрасывает `restrictToBundled()`); `init()` вызывает `dropNonBundled()` **до** регистрации бандла, `restrictToBundled()` оставляет реестр = бандл + встроенные в docx. Порядок `init()` после конструктора — инвариант: `addPhysicalFont` не перезаписывает занятый ключ (иначе системный Calibri ломает em-dash-fallback) |
|
||||||
|2|`DocxRewritePipeline.STEP` → `OleObjectNormalizer` → `WordprocessingMLPackage.load`|Один zip-проход переписывания XML-частей (правила 1–10 — раздел «Нормализаторы: контракт и правила 1–11» в этом файле) + условная OLE-вычистка (правило 11)|
|
|2|`DocxRewritePipeline.STEP` → `OleObjectNormalizer` → `WordprocessingMLPackage.load`|Один zip-проход переписывания XML-частей (правила 1–11 — раздел «Нормализаторы: контракт и правила 1–12» в этом файле) + условная OLE-вычистка (правило 12)|
|
||||||
| 3 | `pkg.setFontMapper(mapper)` | Привязка шрифтов документа к физическим TTF |
|
| 3 | `pkg.setFontMapper(mapper)` | Привязка шрифтов документа к физическим TTF |
|
||||||
| 3.5 | `DrawingPreRenderer.run(pkg, options)` | `c:chart`/`dgm:relIds` → PNG 300 dpi → `pic:pic` (docx2fo.xslt их не умеет) |
|
| 3.5 | `DrawingPreRenderer.run(pkg, options)` | `c:chart`/`dgm:relIds`/`m:oMath` → PNG 300 dpi → `pic:pic` (docx2fo.xslt их не умеет); формулы — собственный растер `MathModel`/`MathRenderer` (только бандл-шрифты, без AWT/JEuclid), inline-картинка опускается ран-`w:rPr/w:position` на свой нижний запас (FOP ставит инлайн-графику нижним краем на базу строки; регрессия — WordPdfConverterTest#ommlMathInline_sitsOnTextBaseline), неподдерживаемая конструкция — текстовая деградация + warn; budget chart/math-PNG общий |
|
||||||
| 4 | `new FOSettings(pkg)` + `FopFallbackFonts.declare(foSettings)` | В FOP-конфиг добавляются **все** бандл-семейства: FOP встраивает только задекларированные |
|
| 4 | `new FOSettings(pkg)` + `FopFallbackFonts.declare(foSettings)` | В FOP-конфиг добавляются **все** бандл-семейства: FOP встраивает только задекларированные. Конфиг обязан быть **полным при каждом `declare`**: docx4j декларирует из `fontsInUse` только использованные начертания (или simulate-style на regular-файле), а общая `FopFactory` замораживает fopconf **первого** документа JVM — `declareFamily`+`hasRealFace` дополняют каждое семейство недостающими реальными начертаниями (регрессия — `fopFactoryFrozenFromFirstDoc_fontsComplete`) |
|
||||||
| 4.25 | `LayoutPostRenderer.register(foSettings)` | Кастомный `FORenderer`: post-FO padding-компенсация таблиц (`start-indent` += `padding-left` первой ячейки), внутри — штатный `FORendererApacheFOP` |
|
| 4.25 | `LayoutPostRenderer.register(foSettings)` | Кастомный `FORenderer`: post-FO padding-компенсация таблиц (`start-indent` += `padding-left` первой ячейки), внутри — штатный `FORendererApacheFOP` |
|
||||||
| 4.5 | `foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES)` | Стилист — вендорный `xslt/docx2fo.xslt` (копия docx4j-export-fo + AUDIT-FIX-патчи: `w:rPr/w:position`→`baseline-shift` и AUDIT-FIX-2 `moveFrom`/`moveTo`/`bdo`/`dir`); `Templates` компилируется один раз — `getTemplates` кастит значение в `Templates` |
|
| 4.5 | `foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES)` | Стилист — вендорный `xslt/docx2fo.xslt` (копия docx4j-export-fo + AUDIT-FIX-патчи: `w:rPr/w:position`→`baseline-shift` и AUDIT-FIX-2 `moveFrom`/`moveTo`/`bdo`/`dir`); `Templates` компилируется один раз — `getTemplates` кастит значение в `Templates` |
|
||||||
| 5 | `FORendererApacheFOP.getFopFactoryBuilder` + `getFOUserAgent` | Непустой `title` → заголовок PDF |
|
| 5 | `FORendererApacheFOP.getFopFactoryBuilder` + `getFOUserAgent` | Непустой `title` → заголовок PDF |
|
||||||
| 6 | `Docx4J.toFO(foSettings, os, FLAG_EXPORT_PREFER_XSL)` | XSL-FO → PDF |
|
| 6 | `Docx4J.toFO(foSettings, os, FLAG_EXPORT_PREFER_XSL)` | XSL-FO → PDF |
|
||||||
| 7 | `finally` → `getFontTablePart().deleteEmbeddedFontTempFiles()` | В docx4j 17.x `OpcPackage.close()` нет — пакет в памяти |
|
| 7 | `finally` → `getFontTablePart().deleteEmbeddedFontTempFiles()` | В docx4j 17.x `OpcPackage.close()` нет — пакет в памяти |
|
||||||
|
|
||||||
|
`BundledFontMapper` переопределяет `getBoldForm`/`getItalicForm`/`getBoldItalicForm`: на macOS `PhysicalFonts.getBoldForm` для имён `Tinos Regular`/`Carlito Regular`/… уходит в `MicrosoftFontsRegistry` и возвращает `null` (у записей нет Mac-имени файла), из-за чего docx4j строил simulate-style fopconf — FOP терял реальные начертания и кернинг (регрессии `strictOoxml_convertsNotRejected`, `ruPlain_regularRunsUseRegularFont`). Override находит реальный вариант по `embeddedURI` regular-варианта.
|
||||||
|
|
||||||
### `warmup()` — прогрев ядра (шаги 0–7 на минимальном docx)
|
### `warmup()` — прогрев ядра (шаги 0–7 на минимальном docx)
|
||||||
|
|
||||||
Первая конвертация после старта JVM стоит 1,3–1,7 с (JAXB/XSLT/FOP/классы; замер 2026-11), её платил первый запрос после деплоя. Публичный `WordPdfConverter.warmup()` прогоняет шаги 0–7 на минимальном docx, собранном в байтах (три zip-части константами, фикстуры не задействованы; алиас Calibri→Carlito греет маппер и embed-подмножество), и греет Java2D/PNG-энкодер (`warmRaster()` — растер + `GlyphFont.draw` + `ImageIO.write`), иначе первый чартный документ платит ещё ~200 мс. Идемпотентен (`volatile warmedUp`, метод `synchronized`), никогда не бросает (провал — warn в JUL), артефакты отбрасываются; вызывать на потоке, сериализующем конвертации. Ядро само себя не зовёт: `wordpdf-app` ставит warmup головой очереди воркеров в конструкторе `ConversionService`. Прогретый первый конверт ru-plain.docx HTTP-запросом: 0,13 с против 1,74 с (A/B на одной машине, сборки ветки и `main`).
|
Первая конвертация после старта JVM стоит 1,3–1,7 с (JAXB/XSLT/FOP/классы; замер 2026-11), её платил первый запрос после деплоя. Публичный `WordPdfConverter.warmup()` прогоняет шаги 0–7 на минимальном docx, собранном в байтах (три zip-части константами, фикстуры не задействованы; алиас Calibri→Carlito греет маппер и embed-подмножество), и греет Java2D/PNG-энкодер (`warmRaster()` — растер + `GlyphFont.draw` + `ImageIO.write`), иначе первый чартный документ платит ещё ~200 мс. Идемпотентен (`volatile warmedUp`, метод `synchronized`), никогда не бросает (провал — warn в JUL), артефакты отбрасываются; вызывать на потоке, сериализующем конвертации. Ядро само себя не зовёт: `wordpdf-app` ставит warmup головой очереди воркеров в конструкторе `ConversionService`. Прогретый первый конверт ru-plain.docx HTTP-запросом: 0,13 с против 1,74 с (A/B на одной машине, сборки ветки и `main`).
|
||||||
|
|
||||||
### Валидация входа и подсчёт страниц
|
### Валидация входа и подсчёт страниц
|
||||||
|
|
||||||
Вход валидируется **до** `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` → контейнер → страницы). Для `.doc` страницы считаются **по сырым байтам .doc, до конвертации**: `checkPageCountDoc` = `max(SummaryInfo PageCount, 1 + разрывы 0x0C − непрерывные межсекционные (sprmSBkc 0/1) + sprmPFPageBreakBefore)` (код — `DocFile.countPages`). Тот же метод — вход приложения. Скан выполняется ровно один раз по сырому входу, до аллокаций docx4j: правила 1–11 число учитываемых разрывов не увеличивают (правило 10 способно только убрать разрыв внутри скрытого рана — счёт по сырому входу остаётся верхней оценкой лимита).
|
||||||
|
|
||||||
- Страницы в валидаторе = `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-частей).
|
- Страницы в валидаторе = `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-частей).
|
||||||
|
|
||||||
### Нормализаторы: контракт и правила 1–11 (детали)
|
### Нормализаторы: контракт и правила 1–12 (детали)
|
||||||
|
|
||||||
Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame` в тестах). Десять rewrite-нормализаторов цепляются в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby; константу `STEP` (`public static final DocxNormalizer`) выставляют девять из десяти (нет только у `RubyNormalizer` — он цепочный, подключается внутри пайплайна), у `OleObjectNormalizer` STEP **нет** — он подключается лямбдой в `WordPdfConverter.normalizers()`. Правила 1–10 применяет `internal/DocxRewritePipeline` — **один zip-проход**: к каждой записи `word/*.xml` рерайты применяются последовательно (каждое правило работает только содержимым одной части — по-частная цепочка эквивалентна последовательным полным проходам); до прохода из `word/document.xml` извлекается полоса набора (`TableIndentNormalizer.bandOf`, −1 — полосы нет), и `word/headerN.xml`/`footerN.xml` дополнительно прогоняются через `TableIndentNormalizer.rewritePart` с этой полосой, и из `word/styles.xml` читается множество vanish-стилей (`HiddenTextNormalizer.vanishStyles`, цепочка `w:basedOn`) — контекст правила 9; неизменённые записи переносятся raw-копией сжатых байтов (без inflate/deflate); нигде не поменялось → тот же массив. `OleObjectNormalizer` — второй условный проход (меняет части, а не XML). Индивидуальные `normalize()` десяти нормализаторов сохранены (контракт юнит-тестов), но `WordPdfConverter` их не вызывает — его `normalizers(options)` = `DocxRewritePipeline.STEP` + лямбда OLE. Порядок правил значим:
|
Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame` в тестах). Одиннадцать rewrite-нормализаторов цепляются в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→MathFallback→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby; константу `STEP` (`public static final DocxNormalizer`) несёт только `DocxRewritePipeline` (собирает рерайты сам), у `OleObjectNormalizer` STEP **нет** — он подключается лямбдой в `WordPdfConverter.normalizers()`, а вместо `normalize(byte[])` у него `normalize(byte[], boolean)`. Правила 1–11 применяет `internal/DocxRewritePipeline` — **один zip-проход**: к каждой записи `word/*.xml` рерайты применяются последовательно (каждое правило работает только содержимым одной части — по-частная цепочка эквивалентна последовательным полным проходам); до прохода из `word/document.xml` извлекается полоса набора (`TableIndentNormalizer.bandOf`, −1 — полосы нет), и `word/headerN.xml`/`footerN.xml` дополнительно прогоняются через `TableIndentNormalizer.rewritePart` с этой полосой, и из `word/styles.xml` читается множество vanish-стилей (`HiddenTextNormalizer.vanishStyles`, цепочка `w:basedOn`) — контекст правила 10; неизменённые записи переносятся raw-копией сжатых байтов (без inflate/deflate); нигде не поменялось → тот же массив. `OleObjectNormalizer` — второй условный проход (меняет части, а не XML). Индивидуальные `normalize()` десяти нормализаторов сохранены (контракт юнит-тестов), но `WordPdfConverter` их не вызывает — его `normalizers(options)` = `DocxRewritePipeline.STEP` + лямбда OLE. Порядок правил значим:
|
||||||
|
|
||||||
1. `StrictOoxmlNormalizer` — strict-OOXML → transitional: `a:`-проценты и `w14:fillToRect` → тысячные ×1000, текст `wp14:pctWidth`/`pctHeight`; элементы `w:start`/`w:end` → `w:left`/`w:right` (кроме `w:lvl/w:start` в numbering.xml); значения `w:val="start"/"end"` у `w:jc` и `w:tab` правятся **всегда** (docx4j `Justification.setXslFO` знает только left/center/right/both, для END `fo:text-align` не пишет вовсе — `jc="end"` рендерился по левому краю; Part 1 §17.3.1.13: `jc val="end"` — правовыравнивание в LTR, ST_Jc §17.18.44; RTL вне контура — FOP без complex-script). Strict-ность части определяется наличием `http://purl.oclc.org` (не «transitional-URI в документе» — mixed-документ трактуется по каждой части). **Guard сосуществования форм**: атрибут `w:start`/`w:end` переименовывается только внутри открывающего тега `w:ind` (MS-OI29500 §2.1.174a — псевдонимы left/right; у `w:pgNumType` `w:start` — старт нумерации страниц, легален в transitional, Part 1 §17.13.7 — не трогается) и не переименовывается, если в том же открывающем теге уже есть `w:left`/`w:right` (дубль атрибута ломает well-formedness — регрессии `indCoexistLeftStartUntouched`, `indCoexistForms_convertsNotRejected`, `pgNumTypeStartAttrUntouched`); элементы `w:start`/`w:end` в strict-части переименовываются глобально, в transitional — только внутри `w:tcMar`/`w:tblCellMar` без одноимённого соседа (`maxOccurs=1` на left). Ничего не поменялось → `rewrite` вернул `null` → исходный массив (`StrictOoxmlNormalizerTest#transitionalCoexistReturnsOriginalArray`).
|
1. `StrictOoxmlNormalizer` — strict-OOXML → transitional: `a:`-проценты и `w14:fillToRect` → тысячные ×1000, текст `wp14:pctWidth`/`pctHeight`; элементы `w:start`/`w:end` → `w:left`/`w:right` (кроме `w:lvl/w:start` в numbering.xml); значения `w:val="start"/"end"` у `w:jc` и `w:tab` правятся **всегда** (docx4j `Justification.setXslFO` знает только left/center/right/both, для END `fo:text-align` не пишет вовсе — `jc="end"` рендерился по левому краю; Part 1 §17.3.1.13: `jc val="end"` — правовыравнивание в LTR, ST_Jc §17.18.44; RTL вне контура — FOP без complex-script). Strict-ность части определяется наличием `http://purl.oclc.org` (не «transitional-URI в документе» — mixed-документ трактуется по каждой части). **Guard сосуществования форм**: атрибут `w:start`/`w:end` переименовывается только внутри открывающего тега `w:ind` (MS-OI29500 §2.1.174 — псевдонимы left/right; у `w:pgNumType` `w:start` — старт нумерации страниц, легален в transitional, Part 1 §17.13.4 — не трогается) и не переименовывается, если в том же открывающем теге уже есть `w:left`/`w:right` (дубль атрибута ломает well-formedness — регрессии `indCoexistLeftStartUntouched`, `indCoexistForms_convertsNotRejected`, `pgNumTypeStartAttrUntouched`); элементы `w:start`/`w:end` в strict-части переименовываются глобально, в transitional — только внутри `w:tcMar`/`w:tblCellMar` без одноимённого соседа (`maxOccurs=1` на left). Ничего не поменялось → `rewrite` вернул `null` → исходный массив (`StrictOoxmlNormalizerTest#transitionalCoexistReturnsOriginalArray`).
|
||||||
2. `DocxOnOffNormalizer` — `w:val="off"/"on"` → `"false"/"true"`; якорь по тегу, правится только атрибут `w:val`, текст между тегами не трогается.
|
2. `DocxOnOffNormalizer` — `w:val="off"/"on"` → `"false"/"true"`; якорь по тегу, правится только атрибут `w:val`, текст между тегами не трогается.
|
||||||
3. `SymbolFontNormalizer` — PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans; переписывает `<w:sym>`, правит `w:lvl` в numbering.xml; 5 карт по 256 слотов (таблица `SymbolMapper` из docx4j 17.x).
|
3. `SymbolFontNormalizer` — PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans; переписывает `<w:sym>`, правит `w:lvl` в numbering.xml; 5 карт по 256 слотов (таблица `SymbolMapper` из docx4j 17.x).
|
||||||
4. `FieldNormalizer` — `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple` (кэш страниц в PDF не попадает); вложенные/битые поля пропускаются.
|
4. `FieldNormalizer` — `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple` (кэш страниц в PDF не попадает); вложенные/битые поля пропускаются.
|
||||||
5. `InvisibleCharNormalizer` — вырезает из `w:t` U+0085, U+2028, U+2029, U+200E/200F, U+202A–202E, U+2060, U+FEFF (FOP делает из них переносы/пустые строки, Arimo/Tinos рисуют боксы). U+00A0/U+00AD/U+200B–U+200D **не** трогает.
|
5. `InvisibleCharNormalizer` — вырезает из `w:t` U+0085, U+2028, U+2029, U+200E/200F, U+202A–202E, U+2060, U+FEFF (FOP делает из них переносы/пустые строки, Arimo/Tinos рисуют боксы). U+00A0/U+00AD/U+200B–U+200D **не** трогает.
|
||||||
6. `GlyphCoverageNormalizer` — режет раны по покрытию глифов и пишет семейство в `w:rFonts`, иначе FOP рисует «#». Покрытие — `GlyphFont` (fontbox, cmap) + BitSet-кэш, **не** docx4j `GlyphCheck` (плодит INFO-лог; `java.awt.Font` требовал fontconfig на хосте). Для serif-ран fallback ищется сначала в `SERIF_FAMILIES` (`dejavu serif`, `tinos`, `caladea`), затем в sans.
|
6. `MathFallbackNormalizer` — байтовый скан OMML-формул (§22.1) до загрузки пакета: формулы с конструкциями вне `MathModel.SUPPORTED` (или structurally битые) деградируют в текст — `m:oMathPara`/`m:oMath` → обычные раны с конкатенацией `m:t` (как в штатном фолбэке docx4j `XsltFOFunctions.mathText`); поддерживаемые части не трогаются (`rewrite` → `null`, тот же массив) — их рисует собственный `MathRenderer` на шаге 3.5. Позиция **до GlyphCoverage** обязательна: деградировавшие раны с математическими символами (U+1D400+) обязаны пройти резку по покрытию, иначе FOP рисует «#». `m:oMathPara` содержит `m:oMath`, поэтому блок para заменяется первым. Регрессия — WordPdfConverterTest#ommlMathUnsupported_flattenedToText, юниты — MathFallbackNormalizerTest.
|
||||||
7. `TableIndentNormalizer` — свёртка `w:tblPr/w:jc` (center/right) с любым (в т.ч. отсутствующим/нулевым) `w:tblInd` в абсолютный `w:tblInd` с удалением `w:jc` (Word: tblInd — сдвиг от поля после центрирования, MS-OI29500 §2.1.155; docx4j при jc≠left игнорирует tblInd буквально — Part 1 §17.4.50, а центрированию пишет абсолютный start-indent **без** вычета cellMar, поверх которого padding-компенсация правила LayoutPostRenderer уводит текст на +padding — свёртка обязательна и при X=0): center → (W−T)/2+X, right → (W−T)+X, W — полоса набора (pgSz − pgMar left/right в transitional и `w:start`/`w:end` в strict; дефолты 11906/1440 — измеренное поведение docx4j, не ECMA-1800), T — Σ gridCol; пропускает несколько body-level `sectPr`, не-dxa `tblInd`, `tblPr` с `tblCellSpacing` без `tblInd` (нет корректной позиции вставки по CT_TblPrBase), `tblW pct`, нецелые gridCol. Кроме `rewrite`/`STEP` (document.xml, полоса из собственного sectPr) есть `rewritePart(part, xml, band)` — `word/headerN.xml`/`footerN.xml` с полосой из document.xml (в частях колонтитуков своего sectPr нет) и `bandOf(documentXml)` — экстрактор полосы (−1 — полосы нет). Регрессия — WordPdfConverterTest#tableIndentCentered_shiftedLikeWord, #headerTableIndent_centeredInHeader, #tableCenteredNoIndent_shiftedLikeWord.
|
7. `GlyphCoverageNormalizer` — режет раны по покрытию глифов и пишет семейство в `w:rFonts`, иначе FOP рисует «#». Покрытие — `GlyphFont` (fontbox, cmap) + BitSet-кэш, **не** docx4j `GlyphCheck` (плодит INFO-лог; `java.awt.Font` требовал fontconfig на хосте). Для serif-ран fallback ищется сначала в `SERIF_FAMILIES` (`dejavu serif`, `tinos`, `caladea`), затем в sans.
|
||||||
8. `NumberingSuffixNormalizer` — `w:suff w:val="space"` → дописанный обычный пробел в конце следующего `w:lvlText` того же уровня (порядок CT_Lvl suff→lvlText, wml.xsd; Part 1 §17.3.1.28): docx4j разделитель не эмитит вовсе (дамп n4.fo); уже пробельный lvlText не дублируется; suff=tab — отдельный Class C-остаток (нужна per-item ширина), nothing совпадает с docx4j. Регрессия — WordPdfConverterTest#suffSpace_labelGetsSpace.
|
8. `TableIndentNormalizer` — свёртка `w:tblPr/w:jc` (center/right) с любым (в т.ч. отсутствующим/нулевым) `w:tblInd` в абсолютный `w:tblInd` с удалением `w:jc` (Word: tblInd — сдвиг от поля после центрирования, MS-OI29500 §2.1.155; docx4j при jc≠left игнорирует tblInd буквально — аудит раскладки ECMA-376, матрица B3, а центрированию пишет абсолютный start-indent **без** вычета cellMar, поверх которого padding-компенсация правила LayoutPostRenderer уводит текст на +padding — свёртка обязательна и при X=0): center → (W−T)/2+X, right → (W−T)+X, W — полоса набора (pgSz − pgMar left/right; у CT_PageMar полей `w:start`/`w:end` нет, полоса берётся из сырого document.xml до правила 1; дефолты 11906/1440 — измеренное поведение docx4j, ECMA дефолтов не фиксирует §17.6.11/.13), T — Σ gridCol; пропускает несколько body-level `sectPr`, `tblInd` с явным `w:type` ≠ dxa (опущенный type — dxa, §17.4.87), `tblPr` с `tblCellSpacing` без `tblInd` (нет корректной позиции вставки по CT_TblPrBase), `tblW pct`, нецелые gridCol. Кроме `rewrite` (document.xml, полоса из собственного sectPr) есть `rewritePart(part, xml, band)` — `word/headerN.xml`/`footerN.xml` с полосой из document.xml (в частях колонтитуков своего sectPr нет) и `bandOf(documentXml)` — экстрактор полосы (−1 — полосы нет). Регрессия — WordPdfConverterTest#tableIndentCentered_shiftedLikeWord, #headerTableIndent_centeredInHeader, #tableCenteredNoIndent_shiftedLikeWord.
|
||||||
9. `HiddenTextNormalizer` — вырезание скрытых ранов (Part 1 §17.3.2.30): truthy `w:vanish` в собственном `w:rPr` ранa (обе OnOff-формы; вал опущен — default true) **или** `w:rStyle` ∈ vanish-стили из `word/styles.xml` (транзитивно по `w:basedOn`, капа цепочки 16, цикл — обрыв); ран с защищённым содержимым (`fldChar`/`instrText`/`footnoteReference`/`endnoteReference`/`drawing`/`pict`/`object`/`txbxContent`) не трогается — удаление спаренных `begin…separate…end` сломало бы поле. Word скрытое не печатает, стилист docx4j `vanish` не читает вовсе → без правила скрытое утекало в PDF. Индивидуальный `normalize()` — свой pass styles.xml. Регрессия — WordPdfConverterTest#hiddenText_notPrinted, юниты — HiddenTextNormalizerTest.
|
9. `NumberingSuffixNormalizer` — `w:suff w:val="space"` → дописанный обычный пробел в конце следующего `w:lvlText` того же уровня (порядок CT_Lvl suff→lvlText, wml.xsd; ST_LevelSuffix Part 1 §17.9.28): docx4j разделитель не эмитит вовсе (дамп n4.fo); уже пробельный lvlText не дублируется; suff=tab — отдельный Class C-остаток (нужна per-item ширина), nothing совпадает с docx4j. Регрессия — WordPdfConverterTest#suffSpace_labelGetsSpace.
|
||||||
10. `RubyNormalizer` — разбор руби-разметки (Part 1 §17.3.3.18/.19/.20/.21): `w:rubyBase`/`w:rubyBaseText` разворачиваются в обычные раны, `w:rt`/`w:rubyPr`/`w:rubyAlign` вырезаются с содержимым (надстрочница — принятая деградация, ruby-разметки в FOP нет; потеря текста хуже потери аннотации). Чинится **в байтах**, а не в XSLT: схема docx4j 17.3.2 не биндит `w:rubyBase`/`w:rt` в `w:r` — unmarshaller теряет их до стилиста (в отличие от `moveFrom`/`moveTo`/`bdo`/`dir`, которых схема знает — тех ловит AUDIT-FIX-2). Регрессия — WordPdfConverterTest#rubyBase_textPrinted, юниты — RubyNormalizerTest.
|
10. `HiddenTextNormalizer` — вырезание скрытых ранов (Part 1 §17.3.2.41): truthy `w:vanish` в собственном `w:rPr` ранa (обе OnOff-формы; вал опущен — default true; явный `false/0/off` в ране **перекрывает** vanish-стиль) **или** `w:rStyle` ∈ vanish-стили из `word/styles.xml` (транзитивно по `w:basedOn`, капа цепочки 16, цикл — обрыв); ран с защищённым содержимым (`fldChar`/`instrText`/`footnoteReference`/`endnoteReference`/`drawing`/`pict`/`object`/`txbxContent`) не трогается — удаление спаренных `begin…separate…end` сломало бы поле. Word скрытое не печатает, стилист docx4j `vanish` не читает вовсе → без правила скрытое утекало в PDF. Индивидуальный `normalize()` — свой pass styles.xml. Регрессия — WordPdfConverterTest#hiddenText_notPrinted, #hiddenText_directFalseOverridesVanishStyle, юниты — HiddenTextNormalizerTest.
|
||||||
11. `OleObjectNormalizer` — принимает флаг `errorOnOle`. Два этапа: дешёвый детект по центральному каталогу zip (`ZipFile`; читаются только `[Content_Types].xml` и `word/*.xml` до первого `<w:object`; не-zip/нет центрального каталога → входной массив — прежняя снисходительность), переупаковка — только при находке. Детект OLE-бинарников — по `[Content_Types].xml`: тип `…oleObject` **или** ложный `+xml`-тип у `.bin` (XML в bin не бывает; `printerSettings` не трогается). Удаляются вместе с rels-ссылками (по типу, включая `TargetMode=External`) и Override удалённых частей. Элементы `<w:object>` из `word/*.xml` не выбрасываются, а заменяются статичным представлением — картинкой-плейсхолдером (ECMA-376 §15.2.10): `w:drawing` переиспользуется дословно, `v:imagedata r:id` → inline-DrawingML на ту же image-часть (размер из `style` `v:shape`, иначе `w:dxaOrig`/`w:dyaOrig` ×635), блоки с `w:control` и без плейсхолдера удаляются. OLE-бинарники никогда не читаются. При `errorOnOle=true` вместо вычистки — `DrawingFoundException(OLE)`. Лечит оба механизма падения docx4j: JAXB-разбор бинарника под ложным XML-типом («Content is not allowed in prolog» → NPE) и NPE `chunkType is null` в VML-сериализации `w:object`. Многочастный: публичный член только `normalize(byte[], boolean)`, `rewrite`-хука нет.
|
11. `RubyNormalizer` — разбор руби-разметки (Part 1 §17.3.3.24–.28): снимается обёртка `w:ruby` (схемно-валидная транзишнл-разметка `w:r`→`w:ruby`→rubyPr/rt/rubyBase иначе достаёт catch-all-шаблону XSLT, и база теряется молча), `w:rubyBase` разворачивается в обычные раны, `w:rt`/`w:rubyPr`/`w:rubyAlign` вырезаются с содержимым (надстрочница — принятая деградация, ruby-разметки в FOP нет; потеря текста хуже потери аннотации). Чинится **в байтах**, а не в XSLT: схема docx4j 17.3.2 не биндит `w:rubyBase`/`w:rt` в `w:r` — unmarshaller теряет их до стилиста (в отличие от `moveFrom`/`moveTo`/`bdo`/`dir`, которых схема знает — тех ловит AUDIT-FIX-2). Регрессия — WordPdfConverterTest#rubyBase_textPrinted, юниты — RubyNormalizerTest.
|
||||||
|
12. `OleObjectNormalizer` — принимает флаг `errorOnOle`. Два этапа: дешёвый детект по центральному каталогу zip (`ZipFile`; читаются только `[Content_Types].xml` и `word/*.xml` до первого `<w:object`; не-zip/нет центрального каталога → входной массив — прежняя снисходительность), переупаковка — только при находке. Детект OLE-бинарников — по `[Content_Types].xml`: тип `…oleObject` **или** ложный `+xml`-тип у `.bin` (XML в bin не бывает; `printerSettings` не трогается). Удаляются вместе с rels-ссылками (по типу, включая `TargetMode=External`) и Override удалённых частей. Элементы `<w:object>` из `word/*.xml` не выбрасываются, а заменяются статичным представлением — картинкой-плейсхолдером (ECMA-376 §15.2.10): `w:drawing` переиспользуется дословно, `v:imagedata r:id` → inline-DrawingML на ту же image-часть (размер из `style` `v:shape`, иначе `w:dxaOrig`/`w:dyaOrig` ×635), блоки с `w:control` и без плейсхолдера удаляются. OLE-бинарники никогда не читаются. При `errorOnOle=true` вместо вычистки — `OleFoundException`. Лечит оба механизма падения docx4j: JAXB-разбор бинарника под ложным XML-типом («Content is not allowed in prolog» → NPE) и NPE `chunkType is null` в VML-сериализации `w:object`. Многочастный: публичный член только `normalize(byte[], boolean)`, `rewrite`-хука нет.
|
||||||
|
|
||||||
`mc-preprocessor.xslt` docx4j (в jar `docx4j-core`) перебивает strict-namespace'ы в transitional и конвертит `pt` в twips/half-points, но ветку перевода процентов в тысячные для namespace'ных атрибутов содержит с закомментированным `<xsl:value-of select="$cleanValue * 1000"/>` (для атрибутов без namespace — она активна), а `w:start`/`w:end` в `w:left`/`w:right` не маппит вовсе. Поэтому собственный рерайт URI ломать нельзя — он сломал бы pt-конверсию preprocessor'а (FOP получил бы «10pt»).
|
`mc-preprocessor.xslt` docx4j (в jar `docx4j-core`) перебивает strict-namespace'ы в transitional и конвертит `pt` в twips/half-points, но ветку перевода процентов в тысячные для namespace'ных атрибутов содержит с закомментированным `<xsl:value-of select="$cleanValue * 1000"/>` (для атрибутов без namespace — она активна), а `w:start`/`w:end` в `w:left`/`w:right` не маппит вовсе. Поэтому собственный рерайт URI ломать нельзя — он сломал бы pt-конверсию preprocessor'а (FOP получил бы «10pt»).
|
||||||
|
|||||||
@@ -4,6 +4,6 @@
|
|||||||
|
|
||||||
- Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
|
- Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
|
||||||
|
|
||||||
- Аудит раскладки по ECMA-376 Part 1 (2026-10) — известные нечинимые ограничения FOP/docx4j (Java-слой): `w:jc="distribute"` рендерится как left — межсимвольного распределения в FOP нет (ST_Jc §17.18.44: distribute — межсимвольный разнос, justify только межсловный), последняя строка блока не растягивается, свойства `text-align-last` в форке нет (в docx4j-fo-renderer отсутствуют классы TextAlign*); `w:suff="tab"` и `w:lvlJc` игнорируются (numbering-лейбл всегда через hanging-tab; suff=space чинит правило 8, suff=nothing совпадает с docx4j — разделителя нет); абзац без `w:line` рендерится natural-высотой FOP 15.44pt@11pt, явный `lineRule="auto"` — 13.4277pt, два «single» в конвертере (13.4277 — канонический single по метрикам Carlito/Calibri 2500/2048 em; обе величины считаются по метрикам шрифта); кернинг не применяется ни для одного бандл-семейства (замер: advance A→V = A→A — Carlito 6.369pt, DejaVu Sans 7.524pt@11pt): 22 TTF — GPOS-only, а legacy `kern`-таблица DejaVu Sans/Serif ключована glyph id, не совпадающими с cmap (2568/2727 пар без Unicode-маппинга, пары A→V нет) — латинский путь FOP (`TextLayoutManager`→`Font.hasKerning`) читает только legacy `kern` и такие пары отбрасывает; свойства `kerning` в форке нет, порог `w:kern` через FO не выражается. Word кернит только при явно заданном `w:kern` в иерархии стилей и при sz ≥ val (Part 1 §17.3.2.19; при отсутствии `w:kern` Office не кернит — MS-OI29500 §21.1.2.3.9a) — по умолчанию совпадает с нами, расходится только для документов с явно заданным `w:kern`. Починено веткой layout-class-c: левый padding ячейки (`LayoutPostRenderer`, шаг 4.25), `w:tblInd` при `w:jc`≠left (правило 7), `w:suff="space"` (правило 8).
|
- Аудит раскладки по ECMA-376 Part 1 (2026-10) — известные нечинимые ограничения FOP/docx4j (Java-слой): `w:jc="distribute"` рендерится как left — межсимвольного распределения в FOP нет (ST_Jc §17.18.44: distribute — межсимвольный разнос, justify только межсловный), последняя строка блока не растягивается, свойства `text-align-last` в форке нет (в docx4j-fo-renderer отсутствуют классы TextAlign*); `w:suff="tab"` и `w:lvlJc` игнорируются (numbering-лейбл всегда через hanging-tab; suff=space чинит правило 9, suff=nothing совпадает с docx4j — разделителя нет); абзац без `w:line` рендерится natural-высотой FOP 15.44pt@11pt, явный `lineRule="auto"` — 13.4277pt, два «single» в конвертере (13.4277 — канонический single по метрикам Carlito/Calibri 2500/2048 em; обе величины считаются по метрикам шрифта); кернинг не применяется ни для одного бандл-семейства (замер: advance A→V = A→A — Carlito 6.369pt, DejaVu Sans 7.524pt@11pt): 22 TTF — GPOS-only, а legacy `kern`-таблица DejaVu Sans/Serif ключована glyph id, не совпадающими с cmap (2568/2727 пар без Unicode-маппинга, пары A→V нет) — латинский путь FOP (`TextLayoutManager`→`Font.hasKerning`) читает только legacy `kern` и такие пары отбрасывает; свойства `kerning` в форке нет, порог `w:kern` через FO не выражается. Word кернит только при явно заданном `w:kern` в иерархии стилей и при sz ≥ val (Part 1 §17.3.2.19: кернинг применяется, только когда элемент задан; при отсутствии `w:kern` не кернит; MS-OI29500 §2.1.83 уточняет лишь диапазон `w:val`) — по умолчанию совпадает с нами, расходится только для документов с явно заданным `w:kern`. Починено веткой layout-class-c: левый padding ячейки (`LayoutPostRenderer`, шаг 4.25), `w:tblInd` при `w:jc`≠left (правило 8), `w:suff="space"` (правило 9).
|
||||||
|
|
||||||
- Аудит .docx-путей по ECMA-376 (2026-11) — запинено синтетикой (без фикстур): сноски/концевые сноски с номерами (§17.11), внешние гиперссылки с `/URI`-аннотацией (§17.12.23), `PAGEREF` (complex и вложенный в результат `TOC`) и `DATE` подменяют кэш живым значением, `titlePg` → first/default колонтитуки (§17.13.1.35), `vMerge` restart/continue (§17.4.70), block-level `w:sdt` (§17.5.2), `wps:txbx`-текст (§17.3.3.23), OMML-формулы рисуются вектором jeuclid-fop (§22.1 — текст из PDF не извлекается, пинь пикселями), фон `w:highlight`/`w:shd` рисуется (§17.3.2.16/.29). Скрытый текст `w:vanish` не печатается (правило 9); текст руби-базы и `w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir` не теряется (правило 10 + AUDIT-FIX-2). Остаток (не чиним): `w:framePr` игнорируется — текст печатается в общем потоке, геометрия фрейма теряется (ни XSLT, ни `createBlockForPPr` не читают); `REF`/`SEQ`/литеральные записи `TOC` печатают устаревший кэш из docx (движка пересчёта нет; инстринции полей не печатаются); надстрочница руби не выводится (правило 10 печатает только базу — ruby-разметки в FOP нет); `w:ptab` без `@w:alignment`, `bar`, `list` теряются catch-all'ом; `w:bdo`/`w:dir` печатаются LTR (bidi вне контура).
|
- Аудит .docx-путей по ECMA-376 (2026-11) — запинено синтетикой (без фикстур): сноски/концевые сноски с номерами (§17.11), внешние гиперссылки с `/URI`-аннотацией (§17.12.23), `PAGEREF` (complex и вложенный в результат `TOC`) и `DATE` подменяют кэш живым значением, `titlePg` → first/default колонтитуки (§17.10.6), `vMerge` restart/continue (§17.4.70), block-level `w:sdt` (§17.5.2), `wps:txbx`-текст (§17.3.3.23; формула внутри текстового бокса до растера не доходит — обход drawing-нагрузку не спускается и уходит в docx4j-фолбэк `mathText`, конкатенация `m:t`; регрессия — WordPdfConverterTest#drawingTextBoxMath_convertsViaDocx4jTextFallback), OMML-формулы (§22.1) рисует собственный растер `MathModel`/`MathRenderer` — PNG 300 dpi, только бандл-шрифты jar, без AWT/JEuclid (текст из PDF не извлекается, пинь пикселями); неподдерживаемая конструкция или превышение бюджета — текстовая деградация (конкатенация `m:t`, `MathFallbackNormalizer`, правило 6) + warn, inline-формула выравнивается по базовой линии текста (мат-ось Word — принятая деградация), `m:oMathPara` — отдельный центрированный абзац (left/right по `m:jc`, indentLeft→left); фон `w:highlight`/`w:shd` рисуется (§17.3.2.16/.29). Скрытый текст `w:vanish` не печатается (правило 10); текст руби-базы и `w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir` не теряется (правило 11 + AUDIT-FIX-2). Остаток (не чиним): `w:framePr` игнорируется — текст печатается в общем потоке, геометрия фрейма теряется (ни XSLT, ни `createBlockForPPr` не читают); `REF`/`SEQ`/литеральные записи `TOC` печатают устаревший кэш из docx (движка пересчёта нет; инстринции полей не печатаются); надстрочница руби не выводится (правило 11 печатает только базу — ruby-разметки в FOP нет); `w:ptab` без `@w:alignment`, `bar`, `list` теряются catch-all'ом; `w:bdo`/`w:dir` печатаются LTR (bidi вне контура).
|
||||||
|
|||||||
+17
-16
@@ -4,18 +4,19 @@
|
|||||||
|
|
||||||
| Путь | Назначение |
|
| Путь | Назначение |
|
||||||
|---|---|
|
|---|---|
|
||||||
| `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-core/src/main/java/ru/pjandro/wordpdf/` | Публичный API: `WordPdfConverter` (`convert(byte[],String,ConvertOptions)`), `WordPdfValidator` (`checkInput`/`validate` наружу; `checkPageCount`/`checkPageCountDoc`/`isBinaryDoc` — package-private, всё без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `ChartsFoundException`/`SmartArtFoundException`/`OleFoundException` (по error-флагам), `ConvertOptions` (record; дефолтов в ядре нет). Пороги защиты — производные от лимитов входа: `WordPdfValidator.maxDecompressedBytes`/`maxDecompressedXmlBytes` (`max(MIN_*×MiB, maxMb×10/4MiB + maxPages×64/32KiB)`, крышек нет), `maxZipEntries` (`max(2048, maxMb×512 + maxPages×32)`), `maxImagePixels` (`maxMb×5_000_000`); коэффициенты и полы — package-private литералы `WordPdfConverter` (`DECOMPRESS_*`, `MIN_DECOMPRESSED_*`, `IMAGE_PIXELS_PER_MAX_MB`, `ZIP_ENTRIES_*`, javac их инлайнит — валидатор не инициализирует конвертер) |
|
||||||
| `…/wordpdf/fonts/` | `BundledFonts` (реестр/выгрузка TTF), `BundledFontMapper` (алиасы, self-map, `DISPLAY_NAMES`, `bundledFamily`), `GlyphFont` (глиф-движок fontbox) |
|
| `…/wordpdf/fonts/` | `BundledFonts` (реестр/выгрузка TTF), `BundledFontAliases` (алиасы, `DISPLAY_NAMES`, `bundledFamily` — без наследования, статика безопасна до гейта), `BundledFontMapper` (экземпляр-маппер docx4j), `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/` | 12 нормализаторов + `DocxRewritePipeline` (один zip-проход правил 1–11, raw-копия неизменённых записей) + `LayoutPostRenderer` (кастомный `FORenderer`, post-FO padding-компенсация таблиц, шаг 4.25) + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка commons-compress, шаг 0). Классы package-private; `public` — `DocxNormalizer`, `DocxRewritePipeline` (наружу только `STEP`, `normalize` package-private), `OleObjectNormalizer`, `FopFallbackFonts` (`declare`), `LayoutPostRenderer` (`register`), `DependencyGuard` (`check`), остальные нормализаторы полностью package-private; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `OleFoundException` |
|
||||||
| `…/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/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/chart/` |18 классов Java2D-рендера диаграмм/SmartArt в PNG (public: `DrawingPreRenderer.run` и `ChartImageHandler` — второй инстанцируется из `WordPdfConverter`)|
|
| `…/wordpdf/internal/chart/` |21 классов Java2D-рендера диаграмм/SmartArt/OMML-формул в PNG (`MathModel`/`MathRenderer`/`MathUnsupportedException` — формулы); public: `DrawingPreRenderer.run` и `ChartImageHandler` — второй инстанцируется из `WordPdfConverter`|
|
||||||
| `wordpdf-core/src/main/resources/fonts/` | 30 TTF + 3 лицензии — бинарные фикстуры, часть jar |
|
| `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/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/` | 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/geom/` | `presetShapeDefinitions.xml` — копия приложения ECMA-376, синхрон таблицы `PresetGeometry` (только в тестах, в jar не попадает) |
|
| `wordpdf-core/src/test/resources/geom/` | `presetShapeDefinitions.xml` — копия приложения ECMA-376, синхрон таблицы `PresetGeometry` (только в тестах, в jar не попадает) |
|
||||||
| `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/` | REST API (11 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`, `OpenApiConfig` (`@SecurityScheme` X-API-Key) + 5 классов исключений (`BadRequest`, `DrawingRejected`, `ConversionFailed`, `ConversionRejected`, `ConversionTimeout`) |
|
| `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/` | REST API (11 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`, `OpenApiConfig` (`@SecurityScheme` X-API-Key) + 5 классов исключений (`BadRequest`, `DrawingRejected`, `ConversionFailed`, `ConversionRejected`, `ConversionTimeout`) |
|
||||||
| `wordpdf-web/src/` | SPA: `api.ts` (вся сеть), `components/` (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo) |
|
| `wordpdf-web/src/` | SPA: `api.ts` (вся сеть), `components/` (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo) |
|
||||||
| корневые `Containerfile`, `compose.yml`, `compose.dev.yml`, `gateway/nginx.conf` | Образ бэкенда (multi-stage `maven:3.9-eclipse-temurin-17` → `eclipse-temurin:17-jre-alpine`, non-root uid 10001, `-XX:MaxRAMPercentage=70`, HEALTHCHECK — busybox `wget`); compose app+web+gateway (`mem_limit: 2g` app, подсеть `10.113.0.0/24` gw `10.113.0.1`, `x-podman.name_separator_compat`); прод-compose не в репо — его рендерит job `deploy`; в репо-`compose.yml` springdoc выключен env (`SPRINGDOC_API_DOCS_ENABLED=false`, `SPRINGDOC_SWAGGER_UI_ENABLED=false`), в `compose.dev.yml` springdoc-переменных нет вовсе — включён по умолчанию (не отключается). `wordpdf-web/Containerfile` — `node:24-alpine` → `nginx:alpine`, `ARG VITE_BASE=/` (прод-CI печёт `/pdf-converter/`); репозиторный `wordpdf-web/nginx.conf` в образ **не** копируется (SPA одностраничная, без клиентского роутинга — SPA-fallback не нужен) |
|
| `wordpdf-web/nginx.conf` | В образ SPA (`Containerfile` COPY в `/etc/nginx/conf.d/default.conf` — переопределение default-сервера, отдельного монтирования нет): `try_files` SPA-fallback + `add_header ... always` (езжают и на 4xx/5xx): CSP `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'` (inline-стили React); `img-src`/`frame-src` + blob: (PDF-предпросмотр в iframe); `connect-src 'self'`; `object-src 'none'` + `nosniff`, XFO DENY (не мешает blob-iframe), Referrer-Policy no-referrer |
|
||||||
|
| корневые `Containerfile`, `compose.yml`, `compose.dev.yml`, `gateway/nginx.conf` | Образ бэкенда (multi-stage `maven:3.9-eclipse-temurin-17` → `eclipse-temurin:17-jre-alpine`, non-root uid 10001, фиксированный heap `-Xms2g -Xmx2g`, HEALTHCHECK — busybox `wget`); compose app+web+gateway (`mem_limit: 3g` app, подсеть `10.113.0.0/24` gw `10.113.0.1`, `x-podman.name_separator_compat`); прод-compose не в репо — его рендерит job `deploy`; в репо-`compose.yml` springdoc выключен env (`SPRINGDOC_API_DOCS_ENABLED=false`, `SPRINGDOC_SWAGGER_UI_ENABLED=false`), в `compose.dev.yml` springdoc-переменных нет вовсе — включён по умолчанию (не отключается). `wordpdf-web/Containerfile` — `node:24-alpine` → `nginx:alpine`, `ARG VITE_BASE=/` (прод-CI печёт `/pdf-converter/`); `wordpdf-web/nginx.conf` копируется в образ (см. строку выше) |
|
||||||
| `.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 |
|
| `.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/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, защита ветки, перезапуск — только имена переменных, без значений |
|
| `GITEA-vars.md` | Инструкция владельца: Secrets/Variables, защита ветки, перезапуск — только имена переменных, без значений |
|
||||||
@@ -28,16 +29,16 @@
|
|||||||
|
|
||||||
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures` + `normalizers(options)` (порядок цепочки).
|
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures` + `normalizers(options)` (порядок цепочки).
|
||||||
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java` — валидация входа и lightweight-подсчёт страниц (StAX, без docx4j).
|
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java` — валидация входа и lightweight-подсчёт страниц (StAX, без docx4j).
|
||||||
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_MB = 5`, `MAX_PAGES = 100`, `ERROR_ON_* = false`); рантайм-конфигурации в ядре нет.
|
- Дефолтов лимитов в ядре нет (`WordPdfSettings` упразднён): лимиты входа всегда приходят с вызовом через `ConvertOptions`, производные пороги считает `WordPdfValidator.max*` (см. таблицу выше).
|
||||||
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/chart/DrawingPreRenderer.java` — замена диаграмм/SmartArt на PNG; владеет `MAX_EXTENT_EMU` и деградацией при падении рендера.
|
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/chart/DrawingPreRenderer.java` — замена диаграмм/SmartArt/OMML-формул на PNG; владеет `MAX_EXTENT_EMU` и деградацией при падении рендера (формула — текст вместо удаления).
|
||||||
- `wordpdf-app/src/main/resources/application.properties` — multipart 100MB (`max-file-size`/`max-request-size` + `file-size-threshold=2MB` — части крупнее 2 МБ на диск, не в память; в тон gateway `client_max_body_size 100m`), `wordpdf.convert-timeout=2m`, пустой `wordpdf.api-key`, `server.forward-headers-strategy=framework` (префикс прод-прокси для springdoc) + `springdoc.swagger-ui.persist-authorization=true`; `wordpdf.max-mb`/`max-pages` здесь намеренно нет.
|
- `wordpdf-app/src/main/resources/application.properties` — multipart 100MB (`max-file-size`/`max-request-size` + `file-size-threshold=2MB` — части крупнее 2 МБ на диск, не в память; в тон gateway `client_max_body_size 100m`), `wordpdf.convert-timeout=2m`, пустой `wordpdf.api-key`, `server.forward-headers-strategy=framework` (префикс прод-прокси для springdoc) + `springdoc.swagger-ui.persist-authorization=true`; `wordpdf.max-mb`/`max-pages` здесь намеренно нет.
|
||||||
- `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён; `spring-boot-starter-webmvc` (Boot 4: переименован из starter-web) + `spring-boot-starter-actuator` (нужен HEALTHCHECK контейнера `/actuator/health`); тест-зависимости: `spring-boot-webmvc-test` (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.
|
- `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён; `spring-boot-starter-webmvc` (Boot 4: переименован из starter-web) + `spring-boot-starter-actuator` (нужен HEALTHCHECK контейнера `/actuator/health`); тест-зависимости: `spring-boot-webmvc-test` (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.
|
||||||
- `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app); JaCoCo execution `check` переопределён (LINE 0.90 + BRANCH 0.85).
|
- `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app); JaCoCo execution `check` переопределён (LINE 0.90 + BRANCH 0.85).
|
||||||
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, commons-compress `1.28.0`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox/fontbox `3.0.8` (`fontbox` — compile в core: глиф-движок `GlyphFont`; `pdfbox` — test в обоих модулях; commons-logging исключён, мост — `jcl-over-slf4j`), POI `5.5.1` (test), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; pluginManagement: compiler `3.16.0`, surefire `3.6.0` с `-Djava.awt.headless=true`, jar `3.5.1`, PMD `3.28.0`, JaCoCo `0.8.15`; пустой дефолт `<argLine>` (для `-Djacoco.skip=true`).
|
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, commons-compress `1.28.0`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox/fontbox `3.0.8` (`fontbox` — compile в core: глиф-движок `GlyphFont`; `pdfbox` — test в обоих модулях; commons-logging исключён, мост — `jcl-over-slf4j`), POI `5.5.1` (test), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; pluginManagement: compiler `3.16.0`, surefire `3.6.0` с `-Djava.awt.headless=true`, jar `3.5.1`, PMD `3.21.2` (движок PMD `6.55.0`), JaCoCo `0.8.15`; пустой дефолт `<argLine>` (для `-Djacoco.skip=true`).
|
||||||
- `pmd-ruleset.xml` — ruleset PMD (см. Code Conventions).
|
- `pmd-ruleset.xml` — ruleset PMD (см. Code Conventions).
|
||||||
- `.ci/maven-settings.xml` — Maven-зеркало Nexus с URL из `${env.MAVEN_MIRROR_URL}` (общий файл CI-job'ов `java` и Containerfile; координаты стенда в репо не хранятся — Variable/build-arg).
|
- `.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.
|
- `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 до перезапуска).
|
- `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 до перезапуска); `X-Forwarded-For`/`-Proto`/`-Host` переписываются безусловно (`$remote_addr`/`$scheme`/`$host` — клиент не подставляет доверяемые Spring заголовки; `X-Forwarded-Prefix` проходит как есть — на нём base swagger-ui за внешним прокси). Тот же набор в прод-ренвере job `deploy` (`main.yml`, heredoc `NGINX`).
|
||||||
- `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`.
|
||||||
- `wordpdf-web/vite.local.config.ts` — легаси-одноразовщик (прокси `/api` → :8091), в `tsconfig.node.json` не включён; кандидат на удаление, не тиражировать паттерн. Корневые `javac.*.args` — мусор пробной компиляции (gitignored), тоже кандидат на удаление.
|
- `wordpdf-web/vite.local.config.ts` — легаси-одноразовщик (прокси `/api` → :8091), в `tsconfig.node.json` не включён; кандидат на удаление, не тиражировать паттерн. Корневые `javac.*.args` — мусор пробной компиляции (gitignored), тоже кандидат на удаление.
|
||||||
|
|
||||||
@@ -79,7 +80,7 @@ unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-expo
|
|||||||
|
|
||||||
## REST API (детали bullet'ов)
|
## REST API (детали bullet'ов)
|
||||||
|
|
||||||
Единственный эндпоинт `POST /api/v1/convert`: multipart-поле `file` + факультативные query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолт каждого — `WordPdfSettings.ERROR_ON_*`). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`/`.doc`-расширения — в `ConvertController` (ошибочный текст 400 — контракт с фронтом); `ConversionService.safeBaseName` — единый источник имени для файла, заголовка ответа и PDF-title (срезает оба расширения; разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). Error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры → картинки, см. «Мост») — описано в `@Operation`.
|
Единственный эндпоинт `POST /api/v1/convert`: multipart-поле `file` + факультативные query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолт каждого — `false`) и `maxMb`/`maxPages` (лимиты входа, см. «Лимиты входа» ниже). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`/`.doc`-расширения — в `ConvertController` (ошибочный текст 400 — контракт с фронтом); `ConversionService.safeBaseName` — единый источник имени для файла, заголовка ответа и PDF-title (срезает оба расширения; разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). Error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры → картинки, см. «Мост») — описано в `@Operation`.
|
||||||
|
|
||||||
Полная карта ответов:
|
Полная карта ответов:
|
||||||
|
|
||||||
@@ -95,8 +96,8 @@ unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-expo
|
|||||||
| 504 | `ConversionTimeoutException` |
|
| 504 | `ConversionTimeoutException` |
|
||||||
|
|
||||||
- **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). Без ключа открыты `OPEN_PREFIXES` = `/actuator/`, `/swagger-ui`, `/v3/api-docs` — матч по пути **без** forwarded-contextPath (`getRequestURI()` минус `getContextPath()`; иначе под `X-Forwarded-Prefix` HEALTHCHECK получил бы 401). Пути с точечными сегментами (`..`/`%2e`) открытыми не считаются никогда.
|
- **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). Без ключа открыты `OPEN_PREFIXES` = `/actuator/`, `/swagger-ui`, `/v3/api-docs` — матч по пути **без** forwarded-contextPath (`getRequestURI()` минус `getContextPath()`; иначе под `X-Forwarded-Prefix` HEALTHCHECK получил бы 401). Пути с точечными сегментами (`..`/`%2e`) открытыми не считаются никогда.
|
||||||
- **Очередь**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` и **не потокобезопасно**. Головой очереди конструктор ставит `WordPdfConverter.warmup()` — прогрев ядра минимальным in-code docx + растром (~1,5–2,5 с, Future никто не забирает, warmup не бросает): первый реальный запрос после деплоя — за прогретым ядром (замер 2026-11: 0,13 с против 1,74 с на `main`), запросы периода прогрева ждут в очереди штатно. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс.
|
- **Очередь**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` и **сериализует конвертации монитором класса `WordPdfConverter.class`**; однопоточность воркера — ради 503/timeout. Головой очереди конструктор ставит `WordPdfConverter.warmup()` — прогрев ядра минимальным in-code docx + растром (~1,5–2,5 с, Future никто не забирает, warmup не бросает): первый реальный запрос после деплоя — за прогретым ядром (замер 2026-11: 0,13 с против 1,74 с на `main`), запросы периода прогрева ждут в очереди штатно. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс.
|
||||||
- **Лимиты входа** задаёт только конфигурация сервера: `wordpdf.max-mb`/`wordpdf.max-pages` (env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`), `@Value` в `ConvertController` с дефолтом-SpEL из `WordPdfSettings` (5 МБ / 100); значение ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются. Ключи в `application.properties` **не объявлены** — пустое значение затенит SpEL-дефолт.
|
- **Лимиты входа**: `wordpdf.max-mb`/`wordpdf.max-pages` (env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`) — дефолт эндпоинта, `@Value` в `ConvertController` с литеральными дефолтами 5/100; значение свойства ≤ 0 → `IllegalStateException` на старте. Параметры запроса `maxMb`/`maxPages` переопределяют дефолт в обе стороны (значения ≤ 0 → 400), верхнего серверного потолка нет — пороги распаковки/записей/растров растут вместе с ними. Ключи в `application.properties` **не объявлены** — пустое значение затенит дефолт `@Value`.
|
||||||
|
|
||||||
- **SPA**: вся сеть в `wordpdf-web/src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается, экран `ApiKeyGate` (`UnauthorizedError` — наследник `ApiError`, проверяется раньше); гейт показывается только когда `probeApiKey()` (GET /api/v1/convert → 401) подтвердил требование ключа. Запросы на `${import.meta.env.BASE_URL}api/...` (vite `base` из `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx под префиксом `/pdf-converter/`). Три переключателя error-флагов в форме («Диаграммы», «SmartArt», «OLE-объекты», дефолт — все выключены). DropZone принимает `.docx,.doc` (`accept` + текст зоны).
|
- **SPA**: вся сеть в `wordpdf-web/src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается, экран `ApiKeyGate` (`UnauthorizedError` — наследник `ApiError`, проверяется раньше); гейт показывается только когда `probeApiKey()` (GET /api/v1/convert → 401) подтвердил требование ключа. Запросы на `${import.meta.env.BASE_URL}api/...` (vite `base` из `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx под префиксом `/pdf-converter/`). Три переключателя error-флагов в форме («Диаграммы», «SmartArt», «OLE-объекты», дефолт — все выключены). DropZone принимает `.docx,.doc` (`accept` + текст зоны).
|
||||||
|
|
||||||
@@ -104,11 +105,11 @@ unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-expo
|
|||||||
|
|
||||||
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчик картинок (`imageCount`/`distinctImageCount` — SMask игнорируется). Негативные маркеры: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`); в `tableImage_tableAndImage` — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах).
|
- **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчик картинок (`imageCount`/`distinctImageCount` — SMask игнорируется). Негативные маркеры: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`); в `tableImage_tableAndImage` — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах).
|
||||||
|
|
||||||
PMD: `failurePriority` в плагине не задан — на практике `verify` валит нарушение любой приоритетности; перечень исключённых правил в AGENTS.md не дублируется — единственный источник `pmd-ruleset.xml`.
|
PMD: `failurePriority` в плагине не задан — на практике `verify` валит нарушение любой приоритетности; закрытый список правил — единственный источник `pmd-ruleset.xml` (в AGENTS.md не дублируется). Четыре правила `*MustUseBraces` деприкейтед в 6.55.0 — предупреждения «Discontinue using…» в логе verify ожидаемы.
|
||||||
|
|
||||||
- Нормализаторы — единый контракт `internal/DocxNormalizer` + константа `STEP`; цепочка `WordPdfConverter.normalizers()` = `DocxRewritePipeline.STEP` (правила 1–10 одним zip-проходом) + лямбда `OleObjectNormalizer`; нечего менять → **тот же массив**; package-private хук `static String rewrite(String xml)` для юнит-тестов (возвращает `null` при отсутствии изменений; есть у 10 из 11 — у многочастного `OleObjectNormalizer` нет); у `StrictOoxmlNormalizer` есть также `rewritePart(entryName, xml)`, у `TableIndentNormalizer` — `rewritePart(name, xml, band)` (per-part-логика, хуки пайплайна); правятся только части `word/*.xml`.
|
- Нормализаторы — единый контракт `internal/DocxNormalizer`; константа `STEP` только у `DocxRewritePipeline` (сам собирает цепочку); цепочка `WordPdfConverter.normalizers()` = `DocxRewritePipeline.STEP` (правила 1–11 одним zip-проходом) + лямбда `OleObjectNormalizer`; нечего менять → **тот же массив**; package-private хук `static String rewrite(String xml)` для юнит-тестов (возвращает `null` при отсутствии изменений; есть у 11 из 12 — у многочастного `OleObjectNormalizer` нет); у `StrictOoxmlNormalizer` есть также `rewritePart(entryName, xml)`, у `TableIndentNormalizer` — `rewritePart(name, xml, band)` (per-part-логика, хуки пайплайна); правятся только части `word/*.xml`.
|
||||||
|
|
||||||
- Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run`/`DependencyGuard.check` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`.
|
- Классы в `internal` — package-private; `public` только контракт наружу: `DocxNormalizer`, `DocxRewritePipeline`(+`STEP`), `OleObjectNormalizer`, `FopFallbackFonts`(+`declare`), `LayoutPostRenderer`(+`register`), `DependencyGuard`(+`check`) и `DrawingPreRenderer`(+`run`); `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`) и защитные ветви сканеров нормализаторов/валидатора.
|
- Гейт 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`) и защитные ветви сканеров нормализаторов/валидатора.
|
||||||
- Счётчики тестов и описание блока аудита .docx 2026-11 — `docs/agent/testing.md`. 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`).
|
- Счётчики тестов и описание блока аудита .docx 2026-11 — `docs/agent/testing.md`. 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`).
|
||||||
@@ -120,4 +121,4 @@ PMD: `failurePriority` в плагине не задан — на практик
|
|||||||
|
|
||||||
## Шрифты (детали)
|
## Шрифты (детали)
|
||||||
|
|
||||||
`DISPLAY_NAMES` — обратный маппинг lowercase→отображаемое имя для `documentFontName` (пишет `GlyphCoverageNormalizer` в `w:rFonts`). `BundledFontMapper.bundledFamily` — public-хук «имя шрифта из docx → бандл-семейство или fallback» (пользуется chart-движком). `GlyphFont` — глиф-движок на fontbox (метрики + растеризация глифов для chart-движка и покрытия глифов); читает TTF **напрямую из classpath** `fonts/<file>` (не из temp-каталога `BundledFonts`), кэш по `family/variant`, `of()` возвращает `null` для неизвестного семейства; `java.awt.Font` из рантайм-пути убран, AWT остаётся только как геометрия Graphics2D.
|
`DISPLAY_NAMES` — обратный маппинг lowercase→отображаемое имя для `documentFontName` (пишет `GlyphCoverageNormalizer` в `w:rFonts`). `BundledFontAliases.bundledFamily` — public-хук «имя шрифта из docx → бандл-семейство или fallback» (пользуется chart/math-движком и покрытием); вынесен из `BundledFontMapper`, чтобы обращение к статике не тянуло `BestMatchingMapper.<clinit>` (скан classpath вне гейта свойств `docx4j.fonts.discover*`, которые выставляет `WordPdfConverter.<clinit>`). `GlyphFont` — глиф-движок на fontbox (метрики + растеризация глифов для chart-движка и покрытия глифов); читает TTF **напрямую из classpath** `fonts/<file>` (не из temp-каталога `BundledFonts`), кэш по `family/variant`, `of()` возвращает `null` для неизвестного семейства; `java.awt.Font` из рантайм-пути убран, AWT остаётся только как геометрия Graphics2D.
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
### Счётчики (2026-11)
|
### Счётчики (2026-11)
|
||||||
|
|
||||||
- 59 тестовых классов / 898 тестов: core 53/849 (`internal/doc/` 17/225, `internal/chart/` 17/271, `WordPdfConverterTest` 77), app 6/49 (ConvertController 23, ApiKeyFilter 8, ConversionService 5, ApiExceptionHandler 5, ConvertLimits 5, ConversionTimeout 3). Обновлять при изменении набора.
|
- 63 тестовых классов / 1004 теста: core 57/956 (`internal/doc/` 17/256, `internal/chart/` 18/301, `WordPdfConverterTest` 87), app 6/48 (ConvertController 26, ApiKeyFilter 8, ConversionService 5, ApiExceptionHandler 5, ConvertLimits 3, ConversionTimeout 1). Обновлять при изменении набора.
|
||||||
|
|
||||||
### Пиксели, метрики шрифтов, стенд без fontconfig
|
### Пиксели, метрики шрифтов, стенд без fontconfig
|
||||||
|
|
||||||
@@ -20,7 +20,7 @@
|
|||||||
|
|
||||||
- Юниты моста (`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`).
|
- Юниты моста (`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`).
|
||||||
|
|
||||||
- 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-контекста (прямые юниты).
|
- App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); четыре контекста — `ConvertControllerTest` (пин `wordpdf.api-key=` — HTTP-контексты явно пиныт пустой ключ: mise подмешивает корневой `.env` в окружение тасок, ambient `WORDPDF_API_KEY` иначе дал бы 401 во всех MockMvc-тестах), `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, 31 проверка — 27 под маркером `needs_key` (SKIP без ключа; включая `.doc`-фикстуры обоих путей — растры/OLE и границы страниц), 4 открытых: health/SPA-root/swagger/spec; env-конфиг, `mise exec -- python -m pytest -q .` из `prod-autotests/`) гоняются CI после deploy против живого прода.
|
||||||
|
|
||||||
@@ -31,5 +31,5 @@
|
|||||||
- `lineRuleAuto_wordSingleLinePitch` — пинит метрический шаг «single» (13.4277pt) от псевдофиксов раскладки; `carlitoAutoBlock_untouched` — блок без явного `w:line` не трогается.
|
- `lineRuleAuto_wordSingleLinePitch` — пинит метрический шаг «single» (13.4277pt) от псевдофиксов раскладки; `carlitoAutoBlock_untouched` — блок без явного `w:line` не трогается.
|
||||||
- `vendoredXsltTracksJarCopy` — дрейф-гейт: вне AUDIT-FIX-регионов вендорный `docx2fo.xslt` обязан быть побайтно равен стилисту из jar'а docx4j-export-fo (при апгрейде docx4j — перевендорить и перенести патчи).
|
- `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 продублирован в обоих тестовых классах).
|
- Крафт 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-шапка)..
|
- Синтетика через общий хелпер `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_renderedAsPng` (пиксели: +150 тёмных px@150dpi сверх текста, текст формулы не извлекается), `ommlMathUnsupported_flattenedToText`, `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`, `oversizedOverCoreLimit_rejected`, `drawingsAlwaysRendered`, `cyrillicAndPathInFilename_sanitizedResponseName`, `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey`, `dotSegmentOpenPrefix_rejected`, `errorFlagNotBoolean_rejected`, `methodNotSupportedReturns405`/`badContentTypeReturns415`.
|
||||||
|
|||||||
@@ -0,0 +1,52 @@
|
|||||||
|
# Аутентификация
|
||||||
|
|
||||||
|
## Ключ доступа
|
||||||
|
|
||||||
|
Все запросы, кроме открытых путей, требуют заголовок:
|
||||||
|
|
||||||
|
```
|
||||||
|
X-API-Key: <ключ>
|
||||||
|
```
|
||||||
|
|
||||||
|
Ключ сверяется со свойством сервера `wordpdf.api-key` (env `WORDPDF_API_KEY`).
|
||||||
|
Сравнение — `MessageDigest.isEqual` (защита от timing-атак). **Пустое свойство =
|
||||||
|
аутентификация выключена** — так работают `java -jar` и dev-стенд (:9011).
|
||||||
|
|
||||||
|
Без ключа или с неверным:
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP 401
|
||||||
|
{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Открытые пути
|
||||||
|
|
||||||
|
Без ключа всегда доступны (матч по **префиксу со слэшем**, без учёта
|
||||||
|
forwarded-contextPath):
|
||||||
|
|
||||||
|
|Префикс|Что|
|
||||||
|
|---|---|
|
||||||
|
|`/actuator/`|health-checks Spring Boot|
|
||||||
|
|`/swagger-ui`|Swagger UI|
|
||||||
|
|`/v3/api-docs`|OpenAPI-спек|
|
||||||
|
|
||||||
|
!!! warning "Точечные сегменты обходят открытие"
|
||||||
|
Пути с точечными сегментами (`..` или их URL-код `%2e`) **никогда** не считаются
|
||||||
|
открытыми: запрос вида `/actuator/../api/v1/convert` потребует ключ даже на
|
||||||
|
открытом префиксе. Это защита от обхода фильтра через нормализацию пути.
|
||||||
|
|
||||||
|
## Где задаётся ключ
|
||||||
|
|
||||||
|
|Среда|Как|
|
||||||
|
|---|---|
|
||||||
|
|`java -jar`|`wordpdf.api-key=` пусто — auth выключен; включить: `--wordpdf.api-key=…` или env `WORDPDF_API_KEY`|
|
||||||
|
|prod-like стенд (:9010)|обязателен `.env` с `WORDPDF_API_KEY` (fail-closed: без него стек не поднимется), шаблон — `.env.example`|
|
||||||
|
|прод|env-переменная контейнера из Gitea Secret (в репозитории и на диске ключа нет)|
|
||||||
|
|
||||||
|
Сгенерировать ключ: `openssl rand -hex 32`.
|
||||||
|
|
||||||
|
## Как фронтенд узнаёт про ключ
|
||||||
|
|
||||||
|
SPA при старте опрашивает сервис (`probeApiKey()`, `GET /api/v1/convert`): 401 —
|
||||||
|
сервер требует ключ, показывается экран ввода; иначе — интерфейс открывается сразу.
|
||||||
|
Введённый ключ хранится в `localStorage` браузера и стирается при ответе 401.
|
||||||
@@ -0,0 +1,45 @@
|
|||||||
|
# Эндпоинт конвертации
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/v1/convert
|
||||||
|
```
|
||||||
|
|
||||||
|
Тело запроса — `multipart/form-data` с обязательным полем **`file`**: файл `.docx`
|
||||||
|
(OOXML) или `.doc` (Word 97–2003, переносится мостом в .docx в памяти). Файлы других
|
||||||
|
расширений отклоняются 400.
|
||||||
|
|
||||||
|
## Факультативные query/form-параметры
|
||||||
|
|
||||||
|
Параметры можно передать в query-строке или как form-поля.
|
||||||
|
|
||||||
|
|Параметр|Тип|Дефолт|Действие|
|
||||||
|
|---|---|---|---|
|
||||||
|
|`errorOnCharts`|Boolean|`false`|при `true` диаграммы в документе отменяют конвертацию (422); диаграммы конвертируются в растры всегда|
|
||||||
|
|`errorOnSmartArt`|Boolean|`false`|при `true` SmartArt отменяет конвертацию (422)|
|
||||||
|
|`errorOnOle`|Boolean|`false`|при `true` OLE-объекты отменяют конвертацию (422); при `false` OLE-объекты тихо удаляются, картинка-плейсхолдер сохраняется|
|
||||||
|
|`maxMb`|число|свойство сервера `wordpdf.max-mb` (5)|лимит размера входа в МБ; переопределяет серверный дефолт **в обе стороны**; `≤ 0` → 400|
|
||||||
|
|`maxPages`|число|свойство сервера `wordpdf.max-pages` (100)|лимит числа страниц; переопределяет в обе стороны; `≤ 0` → 400|
|
||||||
|
|
||||||
|
!!! note "На `.doc` error-флаги не срабатывают"
|
||||||
|
Плейсхолдеры диаграмм/SmartArt/OLE в бинарном формате — это BLIP-растры, мост
|
||||||
|
вставляет их картинками; векторные EMF/WMF/PICT пропускаются с warn. Флаги
|
||||||
|
работают только для `.docx`.
|
||||||
|
|
||||||
|
## Успешный ответ
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP 200
|
||||||
|
Content-Type: application/pdf
|
||||||
|
Content-Disposition: attachment; filename*=UTF-8''Документ.pdf
|
||||||
|
```
|
||||||
|
|
||||||
|
Имя файла берётся из `Content-Disposition` загруженного файла, санитизируется
|
||||||
|
(разрешены буквы, цифры, пробел и `._-`; кириллица разрешена; пустое имя → `document`)
|
||||||
|
и используется единожды для имени файла, заголовка ответа и заголовка PDF.
|
||||||
|
|
||||||
|
## Обработка
|
||||||
|
|
||||||
|
Задача ставится в однопоточную очередь воркеров (16 мест). Проверка размера —
|
||||||
|
синхронно до очереди. Конвертация дольше `wordpdf.convert-timeout` (2m) → 504,
|
||||||
|
очередь полна → 503. Полная таблица ответов — [Коды ошибок](errors.md),
|
||||||
|
пороги — [Лимиты](limits.md).
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
# Коды ошибок
|
||||||
|
|
||||||
|
Ошибки — JSON вида `{"error": "..."}`.
|
||||||
|
|
||||||
|
## Полная таблица
|
||||||
|
|
||||||
|
|Код|Смысл|
|
||||||
|
|---|---|
|
||||||
|
|200|PDF в теле ответа|
|
||||||
|
|400|некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше лимита размера (`maxMb` или `wordpdf.max-mb`) / больше лимита страниц (`maxPages` или `wordpdf.max-pages`) / `maxMb`≤0 / `maxPages`≤0), отсутствующая часть `file`, некорректное значение error-флага|
|
||||||
|
|401|нет или неверен `X-API-Key`|
|
||||||
|
|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)|
|
||||||
|
|405|не-POST|
|
||||||
|
|413|тело запроса больше контейнерного лимита multipart (100 МБ; авторитетный лимит входа — `wordpdf.max-mb`, он даёт 400 раньше)|
|
||||||
|
|415|не-multipart тело|
|
||||||
|
|422|сработал error-флаг: в документе найдены диаграммы / SmartArt / OLE-объекты|
|
||||||
|
|500|ошибка ядра/рендера|
|
||||||
|
|503|очередь конвертации (16 мест) переполнена — повторить позже|
|
||||||
|
|504|конвертация дольше `wordpdf.convert-timeout` (по умолчанию 2m)|
|
||||||
|
|
||||||
|
## Фиксированные тексты
|
||||||
|
|
||||||
|
Тексты ниже — контракт с фронтендом, они не меняются:
|
||||||
|
|
||||||
|
|Код|Тело|
|
||||||
|
|---|---|
|
||||||
|
|401|`{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}`|
|
||||||
|
|404|`{"error":"Не найдено"}`|
|
||||||
|
|405|`{"error":"Метод не поддерживается"}`|
|
||||||
|
|415|`{"error":"Неподдерживаемый тип содержимого"}`|
|
||||||
|
|422 (диаграммы)|`{"error":"Конвертация отменена: в документе найдены диаграммы"}`|
|
||||||
|
|422 (SmartArt)|`{"error":"Конвертация отменена: в документе найден SmartArt"}`|
|
||||||
|
|422 (OLE)|`{"error":"Конвертация отменена: в документе найдены OLE-объекты"}`|
|
||||||
|
|500|`{"error":"Не удалось конвертировать документ"}`|
|
||||||
|
|
||||||
|
Другие 400-тексты параметризованы, например: `Файл не передан (multipart-поле «file»
|
||||||
|
обязательно)`, `Поддерживаются только .docx и .doc: <имя>`, `Файл больше <N> МБ: …`,
|
||||||
|
`Некорректное значение параметра «<имя>»`.
|
||||||
|
|
||||||
|
!!! info "500 — деталь только в лог"
|
||||||
|
Сообщения ядра (`ConversionException` и др.) логируются на сервере, наружу
|
||||||
|
всегда уходит фиксированный текст — внутренние детали не текут клиенту.
|
||||||
|
|
||||||
|
## Исключение → обработчик (для отладки)
|
||||||
|
|
||||||
|
|HTTP|Источник|
|
||||||
|
|---|---|
|
||||||
|
|400|`ValidationException`, `BadRequestException`, `MethodArgumentTypeMismatchException`, `MissingServletRequestPartException`|
|
||||||
|
|401|`ApiKeyFilter` (пишет ответ сам, до диспетчера)|
|
||||||
|
|404 / 405 / 415|`NoResourceFoundException` / `HttpRequestMethodNotSupportedException` / `HttpMediaTypeNotSupportedException`|
|
||||||
|
|413|`MaxUploadSizeExceededException`|
|
||||||
|
|422|`DrawingRejectedException`|
|
||||||
|
|500|`ConversionFailedException`|
|
||||||
|
|503|`ConversionRejectedException`|
|
||||||
|
|504|`ConversionTimeoutException`|
|
||||||
@@ -0,0 +1,74 @@
|
|||||||
|
# Примеры клиентов
|
||||||
|
|
||||||
|
Базовый адрес зависит от стенда: прод `https://pjandro.ru/pdf-converter/api/v1/convert`,
|
||||||
|
prod-like локально `http://localhost:9010/api/v1/convert`, dev `http://<LAN-IP>:9011/api/v1/convert`,
|
||||||
|
`java -jar` — `http://localhost:8080/api/v1/convert`.
|
||||||
|
|
||||||
|
## curl
|
||||||
|
|
||||||
|
Без ключа (сервер с выключенной аутентификацией):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
||||||
|
```
|
||||||
|
|
||||||
|
С ключом и error-флагом:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "X-API-Key: $WORDPDF_API_KEY" \
|
||||||
|
-F "file=@Отчёт.docx" \
|
||||||
|
"https://pjandro.ru/pdf-converter/api/v1/convert?errorOnOle=true&maxMb=10" \
|
||||||
|
-o out.pdf
|
||||||
|
```
|
||||||
|
|
||||||
|
## JavaScript (fetch)
|
||||||
|
|
||||||
|
```js
|
||||||
|
const form = new FormData();
|
||||||
|
form.append("file", fileInput.files[0], fileInput.files[0].name);
|
||||||
|
|
||||||
|
const resp = await fetch("/api/v1/convert", {
|
||||||
|
method: "POST",
|
||||||
|
headers: apiKey ? { "X-API-Key": apiKey } : {},
|
||||||
|
body: form,
|
||||||
|
});
|
||||||
|
|
||||||
|
if (!resp.ok) {
|
||||||
|
const { error } = await resp.json().catch(() => ({ error: resp.statusText }));
|
||||||
|
throw new Error(error);
|
||||||
|
}
|
||||||
|
|
||||||
|
// имя файла из Content-Disposition: attachment; filename*=UTF-8''%D0%9E%D1%82%D1%87%D1%91%D1%82.pdf
|
||||||
|
const cd = resp.headers.get("Content-Disposition") ?? "";
|
||||||
|
const m = cd.match(/filename\*=UTF-8''([^;]+)/i);
|
||||||
|
const name = m ? decodeURIComponent(m[1]) : "document.pdf";
|
||||||
|
|
||||||
|
const blobUrl = URL.createObjectURL(await resp.blob());
|
||||||
|
const a = Object.assign(document.createElement("a"), { href: blobUrl, download: name });
|
||||||
|
a.click();
|
||||||
|
URL.revokeObjectURL(blobUrl);
|
||||||
|
```
|
||||||
|
|
||||||
|
Обработка 401 — стереть сохранённый ключ и показать экран ввода; 422 — показать
|
||||||
|
`error` из тела (документ содержит диаграммы/SmartArt/OLE).
|
||||||
|
|
||||||
|
## Python (requests)
|
||||||
|
|
||||||
|
Таймаут обязан быть больше серверных 2 минут на чтение:
|
||||||
|
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
|
resp = requests.post(
|
||||||
|
"https://pjandro.ru/pdf-converter/api/v1/convert",
|
||||||
|
headers={"X-API-Key": API_KEY} if API_KEY else {},
|
||||||
|
files={"file": open("doc.docx", "rb")},
|
||||||
|
params={"errorOnCharts": "false"},
|
||||||
|
timeout=(10, 180), # connect 10 c, read 180 c — больше серверных 2m
|
||||||
|
)
|
||||||
|
resp.raise_for_status()
|
||||||
|
with open("doc.pdf", "wb") as f:
|
||||||
|
f.write(resp.content)
|
||||||
|
```
|
||||||
|
|
||||||
|
Так же устроены прод-автотесты репозитория (`prod-autotests/`, pytest + requests).
|
||||||
@@ -0,0 +1,53 @@
|
|||||||
|
# REST API
|
||||||
|
|
||||||
|
Базовый путь — корень сервера; единственный эндпоинт:
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/v1/convert
|
||||||
|
```
|
||||||
|
|
||||||
|
Quickstart — конвертировать документ и сохранить PDF (ключ доступа, если сервер его
|
||||||
|
требует, — в заголовке `X-API-Key`):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \
|
||||||
|
https://pjandro.ru/pdf-converter/api/v1/convert -o doc.pdf
|
||||||
|
```
|
||||||
|
|
||||||
|
Локальный бэкенд (`java -jar`, порт 8080, ключ выключен):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
|
||||||
|
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
||||||
|
```
|
||||||
|
|
||||||
|
Успешный ответ — `200`, тело — байты PDF (`Content-Type: application/pdf`,
|
||||||
|
`Content-Disposition: attachment; filename*=UTF-8''…`).
|
||||||
|
|
||||||
|
## Документация в самом сервисе
|
||||||
|
|
||||||
|
|Что|Путь|Когда доступно|
|
||||||
|
|---|---|---|
|
||||||
|
|Swagger UI|`/swagger-ui.html`|пока включён springdoc|
|
||||||
|
|OpenAPI (JSON)|`/v3/api-docs`|пока включён springdoc|
|
||||||
|
|
||||||
|
На `java -jar` и dev-стенде (:9011) springdoc включён; на проде он также открыт
|
||||||
|
(проверяется автотестом `test_swagger_ui_open_without_key`). В локальном prod-like
|
||||||
|
compose-стеке springdoc выключен env-ами `SPRINGDOC_API_DOCS_ENABLED=false` и
|
||||||
|
`SPRINGDOC_SWAGGER_UI_ENABLED=false` (в этом случае `/v3/api-docs` отвечает 404).
|
||||||
|
|
||||||
|
## Разделы
|
||||||
|
|
||||||
|
- [Аутентификация](authentication.md) — ключ `X-API-Key`.
|
||||||
|
- [Эндпоинт конвертации](convert-endpoint.md) — параметры и ответ.
|
||||||
|
- [Коды ошибок](errors.md) — полная таблица и тексты.
|
||||||
|
- [Лимиты](limits.md) — размер, страницы, очередь, таймаут.
|
||||||
|
- [Примеры клиентов](examples.md) — curl, JavaScript, Python.
|
||||||
|
|
||||||
|
## Как устроена обработка
|
||||||
|
|
||||||
|
Конвертации сериализуются **одним воркером**: ядро мутирует глобальный реестр шрифтов,
|
||||||
|
поэтому все конвертации идут последовательно (очередь — 16 мест, переполнение → 503).
|
||||||
|
Головой очереди на старте стоит `warmup()` — прогрев ядра (~1,5–2,5 с), чтобы первый
|
||||||
|
запрос после деплоя не платил за инициализацию JAXB/XSLT/FOP. Проверка размера входа
|
||||||
|
выполняется синхронно, до постановки в очередь.
|
||||||
@@ -0,0 +1,47 @@
|
|||||||
|
# Лимиты
|
||||||
|
|
||||||
|
## Лимиты входа
|
||||||
|
|
||||||
|
|Свойство|Env|Дефолт|Смысл|
|
||||||
|
|---|---|---|---|
|
||||||
|
|`wordpdf.max-mb`|`WORDPDF_MAX_MB`|5|максимальный размер файла в МБ (MiB)|
|
||||||
|
|`wordpdf.max-pages`|`WORDPDF_MAX_PAGES`|100|максимальное число страниц|
|
||||||
|
|
||||||
|
Это **дефолт эндпоинта**: параметры запроса `maxMb`/`maxPages` переопределяют его
|
||||||
|
в обе стороны (значения `≤ 0` → 400; верхнего серверного потолка нет — защитные
|
||||||
|
пороги растут вместе с лимитами). Значение свойства сервера `≤ 0` — падение
|
||||||
|
приложения на старте (`IllegalStateException`).
|
||||||
|
|
||||||
|
## Производные защитные пороги
|
||||||
|
|
||||||
|
Остальные пороги выводятся из лимитов входа (`WordPdfValidator`), проверяются
|
||||||
|
до рендера, одним lightweight-сканом:
|
||||||
|
|
||||||
|
- распакованный размер архива;
|
||||||
|
- суммарный распакованный размер XML-частей;
|
||||||
|
- число записей zip и защита от дубликатов записей;
|
||||||
|
- площади растровых изображений (пиксели);
|
||||||
|
- размер `[Content_Types].xml` (жёсткие 8 МБ).
|
||||||
|
|
||||||
|
Превышение любого — `400` (в библиотеке — `ValidationException`).
|
||||||
|
|
||||||
|
## Потолок инфраструктуры — 100 МБ
|
||||||
|
|
||||||
|
`spring.servlet.multipart.max-file-size`/`max-request-size` = 100MB — потолок
|
||||||
|
контейнера, зеркалит `client_max_body_size 100m` nginx-шлюза. Тело больше — 413.
|
||||||
|
Логический лимит входа (`wordpdf.max-mb`, дефолт 5 МБ) отсекает раньше и даёт 400;
|
||||||
|
413 возможен только когда серверный лимит поднят администратором выше дефолта.
|
||||||
|
|
||||||
|
Части загрузки больше 2 МБ (`file-size-threshold=2MB`) сбрасываются на диск Tomcat —
|
||||||
|
heap держит только копию байтов одной сериализованной конвертации.
|
||||||
|
|
||||||
|
## Очередь и таймаут
|
||||||
|
|
||||||
|
|Параметр|Значение|Поведение|
|
||||||
|
|---|---|---|
|
||||||
|
|ёмкость очереди|16 мест|переполнение → **503** (повторить позже)|
|
||||||
|
|`wordpdf.convert-timeout`|`2m` (env `WORDPDF_CONVERT_TIMEOUT`)|конвертация дольше → **504** (задача отменяется)|
|
||||||
|
|
||||||
|
Конвертации исполняются строго последовательно одним воркером (ядро мутирует
|
||||||
|
глобальный реестр шрифтов); при таймауте `future.cancel(true)` не останавливает FOP
|
||||||
|
мгновенно — текущая конвертация дожигается, следующий запрос ждёт её в очереди.
|
||||||
@@ -0,0 +1,62 @@
|
|||||||
|
# Диаграммы, SmartArt, формулы
|
||||||
|
|
||||||
|
XSLT-экспорт docx4j диаграммы не умеет, поэтому `DrawingPreRenderer` (шаг 3.5
|
||||||
|
конвейера) **до** генерации XSL-FO заменяет `c:chart` / `dgm:relIds` / `m:oMath`
|
||||||
|
на PNG-картинки (`pic:pic`). Рендер — собственный Java2D-движок (`internal/chart`,
|
||||||
|
21 класс), без Word/LibreOffice/JEuclid; текст рисуется глифами fontbox (`GlyphFont`),
|
||||||
|
поэтому fontconfig серверу не нужен.
|
||||||
|
|
||||||
|
## Диаграммы
|
||||||
|
|
||||||
|
- Выход: PNG **300 dpi** (`ChartRenderer.DPI = 300`), размеры из `wp:extent` (EMU→pt).
|
||||||
|
- Поддерживаемые типы (`ChartSpec.Type`): `PIE`, `PIE3D`, `DOUGHNUT`, `BAR`,
|
||||||
|
`BAR_HORIZONTAL`, `LINE`, `AREA`, `SURFACE3D`, `AREA3D`, `BAR3D`, `LINE3D`,
|
||||||
|
`RADAR`, `SCATTER`, `BUBBLE`, `STOCK`, `OF_PIE`, `SURFACE` (+ `UNSUPPORTED`).
|
||||||
|
- **Combo** («Комбинированная», §21.2.2.145): несколько групп в одном plotArea
|
||||||
|
(bar+line/area), привязка по `c:axId`, вторичная ось значений справа; серии
|
||||||
|
масштабируются по своей оси.
|
||||||
|
- Стекинг `stacked`/`percentStacked` — ряды накопленной суммой.
|
||||||
|
- Геометрия/камера 3-D и пропорции откалиброваны по эталонным экспортам Word
|
||||||
|
(пиксельные тесты с допусками).
|
||||||
|
|
||||||
|
## Умные границы (враждебный XML)
|
||||||
|
|
||||||
|
|Бюджет|Значение|Поведение при превышении|
|
||||||
|
|---|---|---|
|
||||||
|
|`ChartRenderer.MAX_PIXELS`|16 777 216 (4096², 64 МБ ARGB)|`fitDpi` понижает эффективный dpi (24″-график: 300→≈171 dpi), геометрия не меняется|
|
||||||
|
|`ChartSpec.MAX_POINTS`|100 000|отказ **до** предвыделения списка|
|
||||||
|
|`ChartRenderer.MAX_TICKS`|1000|безумный шаг оси заменяется «красивым» 1/2/5·10ⁿ|
|
||||||
|
|`DrawingPreRenderer.MAX_EXTENT_EMU`|22 000 000 (≈24″)|объект **остаётся как есть** + warn (не удаляется)|
|
||||||
|
|бюджет chart/math-PNG на документ|128 MiB|объект удаляется + warn|
|
||||||
|
|
||||||
|
## Модель деградации
|
||||||
|
|
||||||
|
Битая/неподдерживаемая часть роняет не конвертацию, а объект:
|
||||||
|
|
||||||
|
|Ситуация|Исход|
|
||||||
|
|---|---|
|
||||||
|
|битая chart-часть / превышение бюджета PNG|объект удалён + warn|
|
||||||
|
|неподдерживаемая/битая OMML-формула|**текст** (конкатенация `m:t`) + warn — текст терять хуже|
|
||||||
|
|`wp:extent` вне диапазона/ноль|объект остаётся + warn (FOP молча потеряет)|
|
||||||
|
|`OutOfMemoryError`|не деградация — `ConversionException` (REST 500)|
|
||||||
|
|
||||||
|
## SmartArt
|
||||||
|
|
||||||
|
`SmartArtRenderer` рисует диаграмму по разметке [MS-ODRAWXML]/§21.4: узлы, макет,
|
||||||
|
связи; тот же DPI/`fitDpi`.
|
||||||
|
|
||||||
|
## Формулы OMML
|
||||||
|
|
||||||
|
Собственный растер: `MathModel` разбирает OMML (§22.1) в дерево боксов,
|
||||||
|
`MathRenderer` рисует его только бандл-шрифтами. Конструкции вне списка `SUPPORTED`
|
||||||
|
деградируют в текст ещё на шаге нормализации (правило 6). Inline-формула опускается
|
||||||
|
на нижний запас рана — FOP ставит инлайн-графику нижним краем на базу строки.
|
||||||
|
|
||||||
|
## Контрафт media-частей
|
||||||
|
|
||||||
|
PNG-части получают имена `/word/media/chart-N.png` (константа
|
||||||
|
`CHART_MEDIA_URI_PREFIX`); по этому префиксу `ChartImageHandler` отключает
|
||||||
|
пересжатие картинок в FOP — переименование молча вернёт «мыльный» ресемпл.
|
||||||
|
|
||||||
|
Глубина (пейнтеры, калибровки, спецификационные секции) —
|
||||||
|
[chart.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/chart.md).
|
||||||
@@ -0,0 +1,61 @@
|
|||||||
|
# Мост .doc → .docx
|
||||||
|
|
||||||
|
Бинарный формат Word 97–2003 читается **собственным мостом** без внешних
|
||||||
|
зависимостей (POI остаётся test-scope): байты `.doc` парсятся по спецификациям
|
||||||
|
**[MS-DOC]** (сам документ) и **[MS-CFB]** (OLE2-контейнер), собираются in-memory
|
||||||
|
`.docx` — и дальше идут тем же конвейером, что и обычные docx.
|
||||||
|
|
||||||
|
## Точка входа
|
||||||
|
|
||||||
|
```java
|
||||||
|
DocToDocx.convert(byte[] docBytes, long maxMb) // → байты .docx (вызывает WordPdfConverter)
|
||||||
|
DocToDocx.countPages(byte[] docBytes) // → страницы по сырым байтам (вызывает валидатор)
|
||||||
|
```
|
||||||
|
|
||||||
|
Страницы `.doc` считаются **по сырым байтам до конвертации** (PageCount из
|
||||||
|
SummaryInformation, разрывы 0x0C, межсекционные разрывы, `pageBreakBefore`) —
|
||||||
|
тот же скан используется валидатором лимита страниц. Любой брак (не-CFB, шифрованный
|
||||||
|
документ, Word 6–95) → `ConversionException` (в REST — 400).
|
||||||
|
|
||||||
|
## Классы пакета `internal/doc` (18 top-level)
|
||||||
|
|
||||||
|
|Класс|Спецификация|Что делает|
|
||||||
|
|---|---|---|
|
||||||
|
|`CfbReader`|[MS-CFB] §2.2–2.6|FAT/DIFAT/miniFAT, directory; бюджеты против враждебного FAT, любой брак → `ConversionException`|
|
||||||
|
|`FibHeader`|[MS-DOC] §2.5.1|заголовок FIB: потоки 1Table/0Table, пары fc/lcb нужных индексов, сверка раскладок по nFib|
|
||||||
|
|`PieceTable`|§2.9.135|текст: куски CP1252/UTF-16LE, клампинг к `cbMac`, проверка aCP|
|
||||||
|
|`Grpprl`|§2.6.2|свойства форматирования (sprm'ы): bold/italic/шрифт/цвет/подсветка/заливка/отступы/табуляции|
|
||||||
|
|`ChpxIndex` / `PapxIndex`|§2.4.6|FKP-страницы символьных/абзацных свойств|
|
||||||
|
|`Styles`|§2.9.271|STSH: стилевые цепочки абзацев и символов (stk=1/2)|
|
||||||
|
|`Tables`|§2.6.3|TAP TTP-абзаца → сетка, границы, выравнивание таблицы|
|
||||||
|
|`Lists`|§2.9.200/.201|PlfLst/PlfLfo → `word/numbering.xml`|
|
||||||
|
|`Sections`|§2.8.26|PlcfSed → геометрия секций, ориентация, нумерация страниц, `titlePg`|
|
||||||
|
|`FontTable`|§2.9.286|SttbfFfn: индекс ftc → имя семейства|
|
||||||
|
|`SummaryInfo`|[MS-OLEPS]|`\x01SummaryInformation`: в т.ч. PageCount|
|
||||||
|
|`Headers`|§2.4.1|Plcfhdd: 6 колонтитуков на секцию → `headerN.xml`/`footerN.xml`|
|
||||||
|
|`OfficeArt`|[MS-ODRAW]|картинки: BLIP-хранилище (JPEG/PNG/TIFF/DIB/EMF/WMF/PICT)|
|
||||||
|
|`PrcData`|§2.9.210|разворачивание «огромных» grpprl, вынесенных за FKP-страницу|
|
||||||
|
|`DocToDocx`|—|оркестратор + вложенный `DocxBody` (сборка document.xml)|
|
||||||
|
|`DocxWriter`|—|мульти-частный zip: content-types, rels, numbering, headers, media|
|
||||||
|
|
||||||
|
17 из 18 классов package-private; наружу — только `DocToDocx`.
|
||||||
|
|
||||||
|
## Модель деградации (не падение)
|
||||||
|
|
||||||
|
|Объект в .doc|Поведение|
|
||||||
|
|---|---|
|
||||||
|
|OLE-внедрения (U+0001 в тексте)|плейсхолдер заменяется его же BLIP-картинкой|
|
||||||
|
|картинки JPEG/PNG/TIFF/DIB|переносятся дословно / через ImageIO в PNG|
|
||||||
|
|EMF/WMF/PICT|пропуск с warn (векторные растеризаторы не в контуре)|
|
||||||
|
|битые/неподдерживаемые конструкции|снисходительный разбор, объект исчезает или упрощается — текст не теряется|
|
||||||
|
|
||||||
|
Поэтому **error-флаги (`errorOnCharts`/`errorOnSmartArt`/`errorOnOle`) на `.doc` не
|
||||||
|
срабатывают**: OLE-вложения бинарного формата — это U+0001 с BLIP-плейсхолдером,
|
||||||
|
мост деградирует их в картинки, «OLE-объектов» в смысле docx-пути в результате нет.
|
||||||
|
|
||||||
|
## Сознательный остаток
|
||||||
|
|
||||||
|
Семантика рестартов списков (`fNoRestart`/`ilvlRestartLim`), `fLegal`,
|
||||||
|
AUTONUM-поля (трактуются как обычные списки), часть тонкостей объединённых ячеек —
|
||||||
|
осознанные упрощения вне контура; полный перечень —
|
||||||
|
[doc-bridge.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/doc-bridge.md).
|
||||||
@@ -0,0 +1,63 @@
|
|||||||
|
# Шрифты
|
||||||
|
|
||||||
|
Конвертация не зависит от шрифтов системы: **30 TTF упакованы в jar**
|
||||||
|
`wordpdf-core/src/main/resources/fonts/`, выгружаются во временный каталог и
|
||||||
|
регистрируются в docx4j/FOP. Реестр шрифтов после каждой конвертации возвращается
|
||||||
|
к бандлу — шрифты, встроенные в чужие docx, не влияют на последующие документы.
|
||||||
|
`java.awt.Font` не используется (метрики и глифы — fontbox напрямую), поэтому
|
||||||
|
**fontconfig серверу не нужен**.
|
||||||
|
|
||||||
|
## Бандл
|
||||||
|
|
||||||
|
7 текстовых семейств по 4 начертания + 2 покрывающих (только regular):
|
||||||
|
|
||||||
|
|Семейство|Аналог MS-шрифта|Назначение|
|
||||||
|
|---|---|---|
|
||||||
|
|Carlito|Calibri|метрически совместимая замена|
|
||||||
|
|Caladea|Cambria|метрически совместимая замена|
|
||||||
|
|Arimo|Arial|метрически совместимая замена|
|
||||||
|
|Tinos|Times New Roman|метрически совместимая замена|
|
||||||
|
|Cousine|Courier New|метрически совместимая замена|
|
||||||
|
|DejaVu Sans / DejaVu Serif|—|fallback с гарантированной кириллицей|
|
||||||
|
|Noto Naskh Arabic|—|арабские дополнения U+07B1–U+08FF|
|
||||||
|
|Noto Sans Armenian|—|армянские знаки Unicode 16|
|
||||||
|
|
||||||
|
## Алиасы (`BundledFontAliases`)
|
||||||
|
|
||||||
|
Имена шрифтов из документа подменяются аналогами при конвертации:
|
||||||
|
|
||||||
|
|Имя в docx|Физический шрифт|
|
||||||
|
|---|---|
|
||||||
|
|Calibri|Carlito|
|
||||||
|
|Cambria|Caladea|
|
||||||
|
|Arial|Arimo|
|
||||||
|
|Times New Roman|Tinos|
|
||||||
|
|Courier New|Cousine|
|
||||||
|
|
||||||
|
## Fallback-цепочка
|
||||||
|
|
||||||
|
1. **Ран** идёт своим шрифтом (по `w:rFonts` + алиасам).
|
||||||
|
2. Знака нет в шрифте рана (тире «—», кавычки, U+2000–U+2EFF) — ран падает в
|
||||||
|
**DejaVu Sans** (FOP-фолбэк-семейства задекларированы всецело, шаг 4 конвейера).
|
||||||
|
3. Serif-раны ищут покрытие сначала в serif-семействах (DejaVu Serif, Tinos, Caladea).
|
||||||
|
4. Знака нет и там — `GlyphCoverageNormalizer` (правило 7) режет ран и каждой части
|
||||||
|
назначает покрывающее семейство: serif → DejaVu Serif, sans → DejaVu Sans,
|
||||||
|
экзотика → Noto.
|
||||||
|
5. Знака нет ни в одном шрифте бандла — остаётся `.notdef` (пустой бокс).
|
||||||
|
|
||||||
|
Все шрифты встраиваются в PDF как **подмножества** (кириллица и латиница
|
||||||
|
воспроизводятся на любом просмотрщике).
|
||||||
|
|
||||||
|
## Лицензии
|
||||||
|
|
||||||
|
|Шрифты|Лицензия|
|
||||||
|
|---|---|
|
||||||
|
|Arimo, Cousine, Tinos, Carlito, Caladea|SIL OFL 1.1 (`fonts/FONT-LICENSE.txt`)|
|
||||||
|
|DejaVu Sans / DejaVu Serif|SIL OFL 1.1 / Bitstream Vera (`fonts/DejaVu-LICENSE.txt`)|
|
||||||
|
|Noto Naskh Arabic, Noto Sans Armenian|SIL OFL 1.1 (`fonts/Noto-LICENSE.txt`)|
|
||||||
|
|
||||||
|
GPL-шрифты в бандл не добавляем намеренно (из-за этого два символа эталона —
|
||||||
|
U+2188/U+218A — остаются `.notdef`; см. [Ограничения](limitations.md)).
|
||||||
|
|
||||||
|
Новый шрифт = файл в `resources/fonts/` + запись в `BundledFonts.ENTRIES`
|
||||||
|
(синхронность проверяет `BundledFontsTest`).
|
||||||
@@ -0,0 +1,40 @@
|
|||||||
|
# Ограничения рендера
|
||||||
|
|
||||||
|
Конвертер **не является pixel-perfect рендером Word**: часть расхождений —
|
||||||
|
неустранимые невозможности связки docx4j + Apache FOP, а не упущения проекта.
|
||||||
|
|
||||||
|
## Что конвертируется приближённо
|
||||||
|
|
||||||
|
- Раскладка, поля и некоторые эффекты могут отличаться от Word (ограничения
|
||||||
|
FOP/docx4j по построению).
|
||||||
|
- Символы U+2000–U+2EFF (тире, кавычки): из шрифта рана, если в нём есть глиф,
|
||||||
|
иначе — из fallback-семейства DejaVu.
|
||||||
|
- Знаков, которых нет ни в одном шрифте бандла, это не касается: вместо них
|
||||||
|
остаётся `.notdef` (пустой бокс). В эталонном наборе таких два: U+2188 (ↈ) и
|
||||||
|
U+218A (↊) — глифы есть только в GNU FreeSerif под GPL, а бандл держится целиком
|
||||||
|
на SIL OFL.
|
||||||
|
- Поддержка таблиц/изображений — базовая (уровень docx4j/FOP).
|
||||||
|
- На `.doc` error-флаги диаграмм/SmartArt/OLE не срабатывают: BLIP-плейсхолдеры
|
||||||
|
бинарного формата — уже растры (вставляются картинками), EMF/WMF/PICT пропускаются
|
||||||
|
с warn — [Мост .doc](doc-bridge.md).
|
||||||
|
|
||||||
|
## Стоп-лист «не чинить»
|
||||||
|
|
||||||
|
До любой попытки «починить» расхождение с Word — сверьтесь со списком: это
|
||||||
|
невозможности движка, попытка фикса хуже самого расхождения.
|
||||||
|
|
||||||
|
|Конструкция|Что происходит|Почему не чинится|
|
||||||
|
|---|---|---|
|
||||||
|
|`w:jc="distribute"`|рендерится как left|межсимвольного распределения в FOP нет; `text-align-last` в форке отсутствует|
|
||||||
|
|`w:suff="tab"`|игнорируется (label через hanging-tab)|нужна per-item ширина; совпадает с поведением docx4j|
|
||||||
|
|`w:lvlJc`|игнорируется|—|
|
||||||
|
|кернинг|не применяется|—|
|
||||||
|
|`framePr` (обтекание)|не поддерживается|—|
|
||||||
|
|кэш полей `REF`/`SEQ`/`TOC`|печатается кэш из docx|живой пересчёт вне контура (`PAGE`/`NUMPAGES`/`PAGEREF`/`DATE` — пересчитываются)|
|
||||||
|
|руби (надстрочница)|надстрочная часть вырезается, база печатается|ruby-разметки в FOP нет; потеря текста хуже потери аннотации|
|
||||||
|
|`ptab`|не поддерживается|—|
|
||||||
|
|U+2188/U+218A|`.notdef`|GPL-шрифты не добавляем намеренно|
|
||||||
|
|`lineRule="auto"`|—|не «чинить»: метрический шаг пинен тестом|
|
||||||
|
|
||||||
|
Полный перечень с доказательствами по ECMA-376 —
|
||||||
|
[render-limitations.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/render-limitations.md).
|
||||||
@@ -0,0 +1,68 @@
|
|||||||
|
# Архитектура
|
||||||
|
|
||||||
|
## Конвейер конвертации (шаги 0–7)
|
||||||
|
|
||||||
|
Единственный вход ядра — `WordPdfConverter.convert(byte[], String, ConvertOptions)`;
|
||||||
|
порядок шагов фиксирован и каждый обоснован:
|
||||||
|
|
||||||
|
|#|Шаг|Зачем|
|
||||||
|
|---|---|---|
|
||||||
|
|0|`DependencyGuard.check()`|API-проба commons-compress ≥ 1.25.0 — понятная ошибка вместо `NoSuchMethodError` внутри docx4j|
|
||||||
|
|1|`new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()`|реестр шрифтов = только бандл (+ встроенные в docx); системные сканы отключены гейт-свойствами; порядок строго такой, до `load()`|
|
||||||
|
|2|нормализаторы → `WordprocessingMLPackage.load`|12 правил переписывания байтов одним zip-проходом + OLE-вычистка (см. ниже)|
|
||||||
|
|3|`setFontMapper`|привязка имён шрифтов документа к физическим TTF|
|
||||||
|
|3.5|`DrawingPreRenderer.run`|диаграммы/SmartArt/OMML-формулы → PNG 300 dpi; **обязателен до `FOSettings`**, иначе FOP молча теряет диаграммы|
|
||||||
|
|4|`FOSettings` + `ChartImageHandler` + `FopFallbackFonts.declare`|FOP встраивает только задекларированные семейства; декларуются все бандл-семейства|
|
||||||
|
|4.25/4.5|`LayoutPostRenderer.register`, `setCustomXsltTemplates`|padding-компенсация таблиц; вендорный XSLT с AUDIT-FIX-патчами|
|
||||||
|
|5–6|общая `FopFactory` (DCL) → `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`|XSL-FO → PDF|
|
||||||
|
|7|`finally`|сброс temp-шрифтов, сброс общих кешей картинок (иначе ~1,5 ГБ за 30 конвертаций), возврат реестра к бандлу|
|
||||||
|
|
||||||
|
Нормализаторы правил 1–11 (один zip-проход, порядок значим): strict→transitional,
|
||||||
|
`on/off`→`true/false`, Symbol/Wingdings→Unicode, поля `PAGE`/`NUMPAGES` →
|
||||||
|
`w:fldSimple` (пересчёт вместо кэша), невидимые символы, OMML-фолбэк, резка ранов
|
||||||
|
по покрытию глифов, отступ таблиц, `suff="space"`, скрытый текст, руби. Правило 12 —
|
||||||
|
`OleObjectNormalizer` (отдельным байтовым проходом).
|
||||||
|
|
||||||
|
Полное «что делает каждый шаг и почему именно так» —
|
||||||
|
[pipeline.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/pipeline.md).
|
||||||
|
|
||||||
|
## Слои ядра (`wordpdf-core`)
|
||||||
|
|
||||||
|
|Слой|Содержимое|
|
||||||
|
|---|---|
|
||||||
|
|публичный API (`ru.pjandro.wordpdf`)|`WordPdfConverter`, `WordPdfValidator`, `ConvertOptions`, иерархия ошибок — см. [API библиотеки](../library/api.md)|
|
||||||
|
|`internal/`|нормализаторы (контракт `byte[] normalize(byte[])`), `FopFallbackFonts`, `LayoutPostRenderer`, `DependencyGuard`|
|
||||||
|
|`internal/doc/`|мост бинарного `.doc` → in-memory `.docx` — [Мост .doc](doc-bridge.md)|
|
||||||
|
|`internal/chart/`|Java2D-рендер диаграмм/SmartArt/формул → PNG — [Диаграммы](charts.md)|
|
||||||
|
|`fonts/`|бандл из 30 TTF, маппинг алиасов, `GlyphFont` (метрики/глифы через fontbox, без AWT) — [Шрифты](fonts.md)|
|
||||||
|
|
||||||
|
Всё, кроме публичного API, — package-private; контракт наружу не расширяется.
|
||||||
|
|
||||||
|
## Параллельность
|
||||||
|
|
||||||
|
`PhysicalFonts` docx4j — глобальный мутируемый реестр → **все конвертации
|
||||||
|
сериализованы монитором класса `WordPdfConverter.class`**. Приложение (`wordpdf-app`)
|
||||||
|
дополнительно держит однопоточный `ThreadPoolExecutor` с очередью 16 мест (переполнение
|
||||||
|
→ 503, timeout 2m → 504), головой очереди стоит `warmup()`.
|
||||||
|
|
||||||
|
## REST-конвейер приложения (`wordpdf-app`)
|
||||||
|
|
||||||
|
`POST /api/v1/convert` → `ApiKeyFilter` (401) → `ConvertController` (проверка
|
||||||
|
расширения/размера, параметры) → `ConversionService` (очередь, Future с таймаутом,
|
||||||
|
перевод исключений ядра в HTTP) → ядро. Обработчик исключений пишет JSON
|
||||||
|
`{"error": …}` — карта кодов в [REST API](../api/errors.md). В модуле 11 классов,
|
||||||
|
все package-private кроме `WordPdfApplication`.
|
||||||
|
|
||||||
|
## Веб-интерфейс (`wordpdf-web`)
|
||||||
|
|
||||||
|
React SPA; вся сеть — ровно две функции в `api.ts` (`convertDocx`, `probeApiKey`),
|
||||||
|
состояние — `useState` в `App.tsx`, store-библиотек нет. Запросы идут на тот же
|
||||||
|
путь `/api/...` относительно базы раздачи — CORS не нужен.
|
||||||
|
|
||||||
|
## Внешние поверхности
|
||||||
|
|
||||||
|
- `gateway/nginx.conf` — единственная наружная точка стендов (:9010/:9011):
|
||||||
|
`/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → app:8080, остальное → web;
|
||||||
|
[Эксплуатация: стенды](../operations/stack.md).
|
||||||
|
- Прод (`https://pjandro.ru/pdf-converter/`) рендерится job'ом `deploy` из
|
||||||
|
Gitea Variables — [Деплой](../operations/deployment.md).
|
||||||
@@ -0,0 +1,64 @@
|
|||||||
|
# Как контрибьютить
|
||||||
|
|
||||||
|
## Ветка и PR
|
||||||
|
|
||||||
|
Репозиторий: `git.pjandro.ru:pjandro/java-word-pdf`. Защищённые ветки — `main`,
|
||||||
|
`master`, `dev`: прямо в них не коммитим.
|
||||||
|
|
||||||
|
1. Ветка от свежей `main` (`git switch -c <name>`).
|
||||||
|
2. Коммиты логическими блоками.
|
||||||
|
3. Перед push — полный гейт: `./mise.sh run verify`.
|
||||||
|
4. `git push -u origin <name>` → pull request в дефолтную ветку.
|
||||||
|
5. CI на PR: `java` (единственный `mvn clean verify` в контейнере без fontconfig +
|
||||||
|
сводка покрытия комментарием) и `web` (`npm ci`, build, lint) — оба required.
|
||||||
|
`macos-sim` — не required.
|
||||||
|
|
||||||
|
## Конвенции кода
|
||||||
|
|
||||||
|
- Классы `final`, приватный конструктор, только `static` (stateless, DI в ядре нет);
|
||||||
|
в `internal/**` — package-private, `public` только вызываемым извне пакета.
|
||||||
|
- Ошибки публичного API — только `ConversionException` (и подтипы); в chart —
|
||||||
|
деградация вместо падения.
|
||||||
|
- Javadoc на русском: «зачем» + ссылка на секцию спецификации (§17.3.2.24,
|
||||||
|
[MS-DOC] §2.6.1…) + что сломается без шага + регрессия в формате
|
||||||
|
`Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx` (по этой строке
|
||||||
|
грепом восстанавливаются пары тестов).
|
||||||
|
- Модели — `record`; константы UPPER_SNAKE с javadoc-обоснованием числа.
|
||||||
|
- PMD-подавления (`@SuppressWarnings("PMD…")`, `// NOPMD`) запрещены.
|
||||||
|
- Логирование: `java.util.logging` — корневой пакет и `internal/`; SLF4J —
|
||||||
|
`internal/chart` и `wordpdf-app`; остальное молчит.
|
||||||
|
|
||||||
|
## Регрессивная конвенция (фикс бага)
|
||||||
|
|
||||||
|
Каждый фикс расхождения с Word оформляется полным набором:
|
||||||
|
|
||||||
|
```
|
||||||
|
нормализатор/рендерер → юнит на правило → тест во всём конвейере
|
||||||
|
→ javadoc-ссылка «Регрессия — Тест#имя, фикстура …»
|
||||||
|
```
|
||||||
|
|
||||||
|
Фикстуры для новых тестов не генерируются на лету и не перезаписываются:
|
||||||
|
`charts-smartart.docx` и `ole-embedded.docx` сделаны руками и **не перезаписываются
|
||||||
|
никогда**; все 12 `.doc` — эталоны заказчика.
|
||||||
|
|
||||||
|
## Критические инварианты (нарушение = битый вывод)
|
||||||
|
|
||||||
|
Прежде чем править ядро — прогнать глазами список (полный — `AGENTS.md`,
|
||||||
|
[repo-map](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/repo-map.md)):
|
||||||
|
|
||||||
|
- static-блок `WordPdfConverter` (sysprops `gsubFeatures=false`, отключение
|
||||||
|
сканов PhysicalFonts) — не удалять;
|
||||||
|
- `DrawingPreRenderer` обязан идти **до** `FOSettings`, иначе FOP молча теряет диаграммы;
|
||||||
|
- порядок нормализаторов правил 1–11 фиксирован;
|
||||||
|
- вендорный `docx2fo.xslt` — единственный XSL-стилист, дрейф-гейт
|
||||||
|
`vendoredXsltTracksJarCopy`;
|
||||||
|
- `slf4j-simple` обязателен в ядре;
|
||||||
|
- префикс `/word/media/chart-*` — контракт с `ChartImageHandler`;
|
||||||
|
- финальный `finally`-блок: temp-шрифты, кеши картинок, возврат реестра к бандлу.
|
||||||
|
|
||||||
|
## Документация сайта
|
||||||
|
|
||||||
|
Разделы сайта живут в `docs/` (кроме `docs/agent/`, `docs/standards/` — они не входят
|
||||||
|
в сайт). Правка/новая страница: обязательна запись в `nav` `mkdocs.yml` (иначе
|
||||||
|
strict-сборка падает). Проверка: `./mise.sh run docs-build`. Публикация —
|
||||||
|
[`docs-deploy`](../operations/docs-site.md).
|
||||||
@@ -0,0 +1,83 @@
|
|||||||
|
# Окружение разработчика
|
||||||
|
|
||||||
|
Требуется **Java 17**, **Maven 3.9.16**, **Node 24** (engines Vite: `^20.19.0 ||
|
||||||
|
>=22.12.0`), **Python 3.15** (прод-автотесты, сайт документации). Всё это ставит
|
||||||
|
project-local mise: сам бинарь — в `./.mise/bin` (gitignored), кеш инструментов —
|
||||||
|
в user-директории mise, **в систему ничего не устанавливается**. Версии пиныны
|
||||||
|
в `mise.toml`.
|
||||||
|
|
||||||
|
## Бутстрап (первая настройка)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sh bootstrap.sh # Linux / macOS: качает mise, ставит инструменты, npm ci SPA
|
||||||
|
```
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
|
||||||
|
```
|
||||||
|
|
||||||
|
Дальше команды — через обёртку `./mise.sh` (Windows: `.\mise.ps1`):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./mise.sh run verify # полный гейт перед push
|
||||||
|
./mise.sh exec -- mvn -v # любая команда с инструментами в PATH
|
||||||
|
./mise.sh tasks # список задач
|
||||||
|
```
|
||||||
|
|
||||||
|
Альтернатива — активировать mise в шелле и работать напрямую (`mvn`, `npm`, `python`):
|
||||||
|
`eval "$(./.mise/bin/mise activate bash)"`.
|
||||||
|
|
||||||
|
## Задачи mise
|
||||||
|
|
||||||
|
|Задача|Содержание|
|
||||||
|
|---|---|
|
||||||
|
|`verify`|`mvn clean verify` — тесты + PMD + JaCoCo (гейт перед push)|
|
||||||
|
|`verify-nofontconfig`|тот же verify в контейнере без fontconfig (как CI; требует podman/docker)|
|
||||||
|
|`mem-bench`|замер памяти конвейера (TSV пиков + JFR)|
|
||||||
|
|`app-package`|исполняемый jar бэкенда|
|
||||||
|
|`app-run`|бэкенд на :8080, ключ выключен (после `app-package`)|
|
||||||
|
|`web-install`|`npm ci` в `wordpdf-web`|
|
||||||
|
|`web-build`|гейт SPA: `tsc -b && vite build`|
|
||||||
|
|`web-lint`|oxlint|
|
||||||
|
|`web-dev`|SPA на :5173, vite-proxy на :8080|
|
||||||
|
|`prod-tests`|прод-автотесты; обязателен `WORDPDF_BASE_URL`, факультативно `WORDPDF_API_KEY`|
|
||||||
|
|`docs-install`|venv `docs/.venv` + `mkdocs-material`|
|
||||||
|
|`docs-serve`|локальный предпросмотр сайта на :8000 (live-reload)|
|
||||||
|
|`docs-build`|strict-сборка сайта в `site/` (битые ссылки/навигация = ошибка)|
|
||||||
|
|`docs-javadoc`|javadoc публичного API core в `wordpdf-core/target/site/apidocs`|
|
||||||
|
|`docs-deploy`|публикация сайта на rpi (:9012): javadoc + strict-build + rsync|
|
||||||
|
|
||||||
|
## Прямые команды (без задач)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mvn clean verify # все модули + тесты
|
||||||
|
mvn test -Djacoco.skip=true # тесты без агента покрытия
|
||||||
|
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
|
||||||
|
mvn -pl wordpdf-app -am test # -am обязателен: app берёт фикстуры из test-jar core
|
||||||
|
mvn -pl wordpdf-app -am package # исполняемый jar → wordpdf-app/target/
|
||||||
|
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен
|
||||||
|
|
||||||
|
npm ci && npm run build # в wordpdf-web/ (или задачи web-*)
|
||||||
|
npm run dev # SPA :5173, проксирует /api на :8080
|
||||||
|
```
|
||||||
|
|
||||||
|
## Стенды на контейнерах (podman)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# dev (:9011), без ключа, springdoc включён
|
||||||
|
podman-compose -f compose.dev.yml up -d --build --force-recreate
|
||||||
|
|
||||||
|
# prod-like (:9010), fail-closed: нужен .env с WORDPDF_API_KEY (шаблон .env.example)
|
||||||
|
cp .env.example .env # ключ: openssl rand -hex 32
|
||||||
|
podman-compose up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
`--force-recreate` для dev обязателен: без него podman-compose пересоберёт образ,
|
||||||
|
но контейнеры оставит на старом jar. Наружу публикуется только nginx-gateway
|
||||||
|
(9010/9011), 8080 наружу не выставляется. Подробности —
|
||||||
|
[Стенды](../operations/stack.md).
|
||||||
|
|
||||||
|
!!! info "«Запусти тестовый сервер»"
|
||||||
|
Так в проекте называют dev-стенд (`compose.dev.yml`, `http://<LAN-IP>:9011`),
|
||||||
|
а не `java -jar`. Готовность — контейнеры healthy (`podman-compose -f
|
||||||
|
compose.dev.yml ps`) + корень SPA отвечает 200.
|
||||||
@@ -0,0 +1,71 @@
|
|||||||
|
# Тесты
|
||||||
|
|
||||||
|
## Гейты
|
||||||
|
|
||||||
|
Полный гейт перед push — `./mise.sh run verify` (= `mvn clean verify`); на `verify`
|
||||||
|
висят и валят сборку:
|
||||||
|
|
||||||
|
|Гейт|Порог|
|
||||||
|
|---|---|
|
||||||
|
|surefire (тесты)|все зелёные, `-Djava.awt.headless=true`|
|
||||||
|
|PMD (`pmd-ruleset.xml`)|любой приоритет нарушения валит; `includeTests=true`; **подавления запрещены** — чинить кодом|
|
||||||
|
|JaCoCo LINE|≥ 0.90 (оба модуля)|
|
||||||
|
|JaCoCo BRANCH|≥ 0.85 (только `wordpdf-core`)|
|
||||||
|
|
||||||
|
Провал — HTML/XML-отчёт уже в `target/site/jacoco/`. CI-эквивалент без fontconfig —
|
||||||
|
`./mise.sh run verify-nofontconfig`. `mvn test` PMD/JaCoCo-гейты не запускает.
|
||||||
|
|
||||||
|
## Стек и конвенции
|
||||||
|
|
||||||
|
- **JUnit 6** (`org.junit.jupiter`), **только `Assertions`** — Mockito/AssertJ
|
||||||
|
запрещены, их нет в pom (в app-тестах допустим inline-Hamcrest
|
||||||
|
`org.hamcrest.Matchers.containsString` в `andExpect`).
|
||||||
|
- Только `@Test` (исключения: два `@BeforeAll` прогрева шрифтов, `@AfterEach
|
||||||
|
drainWorker` в `ConversionTimeoutTest`); ни `@Nested`, ни `@ParameterizedTest`,
|
||||||
|
ни `@Disabled`, ни `assertAll`.
|
||||||
|
- Тестовые классы package-private, зеркалят main-пакеты.
|
||||||
|
- Именование: регрессионные — `объект_условие` (`pageNumbers_recomputedNotCached`),
|
||||||
|
юниты — camelCase (`pageFieldBecomesFldSimple`).
|
||||||
|
- Сообщения ассертов — по-русски, с наблюдаемым значением; литерал слева.
|
||||||
|
- Тестовых утилит нет — хелперы намеренно дублируются в классах.
|
||||||
|
|
||||||
|
## Фикстуры
|
||||||
|
|
||||||
|
Только закоммиченные `wordpdf-core/src/test/resources/samples/`: **13 `.docx` +
|
||||||
|
12 `.doc`** (`.doc` — эталоны заказчика). В тестах фикстуры **не генерировать**;
|
||||||
|
XSD-невалидную `.docx`-фикстуру правят, а не код
|
||||||
|
(`python3 docs/standards/docx/validate-fixtures.py …`). Синтетика в памяти разрешена:
|
||||||
|
docx — `ZipOutputStream` из литеральных XML, `.doc` — крафт `POIFSFileSystem`.
|
||||||
|
|
||||||
|
Ловушка загрузки: **core** грузит classloader-ресурсом без ведущего слэша
|
||||||
|
(`getResourceAsStream("samples/…")`), **app** — class-relative со слэшем
|
||||||
|
(`/samples/…`, ресурсы из test-jar core; отсюда обязательный `-am`).
|
||||||
|
|
||||||
|
## Как проверяется PDF
|
||||||
|
|
||||||
|
**Текстом, не растеризацией**: PDFBox 3 `PDFTextStripper` (нормализация пробелов);
|
||||||
|
негативные маркеры — `#` (.notdef) и `Helvetica` (фолбэк-шрифт FOP); имя шрифта
|
||||||
|
символа — приём `fontNameOf`; встроенные подмножества — обход ресурсов страниц
|
||||||
|
(`EAAAAA+Carlito-Bold`). Пиксели (BufferedImage, отношения к эталонам Word 300 dpi
|
||||||
|
с допусками) — только юниты chart-пейнтеров.
|
||||||
|
|
||||||
|
## App-тесты
|
||||||
|
|
||||||
|
4 набора свойств = 4 Spring-контекста: `ConvertControllerTest` (пин пустого
|
||||||
|
`wordpdf.api-key=`), `ApiKeyFilterTest`, `ConvertLimitsTest`, `ConversionTimeoutTest`;
|
||||||
|
`ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring. Проверяют HTTP-код,
|
||||||
|
заголовки, текст ошибки. Ловушка: mise инжектирует корневой `.env` в окружение задач
|
||||||
|
— ambient `WORDPDF_API_KEY` дал бы 401 во всех MockMvc-тестах, поэтому ключ пинится
|
||||||
|
свойствами контекста.
|
||||||
|
|
||||||
|
## Прод-автотесты
|
||||||
|
|
||||||
|
`prod-autotests/` (pytest + requests): 31 проверка против **живого** стенда —
|
||||||
|
4 открытые + 27 `needs_key` (SKIP без ключа). Конфигурация только env:
|
||||||
|
`WORDPDF_BASE_URL` (обязателен), `WORDPDF_API_KEY`, `WORDPDF_MAX_MB`/`MAX_PAGES`,
|
||||||
|
`WORDPDF_SAMPLES_DIR`. Таймауты `(10, 180)` — больше серверных 2m. Запуск:
|
||||||
|
`WORDPDF_BASE_URL=… ./mise.sh run prod-tests` (в CI гоняются job'ом `autotests`
|
||||||
|
после deploy).
|
||||||
|
|
||||||
|
Глубина (счётчики, пары «нормализатор ↔ тест», пиксельные допуски) —
|
||||||
|
[testing.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/testing.md).
|
||||||
@@ -0,0 +1,64 @@
|
|||||||
|
# Word → PDF конвертер
|
||||||
|
|
||||||
|
Конвертация **.docx/.doc → PDF** на чистой Java: `docx4j` 17.3.2 + форк `Apache FOP`
|
||||||
|
(`org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6), **без LibreOffice и без Aspose**.
|
||||||
|
Бинарный `.doc` (Word 97–2003) читается собственным мостом [MS-DOC]/[MS-CFB]
|
||||||
|
и переносится в .docx в памяти — дальше идёт тем же конвейером. Шрифты упакованы
|
||||||
|
в jar: конвертация не зависит от шрифтов, установленных в системе, и работает
|
||||||
|
«из коробки» на голом сервере.
|
||||||
|
|
||||||
|
## Три поверхности
|
||||||
|
|
||||||
|
|Поверхность|Что это|Куда смотреть|
|
||||||
|
|---|---|---|
|
||||||
|
|Веб-интерфейс|React SPA: перетащил файл → предпросмотр PDF → скачивание. Публикация: `https://pjandro.ru/pdf-converter/`|[Пользователю](user.md)|
|
||||||
|
|REST API|`POST /api/v1/convert` (Spring Boot 4.1.1), ключ доступа, Swagger UI|[REST API](api/index.md)|
|
||||||
|
|Java-библиотека|`wordpdf-core`: `WordPdfConverter.convert(...)` — байты docx на входе, байты PDF на выходе|[Библиотека](library/getting-started.md)|
|
||||||
|
|
||||||
|
## Как это работает (схема)
|
||||||
|
|
||||||
|
```
|
||||||
|
.docx/.doc ──> валидация входа ──> (.doc: мост → .docx в памяти)
|
||||||
|
──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
|
||||||
|
──> диаграммы → PNG ──> XSL-FO (вендорный XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Вход проверяется до рендера (`WordPdfValidator`): размер → сигнатура байтов
|
||||||
|
(zip `PK\x03\x04` или CFB `D0 CF 11 E0`) → контейнер и страницы lightweight-сканом,
|
||||||
|
без зависимости от docx4j.
|
||||||
|
2. XML-части переписывает `DocxRewritePipeline` одним zip-проходом (12 правил
|
||||||
|
нормализации), затем OLE-объекты вычищает `OleObjectNormalizer`.
|
||||||
|
3. Документ загружается в `WordprocessingMLPackage`, привязывается `BundledFontMapper`.
|
||||||
|
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi собственным
|
||||||
|
Java2D-движком (`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
|
||||||
|
5. Экспорт в XSL-FO идёт вендорным стилем `docx2fo.xslt`; `Apache FOP` рендерит
|
||||||
|
PDF, встраивая подмножества шрифтов.
|
||||||
|
|
||||||
|
Полностью, с обоснованиями — [Архитектура](architecture/overview.md).
|
||||||
|
|
||||||
|
## Возможности
|
||||||
|
|
||||||
|
- RU/EN: кириллица и латиница встраиваются в PDF как embedded-подмножества.
|
||||||
|
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
|
||||||
|
([Шрифты](architecture/fonts.md)).
|
||||||
|
- Диаграммы (17 типов, включая комбинированные) и SmartArt — PNG без Word/LibreOffice
|
||||||
|
([Диаграммы](architecture/charts.md)).
|
||||||
|
- `.doc`: текст, стили, таблицы, списки, колонтитуки, картинки — собственный мост
|
||||||
|
([Мост .doc](architecture/doc-bridge.md)).
|
||||||
|
|
||||||
|
## Ключевые версии
|
||||||
|
|
||||||
|
|Компонент|Версия|
|
||||||
|
|---|---|
|
||||||
|
|Java|17 (temurin)|
|
||||||
|
|docx4j|17.3.2|
|
||||||
|
|Apache FOP (форк `docx4j-fo-renderer*`)|2.11-docx4j.6|
|
||||||
|
|commons-compress|1.28.0 (минимум 1.25.0)|
|
||||||
|
|Spring Boot|4.1.1|
|
||||||
|
|springdoc|3.1.1|
|
||||||
|
|SPA|React 19.2 + TypeScript ~6.0 + Vite 8.3|
|
||||||
|
|
||||||
|
## Ссылки
|
||||||
|
|
||||||
|
- [Javadoc публичного API `wordpdf-core`](/apidocs/index.html)
|
||||||
|
- [Внутренние справочники репозитория](internal-guides.md) — для глубокой правки кода.
|
||||||
@@ -0,0 +1,39 @@
|
|||||||
|
# Внутренние справочники репозитория
|
||||||
|
|
||||||
|
Сайт покрывает «как пользоваться и как устроено». Для **глубокой правки кода**
|
||||||
|
в репозитории живут авторитетные справочники (`docs/agent/`, читаются наравне
|
||||||
|
с `AGENTS.md`) и закоммиченные спецификации форматов (`docs/standards/`).
|
||||||
|
В этот сайт они не включены (огромные тексты спецификаций) — ссылки ведут на Gitea.
|
||||||
|
|
||||||
|
## Справочники `docs/agent/`
|
||||||
|
|
||||||
|
|Документ|Читать при|
|
||||||
|
|---|---|
|
||||||
|
|[pipeline.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/pipeline.md)|правке конвейера `WordPdfConverter`, нормализаторов, валидатора; шаги 0–7 с обоснованиями, правила 1–12|
|
||||||
|
|[doc-bridge.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/doc-bridge.md)|правке моста `internal/doc`; классы ↔ секции [MS-DOC]/[MS-CFB], остаток моста|
|
||||||
|
|[chart.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/chart.md)|правке `internal/chart`; пейнтеры, калибровки по Word, защитные лимиты, §ECMA-376|
|
||||||
|
|[render-limitations.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/render-limitations.md)|любой попытке «починить» расхождение с Word — сначала стоп-лист|
|
||||||
|
|[testing.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/testing.md)|добавлении/правке тестов; счётчики, пиксельные допуски, фикстуры, конвенции|
|
||||||
|
|[ci-cd.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/ci-cd.md)|правке workflow'ов, Containerfile'ов, деплоя|
|
||||||
|
|[repo-map.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/repo-map.md)|поиске «где живёт X»: полная карта каталогов/файлов, REST-карта, конвенции|
|
||||||
|
|
||||||
|
## Спецификации `docs/standards/`
|
||||||
|
|
||||||
|
Нормативные тексты форматов, закоммиченные в репозиторий
|
||||||
|
(навигатор — `docs/standards/README.md`, ссылка в коде — с номером секции):
|
||||||
|
|
||||||
|
|Каталог|Содержимое|
|
||||||
|
|---|---|
|
||||||
|
|`ooxml/`|ECMA-376 Part 1 (PDF + md), [MS-OI29500], [MS-ODRAWXML], полные наборы XSD strict/transitional|
|
||||||
|
|`binary/`|[MS-CFB], [MS-OSHARED], [MS-ODRAW], [MS-OLEPS], [MS-OFFCRYPTO], [MS-OVBA], [MS-WMF], [MS-EMF]|
|
||||||
|
|`doc/`|[MS-DOC] — бинарный формат Word 97–2003|
|
||||||
|
|`docx/`|XSD-валидация фикстур (`validate-fixtures.py`)|
|
||||||
|
|
||||||
|
## Корневые документы
|
||||||
|
|
||||||
|
- [`AGENTS.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/AGENTS.md) —
|
||||||
|
правила репозитория: конвейер, инварианты, команды, конвенции, гейты.
|
||||||
|
- [`README.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/README.md) —
|
||||||
|
короткая точка входа в проект.
|
||||||
|
- [`GITEA-vars.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/GITEA-vars.md) —
|
||||||
|
все Secrets/Variables CI и настройка branch protection.
|
||||||
@@ -0,0 +1,75 @@
|
|||||||
|
# API библиотеки
|
||||||
|
|
||||||
|
Публичный API мал и стабилен: два сервисных класса, один record, пять видов ошибок.
|
||||||
|
Javadoc каждого члена — [apidocs](/apidocs/index.html).
|
||||||
|
|
||||||
|
## `WordPdfConverter`
|
||||||
|
|
||||||
|
```java
|
||||||
|
public final class WordPdfConverter {
|
||||||
|
public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options)
|
||||||
|
throws ConversionException;
|
||||||
|
public static synchronized void warmup();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `convert` — единственный путь конвертации (двухаргументной перегрузки **нет**).
|
||||||
|
Принимает байты `.docx` или `.doc` (маршрутизация по сигнатуре), возвращает байты PDF.
|
||||||
|
`title` — заголовок PDF. `options == null` → `ValidationException`.
|
||||||
|
- `warmup()` — идемпотентный прогрев конвейера; не бросает.
|
||||||
|
|
||||||
|
## `WordPdfValidator`
|
||||||
|
|
||||||
|
Те же проверки входа **без рендера** — например, для валидации загрузки до очереди:
|
||||||
|
|
||||||
|
```java
|
||||||
|
public static void checkInput(byte[] docxBytes, long maxMb) throws ValidationException;
|
||||||
|
public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException;
|
||||||
|
```
|
||||||
|
|
||||||
|
Проверяются: непустота, размер (`maxMb`), сигнатура (zip/CFB), для docx — контейнер
|
||||||
|
(`[Content_Types].xml` с типом документа), производные пороги (распаковка, XML,
|
||||||
|
растры, записи zip), число страниц (lightweight-скан, без docx4j; для `.doc` —
|
||||||
|
по сырым байтам мостом).
|
||||||
|
|
||||||
|
## `ConvertOptions`
|
||||||
|
|
||||||
|
```java
|
||||||
|
public record ConvertOptions(boolean errorOnCharts, boolean errorOnSmartArt,
|
||||||
|
boolean errorOnOle, long maxMb, int maxPages) {}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Порядок полей фиксирован.** `maxMb`/`maxPages` должны быть больше 0. Дефолтов
|
||||||
|
в ядре нет — значения задаёт вызывающий. Диаграммы/SmartArt конвертируются всегда;
|
||||||
|
флаги только отменяют конвертацию находкой.
|
||||||
|
|
||||||
|
## Ошибки
|
||||||
|
|
||||||
|
```
|
||||||
|
ConversionException (RuntimeException)
|
||||||
|
├── ValidationException — вход некорректен (не docx/doc, размер, страницы, битый zip…)
|
||||||
|
├── ChartsFoundException — errorOnCharts и найдены диаграммы
|
||||||
|
├── SmartArtFoundException — errorOnSmartArt и найден SmartArt
|
||||||
|
└── OleFoundException — errorOnOle и найдены OLE-объекты
|
||||||
|
```
|
||||||
|
|
||||||
|
Ловите `ConversionException` — он покрывает всё; `ValidationException` — отдельно,
|
||||||
|
когда хотите различать «пользователь прислал мусор» и «конвертер не смог».
|
||||||
|
|
||||||
|
## Инвариант параллельности
|
||||||
|
|
||||||
|
`convert` **потокобезопасен, но сериализован**: все конвертации идут под монитором
|
||||||
|
класса `WordPdfConverter.class` — ядро мутирует глобальный реестр шрифтов docx4j
|
||||||
|
(`PhysicalFonts`). Параллельные вызовы корректны, но исполняются последовательно;
|
||||||
|
собственный пул/очередь с отказом при переполнении — забота вызывающего
|
||||||
|
(так делает `wordpdf-app`: один воркер, очередь 16).
|
||||||
|
|
||||||
|
## Шрифты и окружение
|
||||||
|
|
||||||
|
- Шрифты выгружаются из jar во временный каталог; реестр после каждой конвертации
|
||||||
|
возвращается к бандлу — встроенные в чужие docx шрифты не «травят» последующие
|
||||||
|
конвертации.
|
||||||
|
- `java.awt.Font` не используется (глифы — fontbox напрямую): **fontconfig хосту не нужен**,
|
||||||
|
контейнер без `/etc/fonts` работает.
|
||||||
|
- Нужен SLF4J-провайдер (см. [первые шаги](getting-started.md)) — иначе текст
|
||||||
|
предупреждений попадает в PDF.
|
||||||
@@ -0,0 +1,66 @@
|
|||||||
|
# Зависимости потребителя
|
||||||
|
|
||||||
|
## commons-compress: единственная ловушка интеграции
|
||||||
|
|
||||||
|
Ядру (транзитивно, через docx4j) нужен `org.apache.commons:commons-compress`
|
||||||
|
**≥ 1.25.0**, рекомендован **1.28.0** — версию закрепляет POM `wordpdf-core`.
|
||||||
|
Симптом старой версии в classpath потребителя:
|
||||||
|
|
||||||
|
```
|
||||||
|
NoSuchMethodError: org.apache.commons.compress.archivers.zip.ZipArchiveEntry
|
||||||
|
org.apache.commons.compress.archivers.zip.ZipArchiveInputStream.getNextEntry()
|
||||||
|
```
|
||||||
|
|
||||||
|
До входа в docx4j теперь срабатывает guard (`DependencyGuard`): вместо мутного
|
||||||
|
`NoSuchMethodError` внутри docx4j — `ConversionException` с текстом, объясняющим,
|
||||||
|
какую версию закрепить.
|
||||||
|
|
||||||
|
### Maven: закреплять в `dependencyManagement`
|
||||||
|
|
||||||
|
BOM (например, Spring Boot 3.x) пинит свою версию commons-compress, а
|
||||||
|
`dependencyManagement` потребителя перекрывает транзитивные версии («nearest wins»)
|
||||||
|
— закреплять нужно именно в нём:
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<dependencyManagement>
|
||||||
|
<dependencies>
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.apache.commons</groupId>
|
||||||
|
<artifactId>commons-compress</artifactId>
|
||||||
|
<version>1.28.0</version>
|
||||||
|
</dependency>
|
||||||
|
</dependencies>
|
||||||
|
</dependencyManagement>
|
||||||
|
```
|
||||||
|
|
||||||
|
Диагностика:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mvn dependency:tree -Dincludes=org.apache.commons:commons-compress
|
||||||
|
```
|
||||||
|
|
||||||
|
### Gradle: достаточно не понижать
|
||||||
|
|
||||||
|
По умолчанию Gradle выбирает максимальную версию и конфликт разрешает сам —
|
||||||
|
guard не сработает и не нужен. Понижает версию только явный `constraints` /
|
||||||
|
`platform` / `resolutionStrategy`: уберите понижение либо закрепите нужную версию:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
dependencies {
|
||||||
|
constraints {
|
||||||
|
implementation("org.apache.commons:commons-compress:1.28.0")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
(либо `resolutionStrategy.force("org.apache.commons:commons-compress:1.28.0")`).
|
||||||
|
Диагностика: `gradle dependencies --configuration runtimeClasspath`.
|
||||||
|
|
||||||
|
## Прочие транзитивные зависимости
|
||||||
|
|
||||||
|
|Артефакт|Зачем|Нужно ли трогать|
|
||||||
|
|---|---|---|
|
||||||
|
|`docx4j-export-fo` (+ форк FOP `docx4j-fo-renderer*`)|конвейер XSL-FO → PDF|нет|
|
||||||
|
|`slf4j-simple`|единственный SLF4J-провайдер из коробки — без провайдера docx4j пишет «TO HIDE THESE MESSAGES» в PDF|исключить, если у приложения свой провайдер|
|
||||||
|
|`jcl-over-slf4j`|мост commons-logging (pdfbox/fontbox) → slf4j|нет (`commons-logging` исключён)|
|
||||||
|
|`fontbox`|чтение TTF напрямую, без `java.awt.Font`|нет|
|
||||||
@@ -0,0 +1,72 @@
|
|||||||
|
# wordpdf-core: первые шаги
|
||||||
|
|
||||||
|
`wordpdf-core` — Java-библиотека конвертации `.docx`/`.doc` → PDF. Без LibreOffice,
|
||||||
|
без Aspose, без системных шрифтов: все TTF упакованы в jar.
|
||||||
|
|
||||||
|
## Подключение
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<dependency>
|
||||||
|
<groupId>ru.pjandro</groupId>
|
||||||
|
<artifactId>wordpdf-core</artifactId>
|
||||||
|
<version>1.0.0</version>
|
||||||
|
</dependency>
|
||||||
|
```
|
||||||
|
|
||||||
|
Требуется **Java 17**. Единственный обязательный аспект интеграции — версия
|
||||||
|
`commons-compress` (см. [Зависимости](dependencies.md)).
|
||||||
|
|
||||||
|
## Минимальный пример
|
||||||
|
|
||||||
|
```java
|
||||||
|
import ru.pjandro.wordpdf.WordPdfConverter;
|
||||||
|
import java.nio.file.Files;
|
||||||
|
import java.nio.file.Path;
|
||||||
|
|
||||||
|
byte[] docx = Files.readAllBytes(Path.of("doc.docx"));
|
||||||
|
byte[] pdf = WordPdfConverter.convert(docx, "doc",
|
||||||
|
new ru.pjandro.wordpdf.ConvertOptions(false, false, false, 5, 100));
|
||||||
|
Files.write(Path.of("out.pdf"), pdf);
|
||||||
|
```
|
||||||
|
|
||||||
|
Второй аргумент — заголовок PDF (пустой/`null` — без заголовка). Работа с файлами —
|
||||||
|
забота вызывающего: ядро пути не принимает, только байты.
|
||||||
|
|
||||||
|
Формат входа определяется **по сигнатуре байтов**, расширение имени файла ядру
|
||||||
|
неизвестно:
|
||||||
|
|
||||||
|
|Сигнатура|Маршрут|
|
||||||
|
|---|---|
|
||||||
|
|`PK\x03\x04`|zip → OOXML-путь (docx4j)|
|
||||||
|
|`D0 CF 11 E0 A1 B1 1A E1`|CFB → мост .doc → .docx в памяти → тот же конвейер|
|
||||||
|
|
||||||
|
## Опции конвертации
|
||||||
|
|
||||||
|
`ConvertOptions` — record из пяти полей (детали в [API библиотеки](api.md)):
|
||||||
|
error-флаги диаграмм/SmartArt/OLE и лимиты размера/страниц. Дефолтов в ядре нет —
|
||||||
|
все пять значений задаёт вызывающий:
|
||||||
|
|
||||||
|
```java
|
||||||
|
// отменить конвертацию, если в документе есть диаграммы; лимиты 10 МБ / 200 страниц
|
||||||
|
var opts = new ConvertOptions(true, false, false, 10, 200);
|
||||||
|
byte[] pdf = WordPdfConverter.convert(bytes, "Отчёт", opts);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Прогрев
|
||||||
|
|
||||||
|
Первая конвертация после старта JVM стоит ~1,3–1,7 с (инициализация JAXB/XSLT/FOP).
|
||||||
|
`WordPdfConverter.warmup()` прогоняет весь конвейер на минимальном встроенном docx
|
||||||
|
и идемпотентен (повторные вызовы — no-op); бросать не должен никогда — решение
|
||||||
|
о реакции на сбой прогревает код. Вызывайте на старте приложения, если не хотите,
|
||||||
|
чтобы первый пользователь платил за инициализацию:
|
||||||
|
|
||||||
|
```java
|
||||||
|
WordPdfConverter.warmup(); // ~1,5–2,5 с, один раз при старте
|
||||||
|
```
|
||||||
|
|
||||||
|
## Провайдер логов
|
||||||
|
|
||||||
|
В classpath потребителя **обязан быть SLF4J-провайдер**. Без него docx4j пишет
|
||||||
|
предупреждение «TO HIDE THESE MESSAGES…» **прямо в выходной PDF**. В jar `wordpdf-core`
|
||||||
|
для этого включён `slf4j-simple`; если ваше приложение приносит свой провайдер
|
||||||
|
(logback и т.п.) — исключите `slf4j-simple` из транзитивных зависимостей.
|
||||||
@@ -0,0 +1,52 @@
|
|||||||
|
# Конфигурация сервера (`wordpdf-app`)
|
||||||
|
|
||||||
|
## Свойства и env
|
||||||
|
|
||||||
|
|Свойство|Env|Дефолт|Смысл|
|
||||||
|
|---|---|---|---|
|
||||||
|
|`wordpdf.api-key`|`WORDPDF_API_KEY`|пусто|ключ заголовка `X-API-Key`; пусто = аутентификация выключена|
|
||||||
|
|`wordpdf.max-mb`|`WORDPDF_MAX_MB`|5 (литерал `@Value`)|дефолтный лимит размера входа, МБ (MiB); ≤ 0 на старте → `IllegalStateException`|
|
||||||
|
|`wordpdf.max-pages`|`WORDPDF_MAX_PAGES`|100 (литерал `@Value`)|дефолтный лимит страниц; ≤ 0 → падение на старте|
|
||||||
|
|`wordpdf.convert-timeout`|`WORDPDF_CONVERT_TIMEOUT`|`2m`|таймаут одной конвертации (Duration) → 504|
|
||||||
|
|`spring.servlet.multipart.max-file-size` / `max-request-size`|—|`100MB`|потолок контейнера, зеркалит nginx `client_max_body_size 100m`|
|
||||||
|
|`spring.servlet.multipart.file-size-threshold`|—|`2MB`|части больше — на диск Tomcat (heap держит только копию одной сериализованной конвертации)|
|
||||||
|
|`server.forward-headers-strategy`|—|`framework`|работа за префикс-срезающим прокси (`X-Forwarded-*`); `native` не понимает `X-Forwarded-Prefix`|
|
||||||
|
|`springdoc.api-docs.enabled`|`SPRINGDOC_API_DOCS_ENABLED`|`true`|OpenAPI-спек; `false` → `/v3/api-docs` отдаёт 404|
|
||||||
|
|`springdoc.swagger-ui.enabled`|`SPRINGDOC_SWAGGER_UI_ENABLED`|`true`|Swagger UI|
|
||||||
|
|`springdoc.swagger-ui.persist-authorization`|—|`true`|не требовать ключ заново после перезагрузки страницы UI|
|
||||||
|
|
||||||
|
Ограничитель очереди (16 мест) — константа `ConversionService.QUEUE_CAPACITY`,
|
||||||
|
не конфигурируется.
|
||||||
|
|
||||||
|
!!! warning "Не объявляйте `wordpdf.max-mb`/`max-pages` в `application.properties`"
|
||||||
|
Дефолты 5/100 живут литералами `@Value` в `ConvertController`. Пустое значение
|
||||||
|
ключа в properties **затенит** литерал и сломает старт. Либо не объявляйте
|
||||||
|
(тогда дефолт), либо конкретное число.
|
||||||
|
|
||||||
|
## Примеры запуска
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# ключ + лимиты через env
|
||||||
|
WORDPDF_API_KEY=$(openssl rand -hex 32) WORDPDF_MAX_MB=10 \
|
||||||
|
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
|
||||||
|
|
||||||
|
# или аргументами
|
||||||
|
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar \
|
||||||
|
--wordpdf.api-key=secret --wordpdf.convert-timeout=3m
|
||||||
|
```
|
||||||
|
|
||||||
|
В prod-like compose-стеке `WORDPDF_API_KEY` читается из `.env` (fail-closed:
|
||||||
|
`${WORDPDF_API_KEY:?}` — без него стек не поднимается), на проде ключ приходит
|
||||||
|
только из Gitea Secret через окружение контейнера.
|
||||||
|
|
||||||
|
## Что задала не я, а инфраструктура
|
||||||
|
|
||||||
|
|Параметр|Где|Значение|
|
||||||
|
|---|---|---|
|
||||||
|
|`client_max_body_size`|`gateway/nginx.conf`|`100m`|
|
||||||
|
|proxy_read timeout|`gateway/nginx.conf`|300 с|
|
||||||
|
|heap контейнера app|`Containerfile` (ENTRYPOINT)|`-Xms2g -Xmx2g`; лимит `mem_limit: 3g` — в compose|
|
||||||
|
|`VITE_BASE`|build-arg образа web|`/pdf-converter/` (путь публикации на проде)|
|
||||||
|
|
||||||
|
Значение `maxMb`/`maxPages` конкретного стенда прод-автотесты читают из
|
||||||
|
`WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES` (на проде — 5/100).
|
||||||
@@ -0,0 +1,54 @@
|
|||||||
|
# Деплой (прод)
|
||||||
|
|
||||||
|
Наружный вход прода — **`https://pjandro.ru/pdf-converter/`** (пользовательский
|
||||||
|
nginx режет префикс и проксирует на стек конвертера). Публикация полностью
|
||||||
|
автоматизрована: **push в `main` → Gitea Actions**.
|
||||||
|
|
||||||
|
## Пайплайн `main.yml`
|
||||||
|
|
||||||
|
```
|
||||||
|
java + web (тесты/гейты) ──> images-app + images-web (build+push в реестр)
|
||||||
|
──> deploy (рендер прод-стека, pull, up, health-гейты, автооткат)
|
||||||
|
──> autotests (pytest против живого прода; провал → rollback)
|
||||||
|
```
|
||||||
|
|
||||||
|
1. **`java` / `web`** — те же гейты, что на PR (`mvn clean verify` в контейнере
|
||||||
|
без fontconfig; `npm ci`/build/lint).
|
||||||
|
2. **`images-app` / `images-web`** — сборка Containerfile в Nexus-реестр, теги
|
||||||
|
`prod` + неизменяемый `sha-<7 символов>`; web печётся с
|
||||||
|
`VITE_BASE=/pdf-converter/` (путь публикации запекается в образ).
|
||||||
|
3. **`deploy`** — job **рендерит** `docker-compose.yml` и `nginx.conf` в директорию
|
||||||
|
деплоя из Gitea Variables (прод-хост не хранит ни конфигураций, ни секретов;
|
||||||
|
API-ключ — из Secret через окружение деплоя, на диск не пишется), затем
|
||||||
|
login/pull/`up -d --force-recreate app web`, гейты healthy + recreate gateway.
|
||||||
|
Единственное состояние на проде — `.rollback.env` (image id предыдущего рана).
|
||||||
|
4. **`autotests`** — 31 pytest-проверка против живого стенда; провал → откат
|
||||||
|
на образ из `.rollback.env`.
|
||||||
|
|
||||||
|
## Где креды и координаты
|
||||||
|
|
||||||
|
Всё вне репозитория — **Gitea Actions Variables/Secrets** (полный список и настройка
|
||||||
|
branch protection: [`GITEA-vars.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/GITEA-vars.md)).
|
||||||
|
Прод-ключ `WORDPDF_API_KEY` — только Secret. В репо и на диске прод-хоста ключа нет.
|
||||||
|
|
||||||
|
## Ручные операции
|
||||||
|
|
||||||
|
!!! warning "Перед ручным перезапуском прода"
|
||||||
|
Прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (живёт на прод-хосте,
|
||||||
|
вне репозитория) — там актуальные координаты и процедура. Ручных скриптов
|
||||||
|
деплоя в репозитории нет и не заводить.
|
||||||
|
|
||||||
|
Прод-образ/`compose` правятся только через CI-рендер; копий прод-стека на хосте
|
||||||
|
или в репо быть не должно.
|
||||||
|
|
||||||
|
## Проверка после деплоя
|
||||||
|
|
||||||
|
CI сам докладывает по job'ам (`/actions/runs/<id>/jobs`); руками:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -sf https://pjandro.ru/pdf-converter/actuator/health # 200 {"status":"UP"}
|
||||||
|
curl -s -o /dev/null -w '%{http_code}\n' https://pjandro.ru/pdf-converter/ # 200 SPA
|
||||||
|
```
|
||||||
|
|
||||||
|
Глубина (нюансы runner'ов, `DOCKER_BUILDKIT=0`, реестр, rollback-механика) —
|
||||||
|
[ci-cd.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/ci-cd.md).
|
||||||
@@ -0,0 +1,88 @@
|
|||||||
|
# Этот сайт документации
|
||||||
|
|
||||||
|
Статический сайт (MkDocs Material) собирается из `docs/` этого репозитория и
|
||||||
|
раздаётся nginx-контейнером на rpi-хосте LAN-сервера:
|
||||||
|
|
||||||
|
- адрес: **`http://192.168.88.23:9012/`** (LAN; наружу не публикуется);
|
||||||
|
- статика: `/home/pjandro/srv/wordpdf-docs/` (rsync без рестарта контейнера);
|
||||||
|
- javadoc публичного API: [`/apidocs/index.html`](/apidocs/index.html).
|
||||||
|
|
||||||
|
## Публикация (с хоста, из репозитория)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./mise.sh run docs-install # разово: venv docs/.venv + mkdocs-material
|
||||||
|
./mise.sh run docs-deploy # javadoc → strict-build → rsync в ~/srv/wordpdf-docs
|
||||||
|
```
|
||||||
|
|
||||||
|
`docs-deploy` выполняет фиксированный порядок: `mvn javadoc:javadoc` → копия
|
||||||
|
`wordpdf-core/target/site/apidocs` → `docs/apidocs` → `mkdocs build --strict` →
|
||||||
|
`rsync -a --delete site/ ~/srv/wordpdf-docs/`. **Рестарт сервиса не нужен** —
|
||||||
|
nginx раздаёт файлы с смонтированного тома. Strict-сборка ловит битые ссылки и
|
||||||
|
страницы вне `nav`.
|
||||||
|
|
||||||
|
Dev-цикл: `./mise.sh run docs-serve` → `http://127.0.0.1:8000/` (live-reload).
|
||||||
|
|
||||||
|
## Сервис отдачи
|
||||||
|
|
||||||
|
Rootless podman (nginx-контейнер) под user-systemd (`linger=yes`). Юнит
|
||||||
|
`~/.config/systemd/user/wordpdf-docs.service` (вне git; канон текста — здесь):
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[Unit]
|
||||||
|
Description=Word PDF — сайт документации (nginx static, :9012)
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
# podman run без -d — foreground, systemd видит основной процесс
|
||||||
|
ExecStart=/usr/bin/podman run --name wordpdf-docs --replace -p 9012:80 -v /home/pjandro/srv/wordpdf-docs:/usr/share/nginx/html:ro docker.io/library/nginx:alpine
|
||||||
|
ExecStopPost=/usr/bin/podman rm -f wordpdf-docs
|
||||||
|
Restart=on-failure
|
||||||
|
RestartSec=5
|
||||||
|
TimeoutStopSec=30
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=default.target
|
||||||
|
```
|
||||||
|
|
||||||
|
Разовая установка (на хосте `192.168.88.23`):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
podman pull docker.io/library/nginx:alpine
|
||||||
|
install -d /home/pjandro/srv/wordpdf-docs
|
||||||
|
systemctl --user daemon-reload
|
||||||
|
systemctl --user enable --now wordpdf-docs.service
|
||||||
|
```
|
||||||
|
|
||||||
|
Проверка/управление:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
systemctl --user status wordpdf-docs.service
|
||||||
|
journalctl --user -u wordpdf-docs.service -n 50
|
||||||
|
curl -sf -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9012/
|
||||||
|
```
|
||||||
|
|
||||||
|
Порт 9012: соседние 9010/9011 заняты стендами конвертера (конвенция сети), 8000 —
|
||||||
|
dev-preview. Наружу (wan) не публикуем; наружный nginx `pjandro.ru` при желании
|
||||||
|
добавит владелец сервера отдельно.
|
||||||
|
|
||||||
|
## Почему не Gitea Pages
|
||||||
|
|
||||||
|
Публиковать на инстансе `git.pjandro.ru` (Gitea 1.26.4) проверенным способом «Pages»
|
||||||
|
нельзя — встроенного Pages в этой сборке нет:
|
||||||
|
|
||||||
|
- в swagger инстанса отсутствует эндпоинт `/repos/{owner}/{repo}/pages`,
|
||||||
|
в config cheat sheet — `ENABLE_PAGES`/`PAGES_DOMAIN`;
|
||||||
|
- FAQ инстанса: «Gitea doesn't provide a built-in Pages server»;
|
||||||
|
- в Gitea Actions игнорируется `jobs.*.environment`, не поддерживаются scopes
|
||||||
|
`pages`/`deployments`; тандем `upload-pages-artifact` + `deploy-pages`
|
||||||
|
неработоспособен (`upload-artifact@v4` не поддерживается, `@v3` подвешивается).
|
||||||
|
|
||||||
|
Поэтому публикация — локальная задача `docs-deploy` на том же хосте, где живёт
|
||||||
|
сервис; CI не участвует (docs-файлы не требуют гейтов).
|
||||||
|
|
||||||
|
## Что входит в сайт / не входит
|
||||||
|
|
||||||
|
В сайт попадают все страницы `docs/`, **кроме** `docs/agent/`, `docs/standards/`
|
||||||
|
и `docs/requirements.txt` (`exclude_docs` в `mkdocs.yml`) — это внутренние
|
||||||
|
справочники и спецификации, на них ведут внешние ссылки на Gitea
|
||||||
|
([Внутренние справочники](../internal-guides.md)). Каталог `docs/apidocs/`
|
||||||
|
(gitignored) заполняется задачей `docs-deploy` и копируется mkdocs как статика.
|
||||||
@@ -0,0 +1,61 @@
|
|||||||
|
# Стенды и топология
|
||||||
|
|
||||||
|
Наружу публикуется **только nginx-gateway**; контейнер `app` (:8080) наружу не
|
||||||
|
выставляется никогда. Порты стендов зафиксированы конвенцией сети.
|
||||||
|
|
||||||
|
|Стенд|Файл|Вход|Ключ доступа|springdoc|
|
||||||
|
|---|---|---|---|---|
|
||||||
|
|prod|`docker-compose.yml` (рендерится CI)|`https://pjandro.ru/pdf-converter/`|обязателен (Gitea Secret)|открыт|
|
||||||
|
|prod-like (локально)|`compose.yml`|`http://localhost:9010/`|fail-closed: `.env` с `WORDPDF_API_KEY`|выключен env-ами|
|
||||||
|
|dev|`compose.dev.yml`|`http://<LAN-IP>:9011/`|выключен|включён|
|
||||||
|
|без контейнеров|`java -jar` + `npm run dev`|`:8080` + `:5173`|выключен|включён|
|
||||||
|
|
||||||
|
## Gateway (prod-like/dev)
|
||||||
|
|
||||||
|
`gateway/nginx.conf`: `client_max_body_size 100m`, таймауты прокси 300 с,
|
||||||
|
`resolver` привязан literal-ом к шлюзу docker-сети стенда (10.113.0.1 / 10.112.0.1 —
|
||||||
|
не путать при копировании).
|
||||||
|
|
||||||
|
Маршруты:
|
||||||
|
|
||||||
|
|Location|Куда|
|
||||||
|
|---|---|
|
||||||
|
|`/api/`|`app:8080` (URI передаётся как есть)|
|
||||||
|
|`/swagger-ui`, `/v3/api-docs`, `/actuator`|`app:8080`|
|
||||||
|
|`/` (остальное)|`web` — чистая статика SPA|
|
||||||
|
|
||||||
|
`proxy_pass` через переменную + `resolver` — чтобы DNS-имя контейнера резолвилось
|
||||||
|
на каждый запрос, а не один раз при старте nginx.
|
||||||
|
|
||||||
|
## Подъём
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# dev (:9011) — «тестовый сервер» проекта
|
||||||
|
podman-compose -f compose.dev.yml up -d --build --force-recreate
|
||||||
|
|
||||||
|
# prod-like (:9010) — нужен .env с WORDPDF_API_KEY (fail-closed), шаблон .env.example
|
||||||
|
cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32
|
||||||
|
podman-compose up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! warning "--force-recreate"
|
||||||
|
Без него podman-compose пересоберёт образ, но контейнеры оставит на старом —
|
||||||
|
будет крутиться jar прошлой сборки.
|
||||||
|
|
||||||
|
## Прод
|
||||||
|
|
||||||
|
Прод-стек (`docker-compose.yml` + прод `nginx.conf`) **не хранится ни на хосте, ни в
|
||||||
|
репозитории** — job `deploy` в CI рендерит их из Gitea Variables (ключ — из Secret,
|
||||||
|
на диск не пишется), затем pull/`up -d --force-recreate`/health-гейты/автооткат.
|
||||||
|
Копии прод-конфигов на хосте/в репо — нарушение конвенции. Подробности —
|
||||||
|
[Деплой](deployment.md).
|
||||||
|
|
||||||
|
## Порты (конвенция)
|
||||||
|
|
||||||
|
|Порт|Кто|
|
||||||
|
|---|---|
|
||||||
|
|9010|prod-like gateway|
|
||||||
|
|9011|dev gateway|
|
||||||
|
|9012|сайт документации (nginx static, [Docs-сайт](docs-site.md))|
|
||||||
|
|8080|`java -jar` бэкенд (только localhost)|
|
||||||
|
|5173|vite dev-сервер SPA|
|
||||||
@@ -0,0 +1,74 @@
|
|||||||
|
# Troubleshooting
|
||||||
|
|
||||||
|
Симптом → причина → действие. Только подтверждённое поведение стендов.
|
||||||
|
|
||||||
|
## 401 «Ключ доступа не передан или неверен»
|
||||||
|
|
||||||
|
- Забыт заголовок `X-API-Key` / ключ не совпадает со `WORDPDF_API_KEY` сервера.
|
||||||
|
- Prod-like стенд не поднимается без `.env` — это fail-closed (`${WORDPDF_API_KEY:?}`),
|
||||||
|
не баг.
|
||||||
|
- Запрос идёт через точечный сегмент (`/actuator/../api/...`) — открытые префиксы
|
||||||
|
с `..`/`%2e` ключем не обходятся, так и задумано.
|
||||||
|
- Фронт: экран ключа не появляется, хотя сервер его требует? Проверьте, что
|
||||||
|
`probeApiKey()` дошёл до сервера (network-вкладка); ключ из localStorage
|
||||||
|
стирается при 401.
|
||||||
|
|
||||||
|
## 422 «Конвертация отменена: … найдены диаграммы/SmartArt/OLE-объекты»
|
||||||
|
|
||||||
|
Не ошибка — сработал включённый error-флаг запроса. Снимите `errorOnCharts`/
|
||||||
|
`errorOnSmartArt`/`errorOnOle` (по умолчанию выключены). На `.doc` флаги не
|
||||||
|
срабатывают в принципе (плейсхолдеры — растры).
|
||||||
|
|
||||||
|
## 503
|
||||||
|
|
||||||
|
Очередь конвертации (16 мест) полна: воркер один, все конвертации сериализованы.
|
||||||
|
Повторите позже. Систематически — увеличивайте время ответа вниз (документы
|
||||||
|
поменьше) или масштабируйте количество экземпляров за балансировщиком (каждый
|
||||||
|
со своей очередью).
|
||||||
|
|
||||||
|
## 504
|
||||||
|
|
||||||
|
Конвертация дольше `wordpdf.convert-timeout` (2m). Уменьшите документ (много
|
||||||
|
больших растров/диаграмм) или поднимите таймаут серверу. Учтите: отменённая
|
||||||
|
конвертация дожигается, следующий запрос ждёт её в очереди.
|
||||||
|
|
||||||
|
## 413
|
||||||
|
|
||||||
|
Тело больше контейнерного потолка multipart (100 МБ) или nginx `client_max_body_size
|
||||||
|
100m` — обе границы стоят 100 МБ. Логический лимит входа (`wordpdf.max-mb`, дефолт
|
||||||
|
5 МБ) отсекает раньше и даёт 400, так что 413 — это когда серверный лимит поднят
|
||||||
|
выше 100 МБ бессмысленно либо запрос идёт мимо ожидаемого пути. Файл реально меньше,
|
||||||
|
но 413? Проверьте, не режет ли промежуточный прокси.
|
||||||
|
|
||||||
|
## В PDF напечатано «...TO HIDE THESE MESSAGES...»
|
||||||
|
|
||||||
|
В classpath нет SLF4J-провайдера — docx4j пишет предупреждения прямо в PDF.
|
||||||
|
Для библиотеки: оставить `slf4j-simple` (в транзитивах `wordpdf-core`) или принести
|
||||||
|
свой провайдер. Для app: `slf4j-simple` исключён в пользу logback — если логическая
|
||||||
|
конфигурация app сломана и SLF4J не инициализирован, верните провайдер.
|
||||||
|
|
||||||
|
## Картинки диаграмм «мыльные» (ресемпл)
|
||||||
|
|
||||||
|
Нарушен контракт префикса media-частей `/word/media/chart-*`: по нему
|
||||||
|
`ChartImageHandler` отключает пересжатие PNG в FOP. Если части переименованы
|
||||||
|
ручной правкой — верните префикс (`DrawingPreRenderer.CHART_MEDIA_URI_PREFIX`).
|
||||||
|
|
||||||
|
## Вместо знаков — `#` или пустые боксы
|
||||||
|
|
||||||
|
- `#` — глифа нет ни в шрифте ранa, ни в fallback, и не сработала резка по покрытию
|
||||||
|
(для docx-пута это регрессия — заведите issue с документом).
|
||||||
|
- Пустой бокс `.notdef` для U+2188/U+218A — известное ограничение OFL-бандла, не чинится.
|
||||||
|
- «Битый»/подменённый шрифт в целом — проверьте алиасы (`Calibri→Carlito` и т.д.,
|
||||||
|
[Шрифты](../architecture/fonts.md)): подмена метрически совместима и ожидаема.
|
||||||
|
|
||||||
|
## Стенд крутит старый код после пересборки
|
||||||
|
|
||||||
|
podman-compose пересобрал образ, но контейнеры остались на старом — перезапустите
|
||||||
|
с `--force-recreate` ([Стенды](stack.md)).
|
||||||
|
|
||||||
|
## `.doc` не конвертируется (400)
|
||||||
|
|
||||||
|
Проверьте сигнатуру: `D0 CF 11 E0 A1 B1 1A E1`. Word 6–95 и зашифрованные (Office 95
|
||||||
|
password) документы мостом не поддерживаются → 400/`ValidationException`. Расширение
|
||||||
|
`.doc` при zip-содержимом (переименованный docx) маршрутизируется по байтам — это
|
||||||
|
не ошибка.
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
mkdocs-material==9.8.2
|
||||||
@@ -0,0 +1,56 @@
|
|||||||
|
# Пользователю
|
||||||
|
|
||||||
|
## Где открыть
|
||||||
|
|
||||||
|
Веб-конвертер: **`https://pjandro.ru/pdf-converter/`**. Работает в любом современном
|
||||||
|
браузере, установка не нужна.
|
||||||
|
|
||||||
|
## Как пользоваться
|
||||||
|
|
||||||
|
1. Перетащите файл `.docx` или `.doc` в зону загрузки (или выберите его через диалог).
|
||||||
|
2. Документ конвертируется на сервере; результат появляется во встроенном
|
||||||
|
предпросмотре PDF.
|
||||||
|
3. Нажмите «Скачать» — PDF сохранится под именем исходного файла с расширением `.pdf`
|
||||||
|
(кириллица в имени поддерживается).
|
||||||
|
|
||||||
|
В форме есть три переключателя («Диаграммы», «SmartArt», «OLE-объекты», по умолчанию
|
||||||
|
выключены): при включённом конвертация **отменится**, если документ содержит
|
||||||
|
соответствующие объекты, и интерфейс покажет понятное сообщение. По умолчанию
|
||||||
|
диаграммы и SmartArt конвертируются в картинки всегда, а OLE-объекты тихо удаляются
|
||||||
|
(картинка-плейсхолдер из документа сохраняется).
|
||||||
|
|
||||||
|
## Ключ доступа
|
||||||
|
|
||||||
|
Если сервер защищён ключом доступа, при первом открытии появится экран ввода ключа.
|
||||||
|
Ключ хранится в браузере (localStorage) и подставляется автоматически; при неверном
|
||||||
|
ключе стирается, и экран появляется снова. Если сервер ключ не требует, экран не
|
||||||
|
показывается вовсе.
|
||||||
|
|
||||||
|
## Поддерживаемые форматы
|
||||||
|
|
||||||
|
|Формат|Что это|
|
||||||
|
|---|---|
|
||||||
|
|`.docx`|OOXML (Word 2007 и новее), включая строгий (strict) OOXML|
|
||||||
|
|`.doc`|бинарный Word 97–2003; читается собственным мостом, без Word и LibreOffice|
|
||||||
|
|
||||||
|
Лимиты документа (размер, число страниц) задаёт сервер; конкретные значения зависят
|
||||||
|
от развёрнутого экземпляра.
|
||||||
|
|
||||||
|
## Что конвертируется точно, а что приближённо
|
||||||
|
|
||||||
|
Конвертер **не является pixel-perfect рендером Word**: это ограничения движка
|
||||||
|
FOP/docx4j, а не упущение проекта. Текст, стили, таблицы, списки, колонтитуки,
|
||||||
|
картинки, диаграммы и SmartArt воспроизводятся надёжно; раскладка, поля и некоторые
|
||||||
|
эффекты могут отличаться от Word.
|
||||||
|
|
||||||
|
Символы, которых нет в шрифте ранa (например, тире «—», кавычки), берутся из
|
||||||
|
fallback-семейства DejaVu с гарантированной кириллицей. Знаков, которых нет ни в одном
|
||||||
|
шрифте бандла, это не касается — для них останутся пустые боксы; в эталонном наборе
|
||||||
|
таких символа два (U+2188, U+218A — римские/осмы числительные, доступны только в
|
||||||
|
GPL-шрифтах).
|
||||||
|
|
||||||
|
На `.doc` переключатели «Диаграммы/SmartArt/OLE» не срабатывают: плейсхолдеры
|
||||||
|
бинарного формата — уже растры, они вставляются картинками; векторные EMF/WMF/PICT
|
||||||
|
пропускаются.
|
||||||
|
|
||||||
|
Полный перечень известных расхождений — [Ограничения рендера](architecture/limitations.md).
|
||||||
@@ -16,6 +16,16 @@ server {
|
|||||||
set $upstream_app http://app:8080;
|
set $upstream_app http://app:8080;
|
||||||
set $upstream_web http://web:80;
|
set $upstream_web http://web:80;
|
||||||
|
|
||||||
|
# X-Forwarded-* переписываются безусловно: клиент не должен иметь возможности
|
||||||
|
# подсунуть бэкенду подставной "реальный IP/схема/хост" (Spring
|
||||||
|
# ForwardedHeaderFilter доверяет этим заголовкам; прямое попадание на
|
||||||
|
# 9010 мимо внешнего reverse-proxy — штатный случай стенда).
|
||||||
|
# X-Forwarded-Prefix не трогаем: его проставляет внешний nginx, на нём
|
||||||
|
# держится корректный base у swagger-ui за прокси.
|
||||||
|
proxy_set_header X-Forwarded-For $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-Proto $scheme;
|
||||||
|
proxy_set_header X-Forwarded-Host $host;
|
||||||
|
|
||||||
location /api/ {
|
location /api/ {
|
||||||
# в proxy_pass нет path-части, поэтому URI передаётся как есть
|
# в proxy_pass нет path-части, поэтому URI передаётся как есть
|
||||||
proxy_pass $upstream_app;
|
proxy_pass $upstream_app;
|
||||||
|
|||||||
Executable
+128
@@ -0,0 +1,128 @@
|
|||||||
|
#!/bin/sh
|
||||||
|
# Замер памяти конвейера конвертации: пики кучи на конвертацию (TSV из MemoryBench)
|
||||||
|
# + топ аллокаций по JFR (jdk.ObjectAllocationSample). Методика и числа —
|
||||||
|
# docs/MEM_USAGE_UPGRADE.md.
|
||||||
|
#
|
||||||
|
# Вход: env MB_LABEL — метка прогона (before/after/f1…, файл JFR per-label);
|
||||||
|
# env MB_JAVA_OPTS — доп. флаги JVM ПОСЛЕ дефолтных (переопределение Xmx/GC
|
||||||
|
# для матрицы флагов; при -Xmx меньше дефолтного дефолт просто заменяется;
|
||||||
|
# для смены GC нужен и выключатель дефолта: "-XX:-UseG1GC -XX:+UseSerialGC",
|
||||||
|
# иначе JVM падает на старте с "Multiple garbage collectors selected");
|
||||||
|
# аргументы проходят в MemoryBench: --scenario suite|big|all|, --loops N,
|
||||||
|
# --big-loops N, --dir PATH (реальные документы, напр. develop/).
|
||||||
|
#
|
||||||
|
# Пример: MB_LABEL=before ./mise.sh run mem-bench --scenario all --loops 20 | tee target/mem-before.txt
|
||||||
|
set -eu
|
||||||
|
|
||||||
|
cd "$(dirname "$0")"
|
||||||
|
|
||||||
|
LABEL=${MB_LABEL:-run}
|
||||||
|
|
||||||
|
mvn -q -pl wordpdf-core test-compile
|
||||||
|
CPFILE=$PWD/wordpdf-core/target/cp.txt
|
||||||
|
if [ ! -f "$CPFILE" ] || [ wordpdf-core/pom.xml -nt "$CPFILE" ]; then
|
||||||
|
mvn -q -pl wordpdf-core org.apache.maven.plugins:maven-dependency-plugin:3.8.1:build-classpath \
|
||||||
|
-Dmdep.outputFile="$CPFILE" -Dmdep.includeScope=test
|
||||||
|
fi
|
||||||
|
|
||||||
|
JFR=$PWD/wordpdf-core/target/membench-$LABEL.jfr
|
||||||
|
GCLOG=$PWD/wordpdf-core/target/membench-$LABEL.gc.log
|
||||||
|
ERRLOG=$PWD/wordpdf-core/target/membench-$LABEL.err
|
||||||
|
printf '# git %s\n' "$(git rev-parse HEAD)"
|
||||||
|
printf '# date %s\n' "$(date -u +%FT%TZ)"
|
||||||
|
printf '# MB_JAVA_OPTS=%s\n' "${MB_JAVA_OPTS:-}"
|
||||||
|
|
||||||
|
# MB_JAVA_OPTS без кавычек — намеренно: несколько флагов одним словом пользователя.
|
||||||
|
# shellcheck disable=SC2086
|
||||||
|
java -Xms64m -Xmx2g -XX:+UseG1GC -Djava.awt.headless=true \
|
||||||
|
-Xlog:gc*=info,gc+heap=debug:file=$GCLOG \
|
||||||
|
${MB_JAVA_OPTS:-} \
|
||||||
|
-XX:StartFlightRecording=filename=$JFR,settings=profile,maxsize=0,loglevel=error \
|
||||||
|
-cp "wordpdf-core/target/classes:wordpdf-core/target/test-classes:$(cat "$CPFILE")" \
|
||||||
|
ru.pjandro.wordpdf.MemoryBench "$@" 2>"$ERRLOG"
|
||||||
|
|
||||||
|
# --- аллокации по GC-логу (абсолютная оценка) -----------------------------------
|
||||||
|
# allocated ≈ выметенный Eden + выметенные humongous-области (G1); max-live —
|
||||||
|
# максимум heap после пауз (тренд накопления); паузы — число/сумма.
|
||||||
|
# awk — портативный (mawk/gawk): без 3-аргументного match().
|
||||||
|
echo
|
||||||
|
awk '
|
||||||
|
/Region Size:/ {
|
||||||
|
for (i = 1; i <= NF; i++) { if ($i ~ /^[0-9]+M$/) { tok = $i; sub(/M$/, "", tok); rs = tok + 0 } }
|
||||||
|
}
|
||||||
|
/Eden regions:/ {
|
||||||
|
for (i = 1; i <= NF; i++) {
|
||||||
|
if ($i ~ /^[0-9]+->[0-9]+/) { p = $i; sub(/\(.*/, "", p); split(p, a, "->"); eden += (a[1] - a[2]) * rs }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
/Humongous regions:/ {
|
||||||
|
for (i = 1; i <= NF; i++) {
|
||||||
|
if ($i ~ /^[0-9]+->[0-9]+/) { p = $i; sub(/\(.*/, "", p); split(p, a, "->"); hum += (a[1] - a[2]) * rs }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
/Pause (Young|Full)/ && /M->/ {
|
||||||
|
pauses++
|
||||||
|
tail = $NF; if (tail ~ /[0-9]ms$/) { sub(/ms$/, "", tail); ptime += tail }
|
||||||
|
for (i = 1; i <= NF; i++) {
|
||||||
|
if ($i ~ /^[0-9]+M->[0-9]+M/) {
|
||||||
|
v = $i; sub(/\(.*/, "", v); split(v, m, "->")
|
||||||
|
if (m[2] + 0 > maxlive) { maxlive = m[2] + 0 }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
END {
|
||||||
|
printf "gc-summary allocated-estimate=%dMB max-live-after-gc=%dMB pauses=%d pause-total=%dms\n",
|
||||||
|
eden + hum, maxlive, pauses, ptime
|
||||||
|
}
|
||||||
|
' "$GCLOG"
|
||||||
|
|
||||||
|
# --- агрегация аллокаций из JFR -------------------------------------------------
|
||||||
|
TOPF=$(mktemp); APPF=$(mktemp)
|
||||||
|
trap 'rm -f "$TOPF" "$APPF"' EXIT
|
||||||
|
|
||||||
|
jfr print --events jdk.ObjectAllocationSample "$JFR" | awk \
|
||||||
|
-v TOPF="$TOPF" -v APPF="$APPF" '
|
||||||
|
function framekey(line, k) {
|
||||||
|
k = line
|
||||||
|
sub(/^[ \t]+/, "", k)
|
||||||
|
sub(/ line: [0-9]+$/, "", k)
|
||||||
|
return k
|
||||||
|
}
|
||||||
|
function cls(key, c) {
|
||||||
|
c = key
|
||||||
|
sub(/ ?\(.*$/, "", c)
|
||||||
|
sub(/^[^ ]*\//, "", c)
|
||||||
|
return c
|
||||||
|
}
|
||||||
|
/^ *weight = / { w = $3 + 0 }
|
||||||
|
/^ *stackTrace = \[/ { instk = 1; nf = 0; next }
|
||||||
|
instk == 1 && /^ *\]/ {
|
||||||
|
instk = 0
|
||||||
|
if (nf == 0) { next }
|
||||||
|
top = fr[1]
|
||||||
|
app = ""
|
||||||
|
for (i = 1; i <= nf; i++) {
|
||||||
|
c = cls(fr[i])
|
||||||
|
if (c !~ /^(java|javax|jdk|sun|com\.sun|org\.apache|org\.docx4j|org\.springframework|org\.springdoc|org\.w3c|org\.xml|net\.sf|org\.slf4j|ch\.qos)/) {
|
||||||
|
app = fr[i]
|
||||||
|
break
|
||||||
|
}
|
||||||
|
}
|
||||||
|
wsum[top] += w
|
||||||
|
if (app != "") { asum[app] += w }
|
||||||
|
next
|
||||||
|
}
|
||||||
|
instk == 1 { nf++; fr[nf] = framekey($0) }
|
||||||
|
END {
|
||||||
|
for (k in wsum) { print wsum[k] "\t" k > TOPF }
|
||||||
|
for (k in asum) { print asum[k] "\t" k > APPF }
|
||||||
|
}
|
||||||
|
'
|
||||||
|
|
||||||
|
echo
|
||||||
|
printf '===== top-frames: суммарный вес аллокаций, байт (JFR profile, оценка) — label %s =====\n' "$LABEL"
|
||||||
|
sort -rn "$TOPF" | head -15
|
||||||
|
printf '===== alloc-total: %s байт\n' "$(awk '{s+=$1} END {printf "%.0f", s}' "$TOPF")"
|
||||||
|
echo
|
||||||
|
printf '===== app-sites: аллокации с первым кадром из приложения (attribution) =====\n'
|
||||||
|
sort -rn "$APPF" | head -15
|
||||||
@@ -14,6 +14,14 @@ _.python.venv = { path = "prod-autotests/.venv", create = true }
|
|||||||
description = "mvn clean verify — полный гейт перед push (тесты + PMD + JaCoCo)"
|
description = "mvn clean verify — полный гейт перед push (тесты + PMD + JaCoCo)"
|
||||||
run = "mvn clean verify"
|
run = "mvn clean verify"
|
||||||
|
|
||||||
|
[tasks.verify-nofontconfig]
|
||||||
|
description = "mvn clean verify в контейнере без fontconfig (гейт, которым живёт CI; verify — хост-гейт без контейнера)"
|
||||||
|
run = "podman build -f Containerfile.test ."
|
||||||
|
|
||||||
|
[tasks.mem-bench]
|
||||||
|
description = "Замер памяти конвейера: TSV пиков кучи + топ аллокаций JFR (docs/MEM_USAGE_UPGRADE.md)"
|
||||||
|
run = "sh membench.sh"
|
||||||
|
|
||||||
[tasks.app-package]
|
[tasks.app-package]
|
||||||
description = "Исполняемый jar бэкенда"
|
description = "Исполняемый jar бэкенда"
|
||||||
run = "mvn -pl wordpdf-app -am package"
|
run = "mvn -pl wordpdf-app -am package"
|
||||||
@@ -46,3 +54,33 @@ run = "npm run dev"
|
|||||||
description = "Прод-автотесты; обязателен WORDPDF_BASE_URL (факультативно WORDPDF_API_KEY)"
|
description = "Прод-автотесты; обязателен WORDPDF_BASE_URL (факультативно WORDPDF_API_KEY)"
|
||||||
dir = "prod-autotests"
|
dir = "prod-autotests"
|
||||||
run = "python -m pip install -q -r requirements.txt && python -m pytest -q ."
|
run = "python -m pip install -q -r requirements.txt && python -m pytest -q ."
|
||||||
|
|
||||||
|
[tasks.docs-install]
|
||||||
|
description = "Зависимости сайта документации: venv docs/.venv + mkdocs-material"
|
||||||
|
run = [
|
||||||
|
"[ -d docs/.venv ] || python -m venv docs/.venv",
|
||||||
|
"docs/.venv/bin/python -m pip install -q -r docs/requirements.txt",
|
||||||
|
]
|
||||||
|
|
||||||
|
[tasks.docs-serve]
|
||||||
|
description = "Локальный предпросмотр сайта на :8000 (live-reload)"
|
||||||
|
run = "docs/.venv/bin/mkdocs serve -a 127.0.0.1:8000"
|
||||||
|
|
||||||
|
[tasks.docs-build]
|
||||||
|
description = "Strict-сборка сайта в site/ (битые ссылки/навигация = ошибка)"
|
||||||
|
run = "docs/.venv/bin/mkdocs build --strict"
|
||||||
|
|
||||||
|
[tasks.docs-javadoc]
|
||||||
|
description = "Javadoc публичного API core в wordpdf-core/target/site/apidocs"
|
||||||
|
run = "mvn -q -pl wordpdf-core -am javadoc:javadoc"
|
||||||
|
|
||||||
|
[tasks.docs-deploy]
|
||||||
|
description = "Публикация сайта на rpi (:9012): javadoc + strict-build + rsync в ~/srv/wordpdf-docs"
|
||||||
|
run = [
|
||||||
|
"mvn -q -pl wordpdf-core -am javadoc:javadoc",
|
||||||
|
"rm -rf docs/apidocs",
|
||||||
|
"cp -r wordpdf-core/target/site/apidocs docs/apidocs",
|
||||||
|
"docs/.venv/bin/mkdocs build --strict",
|
||||||
|
"install -d /home/pjandro/srv/wordpdf-docs",
|
||||||
|
"rsync -a --delete site/ /home/pjandro/srv/wordpdf-docs/",
|
||||||
|
]
|
||||||
|
|||||||
+76
@@ -0,0 +1,76 @@
|
|||||||
|
site_name: «Word → PDF конвертер» — документация
|
||||||
|
site_description: "docx4j + Apache FOP на чистой Java: библиотека, REST API, веб-интерфейс"
|
||||||
|
docs_dir: docs
|
||||||
|
site_dir: site
|
||||||
|
exclude_docs: |
|
||||||
|
/agent/
|
||||||
|
/standards/
|
||||||
|
/requirements.txt
|
||||||
|
# javadoc-копия (docs/apidocs, заполняет docs-deploy) — статика вне навигации;
|
||||||
|
# её md-файлы (legal/*) mkdocs иначе показывает как страницы вне nav
|
||||||
|
not_in_nav: |
|
||||||
|
/apidocs/**/*.md
|
||||||
|
theme:
|
||||||
|
name: material
|
||||||
|
language: ru
|
||||||
|
palette:
|
||||||
|
- scheme: default
|
||||||
|
primary: indigo
|
||||||
|
toggle:
|
||||||
|
icon: material/weather-sunny
|
||||||
|
name: Тёмная тема
|
||||||
|
- scheme: slate
|
||||||
|
primary: indigo
|
||||||
|
toggle:
|
||||||
|
icon: material/weather-night
|
||||||
|
name: Светлая тема
|
||||||
|
features:
|
||||||
|
- navigation.sections
|
||||||
|
- navigation.top
|
||||||
|
- toc.follow
|
||||||
|
- search.suggest
|
||||||
|
markdown_extensions:
|
||||||
|
- admonition
|
||||||
|
- attr_list
|
||||||
|
- footnotes
|
||||||
|
- toc:
|
||||||
|
permalink: true
|
||||||
|
- pymdownx.details
|
||||||
|
- pymdownx.superfences
|
||||||
|
- pymdownx.highlight:
|
||||||
|
anchor_linenums: true
|
||||||
|
plugins:
|
||||||
|
- search:
|
||||||
|
lang: ru
|
||||||
|
nav:
|
||||||
|
- Главное: index.md
|
||||||
|
- Пользователю: user.md
|
||||||
|
- REST API:
|
||||||
|
- api/index.md
|
||||||
|
- Аутентификация: api/authentication.md
|
||||||
|
- Эндпоинт конвертации: api/convert-endpoint.md
|
||||||
|
- Коды ошибок: api/errors.md
|
||||||
|
- Лимиты: api/limits.md
|
||||||
|
- Примеры клиентов: api/examples.md
|
||||||
|
- Библиотека wordpdf-core:
|
||||||
|
- library/getting-started.md
|
||||||
|
- library/api.md
|
||||||
|
- library/dependencies.md
|
||||||
|
- Архитектура:
|
||||||
|
- architecture/overview.md
|
||||||
|
- architecture/doc-bridge.md
|
||||||
|
- architecture/charts.md
|
||||||
|
- architecture/fonts.md
|
||||||
|
- architecture/limitations.md
|
||||||
|
- Разработчику:
|
||||||
|
- development/setup.md
|
||||||
|
- development/testing.md
|
||||||
|
- development/contributing.md
|
||||||
|
- Эксплуатация:
|
||||||
|
- operations/stack.md
|
||||||
|
- operations/configuration.md
|
||||||
|
- operations/deployment.md
|
||||||
|
- operations/troubleshooting.md
|
||||||
|
- operations/docs-site.md
|
||||||
|
- "Отчёт: потребление памяти": MEM_USAGE_UPGRADE.md
|
||||||
|
- Внутренние справочники репозитория: internal-guides.md
|
||||||
+30
-70
@@ -2,76 +2,36 @@
|
|||||||
<ruleset name="WordPDF code style" xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
|
<ruleset name="WordPDF code style" xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
|
||||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||||
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
|
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
|
||||||
<description>Код-стиль java-word-pdf: codestyle без opinionated-правил + unused-правила + NPE-safe equals</description>
|
<description>Код-стиль java-word-pdf: закрытый список правил под движок PMD 6.55.0
|
||||||
|
(maven-pmd-plugin 3.21.2; откат с PMD 7 — правила *MustUseBraces удалены в 7-й
|
||||||
|
мажорной, их deprecation-предупреждения в логе verify ожидаемы). Нарушения чинятся
|
||||||
|
кодом — подавление @SuppressWarnings("PMD…") и // NOPMD запрещены; правила не
|
||||||
|
исключаются и не перенастраиваются.</description>
|
||||||
|
|
||||||
<rule ref="category/java/codestyle.xml">
|
<rule ref="category/java/bestpractices.xml/ForLoopCanBeForeach"/>
|
||||||
<!-- opinionated/шумные, намеренно выключены -->
|
<rule ref="category/java/design.xml/ExceptionAsFlowControl"/>
|
||||||
<exclude name="AtLeastOneConstructor"/>
|
<rule ref="category/java/errorprone.xml/EqualsNull"/>
|
||||||
<exclude name="CallSuperInConstructor"/>
|
<rule ref="category/java/errorprone.xml/CloseResource"/>
|
||||||
<exclude name="CommentDefaultAccessModifier"/>
|
<rule ref="category/java/errorprone.xml/BrokenNullCheck"/>
|
||||||
<exclude name="ConfusingTernary"/>
|
<rule ref="category/java/bestpractices.xml/AvoidPrintStackTrace"/>
|
||||||
<exclude name="FieldDeclarationsShouldBeAtStartOfClass"/>
|
<rule ref="category/java/errorprone.xml/AvoidLosingExceptionInformation"/>
|
||||||
<exclude name="LocalVariableCouldBeFinal"/>
|
|
||||||
<exclude name="LongVariable"/>
|
|
||||||
<exclude name="MethodArgumentCouldBeFinal"/>
|
|
||||||
<exclude name="OnlyOneReturn"/>
|
|
||||||
<exclude name="PrematureDeclaration"/>
|
|
||||||
<exclude name="ShortMethodName"/>
|
|
||||||
<exclude name="ShortVariable"/>
|
|
||||||
<exclude name="UseExplicitTypes"/>
|
|
||||||
<exclude name="UseUnderscoresInNumericLiterals"/>
|
|
||||||
<!-- переопределены ниже -->
|
|
||||||
<exclude name="MethodNamingConventions"/>
|
|
||||||
<exclude name="TooManyStaticImports"/>
|
|
||||||
</rule>
|
|
||||||
|
|
||||||
<!-- регрессионные тесты репо именуются объект_условие (AGENTS.md) -->
|
|
||||||
<rule ref="category/java/codestyle.xml/MethodNamingConventions">
|
|
||||||
<properties>
|
|
||||||
<property name="junit5TestPattern" value="^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$"/>
|
|
||||||
</properties>
|
|
||||||
</rule>
|
|
||||||
|
|
||||||
<!-- MockMvc-тесты: >4 статических импортов — норма -->
|
|
||||||
<rule ref="category/java/codestyle.xml/TooManyStaticImports">
|
|
||||||
<properties>
|
|
||||||
<property name="maximumStaticImports" value="12"/>
|
|
||||||
</properties>
|
|
||||||
</rule>
|
|
||||||
|
|
||||||
<!-- PMD 7 удалил EqualsAvoidsNull; NPE-safe порядок операндов: литерал слева -->
|
|
||||||
<rule name="LiteralFirstInEquals" language="java"
|
|
||||||
message="NPE-safe сравнение строк: строковый литерал должен стоять слева: "lit".equals(x)"
|
|
||||||
class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
|
|
||||||
<priority>3</priority>
|
|
||||||
<properties>
|
|
||||||
<property name="xpath">
|
|
||||||
<value><![CDATA[
|
|
||||||
//MethodCall[
|
|
||||||
(@MethodName = 'equals' or @MethodName = 'equalsIgnoreCase')
|
|
||||||
and ArgumentList/StringLiteral
|
|
||||||
and not(*[1][self::StringLiteral
|
|
||||||
or (self::VariableAccess and @CompileTimeConstant = true())])
|
|
||||||
]
|
|
||||||
]]></value>
|
|
||||||
</property>
|
|
||||||
</properties>
|
|
||||||
</rule>
|
|
||||||
|
|
||||||
<rule ref="category/java/bestpractices.xml/UnusedAssignment"/>
|
|
||||||
<rule ref="category/java/bestpractices.xml/UnusedFormalParameter"/>
|
|
||||||
<rule ref="category/java/bestpractices.xml/UnusedLocalVariable"/>
|
|
||||||
<rule ref="category/java/bestpractices.xml/UnusedPrivateField"/>
|
|
||||||
<rule ref="category/java/bestpractices.xml/UnusedPrivateMethod"/>
|
|
||||||
|
|
||||||
<!-- null вместо пустой коллекции запрещён (priority 1 по умолчанию — валит verify) -->
|
|
||||||
<rule ref="category/java/errorprone.xml/ReturnEmptyCollectionRatherThanNull"/>
|
|
||||||
<!-- литералы в условиях if — только именованными константами -->
|
|
||||||
<rule ref="category/java/errorprone.xml/AvoidLiteralsInIfCondition"/>
|
<rule ref="category/java/errorprone.xml/AvoidLiteralsInIfCondition"/>
|
||||||
<rule ref="category/java/errorprone.xml/EmptyCatchBlock">
|
<rule ref="category/java/errorprone.xml/AvoidCatchingNPE"/>
|
||||||
<priority>2</priority>
|
<rule ref="category/java/errorprone.xml/AssignmentToNonFinalStatic"/>
|
||||||
</rule>
|
<rule ref="category/java/errorprone.xml/DoNotCallGarbageCollectionExplicitly"/>
|
||||||
<rule ref="category/java/bestpractices.xml/ForLoopCanBeForeach">
|
<rule ref="category/java/errorprone.xml/EmptyCatchBlock"/>
|
||||||
<priority>2</priority>
|
<rule ref="category/java/errorprone.xml/CompareObjectsWithEquals"/>
|
||||||
</rule>
|
<rule ref="category/java/bestpractices.xml/UnusedPrivateMethod"/>
|
||||||
|
<rule ref="category/java/bestpractices.xml/UnusedPrivateField"/>
|
||||||
|
<rule ref="category/java/codestyle.xml/UnnecessaryImport"/>
|
||||||
|
<rule ref="category/java/bestpractices.xml/SystemPrintln"/>
|
||||||
|
<rule ref="category/java/multithreading.xml/UnsynchronizedStaticFormatter"/>
|
||||||
|
<rule ref="category/java/errorprone.xml/ReturnEmptyCollectionRatherThanNull"/>
|
||||||
|
<rule ref="category/java/errorprone.xml/MisplacedNullCheck"/>
|
||||||
|
<rule ref="category/java/bestpractices.xml/LiteralsFirstInComparisons"/>
|
||||||
|
<rule ref="category/java/codestyle.xml/WhileLoopsMustUseBraces"/>
|
||||||
|
<rule ref="category/java/codestyle.xml/IfStmtsMustUseBraces"/>
|
||||||
|
<rule ref="category/java/codestyle.xml/IfElseStmtsMustUseBraces"/>
|
||||||
|
<rule ref="category/java/errorprone.xml/ImplicitSwitchFallThrough"/>
|
||||||
|
<rule ref="category/java/codestyle.xml/ForLoopsMustUseBraces"/>
|
||||||
</ruleset>
|
</ruleset>
|
||||||
|
|||||||
@@ -39,6 +39,8 @@
|
|||||||
|
|
||||||
<!-- Покрытие: последняя стабильная на Maven Central -->
|
<!-- Покрытие: последняя стабильная на Maven Central -->
|
||||||
<jacoco.version>0.8.15</jacoco.version>
|
<jacoco.version>0.8.15</jacoco.version>
|
||||||
|
<!-- Javadoc публичного API core: последняя стабильная на Maven Central -->
|
||||||
|
<maven-javadoc-plugin.version>3.12.0</maven-javadoc-plugin.version>
|
||||||
<!-- Пустой дефолт: при -Djacoco.skip=true surefire не споткнётся
|
<!-- Пустой дефолт: при -Djacoco.skip=true surefire не споткнётся
|
||||||
о неразвёрнутый @{argLine}; prepare-agent перезаписывает его -->
|
о неразвёрнутый @{argLine}; prepare-agent перезаписывает его -->
|
||||||
<argLine></argLine>
|
<argLine></argLine>
|
||||||
@@ -156,10 +158,31 @@
|
|||||||
<artifactId>maven-jar-plugin</artifactId>
|
<artifactId>maven-jar-plugin</artifactId>
|
||||||
<version>3.5.1</version>
|
<version>3.5.1</version>
|
||||||
</plugin>
|
</plugin>
|
||||||
|
<!-- Javadoc: генерация только по явной цели javadoc:javadoc
|
||||||
|
(объявлен без executions в wordpdf-core) — поведение
|
||||||
|
mvn clean verify не затрагивает. -->
|
||||||
|
<plugin>
|
||||||
|
<groupId>org.apache.maven.plugins</groupId>
|
||||||
|
<artifactId>maven-javadoc-plugin</artifactId>
|
||||||
|
<version>${maven-javadoc-plugin.version}</version>
|
||||||
|
<configuration>
|
||||||
|
<encoding>UTF-8</encoding>
|
||||||
|
<doclint>all,-missing</doclint>
|
||||||
|
<show>protected</show>
|
||||||
|
<nohelp>true</nohelp>
|
||||||
|
<windowtitle>wordpdf-core API</windowtitle>
|
||||||
|
<doctitle>wordpdf-core API (javadoc)</doctitle>
|
||||||
|
<!-- пин вывода: у 3.12.0 дефолт target/reports (параметр
|
||||||
|
outputDirectory, поверх него плагин сам кладёт apidocs/),
|
||||||
|
фиксируем target/site → target/site/apidocs — оттуда
|
||||||
|
копирует задача docs-deploy -->
|
||||||
|
<outputDirectory>${project.build.directory}/site</outputDirectory>
|
||||||
|
</configuration>
|
||||||
|
</plugin>
|
||||||
<plugin>
|
<plugin>
|
||||||
<groupId>org.apache.maven.plugins</groupId>
|
<groupId>org.apache.maven.plugins</groupId>
|
||||||
<artifactId>maven-pmd-plugin</artifactId>
|
<artifactId>maven-pmd-plugin</artifactId>
|
||||||
<version>3.28.0</version>
|
<version>3.21.2</version>
|
||||||
<configuration>
|
<configuration>
|
||||||
<rulesets>
|
<rulesets>
|
||||||
<ruleset>${maven.multiModuleProjectDirectory}/pmd-ruleset.xml</ruleset>
|
<ruleset>${maven.multiModuleProjectDirectory}/pmd-ruleset.xml</ruleset>
|
||||||
|
|||||||
@@ -8,9 +8,9 @@ WORDPDF_BASE_URL обязателен: без него все проверки
|
|||||||
не знает ни одного хоста. WORDPDF_API_KEY факультативен: без него проверки,
|
не знает ни одного хоста. WORDPDF_API_KEY факультативен: без него проверки,
|
||||||
где есть заголовок ключа или ожидается 401, пропускаются (без локального ключа
|
где есть заголовок ключа или ожидается 401, пропускаются (без локального ключа
|
||||||
нельзя знать, включена ли аутентификация на стенде). WORDPDF_MAX_PAGES — ожидаемый
|
нельзя знать, включена ли аутентификация на стенде). WORDPDF_MAX_PAGES — ожидаемый
|
||||||
лимит страниц стенда (конфигурация сервера, не константа набора; дефолт 100 =
|
лимит страниц стенда (конфигурация сервера, не константа набора; дефолт эндпоинта
|
||||||
дефолт ядра). WORDPDF_MAX_MB — ожидаемый лимит размера .docx стенда в МБ (MiB; дефолт
|
100). WORDPDF_MAX_MB — ожидаемый лимит размера .docx стенда в МБ (MiB; дефолт
|
||||||
5 = дефолт ядра). .docx-фикстуры — из wordpdf-core/src/test/resources/samples,
|
эндпоинта 5). .docx-фикстуры — из wordpdf-core/src/test/resources/samples,
|
||||||
либо из WORDPDF_SAMPLES_DIR.
|
либо из WORDPDF_SAMPLES_DIR.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
|
|||||||
@@ -63,11 +63,17 @@ final class ApiExceptionHandler {
|
|||||||
.body(new ApiError(e.getMessage()));
|
.body(new ApiError(e.getMessage()));
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Ошибка ядра/рендера при формально корректном входе. */
|
/**
|
||||||
|
* Ошибка ядра/рендера при формально корректном входе. Сообщение ядра
|
||||||
|
* (тексты docx4j/FOP/JAXB, пути temp-файлов) — только в лог: наружу
|
||||||
|
* фиксированный текст, иначе 500 становится каналом внутренней информации.
|
||||||
|
* Регрессия — ConvertControllerTest#conversionFailure_hidesInternalDetails.
|
||||||
|
*/
|
||||||
@ExceptionHandler(ConversionFailedException.class)
|
@ExceptionHandler(ConversionFailedException.class)
|
||||||
ResponseEntity<ApiError> conversionFailed(ConversionFailedException e) {
|
ResponseEntity<ApiError> conversionFailed(ConversionFailedException e) {
|
||||||
|
LOG.error("Конвертация не удалась", e);
|
||||||
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
|
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
|
||||||
.body(new ApiError(e.getMessage()));
|
.body(new ApiError("Не удалось конвертировать документ"));
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Очередь конвертации занята/прерывание — повторить позже. */
|
/** Очередь конвертации занята/прерывание — повторить позже. */
|
||||||
|
|||||||
@@ -3,9 +3,11 @@ package ru.pjandro.wordpdf.app;
|
|||||||
import jakarta.annotation.PreDestroy;
|
import jakarta.annotation.PreDestroy;
|
||||||
import org.springframework.beans.factory.annotation.Value;
|
import org.springframework.beans.factory.annotation.Value;
|
||||||
import org.springframework.stereotype.Service;
|
import org.springframework.stereotype.Service;
|
||||||
|
import ru.pjandro.wordpdf.ChartsFoundException;
|
||||||
import ru.pjandro.wordpdf.ConvertOptions;
|
import ru.pjandro.wordpdf.ConvertOptions;
|
||||||
import ru.pjandro.wordpdf.ConversionException;
|
import ru.pjandro.wordpdf.ConversionException;
|
||||||
import ru.pjandro.wordpdf.DrawingFoundException;
|
import ru.pjandro.wordpdf.OleFoundException;
|
||||||
|
import ru.pjandro.wordpdf.SmartArtFoundException;
|
||||||
import ru.pjandro.wordpdf.WordPdfConverter;
|
import ru.pjandro.wordpdf.WordPdfConverter;
|
||||||
import ru.pjandro.wordpdf.WordPdfValidator;
|
import ru.pjandro.wordpdf.WordPdfValidator;
|
||||||
import ru.pjandro.wordpdf.ValidationException;
|
import ru.pjandro.wordpdf.ValidationException;
|
||||||
@@ -23,22 +25,23 @@ import java.util.concurrent.TimeoutException;
|
|||||||
/**
|
/**
|
||||||
* Конвертация .docx-байтов в PDF-байты поверх {@code wordpdf-core}.
|
* Конвертация .docx-байтов в PDF-байты поверх {@code wordpdf-core}.
|
||||||
*
|
*
|
||||||
* <p>Конвертации СЕРИАЛИЗОВАНЫ однопоточным executor'ом — не «на всякий
|
* <p>Конвертации СЕРИАЛИЗОВАНЫ однопоточным executor'ом: он держит очередь,
|
||||||
* случай»: каждая конвертация мутирует ГЛОБАЛЬНЫЙ реестр шрифтов docx4j
|
* 503 при переполнении и timeout-семантику (backpressure). Само ядро при этом
|
||||||
* ({@code new BundledFontMapper()} заново добавляет системные шрифты
|
* сериализует конвертации внутренним монитором ({@code WordPdfConverter.class}:
|
||||||
* в {@code PhysicalFonts}, {@code BundledFonts.init()/restrictToBundled()}
|
* глобальный реестр {@code PhysicalFonts}, общая FopFactory с имиджевыми
|
||||||
* их вычищают — WordPdfConverter.convertToStream, шаг 1 пайплайна). Параллельные конвертации
|
* кешами и их сброс в finally мутируются под рендером), так что параллельные
|
||||||
* вырывают реестр друг у друга из-под рендера, ядро не потокобезопасно
|
* вызовы ядра не приводят к порче вывода.
|
||||||
* by design. Регрессия — ConvertControllerTest#concurrentRequests_bothSucceed.</p>
|
* Регрессия — ConvertControllerTest#concurrentRequests_bothSucceed.</p>
|
||||||
*
|
*
|
||||||
* <p>Ошибки разделены по смыслу (требование к API): некорректный вход →
|
* <p>Ошибки разделены по смыслу (требование к API): некорректный вход →
|
||||||
* {@link ValidationException} (400), ошибка рендер-стадии →
|
* {@link ValidationException} (400), ошибка рендер-стадии →
|
||||||
* {@link ConversionFailedException} (500). Граница: сломанный контейнер
|
* {@link ConversionFailedException} (500). Граница: сломанный контейнер
|
||||||
* (не zip / битый zip / слишком большой / слишком длинный) — 400; валидный
|
* (не zip / битый zip / слишком большой / слишком длинный) — 400; валидный
|
||||||
* zip с мусором внутри (нет {@code word/document.xml}) — 500: до очереди и
|
* zip с мусором внутри (нет {@code word/document.xml}) — 500: до очереди
|
||||||
* в конвейере ядра вход проверяется тем же
|
* проверяется только размер, корректность контейнера и число страниц —
|
||||||
* {@link WordPdfValidator#validate(byte[], ConvertOptions)}, поэтому уже
|
* сериализованно внутри воркера (ядро вызывает тот же
|
||||||
* принятый запрос внутренняя проверка ядра в ошибку не превратит.</p>
|
* {@link WordPdfValidator#validate(byte[], ConvertOptions)}), поэтому
|
||||||
|
* тяжёлая проверка не занимает потоки контейнера в обход сериализации.</p>
|
||||||
*/
|
*/
|
||||||
@Service
|
@Service
|
||||||
final class ConversionService {
|
final class ConversionService {
|
||||||
@@ -55,17 +58,18 @@ final class ConversionService {
|
|||||||
new ArrayBlockingQueue<>(QUEUE_CAPACITY));
|
new ArrayBlockingQueue<>(QUEUE_CAPACITY));
|
||||||
// Прогрев ядра — головой той же однопоточной очереди: первый реальный
|
// Прогрев ядра — головой той же однопоточной очереди: первый реальный
|
||||||
// запрос после деплоя становится за прогретым ядром (~50–300 мс вместо
|
// запрос после деплоя становится за прогретым ядром (~50–300 мс вместо
|
||||||
// 1,4–1,9 с) и гарантированно сериализован с конвертациями (ядро не
|
// 1,4–1,9 с); сериализация прогрева с конвертациями — тем же воркером
|
||||||
// потокобезопасно). warmup() не бросает — Future никто не забирает;
|
// и монитором ядра (warmup() синхронизирован им же). warmup() не
|
||||||
|
// бросает — Future никто не забирает;
|
||||||
// запросы, пришедшие во время прогрева, ждут в очереди (штатная
|
// запросы, пришедшие во время прогрева, ждут в очереди (штатная
|
||||||
// семантика, лимит convert-timeout с запасом).
|
// семантика, лимит convert-timeout с запасом).
|
||||||
this.workers.submit(WordPdfConverter::warmup);
|
this.workers.submit(WordPdfConverter::warmup);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Полный путь: синхронная валидация байтов (до очереди — от obvious-отказа
|
* Полный путь: синхронная проверка размера (до очереди) → постановка
|
||||||
* единый воркер не должен быть занят) → постановка в очередь → ожидание
|
* в очередь → ожидание результата с таймаутом; корректность контейнера
|
||||||
* результата с таймаутом.
|
* и число страниц проверяются сериализованно, внутри воркера (ядро).
|
||||||
*
|
*
|
||||||
* @throws ValidationException некорректный вход (400)
|
* @throws ValidationException некорректный вход (400)
|
||||||
* @throws ConversionFailedException ошибка ядра/рендера (500)
|
* @throws ConversionFailedException ошибка ядра/рендера (500)
|
||||||
@@ -77,14 +81,14 @@ final class ConversionService {
|
|||||||
* {@code null} не допускается (контроллер строит всегда).</p>
|
* {@code null} не допускается (контроллер строит всегда).</p>
|
||||||
*/
|
*/
|
||||||
byte[] convert(byte[] docxBytes, String originalFilename, ConvertOptions options) {
|
byte[] convert(byte[] docxBytes, String originalFilename, ConvertOptions options) {
|
||||||
// Бинарный .doc — не zip: .docx-валидация к нему неприменима, размер
|
// До очереди — только дешёвый гейт размера. Полная валидация
|
||||||
// проверяется общим checkInput, страницы — мостом по чистому .doc
|
// (контейнер + страницы — до двух полных распакованных проходов до
|
||||||
// (ядро бросит ValidationException → 400 тем же обработчиком).
|
// 64 МБ на обоих форматах) сериализована воркером: её выполняет ядро
|
||||||
if (WordPdfValidator.isBinaryDoc(docxBytes)) {
|
// внутри WordPdfConverter.convert (тот же validate с теми же
|
||||||
WordPdfValidator.checkInput(docxBytes, options.maxMb());
|
// options, ValidationException → 400 тем же путём). Синхронный
|
||||||
} else {
|
// полный validate до submit отдавал бы zip-бомбе потоки Tomcat
|
||||||
WordPdfValidator.validate(docxBytes, options);
|
// в обход сериализации.
|
||||||
}
|
WordPdfValidator.checkInput(docxBytes, options.maxMb());
|
||||||
Future<byte[]> future;
|
Future<byte[]> future;
|
||||||
try {
|
try {
|
||||||
future = workers.submit(() -> doConvert(docxBytes, originalFilename, options));
|
future = workers.submit(() -> doConvert(docxBytes, originalFilename, options));
|
||||||
@@ -139,10 +143,14 @@ final class ConversionService {
|
|||||||
// отказ проверки страниц внутри конвейера ядра — некорректный
|
// отказ проверки страниц внутри конвейера ядра — некорректный
|
||||||
// вход (400), а не ошибка рендера: без этого утонул бы в 500
|
// вход (400), а не ошибка рендера: без этого утонул бы в 500
|
||||||
throw e;
|
throw e;
|
||||||
} catch (DrawingFoundException e) {
|
} catch (ChartsFoundException e) {
|
||||||
// отказ по настройке запроса (error-флаг) — не ошибка рендера: 422,
|
// отказ по настройке запроса (error-флаг) — не ошибка рендера: 422,
|
||||||
// иначе утонет в общем catch ниже как 500
|
// иначе утонет в общем catch ниже как 500
|
||||||
throw new DrawingRejectedException(e.kind());
|
throw new DrawingRejectedException(DrawingRejectedException.CHARTS);
|
||||||
|
} catch (SmartArtFoundException e) {
|
||||||
|
throw new DrawingRejectedException(DrawingRejectedException.SMART_ART);
|
||||||
|
} catch (OleFoundException e) {
|
||||||
|
throw new DrawingRejectedException(DrawingRejectedException.OLE);
|
||||||
} catch (ConversionException e) {
|
} catch (ConversionException e) {
|
||||||
// всё, что упало на валидации/рендер-стадии ядра, — ошибка преобразования, 500
|
// всё, что упало на валидации/рендер-стадии ядра, — ошибка преобразования, 500
|
||||||
throw new ConversionFailedException("Не удалось конвертировать документ: "
|
throw new ConversionFailedException("Не удалось конвертировать документ: "
|
||||||
|
|||||||
@@ -12,7 +12,6 @@ import org.springframework.web.bind.annotation.RestController;
|
|||||||
import org.springframework.beans.factory.annotation.Value;
|
import org.springframework.beans.factory.annotation.Value;
|
||||||
import org.springframework.web.multipart.MultipartFile;
|
import org.springframework.web.multipart.MultipartFile;
|
||||||
import ru.pjandro.wordpdf.ConvertOptions;
|
import ru.pjandro.wordpdf.ConvertOptions;
|
||||||
import ru.pjandro.wordpdf.WordPdfSettings;
|
|
||||||
|
|
||||||
import java.io.IOException;
|
import java.io.IOException;
|
||||||
import java.nio.charset.StandardCharsets;
|
import java.nio.charset.StandardCharsets;
|
||||||
@@ -25,10 +24,11 @@ import java.util.Locale;
|
|||||||
* <p>Здесь только HTTP-слой: проверка presence/расширения и формирование
|
* <p>Здесь только HTTP-слой: проверка presence/расширения и формирование
|
||||||
* {@code Content-Disposition}; проверка содержимого (zip, размер, страницы) —
|
* {@code Content-Disposition}; проверка содержимого (zip, размер, страницы) —
|
||||||
* зона {@link ConversionService}. Ошибки в JSON-ответ переводит
|
* зона {@link ConversionService}. Ошибки в JSON-ответ переводит
|
||||||
* {@link ApiExceptionHandler}. Лимиты входа — только конфигурация сервера
|
* {@link ApiExceptionHandler}. Лимиты входа: свойства
|
||||||
* (свойства {@code wordpdf.max-mb}/{@code wordpdf.max-pages}, env
|
* {@code wordpdf.max-mb}/{@code wordpdf.max-pages} (env
|
||||||
* {@code WORDPDF_MAX_MB}/{@code WORDPDF_MAX_PAGES}); параметрами запроса
|
* {@code WORDPDF_MAX_MB}/{@code WORDPDF_MAX_PAGES}) — дефолт эндпоинта;
|
||||||
* они не переопределяются.</p>
|
* параметры запроса {@code maxMb}/{@code maxPages} переопределяют его в обе
|
||||||
|
* стороны (значения ≤ 0 → 400).</p>
|
||||||
*/
|
*/
|
||||||
@RestController
|
@RestController
|
||||||
final class ConvertController {
|
final class ConvertController {
|
||||||
@@ -38,14 +38,15 @@ final class ConvertController {
|
|||||||
private final int maxPages;
|
private final int maxPages;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Дефолт плейсхолдеров — константы ядра через SpEL: буквальное значение
|
* Дефолт плейсхолдеров — буквенные литералы 5/100 (дефолтов лимитов в
|
||||||
* в свойствах не дублируется. Невалидное значение (<= 0) роняет
|
* ядре нет); свойства/env переопределяют их, параметры запроса — см.
|
||||||
|
* {@link #convert}. Невалидное значение свойства (<= 0) роняет
|
||||||
* приложение на старте (fail-fast): «сервис поднят, но весь вход
|
* приложение на старте (fail-fast): «сервис поднят, но весь вход
|
||||||
* отсекается» — худший исход, чем не поднявшийся сервис.
|
* отсекается» — худший исход, чем не поднявшийся сервис.
|
||||||
*/
|
*/
|
||||||
ConvertController(ConversionService conversionService,
|
ConvertController(ConversionService conversionService,
|
||||||
@Value("${wordpdf.max-mb:#{T(ru.pjandro.wordpdf.WordPdfSettings).MAX_INPUT_MB}}") long maxMb,
|
@Value("${wordpdf.max-mb:5}") long maxMb,
|
||||||
@Value("${wordpdf.max-pages:#{T(ru.pjandro.wordpdf.WordPdfSettings).MAX_PAGES}}") int maxPages) {
|
@Value("${wordpdf.max-pages:100}") int maxPages) {
|
||||||
if (maxMb <= 0) {
|
if (maxMb <= 0) {
|
||||||
throw new IllegalStateException("wordpdf.max-mb должен быть больше 0: " + maxMb);
|
throw new IllegalStateException("wordpdf.max-mb должен быть больше 0: " + maxMb);
|
||||||
}
|
}
|
||||||
@@ -60,10 +61,11 @@ final class ConvertController {
|
|||||||
@Operation(summary = "Конвертировать .docx/.doc в PDF",
|
@Operation(summary = "Конвертировать .docx/.doc в PDF",
|
||||||
description = "Принимаются .docx (OOXML) и .doc (Word 97–2003, переносится в .docx "
|
description = "Принимаются .docx (OOXML) и .doc (Word 97–2003, переносится в .docx "
|
||||||
+ "мостом: текст и прямое форматирование). errorOnCharts/errorOnSmartArt/errorOnOle — факультативно, по умолчанию "
|
+ "мостом: текст и прямое форматирование). errorOnCharts/errorOnSmartArt/errorOnOle — факультативно, по умолчанию "
|
||||||
+ "настройки ядра (ошибка не выбрасывается); диаграммы/SmartArt "
|
+ "ошибка не выбрасывается; диаграммы/SmartArt "
|
||||||
+ "конвертируются всегда, OLE-объекты при выключенном флаге тихо удаляются. "
|
+ "конвертируются всегда, OLE-объекты при выключенном флаге тихо удаляются. "
|
||||||
+ "Лимиты входа (размер/страницы) задаёт только конфигурация сервера "
|
+ "Лимиты входа (размер/страницы): свойства wordpdf.max-mb/wordpdf.max-pages — "
|
||||||
+ "(свойства wordpdf.max-mb/wordpdf.max-pages), параметрами запроса не переопределяются")
|
+ "дефолт; параметры запроса maxMb/maxPages переопределяют его в обе стороны "
|
||||||
|
+ "(значения ≤ 0 → 400)")
|
||||||
@SecurityRequirement(name = OpenApiConfig.SCHEME)
|
@SecurityRequirement(name = OpenApiConfig.SCHEME)
|
||||||
@PostMapping(
|
@PostMapping(
|
||||||
path = "/api/v1/convert",
|
path = "/api/v1/convert",
|
||||||
@@ -73,7 +75,9 @@ final class ConvertController {
|
|||||||
@RequestParam("file") MultipartFile file,
|
@RequestParam("file") MultipartFile file,
|
||||||
@RequestParam(name = "errorOnCharts", required = false) Boolean errorOnCharts,
|
@RequestParam(name = "errorOnCharts", required = false) Boolean errorOnCharts,
|
||||||
@RequestParam(name = "errorOnSmartArt", required = false) Boolean errorOnSmartArt,
|
@RequestParam(name = "errorOnSmartArt", required = false) Boolean errorOnSmartArt,
|
||||||
@RequestParam(name = "errorOnOle", required = false) Boolean errorOnOle) {
|
@RequestParam(name = "errorOnOle", required = false) Boolean errorOnOle,
|
||||||
|
@RequestParam(name = "maxMb", required = false) Long maxMbParam,
|
||||||
|
@RequestParam(name = "maxPages", required = false) Integer maxPagesParam) {
|
||||||
if (file == null || file.isEmpty()) {
|
if (file == null || file.isEmpty()) {
|
||||||
throw new BadRequestException("Файл не передан (multipart-поле «file» обязательно)");
|
throw new BadRequestException("Файл не передан (multipart-поле «file» обязательно)");
|
||||||
}
|
}
|
||||||
@@ -84,13 +88,24 @@ final class ConvertController {
|
|||||||
// .doc (Word 97–2003) переносится в .docx мостом internal.doc
|
// .doc (Word 97–2003) переносится в .docx мостом internal.doc
|
||||||
throw new BadRequestException("Поддерживаются только .docx и .doc: " + name);
|
throw new BadRequestException("Поддерживаются только .docx и .doc: " + name);
|
||||||
}
|
}
|
||||||
|
// Лимиты входа: свойства сервера — дефолт, параметры запроса
|
||||||
|
// переопределяют в обе стороны (верхнего потолка нет — осознанное
|
||||||
|
// решение; остаточная защита от загрузки — multipart-лимит сервера).
|
||||||
|
if (maxMbParam != null && maxMbParam <= 0) {
|
||||||
|
throw new BadRequestException("maxMb должен быть больше 0: " + maxMbParam);
|
||||||
|
}
|
||||||
|
if (maxPagesParam != null && maxPagesParam <= 0) {
|
||||||
|
throw new BadRequestException("maxPages должен быть больше 0: " + maxPagesParam);
|
||||||
|
}
|
||||||
|
long effMaxMb = maxMbParam != null ? maxMbParam : maxMb;
|
||||||
|
int effMaxPages = maxPagesParam != null ? maxPagesParam : maxPages;
|
||||||
// Размер проверяется до getBytes(): multipart-лимит сервера (100 МБ)
|
// Размер проверяется до getBytes(): multipart-лимит сервера (100 МБ)
|
||||||
// больше логического лимита входа (wordpdf.max-mb), и без этого гварда
|
// больше логического лимита входа, и без этого гварда заведомо
|
||||||
// заведомо oversized-upload сначала материализовался бы в куче.
|
// oversized-upload сначала материализовался бы в куче.
|
||||||
// Текст — тот же формат, что WordPdfValidator.checkInput.
|
// Текст — тот же формат, что WordPdfValidator.checkInput.
|
||||||
long maxBytes = maxMb * 1024 * 1024;
|
long maxBytes = effMaxMb * 1024 * 1024;
|
||||||
if (file.getSize() > maxBytes) {
|
if (file.getSize() > maxBytes) {
|
||||||
throw new BadRequestException("Файл больше " + maxMb + " МБ: "
|
throw new BadRequestException("Файл больше " + effMaxMb + " МБ: "
|
||||||
+ file.getSize() + " байт > " + maxBytes + " байт");
|
+ file.getSize() + " байт > " + maxBytes + " байт");
|
||||||
}
|
}
|
||||||
byte[] docxBytes;
|
byte[] docxBytes;
|
||||||
@@ -100,10 +115,10 @@ final class ConvertController {
|
|||||||
throw new BadRequestException("Не удалось прочитать загруженный файл", e);
|
throw new BadRequestException("Не удалось прочитать загруженный файл", e);
|
||||||
}
|
}
|
||||||
ConvertOptions options = new ConvertOptions(
|
ConvertOptions options = new ConvertOptions(
|
||||||
errorOnCharts != null ? errorOnCharts : WordPdfSettings.ERROR_ON_CHARTS,
|
Boolean.TRUE.equals(errorOnCharts),
|
||||||
errorOnSmartArt != null ? errorOnSmartArt : WordPdfSettings.ERROR_ON_SMARTART,
|
Boolean.TRUE.equals(errorOnSmartArt),
|
||||||
errorOnOle != null ? errorOnOle : WordPdfSettings.ERROR_ON_OLE,
|
Boolean.TRUE.equals(errorOnOle),
|
||||||
maxMb, maxPages);
|
effMaxMb, effMaxPages);
|
||||||
byte[] pdf = conversionService.convert(docxBytes, name, options);
|
byte[] pdf = conversionService.convert(docxBytes, name, options);
|
||||||
ContentDisposition disposition = ContentDisposition.attachment()
|
ContentDisposition disposition = ContentDisposition.attachment()
|
||||||
.filename(ConversionService.safeBaseName(name) + ".pdf", StandardCharsets.UTF_8)
|
.filename(ConversionService.safeBaseName(name) + ".pdf", StandardCharsets.UTF_8)
|
||||||
|
|||||||
@@ -1,28 +1,25 @@
|
|||||||
package ru.pjandro.wordpdf.app;
|
package ru.pjandro.wordpdf.app;
|
||||||
|
|
||||||
import ru.pjandro.wordpdf.DrawingFoundException;
|
import ru.pjandro.wordpdf.ChartsFoundException;
|
||||||
|
import ru.pjandro.wordpdf.OleFoundException;
|
||||||
|
import ru.pjandro.wordpdf.SmartArtFoundException;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Документ содержит диаграммы/SmartArt/OLE-объекты при включённом error-флаге
|
* Документ содержит диаграммы/SmartArt/OLE-объекты при включённом error-флаге
|
||||||
* ({@link DrawingFoundException} ядра).
|
* ({@link ChartsFoundException}, {@link SmartArtFoundException} или
|
||||||
|
* {@link OleFoundException} ядра).
|
||||||
*
|
*
|
||||||
* <p>Маппится в HTTP 422 ({@link ApiExceptionHandler}); клиенту осмысленно
|
* <p>Маппится в HTTP 422 ({@link ApiExceptionHandler}); клиенту осмысленно
|
||||||
* повторить без error-флага. Текст сообщения —
|
* повторить без error-флага.</p>
|
||||||
* пользовательский контракт: фронт показывает его дословно.</p>
|
|
||||||
*/
|
*/
|
||||||
class DrawingRejectedException extends RuntimeException {
|
class DrawingRejectedException extends RuntimeException {
|
||||||
|
|
||||||
DrawingRejectedException(DrawingFoundException.Kind kind) {
|
/** Тексты — пользовательский контракт: фронт показывает их дословно. */
|
||||||
super(message(kind));
|
static final String CHARTS = "Конвертация отменена: в документе найдены диаграммы";
|
||||||
}
|
static final String SMART_ART = "Конвертация отменена: в документе найден SmartArt";
|
||||||
|
static final String OLE = "Конвертация отменена: в документе найдены OLE-объекты";
|
||||||
|
|
||||||
// switch вынесен из super(): парсер PMD 7.17 (движок maven-pmd-plugin)
|
DrawingRejectedException(String message) {
|
||||||
// падает на switch-выражении в аргументе super (pmd/pmd#6234).
|
super(message);
|
||||||
private static String message(DrawingFoundException.Kind kind) {
|
|
||||||
return switch (kind) {
|
|
||||||
case CHARTS -> "Конвертация отменена: в документе найдены диаграммы";
|
|
||||||
case SMARTART -> "Конвертация отменена: в документе найден SmartArt";
|
|
||||||
case OLE -> "Конвертация отменена: в документе найдены OLE-объекты";
|
|
||||||
};
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,12 +1,12 @@
|
|||||||
spring.application.name=wordpdf-app
|
spring.application.name=wordpdf-app
|
||||||
# Потолок инфраструктуры — 100 МБ (совпадает с client_max_body_size в
|
# Потолок инфраструктуры — 100 МБ (совпадает с client_max_body_size в
|
||||||
# nginx-шлюзах): больше не пропустит ни шлюз, ни контейнер. Авторитетный
|
# nginx-шлюзах): больше не пропустит ни шлюз, ни контейнер. Логический лимит
|
||||||
# лимит — свойство wordpdf.max-mb (env WORDPDF_MAX_MB, МБ), по умолчанию
|
# входа — свойство wordpdf.max-mb (env WORDPDF_MAX_MB, МБ) /
|
||||||
# WordPdfSettings.MAX_INPUT_MB = 5; здесь только потолок загрузки.
|
# wordpdf.max-pages (env WORDPDF_MAX_PAGES): дефолты 5/100 — литералы @Value
|
||||||
# Лимиты входа: env WORDPDF_MAX_MB (МБ) / WORDPDF_MAX_PAGES (страницы),
|
# в ConvertController (дефолтов лимитов в ядре нет); параметрами запроса
|
||||||
# дефолты — константы ядра (5 / 100), задаются ConvertController.
|
# maxMb/maxPages дефолт переопределяется в обе стороны. Значение свойства
|
||||||
# Значение <= 0 — падение на старте. Сами ключи здесь не объявлены:
|
# <= 0 — падение на старте. Сами ключи здесь не объявлены: пустое значение
|
||||||
# пустое значение затенит SpEL-дефолт @Value.
|
# затенит дефолт @Value.
|
||||||
# file-size-threshold=2MB: части больше 2 МБ сбрасываются на диск Tomcat, heap
|
# file-size-threshold=2MB: части больше 2 МБ сбрасываются на диск Tomcat, heap
|
||||||
# держит только копию getBytes() одной сериализованной конвертации (порог 100MB
|
# держит только копию getBytes() одной сериализованной конвертации (порог 100MB
|
||||||
# буферизовал в heap каждую параллельную загрузку до валидации размера — OOM-килл
|
# буферизовал в heap каждую параллельную загрузку до валидации размера — OOM-килл
|
||||||
|
|||||||
@@ -92,7 +92,7 @@ class ConversionServiceTest {
|
|||||||
|
|
||||||
byte[] sample = bytes("/samples/ru-plain.docx");
|
byte[] sample = bytes("/samples/ru-plain.docx");
|
||||||
ConversionRejectedException e = assertThrows(ConversionRejectedException.class,
|
ConversionRejectedException e = assertThrows(ConversionRejectedException.class,
|
||||||
() -> svc.convert(sample, "queue.docx", ConvertOptions.defaults()));
|
() -> svc.convert(sample, "queue.docx", new ConvertOptions(false, false, false, 5, 100)));
|
||||||
assertEquals("Сервис конвертации занят — повторите позже", e.getMessage());
|
assertEquals("Сервис конвертации занят — повторите позже", e.getMessage());
|
||||||
} finally {
|
} finally {
|
||||||
block.countDown();
|
block.countDown();
|
||||||
@@ -115,7 +115,7 @@ class ConversionServiceTest {
|
|||||||
try {
|
try {
|
||||||
Thread.currentThread().interrupt();
|
Thread.currentThread().interrupt();
|
||||||
ConversionRejectedException e = assertThrows(ConversionRejectedException.class,
|
ConversionRejectedException e = assertThrows(ConversionRejectedException.class,
|
||||||
() -> svc.convert(sample, "ru-plain.docx", ConvertOptions.defaults()));
|
() -> svc.convert(sample, "ru-plain.docx", new ConvertOptions(false, false, false, 5, 100)));
|
||||||
assertEquals("Сервис конвертации занят — повторите позже", e.getMessage());
|
assertEquals("Сервис конвертации занят — повторите позже", e.getMessage());
|
||||||
assertTrue(Thread.currentThread().isInterrupted(),
|
assertTrue(Thread.currentThread().isInterrupted(),
|
||||||
"флаг прерывания обязан быть восстановлен");
|
"флаг прерывания обязан быть восстановлен");
|
||||||
@@ -125,7 +125,7 @@ class ConversionServiceTest {
|
|||||||
// барьер: отменённая задача ещё домучивает рендер на воркере, а
|
// барьер: отменённая задача ещё домучивает рендер на воркере, а
|
||||||
// глобальный реестр шрифтов ядра не потокобезопасен — ждём освобождения
|
// глобальный реестр шрифтов ядра не потокобезопасен — ждём освобождения
|
||||||
// воркера через успешную сериализованную конвертацию
|
// воркера через успешную сериализованную конвертацию
|
||||||
byte[] pdf = svc.convert(sample, "barrier.docx", ConvertOptions.defaults());
|
byte[] pdf = svc.convert(sample, "barrier.docx", new ConvertOptions(false, false, false, 5, 100));
|
||||||
assertEquals("%PDF", new String(pdf, 0, 4, StandardCharsets.US_ASCII));
|
assertEquals("%PDF", new String(pdf, 0, 4, StandardCharsets.US_ASCII));
|
||||||
svc.shutdown();
|
svc.shutdown();
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -30,7 +30,10 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
|
|||||||
*/
|
*/
|
||||||
@SpringBootTest
|
@SpringBootTest
|
||||||
@AutoConfigureMockMvc
|
@AutoConfigureMockMvc
|
||||||
@TestPropertySource(properties = "wordpdf.convert-timeout=1ms")
|
@TestPropertySource(properties = {"wordpdf.convert-timeout=1ms",
|
||||||
|
// пустой ключ = фильтр выключен; пин от ambient WORDPDF_API_KEY
|
||||||
|
// (mise подмешивает корневой .env в окружение тасок)
|
||||||
|
"wordpdf.api-key="})
|
||||||
class ConversionTimeoutTest {
|
class ConversionTimeoutTest {
|
||||||
|
|
||||||
private static final MediaType DOCX =
|
private static final MediaType DOCX =
|
||||||
|
|||||||
@@ -44,7 +44,8 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
|
|||||||
* ядра, PDF разбирается PDFBox, текст нормализуется по пробелам — паттерны
|
* ядра, PDF разбирается PDFBox, текст нормализуется по пробелам — паттерны
|
||||||
* {@code WordPdfConverterTest} (norm/pdfText).
|
* {@code WordPdfConverterTest} (norm/pdfText).
|
||||||
*/
|
*/
|
||||||
@SpringBootTest
|
@SpringBootTest(properties = "wordpdf.api-key=") // пустой = фильтр выключен; пин от
|
||||||
|
// ambient WORDPDF_API_KEY (mise подмешивает корневой .env в окружение тасок)
|
||||||
@AutoConfigureMockMvc
|
@AutoConfigureMockMvc
|
||||||
class ConvertControllerTest {
|
class ConvertControllerTest {
|
||||||
|
|
||||||
@@ -188,7 +189,8 @@ class ConvertControllerTest {
|
|||||||
|
|
||||||
/**
|
/**
|
||||||
* errorOnSmartArt=true — HTTP 422 с текстом про SmartArt (диаграммы
|
* errorOnSmartArt=true — HTTP 422 с текстом про SmartArt (диаграммы
|
||||||
* конвертируются, их error-флаг выключен, поэтому бросается целевой Kind).
|
* конвертируются, их error-флаг выключен, поэтому бросается
|
||||||
|
* {@code SmartArtFoundException}).
|
||||||
* Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsSmartArt,
|
* Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsSmartArt,
|
||||||
* фикстура samples/charts-smartart.docx.
|
* фикстура samples/charts-smartart.docx.
|
||||||
*/
|
*/
|
||||||
@@ -311,8 +313,8 @@ class ConvertControllerTest {
|
|||||||
@Test
|
@Test
|
||||||
void oversizedOverCoreLimit_rejected() throws Exception {
|
void oversizedOverCoreLimit_rejected() throws Exception {
|
||||||
// 5 MiB + 1 байт: проходит контейнерный multipart-лимит (100 МБ)
|
// 5 MiB + 1 байт: проходит контейнерный multipart-лимит (100 МБ)
|
||||||
// и отсекается валидацией ядра до очереди (дефолт ядра цел —
|
// и отсекается валидацией ядра до очереди (дефолт эндпоинта 5 МБ —
|
||||||
// лимит задаёт только конфигурация сервера)
|
// параметры запроса здесь не участвуют)
|
||||||
byte[] big = new byte[5 * 1024 * 1024 + 1];
|
byte[] big = new byte[5 * 1024 * 1024 + 1];
|
||||||
mockMvc.perform(multipart("/api/v1/convert").file(docx("big.docx", big)))
|
mockMvc.perform(multipart("/api/v1/convert").file(docx("big.docx", big)))
|
||||||
.andExpect(status().isBadRequest())
|
.andExpect(status().isBadRequest())
|
||||||
@@ -321,20 +323,60 @@ class ConvertControllerTest {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Регрессия env-only: лимиты входа параметрами запроса не задаются.
|
* Параметр запроса maxMb ужимает серверный дефолт: файл в пределах
|
||||||
* maxMb/maxPages в multipart-форме игнорируются — маленький
|
* серверных 5 МБ отвергается по параметру 1 МБ (текст гварда — с
|
||||||
* документ проходит на серверных лимитах (дефолты ядра).
|
* числом из запроса).
|
||||||
*/
|
*/
|
||||||
@Test
|
@Test
|
||||||
void requestLimitParams_areIgnored() throws Exception {
|
void requestLimit_maxMbTightens_rejected() throws Exception {
|
||||||
|
byte[] twoMb = new byte[2 * 1024 * 1024];
|
||||||
|
mockMvc.perform(multipart("/api/v1/convert")
|
||||||
|
.file(docx("two.docx", twoMb))
|
||||||
|
.param("maxMb", "1"))
|
||||||
|
.andExpect(status().isBadRequest())
|
||||||
|
.andExpect(jsonPath("$.error",
|
||||||
|
org.hamcrest.Matchers.containsString("больше 1 МБ")));
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Параметр maxMb поднимает серверный дефолт: обычный документ проходит. */
|
||||||
|
@Test
|
||||||
|
void requestLimit_maxMbRaises_smallOk() throws Exception {
|
||||||
mockMvc.perform(multipart("/api/v1/convert")
|
mockMvc.perform(multipart("/api/v1/convert")
|
||||||
.file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx")))
|
.file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx")))
|
||||||
.param("maxMb", "1000")
|
.param("maxMb", "1000")
|
||||||
.param("maxPages", "1"))
|
.param("maxPages", "1000"))
|
||||||
.andExpect(status().isOk())
|
.andExpect(status().isOk())
|
||||||
.andExpect(content().contentType(MediaType.APPLICATION_PDF));
|
.andExpect(content().contentType(MediaType.APPLICATION_PDF));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** Параметр maxPages ужимает дефолт: фикстура на 110 границ отвергается с числом из запроса. */
|
||||||
|
@Test
|
||||||
|
void requestLimit_maxPagesTightens_rejected() throws Exception {
|
||||||
|
mockMvc.perform(multipart("/api/v1/convert")
|
||||||
|
.file(docx("stale-cache.docx", bytes("/samples/stale-cache.docx")))
|
||||||
|
.param("maxPages", "1"))
|
||||||
|
.andExpect(status().isBadRequest())
|
||||||
|
.andExpect(jsonPath("$.error",
|
||||||
|
org.hamcrest.Matchers.containsString("длиннее 1 страниц")));
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Нулевые лимиты в запросе — 400 до любой работы с файлом. */
|
||||||
|
@Test
|
||||||
|
void requestLimit_nonPositive_rejected() throws Exception {
|
||||||
|
mockMvc.perform(multipart("/api/v1/convert")
|
||||||
|
.file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx")))
|
||||||
|
.param("maxMb", "0"))
|
||||||
|
.andExpect(status().isBadRequest())
|
||||||
|
.andExpect(jsonPath("$.error",
|
||||||
|
org.hamcrest.Matchers.containsString("maxMb должен быть больше 0")));
|
||||||
|
mockMvc.perform(multipart("/api/v1/convert")
|
||||||
|
.file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx")))
|
||||||
|
.param("maxPages", "0"))
|
||||||
|
.andExpect(status().isBadRequest())
|
||||||
|
.andExpect(jsonPath("$.error",
|
||||||
|
org.hamcrest.Matchers.containsString("maxPages должен быть больше 0")));
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Невалидные лимиты в конфигурации — падение на старте (fail-fast):
|
* Невалидные лимиты в конфигурации — падение на старте (fail-fast):
|
||||||
* «сервис поднят, но весь вход отсекается» хуже не поднявшегося.
|
* «сервис поднят, но весь вход отсекается» хуже не поднявшегося.
|
||||||
@@ -417,8 +459,14 @@ class ConvertControllerTest {
|
|||||||
mockMvc.perform(multipart("/api/v1/convert")
|
mockMvc.perform(multipart("/api/v1/convert")
|
||||||
.file(docx("bad.docx", docxPackageWithGarbage())))
|
.file(docx("bad.docx", docxPackageWithGarbage())))
|
||||||
.andExpect(status().isInternalServerError())
|
.andExpect(status().isInternalServerError())
|
||||||
.andExpect(jsonPath("$.error",
|
// фиксированный текст: сообщение ядра (docx4j/FOP/JAXB) —
|
||||||
org.hamcrest.Matchers.containsString("Не удалось конвертировать")));
|
// только в лог, наружу не уходит
|
||||||
|
.andExpect(jsonPath("$.error").value("Не удалось конвертировать документ"))
|
||||||
|
.andExpect(result -> {
|
||||||
|
String body = result.getResponse().getContentAsString();
|
||||||
|
assertTrue(!body.contains("docx4j") && !body.contains("Exception"),
|
||||||
|
"500 протёк внутренними деталями: " + body);
|
||||||
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
@Test
|
@Test
|
||||||
@@ -474,7 +522,7 @@ class ConvertControllerTest {
|
|||||||
ConvertController controller =
|
ConvertController controller =
|
||||||
new ConvertController(new ConversionService(Duration.ofSeconds(5)), 5L, 100);
|
new ConvertController(new ConversionService(Duration.ofSeconds(5)), 5L, 100);
|
||||||
BadRequestException e = assertThrows(BadRequestException.class,
|
BadRequestException e = assertThrows(BadRequestException.class,
|
||||||
() -> controller.convert(broken, null, null, null));
|
() -> controller.convert(broken, null, null, null, null, null));
|
||||||
assertTrue(e.getMessage().contains("Не удалось прочитать"), e.getMessage());
|
assertTrue(e.getMessage().contains("Не удалось прочитать"), e.getMessage());
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -35,7 +35,10 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
|
|||||||
*/
|
*/
|
||||||
@SpringBootTest
|
@SpringBootTest
|
||||||
@AutoConfigureMockMvc
|
@AutoConfigureMockMvc
|
||||||
@TestPropertySource(properties = {"wordpdf.max-mb=1", "wordpdf.max-pages=1"})
|
@TestPropertySource(properties = {"wordpdf.max-mb=1", "wordpdf.max-pages=1",
|
||||||
|
// пустой ключ = фильтр выключен; пин от ambient WORDPDF_API_KEY
|
||||||
|
// (mise подмешивает корневой .env в окружение тасок)
|
||||||
|
"wordpdf.api-key="})
|
||||||
class ConvertLimitsTest {
|
class ConvertLimitsTest {
|
||||||
|
|
||||||
private static final MediaType DOCX =
|
private static final MediaType DOCX =
|
||||||
@@ -90,4 +93,26 @@ class ConvertLimitsTest {
|
|||||||
.andExpect(jsonPath("$.error",
|
.andExpect(jsonPath("$.error",
|
||||||
org.hamcrest.Matchers.containsString("страниц")));
|
org.hamcrest.Matchers.containsString("страниц")));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Параметры запроса ПОДНИМАЮТ configured-дефолты (свойство — дефолт, не
|
||||||
|
* потолок): maxMb=5 — и файл за 1 MiB проходит байтовый гейт (отказ уже
|
||||||
|
* по контейнеру, не по размеру); maxPages=2 — и текст отказа несёт
|
||||||
|
* двойку, а не configured единицу.
|
||||||
|
*/
|
||||||
|
@Test
|
||||||
|
void restParamAboveConfigured_applies() throws Exception {
|
||||||
|
mockMvc.perform(multipart("/api/v1/convert")
|
||||||
|
.file(docx("big.docx", oversizedZip()))
|
||||||
|
.param("maxMb", "5"))
|
||||||
|
.andExpect(status().isBadRequest())
|
||||||
|
.andExpect(jsonPath("$.error",
|
||||||
|
org.hamcrest.Matchers.containsString("не является .docx")));
|
||||||
|
mockMvc.perform(multipart("/api/v1/convert")
|
||||||
|
.file(docx("too-many-pages.docx", bytes("/samples/too-many-pages.docx")))
|
||||||
|
.param("maxPages", "2"))
|
||||||
|
.andExpect(status().isBadRequest())
|
||||||
|
.andExpect(jsonPath("$.error",
|
||||||
|
org.hamcrest.Matchers.containsString("длиннее 2 страниц")));
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -29,6 +29,24 @@
|
|||||||
<dependency>
|
<dependency>
|
||||||
<groupId>org.docx4j</groupId>
|
<groupId>org.docx4j</groupId>
|
||||||
<artifactId>docx4j-export-fo</artifactId>
|
<artifactId>docx4j-export-fo</artifactId>
|
||||||
|
<!-- JEuclid (MathML-рендер FOP) исключён: формулы OMML больше не
|
||||||
|
доходят до FO — DrawingPreRenderer заменяет каждую math-узел
|
||||||
|
собственным растером (MathModel/MathRenderer) или текстом, а
|
||||||
|
MathFallbackNormalizer (правило 6) срезает unsupported до
|
||||||
|
загрузки. Jeuclid тянул AWT-менеджер шрифтов (fontconfig —
|
||||||
|
падение на без-fontconfig хостах) и системные шрифты в вывод;
|
||||||
|
инвариант «шрифты только бандла» пинит
|
||||||
|
FontsBundledOnlyInvariantTest. -->
|
||||||
|
<exclusions>
|
||||||
|
<exclusion>
|
||||||
|
<groupId>de.rototor.jeuclid</groupId>
|
||||||
|
<artifactId>jeuclid-fop</artifactId>
|
||||||
|
</exclusion>
|
||||||
|
<exclusion>
|
||||||
|
<groupId>de.rototor.jeuclid</groupId>
|
||||||
|
<artifactId>jeuclid-core</artifactId>
|
||||||
|
</exclusion>
|
||||||
|
</exclusions>
|
||||||
</dependency>
|
</dependency>
|
||||||
<!-- Простой логгер в консоль (slf4j). Обязателен: без него docx4j
|
<!-- Простой логгер в консоль (slf4j). Обязателен: без него docx4j
|
||||||
пишет предупреждение прямо в выходной PDF. -->
|
пишет предупреждение прямо в выходной PDF. -->
|
||||||
@@ -125,6 +143,15 @@
|
|||||||
</execution>
|
</execution>
|
||||||
</executions>
|
</executions>
|
||||||
</plugin>
|
</plugin>
|
||||||
|
<!-- Javadoc публичного API модуля (цель javadoc:javadoc, задача mise
|
||||||
|
docs-javadoc; результат target/site/apidocs попадает на сайт
|
||||||
|
документации). Без executions: в лайфцикл не вмешивается.
|
||||||
|
wordpdf-app javadoc не генерирует — единственного public-класса
|
||||||
|
WordPdfApplication недостаточно для раздела документации. -->
|
||||||
|
<plugin>
|
||||||
|
<groupId>org.apache.maven.plugins</groupId>
|
||||||
|
<artifactId>maven-javadoc-plugin</artifactId>
|
||||||
|
</plugin>
|
||||||
</plugins>
|
</plugins>
|
||||||
</build>
|
</build>
|
||||||
</project>
|
</project>
|
||||||
|
|||||||
@@ -0,0 +1,16 @@
|
|||||||
|
package ru.pjandro.wordpdf;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* В документе найдены диаграммы, а их обработка запрещена включённым
|
||||||
|
* {@link ConvertOptions#errorOnCharts()}. Исключение отвергает документ целиком.
|
||||||
|
*
|
||||||
|
* <p>Наследник {@link ConversionException} — наружу по-прежнему ловится и он.
|
||||||
|
* Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsCharts,
|
||||||
|
* фикстура samples/charts-smartart.docx.</p>
|
||||||
|
*/
|
||||||
|
public final class ChartsFoundException extends ConversionException {
|
||||||
|
|
||||||
|
public ChartsFoundException() {
|
||||||
|
super("В документе найдены диаграммы, а их обработка запрещена (errorOnCharts)");
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -2,25 +2,18 @@ package ru.pjandro.wordpdf;
|
|||||||
|
|
||||||
/**
|
/**
|
||||||
* на один вызов: error-флаги рисунков и лимиты входа (размер/страницы).
|
* на один вызов: error-флаги рисунков и лимиты входа (размер/страницы).
|
||||||
* Дефолты — константы {@link WordPdfSettings}; вызывающий (например, REST API)
|
* Дефолтов в ядре нет — значения задаёт вызывающий (приложение: свойства
|
||||||
* может переопределить их на конкретный вызов. Диаграммы/SmartArt
|
* сервера как дефолт REST-эндпоинта + параметры запроса). Диаграммы/SmartArt
|
||||||
* конвертируются всегда.
|
* конвертируются всегда.
|
||||||
*
|
*
|
||||||
* @param errorOnCharts бросать {@link DrawingFoundException} при находке диаграмм
|
* @param errorOnCharts бросать {@link ChartsFoundException} при находке диаграмм
|
||||||
* @param errorOnSmartArt бросать {@link DrawingFoundException} при находке SmartArt
|
* @param errorOnSmartArt бросать {@link SmartArtFoundException} при находке SmartArt
|
||||||
* @param errorOnOle бросать {@link DrawingFoundException} при находке OLE-объектов
|
* @param errorOnOle бросать {@link OleFoundException} при находке OLE-объектов
|
||||||
* (иначе — тихо удалить их из документа)
|
* (иначе — тихо удалить их из документа)
|
||||||
* @param maxMb лимит размера входа в МБ (MiB) на этот вызов;
|
* @param maxMb лимит размера входа в МБ (MiB) на этот вызов;
|
||||||
* дефолт — {@link WordPdfSettings#MAX_INPUT_MB}
|
* должен быть больше 0
|
||||||
* @param maxPages лимит числа страниц на этот вызов;
|
* @param maxPages лимит числа страниц на этот вызов; должен быть больше 0
|
||||||
* дефолт — {@link WordPdfSettings#MAX_PAGES}
|
|
||||||
*/
|
*/
|
||||||
public record ConvertOptions(boolean errorOnCharts, boolean errorOnSmartArt, boolean errorOnOle,
|
public record ConvertOptions(boolean errorOnCharts, boolean errorOnSmartArt, boolean errorOnOle,
|
||||||
long maxMb, int maxPages) {
|
long maxMb, int maxPages) {
|
||||||
|
|
||||||
/** Дефолты ядра из {@link WordPdfSettings}. */
|
|
||||||
public static ConvertOptions defaults() {
|
|
||||||
return new ConvertOptions(WordPdfSettings.ERROR_ON_CHARTS, WordPdfSettings.ERROR_ON_SMARTART,
|
|
||||||
WordPdfSettings.ERROR_ON_OLE, WordPdfSettings.MAX_INPUT_MB, WordPdfSettings.MAX_PAGES);
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,45 +0,0 @@
|
|||||||
package ru.pjandro.wordpdf;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Документ содержит объект, находку которого вызывающий запретил:
|
|
||||||
* соответствующий error-флаг включён
|
|
||||||
* ({@link ConvertOptions#errorOnCharts()}, {@link ConvertOptions#errorOnSmartArt()},
|
|
||||||
* {@link ConvertOptions#errorOnOle()}).
|
|
||||||
* Диаграммы/SmartArt конвертируются всегда; OLE-объекты при выключенном
|
|
||||||
* {@code errorOnOle} теряют свои данные, но сохраняют картинку-плейсхолдер
|
|
||||||
* (в отличие от них).
|
|
||||||
* Исключение отвергает документ целиком.
|
|
||||||
*
|
|
||||||
* <p>Наследник {@link ConversionException} — наружу по-прежнему ловится
|
|
||||||
* только он; {@code kind()} даёт вызывающему тип объекта без разбора текста.
|
|
||||||
* Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsCharts,
|
|
||||||
* фикстура samples/charts-smartart.docx; OLE —
|
|
||||||
* WordPdfConverterTest#drawingErrors_errorFlagRejectsOle,
|
|
||||||
* фикстура samples/ole-embedded.docx.</p>
|
|
||||||
*/
|
|
||||||
public class DrawingFoundException extends ConversionException {
|
|
||||||
|
|
||||||
/** Тип найденного объекта. */
|
|
||||||
public enum Kind { CHARTS, SMARTART, OLE }
|
|
||||||
|
|
||||||
private final Kind kind;
|
|
||||||
|
|
||||||
public DrawingFoundException(Kind kind) {
|
|
||||||
super(message(kind));
|
|
||||||
this.kind = kind;
|
|
||||||
}
|
|
||||||
|
|
||||||
// switch вынесен из super(): парсер PMD 7.17 (движок maven-pmd-plugin)
|
|
||||||
// падает на switch-выражении в аргументе super (pmd/pmd#6234).
|
|
||||||
private static String message(Kind kind) {
|
|
||||||
return switch (kind) {
|
|
||||||
case CHARTS -> "В документе найдены диаграммы, а их обработка запрещена (errorOnCharts)";
|
|
||||||
case SMARTART -> "В документе найден SmartArt, а его обработка запрещена (errorOnSmartArt)";
|
|
||||||
case OLE -> "В документе найдены OLE-объекты, а их обработка запрещена (errorOnOle)";
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
public Kind kind() {
|
|
||||||
return kind;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@@ -0,0 +1,22 @@
|
|||||||
|
package ru.pjandro.wordpdf;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* В документе найдены OLE-объекты, а их обработка запрещена включённым
|
||||||
|
* {@link ConvertOptions#errorOnOle()}. Исключение отвергает документ целиком.
|
||||||
|
*
|
||||||
|
* <p>При выключенном флаге OLE-объекты теряют свои данные, но сохраняют
|
||||||
|
* картинку-плейсхолдер (в отличие от диаграмм/SmartArt, конвертируемых
|
||||||
|
* всегда). Флаг действует только на {@code .docx}: в бинарном {@code .doc}
|
||||||
|
* вложения OLE — форматирование U+0001, мост деградирует их до картинки,
|
||||||
|
* поэтому находки OLE там не бывает.</p>
|
||||||
|
*
|
||||||
|
* <p>Наследник {@link ConversionException} — наружу по-прежнему ловится и он.
|
||||||
|
* Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsOle,
|
||||||
|
* фикстура samples/ole-embedded.docx; OleObjectNormalizerTest#errorOnOleThrowsOleFound.</p>
|
||||||
|
*/
|
||||||
|
public final class OleFoundException extends ConversionException {
|
||||||
|
|
||||||
|
public OleFoundException() {
|
||||||
|
super("В документе найдены OLE-объекты, а их обработка запрещена (errorOnOle)");
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,16 @@
|
|||||||
|
package ru.pjandro.wordpdf;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* В документе найден SmartArt, а его обработка запрещена включённым
|
||||||
|
* {@link ConvertOptions#errorOnSmartArt()}. Исключение отвергает документ целиком.
|
||||||
|
*
|
||||||
|
* <p>Наследник {@link ConversionException} — наружу по-прежнему ловится и он.
|
||||||
|
* Регрессия — WordPdfConverterTest#drawingErrors_errorFlagRejectsSmartArt,
|
||||||
|
* фикстура samples/charts-smartart.docx.</p>
|
||||||
|
*/
|
||||||
|
public final class SmartArtFoundException extends ConversionException {
|
||||||
|
|
||||||
|
public SmartArtFoundException() {
|
||||||
|
super("В документе найден SmartArt, а его обработка запрещена (errorOnSmartArt)");
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -2,7 +2,8 @@ package ru.pjandro.wordpdf;
|
|||||||
|
|
||||||
import org.apache.fop.apps.FOUserAgent;
|
import org.apache.fop.apps.FOUserAgent;
|
||||||
import org.apache.fop.apps.FopFactory;
|
import org.apache.fop.apps.FopFactory;
|
||||||
import org.apache.fop.apps.FopFactoryBuilder;
|
import org.apache.fop.util.ImageObjectCache;
|
||||||
|
import org.apache.fop.util.ImageObjectCacheImpl;
|
||||||
import org.docx4j.Docx4J;
|
import org.docx4j.Docx4J;
|
||||||
import org.docx4j.XmlUtils;
|
import org.docx4j.XmlUtils;
|
||||||
import org.docx4j.Docx4jProperties;
|
import org.docx4j.Docx4jProperties;
|
||||||
@@ -30,6 +31,7 @@ import java.io.ByteArrayInputStream;
|
|||||||
import java.io.ByteArrayOutputStream;
|
import java.io.ByteArrayOutputStream;
|
||||||
import java.io.IOException;
|
import java.io.IOException;
|
||||||
import javax.xml.transform.Templates;
|
import javax.xml.transform.Templates;
|
||||||
|
import javax.xml.transform.TransformerConfigurationException;
|
||||||
import javax.xml.transform.stream.StreamSource;
|
import javax.xml.transform.stream.StreamSource;
|
||||||
import javax.imageio.ImageIO;
|
import javax.imageio.ImageIO;
|
||||||
import java.io.InputStream;
|
import java.io.InputStream;
|
||||||
@@ -54,9 +56,13 @@ import java.util.zip.ZipOutputStream;
|
|||||||
* подменяются метрически совместимыми open-source аналогами
|
* подменяются метрически совместимыми open-source аналогами
|
||||||
* (см. {@link BundledFontMapper}).
|
* (см. {@link BundledFontMapper}).
|
||||||
*
|
*
|
||||||
* Класс stateless, все методы статические. Класс НЕ потокобезопасен:
|
* Класс stateless, все методы статические. Публичные {@code convert()} можно
|
||||||
* конвертации из нескольких потоков необходимо сериализовать (глобальный
|
* вызывать из нескольких потоков: сериализация обеспечена внутри ядра —
|
||||||
* реестр {@code PhysicalFonts}, кэши шрифтов/покрытия).
|
* конвертации выполняются по одной под монитором класса (глобальный реестр
|
||||||
|
* {@code PhysicalFonts}, общая FopFactory с имиджевыми кешами, сброс кеши в
|
||||||
|
* finally). {@link #warmup()} синхронизирован тем же монитором.
|
||||||
|
* {@link WordPdfValidator} stateless и выполняется до монитора — валидация
|
||||||
|
* параллельна и не блокируется.
|
||||||
*/
|
*/
|
||||||
public final class WordPdfConverter {
|
public final class WordPdfConverter {
|
||||||
|
|
||||||
@@ -83,38 +89,66 @@ public final class WordPdfConverter {
|
|||||||
private WordPdfConverter() {
|
private WordPdfConverter() {
|
||||||
}
|
}
|
||||||
|
|
||||||
|
private static volatile FopFactory sharedFopFactory;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Конвертирует байты .docx (или бинарного .doc Word 97–2003 — формат
|
* FopFactory, общая на JVM: разбор шрифтов форка (GPOS-таблицы, ~140k
|
||||||
* определяется по сигнатуре байтов) в PDF. Работа с файлами — забота
|
* объектов) выполняется один раз, а не на каждую конвертацию. Фабрика
|
||||||
* вызывающего (файловое API было здесь раньше; ядро пути не принимает).
|
* хранит имиджевые кеши ({@code ImageManager#getCache()} и
|
||||||
*
|
* {@link ImageObjectCacheImpl}) c ключами {@code file:/tmp/<uuid>…} —
|
||||||
* <p>.doc предварительно переносится в .docx мостом
|
* уникальными на каждую конвертацию (docx4j выкладывает медиа во временные
|
||||||
* {@link ru.pjandro.wordpdf.internal.doc.DocToDocx} (текст + прямое
|
* файлы), поэтому кеш никогда не попадает и растёт на декодированный растр
|
||||||
* форматирование); число страниц для .doc проверяется мостом по чистому
|
* каждого изображения (замер 2026-11: ~1,5 ГБ живых byte[] после 30
|
||||||
* бинарному документу (кэш PageCount + явные разрывы), сгенерированный
|
* конвертаций с картинками). Поэтому каждая конвертация обязана вызвать
|
||||||
* .docx валидацией не проверяется. Для .docx вход проверяется
|
* {@link #resetSharedImageCaches()} в finally. Вызывается только под локом
|
||||||
* {@link WordPdfValidator#validate(byte[], ConvertOptions)} до рендера:
|
* конвертации (см. {@code convert}), сброс mid-render невозможен. Методы
|
||||||
* {@code null} / размер больше {@link WordPdfSettings#MAX_INPUT_MB} (МБ) / zip-подпись /
|
* приватны: вызов вне лока конвертера вскрыл бы DCL/сброс на параллельный
|
||||||
* число страниц больше {@link WordPdfSettings#MAX_PAGES} — при отказе байтов результата нет;
|
* рендер. Регрессия — WordPdfConverterTest#sharedImageCaches_clearedAfterConversion.
|
||||||
* страницы считаются ровно раз по сырому входу, повторного скана по
|
|
||||||
* нормализованным байтам нет (см. javadoc перегрузки с {@link ConvertOptions}).
|
|
||||||
*
|
|
||||||
* @param docxBytes байты .docx или бинарного .doc
|
|
||||||
* @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся
|
|
||||||
* @return байты готового PDF
|
|
||||||
* @throws ValidationException некорректный вход: {@code null}, размер больше
|
|
||||||
* {@link WordPdfSettings#MAX_INPUT_MB} (МБ), не .docx/.doc, зашифрованный .doc,
|
|
||||||
* документ длиннее {@link WordPdfSettings#MAX_PAGES} страниц
|
|
||||||
* @throws ConversionException прочие ошибки (битый .docx, ошибка рендера)
|
|
||||||
*/
|
*/
|
||||||
public static byte[] convert(byte[] docxBytes, String title) throws ConversionException {
|
private static FopFactory sharedFopFactory(final FOSettings foSettings) {
|
||||||
return convert(docxBytes, title, ConvertOptions.defaults());
|
FopFactory factory = sharedFopFactory;
|
||||||
|
if (factory == null) {
|
||||||
|
synchronized (WordPdfConverter.class) {
|
||||||
|
if (sharedFopFactory == null) {
|
||||||
|
try {
|
||||||
|
sharedFopFactory = FORendererApacheFOP.getFopFactoryBuilder(foSettings).build();
|
||||||
|
} catch (org.apache.fop.apps.FOPException e) {
|
||||||
|
throw new ConversionException("Не удалось собрать FOP-фабрику", e);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
factory = sharedFopFactory;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return factory;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Сброс имиджевых кешей общей фабрики после конвертации. Без него форк
|
||||||
|
* удерживает растр каждого изображения документа до конца жизни JVM:
|
||||||
|
* записи лежат в soft-ссылках, которые сборщик не трогает, пока свободная
|
||||||
|
* куча велика (куча стенда фиксирована 2 ГБ). Сбросы публичные:
|
||||||
|
* {@code ImageCache.clearCache()} и {@code ImageObjectCacheImpl.clearCache()}.
|
||||||
|
* Вызывается исключительно из finally конвертации под локом (см.
|
||||||
|
* {@code convert}) — параллельный рендер под сброс не попадает.
|
||||||
|
* Регрессия — WordPdfConverterTest#sharedImageCaches_clearedAfterConversion.
|
||||||
|
*/
|
||||||
|
private static void resetSharedImageCaches() {
|
||||||
|
FopFactory factory = sharedFopFactory;
|
||||||
|
if (factory == null) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
factory.getImageManager().getCache().clearCache();
|
||||||
|
ImageObjectCache imageObjects = factory.getImageObjectCache();
|
||||||
|
if (imageObjects instanceof ImageObjectCacheImpl impl) {
|
||||||
|
impl.clearCache();
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Конвертирует байты .docx (или бинарного .doc Word 97–2003 — формат
|
* Конвертирует байты .docx (или бинарного .doc Word 97–2003 — формат
|
||||||
* определяется по сигнатуре байтов, см. перегрузку выше) в PDF с
|
* определяется по сигнатуре байтов) в PDF с настройками на вызов:
|
||||||
* настройками на вызов: error-флаги диаграмм/SmartArt и лимиты входа.
|
* error-флаги диаграмм/SmartArt и лимиты входа. Работа с файлами — забота
|
||||||
|
* вызывающего (файловое API было здесь раньше; ядро пути не принимает).
|
||||||
*
|
*
|
||||||
* <p>Вход проверяется {@link WordPdfValidator#validate(byte[], ConvertOptions)}
|
* <p>Вход проверяется {@link WordPdfValidator#validate(byte[], ConvertOptions)}
|
||||||
* до рендера — одна проверка на оба формата: {@code null} / размер больше
|
* до рендера — одна проверка на оба формата: {@code null} / размер больше
|
||||||
@@ -123,15 +157,15 @@ public final class WordPdfConverter {
|
|||||||
* считаются ровно раз по сырому входу, до аллокаций docx4j: для .docx —
|
* считаются ровно раз по сырому входу, до аллокаций docx4j: для .docx —
|
||||||
* lightweight-скан по zip, для .doc — по чистому бинарному документу до
|
* lightweight-скан по zip, для .doc — по чистому бинарному документу до
|
||||||
* конвертации. Повторного скана по нормализованным байтам нет: правила
|
* конвертации. Повторного скана по нормализованным байтам нет: правила
|
||||||
* 1–10 {@code DocxRewritePipeline} число учитываемых разрывов не
|
* 1–11 {@code DocxRewritePipeline} число учитываемых разрывов не
|
||||||
* увеличивают (правило 9 способно только убрать разрыв внутри скрытого
|
* увеличивают (правило 9 способно только убрать разрыв внутри скрытого
|
||||||
* рана — счёт по сырому входу остаётся верхней оценкой лимита), а скан
|
* рана — счёт по сырому входу остаётся верхней оценкой лимита), а скан
|
||||||
* внутри живой JAXB-модели удваивал бы пиковую память.
|
* внутри живой JAXB-модели удваивал бы пиковую память.
|
||||||
*
|
*
|
||||||
* @param docxBytes байты .docx или бинарного .doc
|
* @param docxBytes байты .docx или бинарного .doc
|
||||||
* @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся
|
* @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся
|
||||||
* @param options error-флаги и лимиты входа на этот вызов; {@code null} —
|
* @param options error-флаги и лимиты входа на этот вызов; обязательны,
|
||||||
* дефолты (константы {@link WordPdfSettings})
|
* {@code null} → {@link ValidationException} (дефолтов в ядре нет)
|
||||||
* @return байты готового PDF
|
* @return байты готового PDF
|
||||||
* @throws ValidationException некорректный вход: {@code null}, размер больше
|
* @throws ValidationException некорректный вход: {@code null}, размер больше
|
||||||
* {@code options.maxMb()} (МБ), не .docx/.doc, зашифрованный .doc,
|
* {@code options.maxMb()} (МБ), не .docx/.doc, зашифрованный .doc,
|
||||||
@@ -139,7 +173,11 @@ public final class WordPdfConverter {
|
|||||||
* @throws ConversionException прочие ошибки (битый .docx, ошибка рендера)
|
* @throws ConversionException прочие ошибки (битый .docx, ошибка рендера)
|
||||||
*/
|
*/
|
||||||
public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options) throws ConversionException {
|
public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options) throws ConversionException {
|
||||||
ConvertOptions opts = options == null ? ConvertOptions.defaults() : options;
|
if (options == null) {
|
||||||
|
throw new ValidationException("Не переданы параметры конвертации (ConvertOptions): "
|
||||||
|
+ "лимиты входа задаёт вызывающий");
|
||||||
|
}
|
||||||
|
ConvertOptions opts = options;
|
||||||
// Полная проверка входа — одна на оба формата: размер до
|
// Полная проверка входа — одна на оба формата: размер до
|
||||||
// классификации (враждебный вход без подписи обязан получить ошибку
|
// классификации (враждебный вход без подписи обязан получить ошибку
|
||||||
// лимита), затем для .docx — zip/контейнер/страницы, для .doc —
|
// лимита), затем для .docx — zip/контейнер/страницы, для .doc —
|
||||||
@@ -152,18 +190,27 @@ public final class WordPdfConverter {
|
|||||||
// .doc сбрасываются в кадре на этом же месте — детерминированно, до
|
// .doc сбрасываются в кадре на этом же месте — детерминированно, до
|
||||||
// рендера (точные liveness-карты HotSpot строит только для
|
// рендера (точные liveness-карты HotSpot строит только для
|
||||||
// скомпилированных кадров; отдельное присваивание null не нужно).
|
// скомпилированных кадров; отдельное присваивание null не нужно).
|
||||||
docxBytes = WordPdfValidator.isBinaryDoc(docxBytes) ? DocToDocx.convert(docxBytes) : docxBytes;
|
// Единый лок ядра: реестр PhysicalFonts, общая FopFactory (per-render
|
||||||
ByteArrayOutputStream bos = new ByteArrayOutputStream(Math.max(1 << 16, docxBytes.length));
|
// disableFontCache, имиджевые кеши) и её сброс в finally мутируются под
|
||||||
try {
|
// рендером — параллельная конвертация обязана ждать, иначе чистит кеши
|
||||||
convertToStream(docxBytes, title, opts, bos);
|
// посреди чужого рендера. Монитор класса тот же, что у warmup()
|
||||||
} catch (ConversionException e) {
|
// (реентельно) и DCL в sharedFopFactory. Регрессия —
|
||||||
// ValidationException (отказ валидации входа) — подтип, уходит
|
// WordPdfConverterTest#concurrentConversions_twoThreadsBothSucceed.
|
||||||
// вызывающему без обёртки
|
synchronized (WordPdfConverter.class) {
|
||||||
throw e;
|
docxBytes = WordPdfValidator.isBinaryDoc(docxBytes)
|
||||||
} catch (Exception e) {
|
? DocToDocx.convert(docxBytes, opts.maxMb()) : docxBytes;
|
||||||
throw new ConversionException("Не удалось конвертировать документ", e);
|
ByteArrayOutputStream bos = new ByteArrayOutputStream(Math.max(1 << 16, docxBytes.length));
|
||||||
|
try {
|
||||||
|
convertToStream(docxBytes, title, opts, bos);
|
||||||
|
} catch (ConversionException e) {
|
||||||
|
// ValidationException (отказ валидации входа) — подтип, уходит
|
||||||
|
// вызывающему без обёртки
|
||||||
|
throw e;
|
||||||
|
} catch (Exception e) {
|
||||||
|
throw new ConversionException("Не удалось конвертировать документ", e);
|
||||||
|
}
|
||||||
|
return bos.toByteArray();
|
||||||
}
|
}
|
||||||
return bos.toByteArray();
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Флаг «ядро прогрето»: повторные вызовы {@link #warmup()} — no-op. */
|
/** Флаг «ядро прогрето»: повторные вызовы {@link #warmup()} — no-op. */
|
||||||
@@ -171,14 +218,42 @@ public final class WordPdfConverter {
|
|||||||
|
|
||||||
private static final Logger LOG = Logger.getLogger(WordPdfConverter.class.getName());
|
private static final Logger LOG = Logger.getLogger(WordPdfConverter.class.getName());
|
||||||
|
|
||||||
|
// Пороги защиты входа (считает WordPdfValidator.max* от лимитов входа
|
||||||
|
// ConvertOptions). Значения — строго литералы compile-time констант: javac
|
||||||
|
// инлайнит их в WordPdfValidator, и обращение из валидатора НЕ
|
||||||
|
// инициализирует этот класс (его static-блок выставляет sysprops docx4j —
|
||||||
|
// инвариант «WordPdfValidator не зависит от docx4j» сохраняется).
|
||||||
|
/** Бюджет суммарной распаковки: MiB на каждый МБ лимита размера входа. */
|
||||||
|
static final int DECOMPRESS_MB_PER_MAX_MB = 10;
|
||||||
|
/** Бюджет суммарной распаковки: KiB на каждую страницу лимита. */
|
||||||
|
static final int DECOMPRESS_KIB_PER_PAGE = 64;
|
||||||
|
/** Бюджет XML-частей: MiB на каждый МБ лимита (JAXB-разбор дороже байта). */
|
||||||
|
static final int DECOMPRESS_XML_MB_PER_MAX_MB = 4;
|
||||||
|
/** Бюджет XML-частей: KiB на каждую страницу лимита. */
|
||||||
|
static final int DECOMPRESS_XML_KIB_PER_PAGE = 32;
|
||||||
|
/** Пол бюджета суммарной распаковки (MiB) — чтобы мелкие лимиты не ломали легитимные документы. */
|
||||||
|
static final long MIN_DECOMPRESSED_MB = 16;
|
||||||
|
/** Пол бюджета XML-частей (MiB). */
|
||||||
|
static final long MIN_DECOMPRESSED_XML_MB = 4;
|
||||||
|
/** Порог пиксельной площади одного растра: пикселей на каждый МБ лимита размера. */
|
||||||
|
static final long IMAGE_PIXELS_PER_MAX_MB = 5_000_000;
|
||||||
|
/** Порог числа zip-записей: записей на каждый МБ лимита размера. */
|
||||||
|
static final int ZIP_ENTRIES_PER_MAX_MB = 512;
|
||||||
|
/** Порог числа zip-записей: записей на каждую страницу лимита. */
|
||||||
|
static final int ZIP_ENTRIES_PER_PAGE = 32;
|
||||||
|
/** Пол порога числа zip-записей. */
|
||||||
|
static final int MIN_ZIP_ENTRIES = 2048;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Прогрев ядра: первая конвертация после старта JVM стоит 1,3–1,7 с
|
* Прогрев ядра: первая конвертация после старта JVM стоит 1,3–1,7 с
|
||||||
* (JAXB/XSLT/FOP/классы), её платил первый запрос после деплоя. Прогоняет
|
* (JAXB/XSLT/FOP/классы), её платил первый запрос после деплоя. Прогоняет
|
||||||
* пайплайн на минимальном docx, собранном в байтах (фикстуры тестов не
|
* пайплайн на минимальном docx, собранном в байтах (фикстуры тестов не
|
||||||
* задействуются), и греет Java2D/PNG-энкодер для пре-рендера диаграмм.
|
* задействуются), и греет Java2D/PNG-энкодер для пре-рендера диаграмм.
|
||||||
* Идемпотентен, никогда не бросает (провал — только warn); вызывать нужно
|
* Идемпотентен, никогда не бросает (провал — только warn); метод
|
||||||
* на том же потоке, на котором сериализованы конвертации (ядро не
|
* синхронизирован монитором класса — тем же, что сериализует конвертации
|
||||||
* потокобезопасно, см. {@code PhysicalFonts}). Артефакты (PDF, растр)
|
* в {@code convert()}, так что прогрев гарантированно не пересекается с
|
||||||
|
* рендером; приложение дополнительно держит warmup головой очереди.
|
||||||
|
* Артефакты (PDF, растр)
|
||||||
* отбрасываются. Ядро само {@code warmup()} не вызывает — момент прогрева
|
* отбрасываются. Ядро само {@code warmup()} не вызывает — момент прогрева
|
||||||
* решает вызывающее приложение.
|
* решает вызывающее приложение.
|
||||||
*/
|
*/
|
||||||
@@ -187,7 +262,7 @@ public final class WordPdfConverter {
|
|||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
try {
|
try {
|
||||||
convert(warmupDocx(), "warmup");
|
convert(warmupDocx(), "warmup", new ConvertOptions(false, false, false, 1, 1));
|
||||||
warmRaster();
|
warmRaster();
|
||||||
warmedUp = true;
|
warmedUp = true;
|
||||||
} catch (Throwable t) {
|
} catch (Throwable t) {
|
||||||
@@ -326,13 +401,15 @@ public final class WordPdfConverter {
|
|||||||
LayoutPostRenderer.register(foSettings);
|
LayoutPostRenderer.register(foSettings);
|
||||||
|
|
||||||
// 4.5 Вендорный xslt/docx2fo.xslt = копия из docx4j-export-fo +
|
// 4.5 Вендорный xslt/docx2fo.xslt = копия из docx4j-export-fo +
|
||||||
// AUDIT-FIX-патч (w:rPr position) — стилист jar'а не
|
// AUDIT-FIX-патчи (w:rPr/w:position→baseline-shift;
|
||||||
|
// AUDIT-FIX-2: moveFrom/moveTo/bdo/dir) — стилист jar'а не
|
||||||
// используется.
|
// используется.
|
||||||
foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES);
|
foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES);
|
||||||
|
|
||||||
// 5. Метаданные PDF: заголовок — из параметра title
|
// 5. Метаданные PDF: заголовок — из параметра title. Фабрика —
|
||||||
FopFactoryBuilder builder = FORendererApacheFOP.getFopFactoryBuilder(foSettings);
|
// общая на JVM (см. sharedFopFactory); после конвертации её
|
||||||
FopFactory fopFactory = builder.build();
|
// имиджевые кеши обязаны быть сброшены (шаг 7).
|
||||||
|
FopFactory fopFactory = sharedFopFactory(foSettings);
|
||||||
FOUserAgent foUserAgent = FORendererApacheFOP.getFOUserAgent(foSettings, fopFactory);
|
FOUserAgent foUserAgent = FORendererApacheFOP.getFOUserAgent(foSettings, fopFactory);
|
||||||
if (title != null && !title.isEmpty()) {
|
if (title != null && !title.isEmpty()) {
|
||||||
foUserAgent.setTitle(title);
|
foUserAgent.setTitle(title);
|
||||||
@@ -341,18 +418,26 @@ public final class WordPdfConverter {
|
|||||||
// 6. Проход XSLT (медленнее, но полнее), вывод в поток
|
// 6. Проход XSLT (медленнее, но полнее), вывод в поток
|
||||||
Docx4J.toFO(foSettings, os, Docx4J.FLAG_EXPORT_PREFER_XSL);
|
Docx4J.toFO(foSettings, os, Docx4J.FLAG_EXPORT_PREFER_XSL);
|
||||||
} finally {
|
} finally {
|
||||||
// 7. Уборка временных файлов встроенных в docx шрифтов
|
// 7. Уборка временных файлов встроенных в docx шрифтов, сброс
|
||||||
|
// имиджевых кешей общей FopFactory (без него форк копит растр
|
||||||
|
// каждого изображения: ~1,5 ГБ на 30 конвертаций, 2026-11) и
|
||||||
|
// возврат реестра шрифтов в бандл-состояние: load() регистрирует
|
||||||
|
// в глобальном PhysicalFonts встроенные шрифты документа, и без
|
||||||
|
// restrictToBundled последний документ продолжал бы влиять на
|
||||||
|
// выбор шрифта до следующей конвертации.
|
||||||
if (pkg.getMainDocumentPart() != null
|
if (pkg.getMainDocumentPart() != null
|
||||||
&& pkg.getMainDocumentPart().getFontTablePart() != null) {
|
&& pkg.getMainDocumentPart().getFontTablePart() != null) {
|
||||||
pkg.getMainDocumentPart().getFontTablePart().deleteEmbeddedFontTempFiles();
|
pkg.getMainDocumentPart().getFontTablePart().deleteEmbeddedFontTempFiles();
|
||||||
}
|
}
|
||||||
// Примечание: в docx4j 11.x OpcPackage.close() отсутствует —
|
resetSharedImageCaches();
|
||||||
|
BundledFonts.restrictToBundled();
|
||||||
|
// Примечание: в docx4j 17.x OpcPackage.close() отсутствует —
|
||||||
// пакет загружается в память и ничего не закрывает.
|
// пакет загружается в память и ничего не закрывает.
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Нормализация входных байтов (цепочка {@link #normalizers}: правила 1–10
|
* Нормализация входных байтов (цепочка {@link #normalizers}: правила 1–11
|
||||||
* одним zip-проходом {@code DocxRewritePipeline} + условная OLE-вычистка)
|
* одним zip-проходом {@code DocxRewritePipeline} + условная OLE-вычистка)
|
||||||
* и {@code WordprocessingMLPackage.load} полученного transitional-байта.
|
* и {@code WordprocessingMLPackage.load} полученного transitional-байта.
|
||||||
* Нормализация переиспользует слот {@code bytes}: каждая замена массива
|
* Нормализация переиспользует слот {@code bytes}: каждая замена массива
|
||||||
@@ -371,10 +456,11 @@ public final class WordPdfConverter {
|
|||||||
* Конвейер байтовой нормализации docx. Порядок фиксирован: сначала один
|
* Конвейер байтовой нормализации docx. Порядок фиксирован: сначала один
|
||||||
* zip-проход переписывания XML-частей (внутри части порядок рерайтов
|
* zip-проход переписывания XML-частей (внутри части порядок рерайтов
|
||||||
* Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→
|
* Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→
|
||||||
* NumberingSuffix→Hidden→Ruby значим: Strict первым — дальше transitional-байт;
|
* NumberingSuffix→Hidden→Ruby→MathFallback значим: Strict первым — дальше transitional-байт;
|
||||||
* GlyphCoverage — по финальному тексту рана; Hidden — вырезает скрытые
|
* GlyphCoverage — по финальному тексту рана; Hidden — вырезает скрытые
|
||||||
* раны по финальному содержимому; Ruby — разворачивает руби-разметку,
|
* раны по финальному содержимому; Ruby — разворачивает руби-разметку,
|
||||||
* которую схема docx4j не биндит), затем OleObjectNormalizer
|
* которую схема docx4j не биндит; MathFallback — деградирует OMML-формулы
|
||||||
|
* в текст m:t, когда JEuclid недоступен), затем OleObjectNormalizer
|
||||||
* (меняет части, а не XML ранов).
|
* (меняет части, а не XML ранов).
|
||||||
* Регрессии каждого рерайта — в javadoc соответствующего нормализатора.
|
* Регрессии каждого рерайта — в javadoc соответствующего нормализатора.
|
||||||
*/
|
*/
|
||||||
@@ -382,17 +468,19 @@ public final class WordPdfConverter {
|
|||||||
return List.of(
|
return List.of(
|
||||||
// один zip-проход: strict→transitional, on/off, Symbol-PUA,
|
// один zip-проход: strict→transitional, on/off, Symbol-PUA,
|
||||||
// поля PAGE/NUMPAGES, невидимки, покрытие глифов, tblInd при
|
// поля PAGE/NUMPAGES, невидимки, покрытие глифов, tblInd при
|
||||||
// jc≠left, suff=space, скрытый текст (vanish) — порядок
|
// jc≠left, suff=space, скрытый текст (vanish), снятие обёртки
|
||||||
|
// w:ruby, OMML-фолбэк в текст — порядок
|
||||||
// рерайтов внутри части фиксирован (DocxRewritePipeline)
|
// рерайтов внутри части фиксирован (DocxRewritePipeline)
|
||||||
DocxRewritePipeline.STEP,
|
DocxRewritePipeline.STEP,
|
||||||
// OLE-объекты: при выключенном errorOnOle тихо удаляем
|
// OLE-объекты: при выключенном errorOnOle тихо удаляем
|
||||||
// (часть/rels/w:object), при включённом — DrawingFoundException
|
// (часть/rels/w:object), при включённом — OleFoundException
|
||||||
// (OleObjectNormalizer); второй проход, т.к. меняет части, а не XML
|
// (OleObjectNormalizer); второй проход, т.к. меняет части, а не XML
|
||||||
bytes -> OleObjectNormalizer.normalize(bytes, options.errorOnOle()));
|
bytes -> OleObjectNormalizer.normalize(bytes, options.errorOnOle()));
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Вендорный docx2fo.xslt (копия из docx4j-export-fo + AUDIT-FIX-патч).
|
* Вендорный docx2fo.xslt (копия из docx4j-export-fo + AUDIT-FIX-патчи:
|
||||||
|
* w:rPr/w:position→baseline-shift; AUDIT-FIX-2: moveFrom/moveTo/bdo/dir).
|
||||||
* {@code AbstractXsltExporterDelegate.getTemplates} кастит значение
|
* {@code AbstractXsltExporterDelegate.getTemplates} кастит значение
|
||||||
* {@code setCustomXsltTemplates} в {@code Templates} — компилируем заранее;
|
* {@code setCustomXsltTemplates} в {@code Templates} — компилируем заранее;
|
||||||
* {@code Templates} неизменяем и потокобезопасен, один экземпляр на процесс.
|
* {@code Templates} неизменяем и потокобезопасен, один экземпляр на процесс.
|
||||||
@@ -407,7 +495,7 @@ public final class WordPdfConverter {
|
|||||||
throw new ConversionException("Ресурс xslt/docx2fo.xslt не найден");
|
throw new ConversionException("Ресурс xslt/docx2fo.xslt не найден");
|
||||||
}
|
}
|
||||||
return XmlUtils.getTransformerFactory().newTemplates(new StreamSource(xslt));
|
return XmlUtils.getTransformerFactory().newTemplates(new StreamSource(xslt));
|
||||||
} catch (Exception e) {
|
} catch (IOException | TransformerConfigurationException e) {
|
||||||
throw new ConversionException("Не удалось скомпилировать xslt/docx2fo.xslt", e);
|
throw new ConversionException("Не удалось скомпилировать xslt/docx2fo.xslt", e);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,42 +0,0 @@
|
|||||||
package ru.pjandro.wordpdf;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Единая точка конфигурации ядра: все настройки-дефолты — константы здесь.
|
|
||||||
* Рантайм-конфигурации нет: изменение значения = правка этого файла и пересборка.
|
|
||||||
* Лимиты входа ({@link #MAX_INPUT_MB}, {@link #MAX_PAGES}) — дефолты:
|
|
||||||
* вызывающий может переопределить их на конкретный вызов через
|
|
||||||
* {@link ConvertOptions}.
|
|
||||||
*/
|
|
||||||
public final class WordPdfSettings {
|
|
||||||
|
|
||||||
/** Максимальный размер входного .docx в МБ (дефолт). МБ = MiB = 1024 × 1024 байт. */
|
|
||||||
public static final long MAX_INPUT_MB = 5;
|
|
||||||
|
|
||||||
/** Документ длиннее — ошибка (дефолт). */
|
|
||||||
public static final int MAX_PAGES = 100;
|
|
||||||
|
|
||||||
/** Потолок суммарного распакованного размера архива (МБ) — защита от zip-бомбы. */
|
|
||||||
public static final long MAX_DECOMPRESSED_MB = 200;
|
|
||||||
|
|
||||||
/** Потолок числа записей в архиве — защита от бомбы «много записей». */
|
|
||||||
public static final int MAX_ZIP_ENTRIES = 8192;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Ошибка при находке диаграмм ({@code c:chart}) — {@link DrawingFoundException}.
|
|
||||||
* Дефолт {@code false} — конвертация проходит.
|
|
||||||
*/
|
|
||||||
public static final boolean ERROR_ON_CHARTS = false;
|
|
||||||
|
|
||||||
/** Ошибка при находке SmartArt ({@code dgm:relIds}) — {@link DrawingFoundException}. */
|
|
||||||
public static final boolean ERROR_ON_SMARTART = false;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Ошибка при находке OLE-объектов (бинарные {@code .bin}-части) —
|
|
||||||
* {@link DrawingFoundException}. Дефолт {@code false} — объекты тихо
|
|
||||||
* удаляются из документа (см. OleObjectNormalizer), конвертация проходит.
|
|
||||||
*/
|
|
||||||
public static final boolean ERROR_ON_OLE = false;
|
|
||||||
|
|
||||||
private WordPdfSettings() {
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@@ -30,19 +30,15 @@ import java.util.zip.ZipInputStream;
|
|||||||
* но им можно пользоваться и напрямую — например, проверить байты
|
* но им можно пользоваться и напрямую — например, проверить байты
|
||||||
* документа, полученного из сети или БД, до любой работы с ними.
|
* документа, полученного из сети или БД, до любой работы с ними.
|
||||||
*
|
*
|
||||||
* <p>Лимиты по умолчанию:
|
* <p>Лимитов-констант в ядре нет: все пороги выводятся из лимитов входа
|
||||||
* <ul>
|
* {@link ConvertOptions} ({@code maxMb} — размер в МБ, {@code maxPages} —
|
||||||
* <li>{@link WordPdfSettings#MAX_INPUT_MB} — максимальный размер входного .docx (МБ);</li>
|
* число страниц): бюджеты распаковки {@link #maxDecompressedBytes(long, int)}
|
||||||
* <li>{@link WordPdfSettings#MAX_PAGES} — максимально допустимое число страниц;</li>
|
* и {@link #maxDecompressedXmlBytes(long, int)}, порог площади растра
|
||||||
* <li>{@link WordPdfSettings#MAX_DECOMPRESSED_MB} — потолок суммарного
|
* {@link #maxImagePixels(long)}, потолок числа zip-записей
|
||||||
* распакованного размера архива (МБ);</li>
|
* {@code maxZipEntries} (package-private) — коэффициенты в
|
||||||
* <li>{@link WordPdfSettings#MAX_ZIP_ENTRIES} — потолок числа записей
|
* {@link WordPdfConverter}. Конвертер применяет {@link ConvertOptions} сам;
|
||||||
* в архиве.</li>
|
* одноаргументных оверлодов-дефолтов нет — лимит задаётся параметром каждого
|
||||||
* </ul>
|
* метода.
|
||||||
* Первые два переопределяются на вызов: перегрузками с явным лимитом или
|
|
||||||
* {@link ConvertOptions} (конвертер {@link WordPdfConverter} применяет их сам).
|
|
||||||
* Последние два — защитные константные пороги ({@link #validate(byte[], ConvertOptions)}),
|
|
||||||
* {@link ConvertOptions} их не переопределяет.
|
|
||||||
*
|
*
|
||||||
* <p>Проверка контейнера: архив обязан декларировать документ
|
* <p>Проверка контейнера: архив обязан декларировать документ
|
||||||
* wordprocessingml в {@code [Content_Types].xml} — иначе это не .docx
|
* wordprocessingml в {@code [Content_Types].xml} — иначе это не .docx
|
||||||
@@ -70,6 +66,15 @@ public final class WordPdfValidator {
|
|||||||
/** Элемент-контейнер body, внутри которого sectPr — межсекционный разрыв. */
|
/** Элемент-контейнер body, внутри которого sectPr — межсекционный разрыв. */
|
||||||
private static final String BODY_ELEMENT = "body";
|
private static final String BODY_ELEMENT = "body";
|
||||||
|
|
||||||
|
/** Кэш-элемент <Pages> в docProps/app.xml. */
|
||||||
|
private static final String PAGES_ELEMENT = "Pages";
|
||||||
|
|
||||||
|
/** Элемент sectPr — секция документа (межсекционный разрыв). */
|
||||||
|
private static final String SECTION_PROPERTIES = "sectPr";
|
||||||
|
|
||||||
|
/** Элемент w:br — разрыв строки/страницы. */
|
||||||
|
private static final String BREAK_ELEMENT = "br";
|
||||||
|
|
||||||
/** Кэш Word <Pages>. */
|
/** Кэш Word <Pages>. */
|
||||||
private static final String APP_PART = "docProps/app.xml";
|
private static final String APP_PART = "docProps/app.xml";
|
||||||
|
|
||||||
@@ -79,15 +84,6 @@ public final class WordPdfValidator {
|
|||||||
private WordPdfValidator() {
|
private WordPdfValidator() {
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* Проверяет размер байтов входа (для документа, полученного из сети/БД).
|
|
||||||
*
|
|
||||||
* @throws ValidationException при {@code null} или превышении лимита (МБ)
|
|
||||||
*/
|
|
||||||
public static void checkInput(byte[] docxBytes) throws ValidationException {
|
|
||||||
checkInput(docxBytes, WordPdfSettings.MAX_INPUT_MB);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Проверяет размер байтов входа против явного лимита в МБ (переопределение
|
* Проверяет размер байтов входа против явного лимита в МБ (переопределение
|
||||||
* на вызов, см. {@link ConvertOptions#maxMb()}). МБ = MiB = 1024 × 1024 байт.
|
* на вызов, см. {@link ConvertOptions#maxMb()}). МБ = MiB = 1024 × 1024 байт.
|
||||||
@@ -111,7 +107,7 @@ public final class WordPdfValidator {
|
|||||||
* такой вход не проверяется .docx-валидацией (zip-пути), его страницы
|
* такой вход не проверяется .docx-валидацией (zip-пути), его страницы
|
||||||
* считает мост {@code internal.doc} по чистому бинарному документу.
|
* считает мост {@code internal.doc} по чистому бинарному документу.
|
||||||
*/
|
*/
|
||||||
public static boolean isBinaryDoc(byte[] bytes) {
|
static boolean isBinaryDoc(byte[] bytes) {
|
||||||
byte[] sig = {(byte) 0xD0, (byte) 0xCF, 0x11, (byte) 0xE0,
|
byte[] sig = {(byte) 0xD0, (byte) 0xCF, 0x11, (byte) 0xE0,
|
||||||
(byte) 0xA1, (byte) 0xB1, 0x1A, (byte) 0xE1};
|
(byte) 0xA1, (byte) 0xB1, 0x1A, (byte) 0xE1};
|
||||||
if (bytes == null || bytes.length < sig.length) {
|
if (bytes == null || bytes.length < sig.length) {
|
||||||
@@ -154,19 +150,13 @@ public final class WordPdfValidator {
|
|||||||
* .docx-манифест и распакованный размер (регрессия —
|
* .docx-манифест и распакованный размер (регрессия —
|
||||||
* {@code WordPdfValidatorTest#validate_notAZip}); поэтому вызывать
|
* {@code WordPdfValidatorTest#validate_notAZip}); поэтому вызывать
|
||||||
* {@code checkPageCount} напрямую допустимо только над доверенным входом.
|
* {@code checkPageCount} напрямую допустимо только над доверенным входом.
|
||||||
* @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@link WordPdfSettings#MAX_PAGES}
|
*
|
||||||
*/
|
* <p>Лимит страниц задаётся параметром (переопределение на вызов,
|
||||||
public static void checkPageCount(byte[] docxBytes) throws ValidationException {
|
* см. {@link ConvertOptions#maxPages()}).
|
||||||
checkPageCount(docxBytes, WordPdfSettings.MAX_PAGES);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* То же, что {@link #checkPageCount(byte[])}, с явным лимитом
|
|
||||||
* страниц (переопределение на вызов, см. {@link ConvertOptions#maxPages()}).
|
|
||||||
*
|
*
|
||||||
* @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@code maxPages}
|
* @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@code maxPages}
|
||||||
*/
|
*/
|
||||||
public static void checkPageCount(byte[] docxBytes, int maxPages) throws ValidationException {
|
static void checkPageCount(byte[] docxBytes, int maxPages) throws ValidationException {
|
||||||
if (docxBytes == null) {
|
if (docxBytes == null) {
|
||||||
throw new ValidationException("Не указаны байты входного .docx");
|
throw new ValidationException("Не указаны байты входного .docx");
|
||||||
}
|
}
|
||||||
@@ -215,17 +205,7 @@ public final class WordPdfValidator {
|
|||||||
* разрывы 0x0C − непрерывные межсекционные разрывы + абзацы с
|
* разрывы 0x0C − непрерывные межсекционные разрывы + абзацы с
|
||||||
* pageBreakBefore)} — тот же контур, что lightweight-скан по zip для
|
* pageBreakBefore)} — тот же контур, что lightweight-скан по zip для
|
||||||
* .docx. Разбор делает {@code internal.doc} ({@link DocToDocx#countPages(byte[])}).
|
* .docx. Разбор делает {@code internal.doc} ({@link DocToDocx#countPages(byte[])}).
|
||||||
*
|
* Лимит страниц задаётся параметром (см. {@link ConvertOptions#maxPages()}).
|
||||||
* @throws ValidationException при {@code null}, не-.doc-входе, шифровании
|
|
||||||
* или превышении {@link WordPdfSettings#MAX_PAGES}
|
|
||||||
*/
|
|
||||||
public static void checkPageCountDoc(byte[] docBytes) throws ValidationException {
|
|
||||||
checkPageCountDoc(docBytes, WordPdfSettings.MAX_PAGES);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* То же, что {@link #checkPageCountDoc(byte[])}, с явным лимитом
|
|
||||||
* страниц (переопределение на вызов, см. {@link ConvertOptions#maxPages()}).
|
|
||||||
*
|
*
|
||||||
* <p>Отказ разбора {@code .doc}-моста ({@code internal.doc}) —
|
* <p>Отказ разбора {@code .doc}-моста ({@code internal.doc}) —
|
||||||
* {@link ConversionException} — оборачивается здесь в
|
* {@link ConversionException} — оборачивается здесь в
|
||||||
@@ -237,7 +217,7 @@ public final class WordPdfValidator {
|
|||||||
* @throws ValidationException при {@code null}, не-.doc-входе, шифровании
|
* @throws ValidationException при {@code null}, не-.doc-входе, шифровании
|
||||||
* или превышении {@code maxPages}
|
* или превышении {@code maxPages}
|
||||||
*/
|
*/
|
||||||
public static void checkPageCountDoc(byte[] docBytes, int maxPages) throws ValidationException {
|
static void checkPageCountDoc(byte[] docBytes, int maxPages) throws ValidationException {
|
||||||
if (docBytes == null) {
|
if (docBytes == null) {
|
||||||
throw new ValidationException("Не указаны байты входного .doc");
|
throw new ValidationException("Не указаны байты входного .doc");
|
||||||
}
|
}
|
||||||
@@ -273,18 +253,25 @@ public final class WordPdfValidator {
|
|||||||
* <p>Проверка контейнера: в {@code [Content_Types].xml} обязана быть
|
* <p>Проверка контейнера: в {@code [Content_Types].xml} обязана быть
|
||||||
* декларация документа wordprocessingml (архив без неё — не .docx);
|
* декларация документа wordprocessingml (архив без неё — не .docx);
|
||||||
* zip-бомба отсекается потоковым счётчиком распакованных байт
|
* zip-бомба отсекается потоковым счётчиком распакованных байт
|
||||||
* ({@link WordPdfSettings#MAX_DECOMPRESSED_MB}) и числом записей
|
* ({@link #maxDecompressedBytes(long, int)}, XML —
|
||||||
* ({@link WordPdfSettings#MAX_ZIP_ENTRIES}) — до разбора содержимого
|
* {@link #maxDecompressedXmlBytes(long, int)}) и числом записей
|
||||||
* в {@link #checkPageCount(byte[], int)}. Оба лимита —
|
* ({@code maxZipEntries}) — до разбора содержимого
|
||||||
* защитные пороги, {@link ConvertOptions} их не переопределяет.
|
* в {@link #checkPageCount(byte[], int)}. Все пороги — производные от
|
||||||
|
* {@code options.maxMb()}/{@code options.maxPages()}, отдельных
|
||||||
|
* констант в ядре нет.
|
||||||
* Регрессии — {@code WordPdfValidatorTest#validate_plainZipRejected},
|
* Регрессии — {@code WordPdfValidatorTest#validate_plainZipRejected},
|
||||||
* {@code #validate_xlsxRenamedRejected}, {@code #validate_zipBombRejected},
|
* {@code #validate_xlsxRenamedRejected}, {@code #validate_zipBombRejected},
|
||||||
* {@code #validate_tooManyEntriesRejected}.</p>
|
* {@code #validate_tooManyEntriesRejected}.</p>
|
||||||
* @throws ValidationException при {@code null}, превышении {@code options.maxMb()},
|
* @throws ValidationException при {@code null} входа или {@code options},
|
||||||
|
* превышении {@code options.maxMb()},
|
||||||
* отсутствии zip-подписи, не-.docx-контейнере, признаках zip-бомбы,
|
* отсутствии zip-подписи, не-.docx-контейнере, признаках zip-бомбы,
|
||||||
* ошибке разбора zip или превышении {@code options.maxPages()}
|
* ошибке разбора zip или превышении {@code options.maxPages()}
|
||||||
*/
|
*/
|
||||||
public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException {
|
public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException {
|
||||||
|
if (options == null) {
|
||||||
|
throw new ValidationException("Не переданы параметры конвертации (ConvertOptions): "
|
||||||
|
+ "лимиты входа задаёт вызывающий");
|
||||||
|
}
|
||||||
checkInput(docxBytes, options.maxMb());
|
checkInput(docxBytes, options.maxMb());
|
||||||
if (isBinaryDoc(docxBytes)) {
|
if (isBinaryDoc(docxBytes)) {
|
||||||
// Бинарный .doc: страницы — по чистому бинарному документу,
|
// Бинарный .doc: страницы — по чистому бинарному документу,
|
||||||
@@ -296,7 +283,11 @@ public final class WordPdfValidator {
|
|||||||
|| (docxBytes[2] & 0xFF) != 0x03 || (docxBytes[3] & 0xFF) != 0x04) {
|
|| (docxBytes[2] & 0xFF) != 0x03 || (docxBytes[3] & 0xFF) != 0x04) {
|
||||||
throw new ValidationException("Содержимое не похоже на .docx или .doc (не zip-архив)");
|
throw new ValidationException("Содержимое не похоже на .docx или .doc (не zip-архив)");
|
||||||
}
|
}
|
||||||
checkDocxContainer(docxBytes);
|
checkDocxContainer(docxBytes,
|
||||||
|
maxDecompressedBytes(options.maxMb(), options.maxPages()),
|
||||||
|
maxDecompressedXmlBytes(options.maxMb(), options.maxPages()),
|
||||||
|
maxZipEntries(options.maxMb(), options.maxPages()),
|
||||||
|
maxImagePixels(options.maxMb()));
|
||||||
checkPageCount(docxBytes, options.maxPages());
|
checkPageCount(docxBytes, options.maxPages());
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -306,30 +297,60 @@ public final class WordPdfValidator {
|
|||||||
* в {@link #checkPageCount(byte[], int)}) и наличие в
|
* в {@link #checkPageCount(byte[], int)}) и наличие в
|
||||||
* {@code [Content_Types].xml} декларации документа wordprocessingml
|
* {@code [Content_Types].xml} декларации документа wordprocessingml
|
||||||
* (архив без неё — не .docx: обычный zip, переименованный .xlsx/.pptx).
|
* (архив без неё — не .docx: обычный zip, переименованный .xlsx/.pptx).
|
||||||
|
*
|
||||||
|
* <p>Пороги передаются параметром (считает
|
||||||
|
* {@link #validate(byte[], ConvertOptions)} из лимитов входа через
|
||||||
|
* {@link #maxDecompressedBytes} / {@link #maxDecompressedXmlBytes} /
|
||||||
|
* {@code maxZipEntries} / {@link #maxImagePixels}): заголовок
|
||||||
|
* центрального каталога врёт о размере, поэтому считается по ходу чтения.
|
||||||
*/
|
*/
|
||||||
private static void checkDocxContainer(byte[] docxBytes) throws ValidationException {
|
private static void checkDocxContainer(byte[] docxBytes, long maxTotal, long maxXmlTotal,
|
||||||
long maxTotal = WordPdfSettings.MAX_DECOMPRESSED_MB * 1024 * 1024;
|
long maxEntries, long maxPixels)
|
||||||
|
throws ValidationException {
|
||||||
long total = 0;
|
long total = 0;
|
||||||
|
long xmlTotal = 0;
|
||||||
int entries = 0;
|
int entries = 0;
|
||||||
|
// OPC требует уникальных имён частей: дубликат — либо крафт, либо
|
||||||
|
// обход кэша страниц (валидатор читает ПЕРВУЮ партию document.xml,
|
||||||
|
// парсер может взять другую) — отказ по первому повтору имени.
|
||||||
|
Set<String> names = new HashSet<>();
|
||||||
ByteArrayOutputStream ctBuf = new ByteArrayOutputStream();
|
ByteArrayOutputStream ctBuf = new ByteArrayOutputStream();
|
||||||
try (ZipInputStream zip = new ZipInputStream(new ByteArrayInputStream(docxBytes))) {
|
try (ZipInputStream zip = new ZipInputStream(new ByteArrayInputStream(docxBytes))) {
|
||||||
ZipEntry entry;
|
ZipEntry entry;
|
||||||
while ((entry = zip.getNextEntry()) != null) {
|
while ((entry = zip.getNextEntry()) != null) {
|
||||||
|
if (!names.add(entry.getName())) {
|
||||||
|
throw new ValidationException("Дубликаты записей в архиве: " + entry.getName());
|
||||||
|
}
|
||||||
if (!entry.isDirectory()) {
|
if (!entry.isDirectory()) {
|
||||||
entries++;
|
entries++;
|
||||||
if (entries > WordPdfSettings.MAX_ZIP_ENTRIES) {
|
if (entries > maxEntries) {
|
||||||
throw new ValidationException("Слишком много записей в архиве: больше "
|
throw new ValidationException("Слишком много записей в архиве: больше "
|
||||||
+ WordPdfSettings.MAX_ZIP_ENTRIES);
|
+ maxEntries);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
boolean isCt = "[Content_Types].xml".equals(entry.getName());
|
String name = entry.getName();
|
||||||
|
boolean isCt = "[Content_Types].xml".equals(name);
|
||||||
|
boolean isXml = name.endsWith(".xml") || name.endsWith(".rels");
|
||||||
|
// Raster-bomb: маленькая запись объявляет гигантский растр
|
||||||
|
// (декод по заголовку) — размеры читаются из head-буфера,
|
||||||
|
// весь содержимый поток идёт через счётчик total как раньше.
|
||||||
|
boolean isRaster = isRasterMedia(name);
|
||||||
|
byte[] head = isRaster ? new byte[RASTER_HEAD_LIMIT] : null;
|
||||||
|
int headLen = 0;
|
||||||
byte[] buf = new byte[8192];
|
byte[] buf = new byte[8192];
|
||||||
int n;
|
int n;
|
||||||
while ((n = zip.read(buf)) > 0) {
|
while ((n = zip.read(buf)) > 0) {
|
||||||
total += n;
|
total += n;
|
||||||
if (total > maxTotal) {
|
if (total > maxTotal) {
|
||||||
throw new ValidationException("Распакованный размер архива больше "
|
throw new ValidationException("Распакованный размер архива больше "
|
||||||
+ WordPdfSettings.MAX_DECOMPRESSED_MB + " МБ (признак zip-бомбы)");
|
+ (maxTotal / 1048576) + " МБ (признак zip-бомбы)");
|
||||||
|
}
|
||||||
|
if (isXml) {
|
||||||
|
xmlTotal += n;
|
||||||
|
if (xmlTotal > maxXmlTotal) {
|
||||||
|
throw new ValidationException("Суммарный распакованный размер XML-частей больше "
|
||||||
|
+ (maxXmlTotal / 1048576) + " МБ (признак zip-бомбы)");
|
||||||
|
}
|
||||||
}
|
}
|
||||||
if (isCt) {
|
if (isCt) {
|
||||||
if (ctBuf.size() + n > 8 * 1024 * 1024) {
|
if (ctBuf.size() + n > 8 * 1024 * 1024) {
|
||||||
@@ -338,6 +359,18 @@ public final class WordPdfValidator {
|
|||||||
}
|
}
|
||||||
ctBuf.write(buf, 0, n);
|
ctBuf.write(buf, 0, n);
|
||||||
}
|
}
|
||||||
|
if (head != null && headLen < head.length) {
|
||||||
|
int take = Math.min(n, head.length - headLen);
|
||||||
|
System.arraycopy(buf, 0, head, headLen, take);
|
||||||
|
headLen += take;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (head != null) {
|
||||||
|
long area = rasterArea(name, head, headLen);
|
||||||
|
if (area > maxPixels) {
|
||||||
|
throw new ValidationException("Изображение слишком большое: " + name
|
||||||
|
+ " объявляет не менее " + area + " пикселей");
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
} catch (ValidationException e) {
|
} catch (ValidationException e) {
|
||||||
@@ -357,6 +390,55 @@ public final class WordPdfValidator {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Бюджет суммарной распаковки docx, байты: {@code max(MIN_DECOMPRESSED_MB×MiB,
|
||||||
|
* maxMb×10MiB + maxPages×64KiB)} — без верхней крышки: бюджет догоняет
|
||||||
|
* лимиты входа (защита от upload-бомбы масштабируется вместе с них).
|
||||||
|
* Коэффициенты — {@link WordPdfConverter#DECOMPRESS_MB_PER_MAX_MB} и
|
||||||
|
* {@link WordPdfConverter#DECOMPRESS_KIB_PER_PAGE} (запас на XML/медиа
|
||||||
|
* легитимного архива), пол — {@link WordPdfConverter#MIN_DECOMPRESSED_MB}
|
||||||
|
* (мелким лимитам входа). Регрессия —
|
||||||
|
* WordPdfValidatorTest#validate_smallLimitsBudgetFloor,
|
||||||
|
* #validate_budgetScalesWithInputLimits.
|
||||||
|
*/
|
||||||
|
static long maxDecompressedBytes(long maxMb, int maxPages) {
|
||||||
|
long budget = Math.multiplyExact(maxMb,
|
||||||
|
WordPdfConverter.DECOMPRESS_MB_PER_MAX_MB * 1048576L)
|
||||||
|
+ (long) maxPages * WordPdfConverter.DECOMPRESS_KIB_PER_PAGE * 1024L;
|
||||||
|
return Math.max(WordPdfConverter.MIN_DECOMPRESSED_MB * 1048576L, budget);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Бюджет распаковки XML-частей docx, байты: {@code max(MIN_DECOMPRESSED_XML_MB×MiB,
|
||||||
|
* maxMb×4MiB + maxPages×32KiB)} (XML парсится JAXB DOM — дороже байта,
|
||||||
|
* поэтому коэффициенты вдвое ниже суммарных, и пол ниже). Инвариант: при
|
||||||
|
* одних лимитах строго меньше суммарного бюджета, поэтому гейт XML
|
||||||
|
* достижим.
|
||||||
|
*/
|
||||||
|
static long maxDecompressedXmlBytes(long maxMb, int maxPages) {
|
||||||
|
long budget = Math.multiplyExact(maxMb,
|
||||||
|
WordPdfConverter.DECOMPRESS_XML_MB_PER_MAX_MB * 1048576L)
|
||||||
|
+ (long) maxPages * WordPdfConverter.DECOMPRESS_XML_KIB_PER_PAGE * 1024L;
|
||||||
|
return Math.max(WordPdfConverter.MIN_DECOMPRESSED_XML_MB * 1048576L, budget);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Порог пиксельной площади одного растрового медиа, пиксели:
|
||||||
|
* {@code maxMb×5_000_000} (при лимите 5 МБ — 25 Мпикс, как в Word;
|
||||||
|
* разложение в ARGB-буфер ≈ 4 байта/пиксель). Публичный — нужен
|
||||||
|
* .doc-мосту ({@code OfficeArt}) для той же защиты на своём пути.
|
||||||
|
*/
|
||||||
|
public static long maxImagePixels(long maxMb) {
|
||||||
|
return Math.multiplyExact(maxMb, WordPdfConverter.IMAGE_PIXELS_PER_MAX_MB);
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Порог числа zip-записей: {@code max(2048, maxMb×512 + maxPages×32)} — защита от бомбы «много записей». */
|
||||||
|
static long maxZipEntries(long maxMb, int maxPages) {
|
||||||
|
long v = Math.multiplyExact(maxMb, WordPdfConverter.ZIP_ENTRIES_PER_MAX_MB)
|
||||||
|
+ (long) maxPages * WordPdfConverter.ZIP_ENTRIES_PER_PAGE;
|
||||||
|
return Math.max(WordPdfConverter.MIN_ZIP_ENTRIES, v);
|
||||||
|
}
|
||||||
|
|
||||||
/** Поиск байтов ASCII-строки в массиве (манифест ограничен 8 МБ — наивного поиска достаточно). */
|
/** Поиск байтов ASCII-строки в массиве (манифест ограничен 8 МБ — наивного поиска достаточно). */
|
||||||
private static boolean containsAscii(byte[] data, String needle) {
|
private static boolean containsAscii(byte[] data, String needle) {
|
||||||
byte[] pat = needle.getBytes(StandardCharsets.UTF_8);
|
byte[] pat = needle.getBytes(StandardCharsets.UTF_8);
|
||||||
@@ -372,6 +454,89 @@ public final class WordPdfValidator {
|
|||||||
return false;
|
return false;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** Растровые медиа, чьи размеры читываются из заголовка (прочие форматы не инспектируются). */
|
||||||
|
private static boolean isRasterMedia(String name) {
|
||||||
|
String n = name.toLowerCase(java.util.Locale.ROOT);
|
||||||
|
return n.endsWith(".png") || n.endsWith(".gif") || n.endsWith(".bmp")
|
||||||
|
|| n.endsWith(".jpg") || n.endsWith(".jpeg");
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Хватает на PNG/GIF/BMP-заголовок и на JPEG-SOF даже с большими embedded-превью. */
|
||||||
|
private static final int RASTER_HEAD_LIMIT = 64 * 1024;
|
||||||
|
|
||||||
|
/** Минимальный читаемый заголовок GIF: сигнатура «GIF8xа» + width/height (2×u16). */
|
||||||
|
private static final int GIF_HEADER_MIN = 10;
|
||||||
|
/** Префикс каждого JPEG-сегмента: маркер 0xFF. */
|
||||||
|
private static final int JPEG_MARKER = 0xFF;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Пиксельная площадь по заголовку растра (PNG — IHDR big-endian, GIF/BMP —
|
||||||
|
* little-endian, JPEG — скан сегментов SOFn); нераспознанный/неполный
|
||||||
|
* заголовок → -1 (не отклонять: формат мог быть нестандартным, декод
|
||||||
|
* всё равно ограничен {@code total}).
|
||||||
|
*/
|
||||||
|
private static long rasterArea(String name, byte[] h, int len) {
|
||||||
|
String n = name.toLowerCase(java.util.Locale.ROOT);
|
||||||
|
if (n.endsWith(".png")) {
|
||||||
|
if (len >= 24 && (h[0] & 0xFF) == 0x89 && h[1] == 'P' && h[2] == 'N' && h[3] == 'G') {
|
||||||
|
return be32(h, 16) * (long) be32(h, 20);
|
||||||
|
}
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
if (n.endsWith(".gif")) {
|
||||||
|
if (len >= GIF_HEADER_MIN) {
|
||||||
|
return (long) le16(h, 6) * le16(h, 8);
|
||||||
|
}
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
if (n.endsWith(".bmp")) {
|
||||||
|
if (len >= 26 && h[0] == 'B' && h[1] == 'M') {
|
||||||
|
return Math.abs((long) le32(h, 18)) * Math.abs((long) le32(h, 22));
|
||||||
|
}
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
// JPEG: скан маркеров до SOFn (C0–CF кроме C4/DHT, C8, CC/DAC);
|
||||||
|
// префикс FFD8 обязателен, иначе — не JPEG.
|
||||||
|
if (len < 4 || (h[0] & 0xFF) != 0xFF || (h[1] & 0xFF) != 0xD8) {
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
int i = 2;
|
||||||
|
while (i + 4 <= len) {
|
||||||
|
if ((h[i] & JPEG_MARKER) != JPEG_MARKER) {
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
int marker = h[i + 1] & 0xFF;
|
||||||
|
if (marker >= 0xC0 && marker <= 0xCF && marker != 0xC4 && marker != 0xC8 && marker != 0xCC) {
|
||||||
|
if (i + 9 > len) {
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
return (long) be16(h, i + 7) * be16(h, i + 5);
|
||||||
|
}
|
||||||
|
if (marker == 0xD8 || (marker >= 0xD0 && marker <= 0xD7) || marker == 0x01) {
|
||||||
|
i += 2;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
i += 2 + be16(h, i + 2);
|
||||||
|
}
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static int be16(byte[] b, int off) {
|
||||||
|
return ((b[off] & 0xFF) << 8) | (b[off + 1] & 0xFF);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static int le16(byte[] b, int off) {
|
||||||
|
return (b[off] & 0xFF) | ((b[off + 1] & 0xFF) << 8);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static int be32(byte[] b, int off) {
|
||||||
|
return (be16(b, off) << 16) | be16(b, off + 2);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static int le32(byte[] b, int off) {
|
||||||
|
return (le16(b, off) & 0xFFFF) | (le16(b, off + 2) << 16);
|
||||||
|
}
|
||||||
|
|
||||||
/** {@code word/headerN.xml} / {@code word/footerN.xml} (не .rels). */
|
/** {@code word/headerN.xml} / {@code word/footerN.xml} (не .rels). */
|
||||||
private static boolean isHeaderFooterPart(String name) {
|
private static boolean isHeaderFooterPart(String name) {
|
||||||
return (name.startsWith("word/header") || name.startsWith("word/footer"))
|
return (name.startsWith("word/header") || name.startsWith("word/footer"))
|
||||||
@@ -407,7 +572,7 @@ public final class WordPdfValidator {
|
|||||||
XMLStreamReader xr = newSecureReader().createXMLStreamReader(in);
|
XMLStreamReader xr = newSecureReader().createXMLStreamReader(in);
|
||||||
while (xr.hasNext()) {
|
while (xr.hasNext()) {
|
||||||
if (xr.next() == XMLStreamReader.START_ELEMENT
|
if (xr.next() == XMLStreamReader.START_ELEMENT
|
||||||
&& "Pages".equals(xr.getLocalName())) {
|
&& PAGES_ELEMENT.equals(xr.getLocalName())) {
|
||||||
String text = xr.getElementText().trim();
|
String text = xr.getElementText().trim();
|
||||||
return Math.max(0, Integer.parseInt(text));
|
return Math.max(0, Integer.parseInt(text));
|
||||||
}
|
}
|
||||||
@@ -496,7 +661,7 @@ public final class WordPdfValidator {
|
|||||||
// различает финальную и межсекционные)
|
// различает финальную и межсекционные)
|
||||||
}
|
}
|
||||||
case "type" -> {
|
case "type" -> {
|
||||||
if (inBodySectPr && "sectPr".equals(parent)) {
|
if (inBodySectPr && SECTION_PROPERTIES.equals(parent)) {
|
||||||
sectTypeVal = attrLocal(xr, "val");
|
sectTypeVal = attrLocal(xr, "val");
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -504,7 +669,7 @@ public final class WordPdfValidator {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
} else if (ev == XMLStreamReader.END_ELEMENT) {
|
} else if (ev == XMLStreamReader.END_ELEMENT) {
|
||||||
if ("sectPr".equals(xr.getLocalName()) && inBodySectPr) {
|
if (SECTION_PROPERTIES.equals(xr.getLocalName()) && inBodySectPr) {
|
||||||
if (pendingNewPageSection) {
|
if (pendingNewPageSection) {
|
||||||
bodyDirectSectPr++;
|
bodyDirectSectPr++;
|
||||||
}
|
}
|
||||||
@@ -537,7 +702,7 @@ public final class WordPdfValidator {
|
|||||||
XMLStreamReader xr = newSecureReader().createXMLStreamReader(in);
|
XMLStreamReader xr = newSecureReader().createXMLStreamReader(in);
|
||||||
while (xr.hasNext()) {
|
while (xr.hasNext()) {
|
||||||
if (xr.next() == XMLStreamReader.START_ELEMENT
|
if (xr.next() == XMLStreamReader.START_ELEMENT
|
||||||
&& "br".equals(xr.getLocalName()) && isPageBreak(xr)) {
|
&& BREAK_ELEMENT.equals(xr.getLocalName()) && isPageBreak(xr)) {
|
||||||
count++;
|
count++;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -0,0 +1,106 @@
|
|||||||
|
package ru.pjandro.wordpdf.fonts;
|
||||||
|
|
||||||
|
import java.util.HashMap;
|
||||||
|
import java.util.Locale;
|
||||||
|
import java.util.Map;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Таблица алиасов имён шрифтов и обратное имя для {@code w:rFonts}.
|
||||||
|
*
|
||||||
|
* Почему это вынесено из {@link BundledFontMapper}: обращение к статикам
|
||||||
|
* маппера (чарты, GlyphCoverageNormalizer, MathModel) по правилам JVM
|
||||||
|
* инициализирует и суперкласс {@code BestMatchingMapper}, чей
|
||||||
|
* {@code <clinit>} сканирует classpath-джары в реестр {@code PhysicalFonts};
|
||||||
|
* системный скан гейтится свойствами {@code docx4j.fonts.discover*},
|
||||||
|
* которые выставляет {@code WordPdfConverter.<clinit>}, — и при раннем
|
||||||
|
* обращении к мапперу скан мог пройти без гейта. У этого класса нет
|
||||||
|
* наследования, его статика безопасна при любом порядке загрузки.
|
||||||
|
* Экземпляр {@code BundledFontMapper} создаётся только в конвейере
|
||||||
|
* {@code WordPdfConverter} — всегда после его {@code <clinit>}.
|
||||||
|
*/
|
||||||
|
public final class BundledFontAliases {
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Алиасы: имя шрифта из документа (lowercase) -> бандл-семейство (lowercase).
|
||||||
|
* Croscore (Arimo/Tinos/Cousine) и crosextra (Carlito/Caladea) шрифты
|
||||||
|
* метрически совместимы с соответствующими MS-шрифтами и содержат
|
||||||
|
* кириллицу.
|
||||||
|
*/
|
||||||
|
static final Map<String, String> ALIASES;
|
||||||
|
|
||||||
|
static {
|
||||||
|
Map<String, String> m = new HashMap<>();
|
||||||
|
// Частые MS-шрифты -> open-source аналоги
|
||||||
|
m.put("calibri", "carlito");
|
||||||
|
m.put("calibri light", "carlito");
|
||||||
|
m.put("cambria", "caladea");
|
||||||
|
m.put("arial", "arimo");
|
||||||
|
m.put("times new roman", "tinos");
|
||||||
|
m.put("courier new", "cousine");
|
||||||
|
// Бандл-шрифты сами по себе (на случай, если документ прямо
|
||||||
|
// указывает одно из них)
|
||||||
|
m.put("carlito", "carlito");
|
||||||
|
m.put("caladea", "caladea");
|
||||||
|
m.put("arimo", "arimo");
|
||||||
|
m.put("tinos", "tinos");
|
||||||
|
m.put("cousine", "cousine");
|
||||||
|
m.put("dejavu sans", "dejavu sans");
|
||||||
|
m.put("dejavu serif", "dejavu serif");
|
||||||
|
// Покрывающие шрифты (в документе обычно не встречаются, но если
|
||||||
|
// встречаться — маппятся на себя, а не в DejaVu-фолбэк)
|
||||||
|
m.put("noto naskh arabic", "noto naskh arabic");
|
||||||
|
m.put("noto sans armenian", "noto sans armenian");
|
||||||
|
ALIASES = Map.copyOf(m);
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Финальный fallback: шрифт с гарантированной кириллицей. */
|
||||||
|
private static final String FALLBACK_FAMILY = BundledFonts.FALLBACK_FAMILY;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Имя семейства для записи в {@code w:rFonts} (ключ — lowercase-семейство).
|
||||||
|
* Нужно {@code GlyphCoverageNormalizer}: он пишет в разрезанный ран
|
||||||
|
* человекочитаемое имя, а {@code BundledFontMapper.populateFontMappings}
|
||||||
|
* маппит его обратно на TTF.
|
||||||
|
*/
|
||||||
|
private static final Map<String, String> DISPLAY_NAMES = Map.of(
|
||||||
|
"dejavu sans", "DejaVu Sans",
|
||||||
|
"dejavu serif", "DejaVu Serif",
|
||||||
|
"noto naskh arabic", "Noto Naskh Arabic",
|
||||||
|
"noto sans armenian", "Noto Sans Armenian");
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Имя, которое docx4j {@code RunFontSelector} запрашивает у маппера для
|
||||||
|
* символов диапазона U+2000–U+2EFF (em-dash «—», кавычки «„», многоточие
|
||||||
|
* «…»), если шрифт ранa не содержит глифа. Это виртуальное имя (в
|
||||||
|
* документе его нет), поэтому маппим его на {@link #FALLBACK_FAMILY}:
|
||||||
|
* без записи символ остаётся без font-family в FO и рендерится системным
|
||||||
|
* неembedded-шрифтом (Helvetica).
|
||||||
|
*/
|
||||||
|
static final String SYMBOL_FONT = "Segoe UI Symbol";
|
||||||
|
|
||||||
|
private BundledFontAliases() {
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Бандл-семейство для имени шрифта из документа (таблица алиасов)
|
||||||
|
* или финальный fallback. Используется пре-рендером диаграмм и формул
|
||||||
|
* (internal/chart), которому нужен тот же шрифт, что и у текста PDF.
|
||||||
|
*/
|
||||||
|
public static String bundledFamily(String docFontName) {
|
||||||
|
String family = ALIASES.get(docFontName.toLowerCase(Locale.ROOT));
|
||||||
|
return family != null && BundledFonts.regular(family) != null
|
||||||
|
? family
|
||||||
|
: FALLBACK_FAMILY;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Имя шрифта, которое можно поставить в {@code w:rFonts}, чтобы получить
|
||||||
|
* бандл-семейство {@code family}: {@code GlyphCoverageNormalizer} пишет
|
||||||
|
* его в разрезанные раны. Обратная к {@link #bundledFamily} операция —
|
||||||
|
* имена берутся из таблицы алиасов, поэтому маппинг гарантированно
|
||||||
|
* возвращается к тому же семейству.
|
||||||
|
*/
|
||||||
|
public static String documentFontName(String family) {
|
||||||
|
return DISPLAY_NAMES.getOrDefault(family, family);
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -4,10 +4,8 @@ import org.docx4j.fonts.BestMatchingMapper;
|
|||||||
import org.docx4j.fonts.PhysicalFont;
|
import org.docx4j.fonts.PhysicalFont;
|
||||||
import org.docx4j.wml.Fonts;
|
import org.docx4j.wml.Fonts;
|
||||||
|
|
||||||
import java.util.HashMap;
|
|
||||||
import java.util.LinkedHashSet;
|
import java.util.LinkedHashSet;
|
||||||
import java.util.Locale;
|
import java.util.Locale;
|
||||||
import java.util.Map;
|
|
||||||
import java.util.Set;
|
import java.util.Set;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -15,7 +13,8 @@ import java.util.Set;
|
|||||||
*
|
*
|
||||||
* Стратегия (см. {@link #populateFontMappings}):
|
* Стратегия (см. {@link #populateFontMappings}):
|
||||||
* 1. Частые MS-шрифты заменяются метрически совместимыми open-source
|
* 1. Частые MS-шрифты заменяются метрически совместимыми open-source
|
||||||
* аналогами (таблица алиасов) — они есть в jar и содержат кириллицу.
|
* аналогами (таблица алиасов {@link BundledFontAliases}) — они есть в
|
||||||
|
* jar и содержат кириллицу.
|
||||||
* 2. Нераспознанные шрифты передаются родительскому
|
* 2. Нераспознанные шрифты передаются родительскому
|
||||||
* {@link BestMatchingMapper} (совпадение по Panose-кодам среди
|
* {@link BestMatchingMapper} (совпадение по Panose-кодам среди
|
||||||
* доступных шрифтов).
|
* доступных шрифтов).
|
||||||
@@ -27,95 +26,30 @@ import java.util.Set;
|
|||||||
* файл для каждого начертания. Ключи register*Form — точное имя из
|
* файл для каждого начертания. Ключи register*Form — точное имя из
|
||||||
* документа: docx4j ищет варианты именно по нему.
|
* документа: docx4j ищет варианты именно по нему.
|
||||||
*
|
*
|
||||||
|
* ВАЖНО (macOS): {@code PhysicalFonts.getBoldForm} для имён бандл-шрифтов
|
||||||
|
* ({@code Tinos Regular}, {@code Carlito Regular}, …) на macOS уходит в
|
||||||
|
* {@code MicrosoftFontsRegistry} и возвращает {@code null} — у этих записей
|
||||||
|
* нет Mac-имени файла. docx4j тогда строит simulate-style fopconf (все
|
||||||
|
* начертания на regular-TTF), и FOP теряет реальные Bold/Italic: другие
|
||||||
|
* метрики и кернинг ломают переносы в узких ячейках (регрессии —
|
||||||
|
* {@code WordPdfConverterTest#strictOoxml_convertsNotRejected},
|
||||||
|
* {@code #ruPlain_regularRunsUseRegularFont}). Override-ы
|
||||||
|
* {@code getBoldForm}/{@code getItalicForm}/{@code getBoldItalicForm}
|
||||||
|
* отдают реальные бандл-варианты.
|
||||||
|
*
|
||||||
* ВАЖНО (порядок инициализации): конструктор BestMatchingMapper
|
* ВАЖНО (порядок инициализации): конструктор BestMatchingMapper
|
||||||
* запускает обнаружение системных шрифтов, которые могут занять те же
|
* запускает обнаружение системных шрифтов, которые могут занять те же
|
||||||
* имена в реестре docx4j. Поэтому {@code BundledFonts.init()} нужно
|
* имена в реестре docx4j. Поэтому {@code BundledFonts.init()} нужно
|
||||||
* вызывать ПОСЛЕ создания маппера, чтобы бандл-шрифты оказались в
|
* вызывать ПОСЛЕ создания маппера, чтобы бандл-шрифты оказались в
|
||||||
* реестре поверх системных.
|
* реестре поверх системных. Таблица алиасов вынесена в
|
||||||
|
* {@link BundledFontAliases}, чтобы обращение к ней не инициировало этот
|
||||||
|
* класс до гейта {@code WordPdfConverter.<clinit>}.
|
||||||
*/
|
*/
|
||||||
public class BundledFontMapper extends BestMatchingMapper {
|
public class BundledFontMapper extends BestMatchingMapper {
|
||||||
|
|
||||||
/**
|
|
||||||
* Алиасы: имя шрифта из документа (lowercase) -> бандл-семейство (lowercase).
|
|
||||||
* Croscore (Arimo/Tinos/Cousine) и crosextra (Carlito/Caladea) шрифты
|
|
||||||
* метрически совместимы с соответствующими MS-шрифтами и содержат
|
|
||||||
* кириллицу.
|
|
||||||
*/
|
|
||||||
private static final Map<String, String> ALIASES;
|
|
||||||
|
|
||||||
/** Финальный fallback: шрифт с гарантированной кириллицей. */
|
/** Финальный fallback: шрифт с гарантированной кириллицей. */
|
||||||
private static final String FALLBACK_FAMILY = BundledFonts.FALLBACK_FAMILY;
|
private static final String FALLBACK_FAMILY = BundledFonts.FALLBACK_FAMILY;
|
||||||
|
|
||||||
/**
|
|
||||||
* Имя семейства для записи в {@code w:rFonts} (ключ — lowercase-семейство).
|
|
||||||
* Нужно {@code GlyphCoverageNormalizer}: он пишет в разрезанный ран
|
|
||||||
* человекочитаемое имя, а {@link #populateFontMappings} маппит его
|
|
||||||
* обратно на TTF.
|
|
||||||
*/
|
|
||||||
private static final Map<String, String> DISPLAY_NAMES = Map.of(
|
|
||||||
"dejavu sans", "DejaVu Sans",
|
|
||||||
"dejavu serif", "DejaVu Serif",
|
|
||||||
"noto naskh arabic", "Noto Naskh Arabic",
|
|
||||||
"noto sans armenian", "Noto Sans Armenian");
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Имя, которое docx4j {@code RunFontSelector} запрашивает у маппера для
|
|
||||||
* символов диапазона U+2000–U+2EFF (em-dash «—», кавычки «„», многоточие
|
|
||||||
* «…»), если шрифт ранa не содержит глифа. Это виртуальное имя (в
|
|
||||||
* документе его нет), поэтому маппим его на {@link #FALLBACK_FAMILY}:
|
|
||||||
* без записи символ остаётся без font-family в FO и рендерится системным
|
|
||||||
* неembedded-шрифтом (Helvetica).
|
|
||||||
*/
|
|
||||||
static final String SYMBOL_FONT = "Segoe UI Symbol";
|
|
||||||
|
|
||||||
static {
|
|
||||||
Map<String, String> m = new HashMap<>();
|
|
||||||
// Частые MS-шрифты -> open-source аналоги
|
|
||||||
m.put("calibri", "carlito");
|
|
||||||
m.put("calibri light", "carlito");
|
|
||||||
m.put("cambria", "caladea");
|
|
||||||
m.put("arial", "arimo");
|
|
||||||
m.put("times new roman", "tinos");
|
|
||||||
m.put("courier new", "cousine");
|
|
||||||
// Бандл-шрифты сами по себе (на случай, если документ прямо
|
|
||||||
// указывает одно из них)
|
|
||||||
m.put("carlito", "carlito");
|
|
||||||
m.put("caladea", "caladea");
|
|
||||||
m.put("arimo", "arimo");
|
|
||||||
m.put("tinos", "tinos");
|
|
||||||
m.put("cousine", "cousine");
|
|
||||||
m.put("dejavu sans", "dejavu sans");
|
|
||||||
m.put("dejavu serif", "dejavu serif");
|
|
||||||
// Покрывающие шрифты (в документе обычно не встречаются, но если
|
|
||||||
// встречаться — маппятся на себя, а не в DejaVu-фолбэк)
|
|
||||||
m.put("noto naskh arabic", "noto naskh arabic");
|
|
||||||
m.put("noto sans armenian", "noto sans armenian");
|
|
||||||
ALIASES = Map.copyOf(m);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Бандл-семейство для имени шрифта из документа (таблица алиасов)
|
|
||||||
* или финальный fallback. Используется пре-рендером диаграмм
|
|
||||||
* (internal/chart), которому нужен тот же шрифт, что и у текста PDF.
|
|
||||||
*/
|
|
||||||
public static String bundledFamily(String docFontName) {
|
|
||||||
String family = ALIASES.get(docFontName.toLowerCase(Locale.ROOT));
|
|
||||||
return family != null && BundledFonts.regular(family) != null
|
|
||||||
? family
|
|
||||||
: FALLBACK_FAMILY;
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Имя шрифта, которое можно поставить в {@code w:rFonts}, чтобы получить
|
|
||||||
* бандл-семейство {@code family}: {@link GlyphCoverageNormalizer} пишет
|
|
||||||
* его в разрезанные раны. Обратная к {@link #bundledFamily} операция —
|
|
||||||
* имена берутся из таблицы алиасов, поэтому маппинг гарантированно
|
|
||||||
* возвращается к тому же семейству.
|
|
||||||
*/
|
|
||||||
public static String documentFontName(String family) {
|
|
||||||
return DISPLAY_NAMES.getOrDefault(family, family);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Вызывается docx4j при {@code package.setFontMapper(...)}: для каждого
|
* Вызывается docx4j при {@code package.setFontMapper(...)}: для каждого
|
||||||
* имени шрифта, использованного в документе, нужно определить, каким
|
* имени шрифта, использованного в документе, нужно определить, каким
|
||||||
@@ -126,21 +60,21 @@ public class BundledFontMapper extends BestMatchingMapper {
|
|||||||
*/
|
*/
|
||||||
@Override
|
@Override
|
||||||
public void populateFontMappings(Set<String> documentFontNames, Fonts wmlFonts) throws Exception {
|
public void populateFontMappings(Set<String> documentFontNames, Fonts wmlFonts) throws Exception {
|
||||||
// Виртуальное имя для символов U+2000–U+2EFF (см. SYMBOL_FONT):
|
// Виртуальное имя для символов U+2000–U+2EFF (см. BundledFontAliases.SYMBOL_FONT):
|
||||||
// маппим сразу, чтобы оно не попало в remaining и родительский
|
// маппим сразу, чтобы оно не попало в remaining и родительский
|
||||||
// BestMatchingMapper не пытался искать его в fontTable (и не логировал
|
// BestMatchingMapper не пытался искать его в fontTable (и не логировал
|
||||||
// "Font Segoe UI Symbol not found in font table!").
|
// "Font Segoe UI Symbol not found in font table!").
|
||||||
if (BundledFonts.regular(FALLBACK_FAMILY) != null) {
|
if (BundledFonts.regular(FALLBACK_FAMILY) != null) {
|
||||||
mapFamily(SYMBOL_FONT, FALLBACK_FAMILY);
|
mapFamily(BundledFontAliases.SYMBOL_FONT, FALLBACK_FAMILY);
|
||||||
}
|
}
|
||||||
|
|
||||||
Set<String> remaining = new LinkedHashSet<>();
|
Set<String> remaining = new LinkedHashSet<>();
|
||||||
for (String docFontName : documentFontNames) {
|
for (String docFontName : documentFontNames) {
|
||||||
if (SYMBOL_FONT.equalsIgnoreCase(docFontName)) {
|
if (BundledFontAliases.SYMBOL_FONT.equalsIgnoreCase(docFontName)) {
|
||||||
// уже маппировано выше
|
// уже маппировано выше
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
String family = ALIASES.get(docFontName.toLowerCase(Locale.ROOT));
|
String family = BundledFontAliases.ALIASES.get(docFontName.toLowerCase(Locale.ROOT));
|
||||||
if (family == null || BundledFonts.regular(family) == null) {
|
if (family == null || BundledFonts.regular(family) == null) {
|
||||||
// Нет алиаса (или init() не вызван) — доверимся родителю
|
// Нет алиаса (или init() не вызван) — доверимся родителю
|
||||||
remaining.add(docFontName);
|
remaining.add(docFontName);
|
||||||
@@ -163,6 +97,51 @@ public class BundledFontMapper extends BestMatchingMapper {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** Начертание бандла вместо registry-эвристики: см. «ВАЖНО (macOS)» в javadoc класса. */
|
||||||
|
@Override
|
||||||
|
public PhysicalFont getBoldForm(String fontName, PhysicalFont physicalFont) {
|
||||||
|
PhysicalFont bundled = bundledSibling(physicalFont, BundledFonts.V_BOLD);
|
||||||
|
return bundled != null ? bundled : super.getBoldForm(fontName, physicalFont);
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Начертание бандла вместо registry-эвристики: см. «ВАЖНО (macOS)» в javadoc класса. */
|
||||||
|
@Override
|
||||||
|
public PhysicalFont getItalicForm(String fontName, PhysicalFont physicalFont) {
|
||||||
|
PhysicalFont bundled = bundledSibling(physicalFont, BundledFonts.V_ITALIC);
|
||||||
|
return bundled != null ? bundled : super.getItalicForm(fontName, physicalFont);
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Начертание бандла вместо registry-эвристики: см. «ВАЖНО (macOS)» в javadoc класса. */
|
||||||
|
@Override
|
||||||
|
public PhysicalFont getBoldItalicForm(String fontName, PhysicalFont physicalFont) {
|
||||||
|
PhysicalFont bundled = bundledSibling(physicalFont, BundledFonts.V_BOLD_ITALIC);
|
||||||
|
return bundled != null ? bundled : super.getBoldItalicForm(fontName, physicalFont);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Реальное начертание бандл-семейства, к которому относится {@code pf}.
|
||||||
|
*
|
||||||
|
* <p>Семейство опознаётся по {@code embeddedURI} regular-варианта, а не
|
||||||
|
* по имени: на macOS имя в реестре docx4j — полное из TTF-таблицы
|
||||||
|
* ({@code Tinos Regular}), и именно на нём ломается
|
||||||
|
* {@code PhysicalFonts.getBoldForm}. Шрифт вне бандла (или {@code pf ==
|
||||||
|
* null}, {@code BundledFonts.init()} не вызван) → {@code null}, вызывающий
|
||||||
|
* идёт родительской логикой.</p>
|
||||||
|
*/
|
||||||
|
private static PhysicalFont bundledSibling(PhysicalFont pf, String variant) {
|
||||||
|
if (pf == null || pf.getEmbeddedURI() == null) {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
String uri = pf.getEmbeddedURI().toString();
|
||||||
|
for (String family : BundledFonts.families()) {
|
||||||
|
PhysicalFont regular = BundledFonts.regular(family);
|
||||||
|
if (regular != null && uri.equals(regular.getEmbeddedURI().toString())) {
|
||||||
|
return BundledFonts.font(family, variant);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Привязывает все начертания семейства к имени шрифта из документа.
|
* Привязывает все начертания семейства к имени шрифта из документа.
|
||||||
*/
|
*/
|
||||||
|
|||||||
@@ -2,6 +2,7 @@ package ru.pjandro.wordpdf.fonts;
|
|||||||
|
|
||||||
import org.docx4j.fonts.PhysicalFont;
|
import org.docx4j.fonts.PhysicalFont;
|
||||||
import org.docx4j.fonts.PhysicalFonts;
|
import org.docx4j.fonts.PhysicalFonts;
|
||||||
|
import ru.pjandro.wordpdf.WordPdfConverter;
|
||||||
|
|
||||||
import java.io.IOException;
|
import java.io.IOException;
|
||||||
import java.io.InputStream;
|
import java.io.InputStream;
|
||||||
@@ -124,57 +125,65 @@ public final class BundledFonts {
|
|||||||
/**
|
/**
|
||||||
* Выгружает шрифты из jar и регистрирует их в docx4j.
|
* Выгружает шрифты из jar и регистрирует их в docx4j.
|
||||||
* Повторные вызовы игнорируются (idempotентно).
|
* Повторные вызовы игнорируются (idempotентно).
|
||||||
|
*
|
||||||
|
* <p>Монитор — {@code WordPdfConverter.class}, а не {@code BundledFonts.class}:
|
||||||
|
* {@code PhysicalFonts} и {@link #VARIANTS} читаются рендером внутри
|
||||||
|
* конвертации (она сериализована монитором конвертера), и мутация под
|
||||||
|
* собственным замком вырезала бы записи из-под идущего рендера.
|
||||||
|
* Все синхронизированные методы класса держат ровно этот монитор.</p>
|
||||||
*/
|
*/
|
||||||
public static synchronized void init() {
|
public static void init() {
|
||||||
if (inited) {
|
synchronized (WordPdfConverter.class) {
|
||||||
return;
|
if (inited) {
|
||||||
}
|
return;
|
||||||
try {
|
}
|
||||||
extractDir = Files.createTempDirectory("wordpdf-fonts-");
|
try {
|
||||||
} catch (IOException e) {
|
extractDir = Files.createTempDirectory("wordpdf-fonts-");
|
||||||
throw new IllegalStateException("Не удалось создать временный каталог для шрифтов", e);
|
|
||||||
}
|
|
||||||
// Ключ реестра docx4j — имя шрифта, и addPhysicalFont не перезаписывает
|
|
||||||
// занятый ключ. Системный DejaVuSerif.ttf занимает «dejavu serif», и
|
|
||||||
// наш DejaVuSerif-Regular.ttf (то же имя) просто не добавился бы.
|
|
||||||
dropNonBundled();
|
|
||||||
|
|
||||||
for (Entry entry : ENTRIES) {
|
|
||||||
// 1. Выгружаем файл из jar
|
|
||||||
Path target = extractDir.resolve(entry.file());
|
|
||||||
try (InputStream in = BundledFonts.class.getClassLoader()
|
|
||||||
.getResourceAsStream(CLASSPATH_DIR + "/" + entry.file())) {
|
|
||||||
if (in == null) {
|
|
||||||
throw new IllegalStateException(
|
|
||||||
"Шрифт не найден в jar: " + CLASSPATH_DIR + "/" + entry.file());
|
|
||||||
}
|
|
||||||
Files.copy(in, target, StandardCopyOption.REPLACE_EXISTING);
|
|
||||||
// deleteOnExit не рекурсивен: каталог удалится только пустым,
|
|
||||||
// поэтому регистрируем каждый выгруженный TTF.
|
|
||||||
target.toFile().deleteOnExit();
|
|
||||||
} catch (IOException e) {
|
} catch (IOException e) {
|
||||||
throw new IllegalStateException("Не удалось выгрузить шрифт " + entry.file(), e);
|
throw new IllegalStateException("Не удалось создать временный каталог для шрифтов", e);
|
||||||
|
}
|
||||||
|
// Ключ реестра docx4j — имя шрифта, и addPhysicalFont не перезаписывает
|
||||||
|
// занятый ключ. Системный DejaVuSerif.ttf занимает «dejavu serif», и
|
||||||
|
// наш DejaVuSerif-Regular.ttf (то же имя) просто не добавился бы.
|
||||||
|
dropNonBundled();
|
||||||
|
|
||||||
|
for (Entry entry : ENTRIES) {
|
||||||
|
// 1. Выгружаем файл из jar
|
||||||
|
Path target = extractDir.resolve(entry.file());
|
||||||
|
try (InputStream in = BundledFonts.class.getClassLoader()
|
||||||
|
.getResourceAsStream(CLASSPATH_DIR + "/" + entry.file())) {
|
||||||
|
if (in == null) {
|
||||||
|
throw new IllegalStateException(
|
||||||
|
"Шрифт не найден в jar: " + CLASSPATH_DIR + "/" + entry.file());
|
||||||
|
}
|
||||||
|
Files.copy(in, target, StandardCopyOption.REPLACE_EXISTING);
|
||||||
|
// deleteOnExit не рекурсивен: каталог удалится только пустым,
|
||||||
|
// поэтому регистрируем каждый выгруженный TTF.
|
||||||
|
target.toFile().deleteOnExit();
|
||||||
|
} catch (IOException e) {
|
||||||
|
throw new IllegalStateException("Не удалось выгрузить шрифт " + entry.file(), e);
|
||||||
|
}
|
||||||
|
|
||||||
|
// 2. Регистрируем в docx4j: имя в реестре docx4j берёт из
|
||||||
|
// name-таблицы TTF, поэтому ищем результат по URI файла
|
||||||
|
PhysicalFonts.addPhysicalFont(target.toUri());
|
||||||
|
PhysicalFont pf = findByFile(target.getFileName().toString());
|
||||||
|
if (pf == null) {
|
||||||
|
throw new IllegalStateException(
|
||||||
|
"docx4j не зарегистрировал шрифт: " + entry.file()
|
||||||
|
+ " (файл повреждён или не embeddable?)");
|
||||||
|
}
|
||||||
|
|
||||||
|
// 3. Учимся: семейство -> начертание -> PhysicalFont
|
||||||
|
VARIANTS
|
||||||
|
.computeIfAbsent(entry.family(), k -> new HashMap<>())
|
||||||
|
.put(entry.variant(), pf);
|
||||||
}
|
}
|
||||||
|
|
||||||
// 2. Регистрируем в docx4j: имя в реестре docx4j берёт из
|
// Удаление временного каталога при завершении JVM
|
||||||
// name-таблицы TTF, поэтому ищем результат по URI файла
|
extractDir.toFile().deleteOnExit();
|
||||||
PhysicalFonts.addPhysicalFont(target.toUri());
|
inited = true;
|
||||||
PhysicalFont pf = findByFile(target.getFileName().toString());
|
|
||||||
if (pf == null) {
|
|
||||||
throw new IllegalStateException(
|
|
||||||
"docx4j не зарегистрировал шрифт: " + entry.file()
|
|
||||||
+ " (файл повреждён или не embeddable?)");
|
|
||||||
}
|
|
||||||
|
|
||||||
// 3. Учимся: семейство -> начертание -> PhysicalFont
|
|
||||||
VARIANTS
|
|
||||||
.computeIfAbsent(entry.family(), k -> new HashMap<>())
|
|
||||||
.put(entry.variant(), pf);
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// Удаление временного каталога при завершении JVM
|
|
||||||
extractDir.toFile().deleteOnExit();
|
|
||||||
inited = true;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -188,12 +197,18 @@ public final class BundledFonts {
|
|||||||
* em-dash на шрифте ранa (Carlito) вместо fallback-DejaVu.
|
* em-dash на шрифте ранa (Carlito) вместо fallback-DejaVu.
|
||||||
* Шрифты, встроенные в docx, регистрируются при {@code load()} —
|
* Шрифты, встроенные в docx, регистрируются при {@code load()} —
|
||||||
* если чистить до load(), они останутся в реестре.
|
* если чистить до load(), они останутся в реестре.
|
||||||
|
* <p>Мутирует глобальный реестр {@code PhysicalFonts} под монитором
|
||||||
|
* {@code WordPdfConverter.class} — тем же, что сериализует конвертации,
|
||||||
|
* поэтому вызов рядом с идущей {@code WordPdfConverter.convert()}
|
||||||
|
* безопасен автоматически (замок удерживается внутри метода).
|
||||||
*/
|
*/
|
||||||
public static synchronized void restrictToBundled() {
|
public static void restrictToBundled() {
|
||||||
if (!inited) {
|
synchronized (WordPdfConverter.class) {
|
||||||
return;
|
if (!inited) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
dropNonBundled();
|
||||||
}
|
}
|
||||||
dropNonBundled();
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Удаляет из реестра всё, что не было выгружено из jar в {@link #extractDir}. */
|
/** Удаляет из реестра всё, что не было выгружено из jar в {@link #extractDir}. */
|
||||||
@@ -232,12 +247,18 @@ public final class BundledFonts {
|
|||||||
|
|
||||||
/**
|
/**
|
||||||
* Зарегистрированный шрифт: семейство (lowercase) + начертание.
|
* Зарегистрированный шрифт: семейство (lowercase) + начертание.
|
||||||
|
* Синхронизирован с {@link #init()} общим монитором
|
||||||
|
* {@code WordPdfConverter.class}: {@code VARIANTS} — обычный
|
||||||
|
* {@code HashMap}, наполняемый в {@code init()}; без замка внешний
|
||||||
|
* читатель мог бы увидеть недобранную карту.
|
||||||
*
|
*
|
||||||
* @return PhysicalFont или null (если init() не вызван или шрифта нет)
|
* @return PhysicalFont или null (если init() не вызван или шрифта нет)
|
||||||
*/
|
*/
|
||||||
public static PhysicalFont font(String family, String variant) {
|
public static PhysicalFont font(String family, String variant) {
|
||||||
Map<String, PhysicalFont> m = VARIANTS.get(family);
|
synchronized (WordPdfConverter.class) {
|
||||||
return m == null ? null : m.get(variant);
|
Map<String, PhysicalFont> m = VARIANTS.get(family);
|
||||||
|
return m == null ? null : m.get(variant);
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
public static PhysicalFont regular(String family) {
|
public static PhysicalFont regular(String family) {
|
||||||
|
|||||||
@@ -38,6 +38,12 @@ import java.util.Map;
|
|||||||
* каталога {@link BundledFonts#init()} — поэтому класс не зависит от
|
* каталога {@link BundledFonts#init()} — поэтому класс не зависит от
|
||||||
* порядка шагов конвертации. TTF буферизуется в памяти и живёт до конца
|
* порядка шагов конвертации. TTF буферизуется в памяти и живёт до конца
|
||||||
* JVM (шрифты бандла конечны, {@link TrueTypeFont} намеренно не закрываем).
|
* JVM (шрифты бандла конечны, {@link TrueTypeFont} намеренно не закрываем).
|
||||||
|
*
|
||||||
|
* Потокобезопасен: {@link #of(String, String)} идёт под монитором класса
|
||||||
|
* (единый {@code CACHE}), {@code cmap} — {@code volatile} поле с
|
||||||
|
* идемпотентным пересчётом, а ленивые таблицы fontbox читаются под её
|
||||||
|
* внутренними замками ({@code TrueTypeFont.lockReadtable}, fontbox 3.x) —
|
||||||
|
* один экземпляр можно держать в нескольких потоках.
|
||||||
*/
|
*/
|
||||||
public final class GlyphFont {
|
public final class GlyphFont {
|
||||||
|
|
||||||
|
|||||||
@@ -13,7 +13,7 @@ import java.util.regex.Pattern;
|
|||||||
/**
|
/**
|
||||||
* Нормализация ST_OnOff-значений в docx перед загрузкой docx4j.
|
* Нормализация ST_OnOff-значений в docx перед загрузкой docx4j.
|
||||||
*
|
*
|
||||||
* docx4j 11.x теряет атрибуты {@code w:val="off"} / {@code w:val="on"}
|
* docx4j 17.x теряет атрибуты {@code w:val="off"} / {@code w:val="on"}
|
||||||
* при JAXB-разборе (тип поля {@code Boolean} не принимает "on"/"off",
|
* при JAXB-разборе (тип поля {@code Boolean} не принимает "on"/"off",
|
||||||
* поле остаётся null и {@code BooleanDefaultTrue.isVal()} считается
|
* поле остаётся null и {@code BooleanDefaultTrue.isVal()} считается
|
||||||
* true). Из-за этого явные {@code <w:b w:val="off"/>} и
|
* true). Из-за этого явные {@code <w:b w:val="off"/>} и
|
||||||
@@ -22,9 +22,14 @@ import java.util.regex.Pattern;
|
|||||||
* docx4j разбирает корректно, поэтому заменяем "off"->"false",
|
* docx4j разбирает корректно, поэтому заменяем "off"->"false",
|
||||||
* "on"->"true" в XML-частях word/*.xml.
|
* "on"->"true" в XML-частях word/*.xml.
|
||||||
*
|
*
|
||||||
|
* <p>Исключение — {@code w:scrollbar} (свойство фрейма, §17.15.2.37): его
|
||||||
|
* {@code w:val} — ST_FrameScrollbar (none/left/right/leftAndRight,
|
||||||
|
* §17.18.32), единственный не-ST_OnOff носитель on/off в WML; переписывать
|
||||||
|
* его нельзя — вывод станет невалидным.
|
||||||
|
*
|
||||||
* Если совпадений нет, возвращает исходный массив без переупаковки zip.
|
* Если совпадений нет, возвращает исходный массив без переупаковки zip.
|
||||||
*/
|
*/
|
||||||
public final class DocxOnOffNormalizer {
|
final class DocxOnOffNormalizer {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* {@code w:val="on"/"off"} только внутри открывающего тега: group 1 — от
|
* {@code w:val="on"/"off"} только внутри открывающего тега: group 1 — от
|
||||||
@@ -33,15 +38,12 @@ public final class DocxOnOffNormalizer {
|
|||||||
* {@code w:t} не правится. Регрессия — DocxOnOffNormalizerTest#onOffInTextNotTouched.
|
* {@code w:t} не правится. Регрессия — DocxOnOffNormalizerTest#onOffInTextNotTouched.
|
||||||
*/
|
*/
|
||||||
private static final Pattern ON_OFF = Pattern.compile(
|
private static final Pattern ON_OFF = Pattern.compile(
|
||||||
"(<[A-Za-z][A-Za-z0-9:]*(?:\\s[^<>]*)?)w:val=([\"'])(on|off)\\2",
|
"(<(?!w:scrollbar\\b)[A-Za-z][A-Za-z0-9:]*(?:\\s[^<>]*)?)w:val=([\"'])(on|off)\\2",
|
||||||
Pattern.CASE_INSENSITIVE);
|
Pattern.CASE_INSENSITIVE);
|
||||||
|
|
||||||
private DocxOnOffNormalizer() {
|
private DocxOnOffNormalizer() {
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
|
|
||||||
public static final DocxNormalizer STEP = DocxOnOffNormalizer::normalize;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Заменяет в XML-частях docx (word/*.xml) w:val="off"/"on"
|
* Заменяет в XML-частях docx (word/*.xml) w:val="off"/"on"
|
||||||
* на "false"/"true".
|
* на "false"/"true".
|
||||||
@@ -49,7 +51,7 @@ public final class DocxOnOffNormalizer {
|
|||||||
* @param docx байты .docx (zip)
|
* @param docx байты .docx (zip)
|
||||||
* @return те же или переупакованные байты
|
* @return те же или переупакованные байты
|
||||||
*/
|
*/
|
||||||
public static byte[] normalize(byte[] docx) throws IOException {
|
static byte[] normalize(byte[] docx) throws IOException {
|
||||||
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
||||||
boolean changed = false;
|
boolean changed = false;
|
||||||
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
||||||
|
|||||||
@@ -15,12 +15,14 @@ import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
|
|||||||
/**
|
/**
|
||||||
* Единый zip-проход переписывания XML-частей (.docx) вместо отдельных
|
* Единый zip-проход переписывания XML-частей (.docx) вместо отдельных
|
||||||
* проходов нормализаторов: к каждой записи {@code word/*.xml} применяются
|
* проходов нормализаторов: к каждой записи {@code word/*.xml} применяются
|
||||||
* все десять рерайтов в фиксированном порядке
|
* все одиннадцать рерайтов в фиксированном порядке
|
||||||
* Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby.
|
* Strict→OnOff→Symbol→Field→Invisible→MathFallback→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby.
|
||||||
* Порядок значим: Strict первым — дальше части в transitional-виде
|
* Порядок значим: Strict первым — дальше части в transitional-виде
|
||||||
* (TableIndent читает transitional-атрибуты {@code w:}); GlyphCoverage
|
* (TableIndent читает transitional-атрибуты {@code w:}); MathFallback
|
||||||
|
* шестым — flatten unsupported-формул даёт обычный текст ранов, который
|
||||||
|
* следующий GlyphCoverage покрывает кириллицей бандла; GlyphCoverage
|
||||||
* режет раны по финальному тексту рана (после Symbol/Invisible); Hidden
|
* режет раны по финальному тексту рана (после Symbol/Invisible); Hidden
|
||||||
* последним — вырезает уже финальные раны (после Symbol/GLYPH-разбиений),
|
* девятым — вырезает уже финальные раны (после Symbol/GLYPH-разбиений),
|
||||||
* а его OnOff-форма vanish читается после правила 2. Каждый
|
* а его OnOff-форма vanish читается после правила 2. Каждый
|
||||||
* рерайт работает только содержимым одной части, поэтому по-частная
|
* рерайт работает только содержимым одной части, поэтому по-частная
|
||||||
* цепочка эквивалентна последовательным полным проходам. Исключения из
|
* цепочка эквивалентна последовательным полным проходам. Исключения из
|
||||||
@@ -52,13 +54,13 @@ public final class DocxRewritePipeline {
|
|||||||
public static final DocxNormalizer STEP = DocxRewritePipeline::normalize;
|
public static final DocxNormalizer STEP = DocxRewritePipeline::normalize;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Применяет десять рерайтов к каждой записи {@code word/*.xml} за один
|
* Применяет одиннадцать рерайтов к каждой записи {@code word/*.xml} за один
|
||||||
* проход zip.
|
* проход zip.
|
||||||
*
|
*
|
||||||
* @param docx байты .docx (валидный zip)
|
* @param docx байты .docx (валидный zip)
|
||||||
* @return те же или переупакованные байты
|
* @return те же или переупакованные байты
|
||||||
*/
|
*/
|
||||||
public static byte[] normalize(byte[] docx) throws IOException {
|
static byte[] normalize(byte[] docx) throws IOException {
|
||||||
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
||||||
boolean changed = false;
|
boolean changed = false;
|
||||||
try (ZipFile zf = new ZipFile(new SeekableInMemoryByteChannel(docx));
|
try (ZipFile zf = new ZipFile(new SeekableInMemoryByteChannel(docx));
|
||||||
@@ -66,7 +68,8 @@ public final class DocxRewritePipeline {
|
|||||||
// Ширина полосы набора для правила 7 (таблицы в header/footer-
|
// Ширина полосы набора для правила 7 (таблицы в header/footer-
|
||||||
// частях своей sectPr не содержат): из сырого document.xml —
|
// частях своей sectPr не содержат): из сырого document.xml —
|
||||||
// геометрия инвариантна к рерайтам цепочки (Strict не трогает
|
// геометрия инвариантна к рерайтам цепочки (Strict не трогает
|
||||||
// w:pgSz/@w:w, а pgMar-чередование left|start покрывает strict).
|
// w:pgSz/@w:w; у strict CT_PageMar start/end нет вовсе —
|
||||||
|
// только left/right).
|
||||||
// Записи нет/несколько секций → −1, header/footer консервативно
|
// Записи нет/несколько секций → −1, header/footer консервативно
|
||||||
// пропускаются (та же неоднозначность полосы, что для body).
|
// пропускаются (та же неоднозначность полосы, что для body).
|
||||||
int band = -1;
|
int band = -1;
|
||||||
@@ -113,6 +116,10 @@ public final class DocxRewritePipeline {
|
|||||||
if (next != null) {
|
if (next != null) {
|
||||||
cur = next;
|
cur = next;
|
||||||
}
|
}
|
||||||
|
next = MathFallbackNormalizer.rewrite(cur);
|
||||||
|
if (next != null) {
|
||||||
|
cur = next;
|
||||||
|
}
|
||||||
next = GlyphCoverageNormalizer.rewrite(cur);
|
next = GlyphCoverageNormalizer.rewrite(cur);
|
||||||
if (next != null) {
|
if (next != null) {
|
||||||
cur = next;
|
cur = next;
|
||||||
@@ -133,7 +140,7 @@ public final class DocxRewritePipeline {
|
|||||||
if (next != null) {
|
if (next != null) {
|
||||||
cur = next;
|
cur = next;
|
||||||
}
|
}
|
||||||
if (cur != xml) {
|
if (!cur.equals(xml)) {
|
||||||
changed = true;
|
changed = true;
|
||||||
rewritten = cur.getBytes(StandardCharsets.UTF_8);
|
rewritten = cur.getBytes(StandardCharsets.UTF_8);
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -36,7 +36,7 @@ import java.util.zip.ZipOutputStream;
|
|||||||
* разбираются — если внутри {@code begin … end} встречается ещё один
|
* разбираются — если внутри {@code begin … end} встречается ещё один
|
||||||
* {@code begin}, поле пропускается.
|
* {@code begin}, поле пропускается.
|
||||||
*/
|
*/
|
||||||
public final class FieldNormalizer {
|
final class FieldNormalizer {
|
||||||
|
|
||||||
/** Инструкции, для которых в docx4j-export-fo есть обработчик fldSimple. */
|
/** Инструкции, для которых в docx4j-export-fo есть обработчик fldSimple. */
|
||||||
private static final String[] SUPPORTED = {"PAGE", "NUMPAGES", "SECTIONPAGES"};
|
private static final String[] SUPPORTED = {"PAGE", "NUMPAGES", "SECTIONPAGES"};
|
||||||
@@ -44,16 +44,13 @@ public final class FieldNormalizer {
|
|||||||
private FieldNormalizer() {
|
private FieldNormalizer() {
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
|
|
||||||
public static final DocxNormalizer STEP = FieldNormalizer::normalize;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Переписывает поддерживаемые поля во всех word/*.xml частях docx.
|
* Переписывает поддерживаемые поля во всех word/*.xml частях docx.
|
||||||
*
|
*
|
||||||
* @param docx байты .docx (zip)
|
* @param docx байты .docx (zip)
|
||||||
* @return те же или переупакованные байты
|
* @return те же или переупакованные байты
|
||||||
*/
|
*/
|
||||||
public static byte[] normalize(byte[] docx) throws IOException {
|
static byte[] normalize(byte[] docx) throws IOException {
|
||||||
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
||||||
boolean changed = false;
|
boolean changed = false;
|
||||||
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
||||||
|
|||||||
@@ -26,7 +26,16 @@ import ru.pjandro.wordpdf.fonts.BundledFonts;
|
|||||||
* рендерится шрифтом просмотрщика либо .notdef («#»). Поэтому в конфиг
|
* рендерится шрифтом просмотрщика либо .notdef («#»). Поэтому в конфиг
|
||||||
* добавляются ВСЕ шрифты бандла: стоит они в документе или нет, решает FO.
|
* добавляются ВСЕ шрифты бандла: стоит они в документе или нет, решает FO.
|
||||||
*
|
*
|
||||||
* Метод идемпотентен: уже задекларированное семейство не дублируется.
|
* Конфиг обязан быть полным при каждом {@code declare}: общая FopFactory
|
||||||
|
* ({@code WordPdfConverter.sharedFopFactory}) строится из fopconf первого
|
||||||
|
* документа JVM, а docx4j декларирует из {@code fontsInUse} только
|
||||||
|
* использованные начертания — {@code declareFamily} дополняет семейство
|
||||||
|
* недостающими реальными начертаниями, а не пропускает его целиком.
|
||||||
|
* Идемпотентность: начертание, уже имеющее в конфиге запись на реальном
|
||||||
|
* TTF, не дублируется.
|
||||||
|
*
|
||||||
|
* <p>Регрессия — FopFallbackFontsTest#declareWhenDocx4jDeclaredRegularOnly_addsMissingVariants,
|
||||||
|
* WordPdfConverterTest#fopFactoryFrozenFromFirstDoc_fontsComplete.
|
||||||
*/
|
*/
|
||||||
public final class FopFallbackFonts {
|
public final class FopFallbackFonts {
|
||||||
|
|
||||||
@@ -49,7 +58,15 @@ public final class FopFallbackFonts {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Одно семейство: regular + существующие начертания (Noto — только regular). */
|
/**
|
||||||
|
* Одно семейство: каждое начертание, для которого в конфиге нет
|
||||||
|
* записи с реальным TTF этого начертания (Noto — только regular,
|
||||||
|
* отсутствующие варианты пропускаются). Family-level «уже есть —
|
||||||
|
* пропускаем всё» запрещён: docx4j декларирует только использованные
|
||||||
|
* начертания (или simulate-style на одном файле), а общая FopFactory
|
||||||
|
* замораживает конфиг первого документа на всю JVM — пропущенное
|
||||||
|
* семейство остаётся неполным для всех последующих конвертаций.
|
||||||
|
*/
|
||||||
private static void declareFamily(Fonts rendererFonts, ObjectFactory factory,
|
private static void declareFamily(Fonts rendererFonts, ObjectFactory factory,
|
||||||
String family) {
|
String family) {
|
||||||
PhysicalFont regular = BundledFonts.regular(family);
|
PhysicalFont regular = BundledFonts.regular(family);
|
||||||
@@ -61,21 +78,43 @@ public final class FopFallbackFonts {
|
|||||||
// и под это же имя декларируются все начертания (так делает
|
// и под это же имя декларируются все начертания (так делает
|
||||||
// docx4j FopConfigUtil.createVariant).
|
// docx4j FopConfigUtil.createVariant).
|
||||||
String familyName = regular.getName();
|
String familyName = regular.getName();
|
||||||
for (Fonts.Font existing : rendererFonts.getFont()) {
|
String[][] variants = {
|
||||||
for (Fonts.Font.FontTriplet triplet : existing.getFontTriplet()) {
|
{BundledFonts.V_REGULAR, "normal", "normal"},
|
||||||
if (familyName.equals(triplet.getName())) {
|
{BundledFonts.V_BOLD, "normal", "bold"},
|
||||||
return;
|
{BundledFonts.V_ITALIC, "italic", "normal"},
|
||||||
|
{BundledFonts.V_BOLD_ITALIC, "italic", "bold"},
|
||||||
|
};
|
||||||
|
for (String[] v : variants) {
|
||||||
|
PhysicalFont variant = BundledFonts.font(family, v[0]);
|
||||||
|
if (variant == null
|
||||||
|
|| hasRealFace(rendererFonts, familyName, v[1], v[2], variant)) {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
addFont(rendererFonts, factory, familyName, variant, v[1], v[2]);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Есть ли в конфиге запись триплета (familyName, style, weight) именно
|
||||||
|
* на реальном TTF {@code variant}. Триплет без этого embed-url
|
||||||
|
* (simulate-style docx4j — все начертания на regular-файле) реальным
|
||||||
|
* лицом не считается: FOP встроит из него не то начертание.
|
||||||
|
*/
|
||||||
|
private static boolean hasRealFace(Fonts rendererFonts, String familyName,
|
||||||
|
String style, String weight, PhysicalFont variant) {
|
||||||
|
String url = variant.getEmbeddedURI().toString();
|
||||||
|
for (Fonts.Font font : rendererFonts.getFont()) {
|
||||||
|
if (!url.equals(font.getEmbedUrl())) {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
for (Fonts.Font.FontTriplet triplet : font.getFontTriplet()) {
|
||||||
|
if (familyName.equals(triplet.getName()) && style.equals(triplet.getStyle())
|
||||||
|
&& weight.equals(triplet.getWeight())) {
|
||||||
|
return true;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
return false;
|
||||||
addFont(rendererFonts, factory, familyName, regular, "normal", "normal");
|
|
||||||
addFont(rendererFonts, factory, familyName,
|
|
||||||
BundledFonts.bold(family), "normal", "bold");
|
|
||||||
addFont(rendererFonts, factory, familyName,
|
|
||||||
BundledFonts.italic(family), "italic", "normal");
|
|
||||||
addFont(rendererFonts, factory, familyName,
|
|
||||||
BundledFonts.boldItalic(family), "italic", "bold");
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
package ru.pjandro.wordpdf.internal;
|
package ru.pjandro.wordpdf.internal;
|
||||||
|
|
||||||
import ru.pjandro.wordpdf.fonts.BundledFontMapper;
|
import ru.pjandro.wordpdf.fonts.BundledFontAliases;
|
||||||
import ru.pjandro.wordpdf.fonts.BundledFonts;
|
import ru.pjandro.wordpdf.fonts.BundledFonts;
|
||||||
import ru.pjandro.wordpdf.fonts.GlyphFont;
|
import ru.pjandro.wordpdf.fonts.GlyphFont;
|
||||||
|
|
||||||
@@ -38,7 +38,7 @@ import java.util.concurrent.ConcurrentHashMap;
|
|||||||
* Делаем то, что должен был сделать рендер: ран, в тексте которого есть
|
* Делаем то, что должен был сделать рендер: ран, в тексте которого есть
|
||||||
* знаки без глифа, разрезается на части, и каждой части явно назначается
|
* знаки без глифа, разрезается на части, и каждой части явно назначается
|
||||||
* бандл-семейство, где глиф есть ({@link #targetFamily}). Имя пишется в
|
* бандл-семейство, где глиф есть ({@link #targetFamily}). Имя пишется в
|
||||||
* {@code w:rFonts}, дальше {@link BundledFontMapper} маппит его на TTF,
|
* {@code w:rFonts}, дальше {@code BundledFontMapper} маппит его на TTF,
|
||||||
* а {@link FopFallbackFonts} декларирует его в FOP-конфиге.
|
* а {@link FopFallbackFonts} декларирует его в FOP-конфиге.
|
||||||
*
|
*
|
||||||
* Правила, ограничивающие вмешательство:
|
* Правила, ограничивающие вмешательство:
|
||||||
@@ -54,7 +54,7 @@ import java.util.concurrent.ConcurrentHashMap;
|
|||||||
*
|
*
|
||||||
* Как и {@link SymbolFontNormalizer}, правим байты zip до JAXB-разбора.
|
* Как и {@link SymbolFontNormalizer}, правим байты zip до JAXB-разбора.
|
||||||
*/
|
*/
|
||||||
public final class GlyphCoverageNormalizer {
|
final class GlyphCoverageNormalizer {
|
||||||
|
|
||||||
/** Семейства с засечками: для них fallback ищется сначала среди serif. */
|
/** Семейства с засечками: для них fallback ищется сначала среди serif. */
|
||||||
private static final List<String> SERIF_FAMILIES =
|
private static final List<String> SERIF_FAMILIES =
|
||||||
@@ -81,16 +81,13 @@ public final class GlyphCoverageNormalizer {
|
|||||||
private GlyphCoverageNormalizer() {
|
private GlyphCoverageNormalizer() {
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
|
|
||||||
public static final DocxNormalizer STEP = GlyphCoverageNormalizer::normalize;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Разрезает раны с непокрытыми глифами в XML-частях docx (word/*.xml).
|
* Разрезает раны с непокрытыми глифами в XML-частях docx (word/*.xml).
|
||||||
*
|
*
|
||||||
* @param docx байты .docx (zip)
|
* @param docx байты .docx (zip)
|
||||||
* @return те же или переупакованные байты
|
* @return те же или переупакованные байты
|
||||||
*/
|
*/
|
||||||
public static byte[] normalize(byte[] docx) throws IOException {
|
static byte[] normalize(byte[] docx) throws IOException {
|
||||||
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
||||||
boolean changed = false;
|
boolean changed = false;
|
||||||
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
||||||
@@ -409,7 +406,7 @@ public final class GlyphCoverageNormalizer {
|
|||||||
if (!m.find()) {
|
if (!m.find()) {
|
||||||
return null;
|
return null;
|
||||||
}
|
}
|
||||||
return BundledFontMapper.bundledFamily(m.group(2));
|
return BundledFontAliases.bundledFamily(m.group(2));
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -417,7 +414,7 @@ public final class GlyphCoverageNormalizer {
|
|||||||
* {@code w:rFonts}, а если их нет — вставляет элемент первым ребёнком.
|
* {@code w:rFonts}, а если их нет — вставляет элемент первым ребёнком.
|
||||||
*/
|
*/
|
||||||
private static String forceFont(String rPr, String family) {
|
private static String forceFont(String rPr, String family) {
|
||||||
String name = BundledFontMapper.documentFontName(family);
|
String name = BundledFontAliases.documentFontName(family);
|
||||||
String fonts = "<w:rFonts w:ascii=\"" + name + "\" w:hAnsi=\"" + name + "\"/>";
|
String fonts = "<w:rFonts w:ascii=\"" + name + "\" w:hAnsi=\"" + name + "\"/>";
|
||||||
if (rPr.isEmpty()) {
|
if (rPr.isEmpty()) {
|
||||||
return "<w:rPr>" + fonts + "</w:rPr>";
|
return "<w:rPr>" + fonts + "</w:rPr>";
|
||||||
|
|||||||
@@ -24,7 +24,7 @@ import org.apache.commons.compress.archivers.zip.ZipFile;
|
|||||||
import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
|
import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Вырезание скрытых ранов ({@code w:rPr/w:vanish}, Part 1 §17.3.2.30) из
|
* Вырезание скрытых ранов ({@code w:rPr/w:vanish}, Part 1 §17.3.2.41) из
|
||||||
* XML-частей — до загрузки docx4j.
|
* XML-частей — до загрузки docx4j.
|
||||||
*
|
*
|
||||||
* <p>Word по умолчанию не выводит скрытый текст ни на экран, ни на печать,
|
* <p>Word по умолчанию не выводит скрытый текст ни на экран, ни на печать,
|
||||||
@@ -39,8 +39,13 @@ import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
|
|||||||
* правило 2 к моменту запуска уже привело on/off к true/false, но обе формы
|
* правило 2 к моменту запуска уже привело on/off к true/false, но обе формы
|
||||||
* принимаются) либо {@code w:rStyle} ссылается на стиль с vanish — по
|
* принимаются) либо {@code w:rStyle} ссылается на стиль с vanish — по
|
||||||
* цепочке {@code w:basedOn} (капа 16, цикл — обрыв; тот же приём, что
|
* цепочке {@code w:basedOn} (капа 16, цикл — обрыв; тот же приём, что
|
||||||
* {@code internal/doc/Styles}). Прямой vanish ранa перекрывает стилевой;
|
* {@code internal/doc/Styles}). Прямой vanish ранa перекрывает стилевой
|
||||||
* вложенные раны ({@code w:rubyBase}/{@code w:rt}, текстовые боксы)
|
* (§17.7.3: в конфликте toggle выигрывает direct formatting); принятое
|
||||||
|
* упрощение стилевого слоя — явный falsy {@code w:val} <b>у стиля</b>
|
||||||
|
* (vanish=false поверх vanish-предка по {@code w:basedOn}) не
|
||||||
|
* разворачивается: стиль с {@code w:vanish} делает раны скрытыми
|
||||||
|
* независимо от {@code w:val}; вложенные раны
|
||||||
|
* ({@code w:rubyBase}/{@code w:rt}, текстовые боксы)
|
||||||
* оцениваются независимо, но ран внутри уже удалённого внешнего не
|
* оцениваются независимо, но ран внутри уже удалённого внешнего не
|
||||||
* вырезается повторно (диапазоны сливаются при сборке).
|
* вырезается повторно (диапазоны сливаются при сборке).
|
||||||
*
|
*
|
||||||
@@ -64,7 +69,7 @@ import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
|
|||||||
*
|
*
|
||||||
* <p>Регрессия — WordPdfConverterTest#hiddenText_notPrinted.
|
* <p>Регрессия — WordPdfConverterTest#hiddenText_notPrinted.
|
||||||
*/
|
*/
|
||||||
public final class HiddenTextNormalizer {
|
final class HiddenTextNormalizer {
|
||||||
|
|
||||||
/** Капа цепочки {@code w:basedOn} (образец — {@code doc.Styles.MAX_CHAIN}). */
|
/** Капа цепочки {@code w:basedOn} (образец — {@code doc.Styles.MAX_CHAIN}). */
|
||||||
private static final int MAX_CHAIN = 16;
|
private static final int MAX_CHAIN = 16;
|
||||||
@@ -72,6 +77,10 @@ public final class HiddenTextNormalizer {
|
|||||||
/** Закрывающий слэш самозакрывающегося тега. */
|
/** Закрывающий слэш самозакрывающегося тега. */
|
||||||
private static final char SELF_CLOSE = '/';
|
private static final char SELF_CLOSE = '/';
|
||||||
|
|
||||||
|
/** Части, которые рерайт пропускает: ранов там нет, а vanish в styles — входные данные. */
|
||||||
|
private static final String STYLES_PART = "word/styles.xml";
|
||||||
|
private static final String NUMBERING_PART = "word/numbering.xml";
|
||||||
|
|
||||||
/** Открывающий/закрывающий тег рана; {@code <w:rPr>}/{@code <w:rStyle>} и прочее не матчатся по границе имени. */
|
/** Открывающий/закрывающий тег рана; {@code <w:rPr>}/{@code <w:rStyle>} и прочее не матчатся по границе имени. */
|
||||||
private static final Pattern RUN_TOKEN = Pattern.compile("<w:r(?=[ >/])|</w:r>");
|
private static final Pattern RUN_TOKEN = Pattern.compile("<w:r(?=[ >/])|</w:r>");
|
||||||
|
|
||||||
@@ -97,9 +106,6 @@ public final class HiddenTextNormalizer {
|
|||||||
private HiddenTextNormalizer() {
|
private HiddenTextNormalizer() {
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
|
|
||||||
public static final DocxNormalizer STEP = HiddenTextNormalizer::normalize;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Вырезает скрытые раны (только прямой {@code w:vanish}) из XML-частей
|
* Вырезает скрытые раны (только прямой {@code w:vanish}) из XML-частей
|
||||||
* docx; {@code word/styles.xml}/{@code word/numbering.xml} пропускаются.
|
* docx; {@code word/styles.xml}/{@code word/numbering.xml} пропускаются.
|
||||||
@@ -107,10 +113,10 @@ public final class HiddenTextNormalizer {
|
|||||||
* @param docx байты .docx (zip)
|
* @param docx байты .docx (zip)
|
||||||
* @return те же или переупакованные байты
|
* @return те же или переупакованные байты
|
||||||
*/
|
*/
|
||||||
public static byte[] normalize(byte[] docx) throws IOException {
|
static byte[] normalize(byte[] docx) throws IOException {
|
||||||
Set<String> vanishStyles = Set.of();
|
Set<String> vanishStyles = Set.of();
|
||||||
try (ZipFile zf = new ZipFile(new SeekableInMemoryByteChannel(docx))) {
|
try (ZipFile zf = new ZipFile(new SeekableInMemoryByteChannel(docx))) {
|
||||||
ZipArchiveEntry styles = zf.getEntry("word/styles.xml");
|
ZipArchiveEntry styles = zf.getEntry(STYLES_PART);
|
||||||
if (styles != null) {
|
if (styles != null) {
|
||||||
vanishStyles = vanishStyles(new String(
|
vanishStyles = vanishStyles(new String(
|
||||||
zf.getInputStream(styles).readAllBytes(), StandardCharsets.UTF_8));
|
zf.getInputStream(styles).readAllBytes(), StandardCharsets.UTF_8));
|
||||||
@@ -152,7 +158,7 @@ public final class HiddenTextNormalizer {
|
|||||||
* @return новая строка либо null, если менять нечего
|
* @return новая строка либо null, если менять нечего
|
||||||
*/
|
*/
|
||||||
static String rewritePart(String name, String xml, Set<String> vanishStyleIds) {
|
static String rewritePart(String name, String xml, Set<String> vanishStyleIds) {
|
||||||
if ("word/styles.xml".equals(name) || "word/numbering.xml".equals(name)) {
|
if (STYLES_PART.equals(name) || NUMBERING_PART.equals(name)) {
|
||||||
return null;
|
return null;
|
||||||
}
|
}
|
||||||
return rewrite(vanishStyleIds, xml);
|
return rewrite(vanishStyleIds, xml);
|
||||||
@@ -309,6 +315,9 @@ public final class HiddenTextNormalizer {
|
|||||||
if (hasTruthyVanish(region)) {
|
if (hasTruthyVanish(region)) {
|
||||||
return true;
|
return true;
|
||||||
}
|
}
|
||||||
|
if (hasExplicitFalsyVanish(region)) {
|
||||||
|
return false; // явный w:val=false/0/off перекрывает стилевой vanish (§17.7.3)
|
||||||
|
}
|
||||||
if (!vanishStyleIds.isEmpty()) {
|
if (!vanishStyleIds.isEmpty()) {
|
||||||
Matcher r = RSTYLE.matcher(region);
|
Matcher r = RSTYLE.matcher(region);
|
||||||
if (r.find() && vanishStyleIds.contains(r.group(1))) {
|
if (r.find() && vanishStyleIds.contains(r.group(1))) {
|
||||||
@@ -360,7 +369,7 @@ public final class HiddenTextNormalizer {
|
|||||||
String tag = end < 0 ? region.substring(i) : region.substring(i, end + 1);
|
String tag = end < 0 ? region.substring(i) : region.substring(i, end + 1);
|
||||||
Matcher v = VAL_ATTR.matcher(tag);
|
Matcher v = VAL_ATTR.matcher(tag);
|
||||||
if (!v.find()) {
|
if (!v.find()) {
|
||||||
return true; // вал опущен — default true (Part 1 §17.3.2.30)
|
return true; // вал опущен — default true (Part 1 §17.3.2.41)
|
||||||
}
|
}
|
||||||
if (truthy(v.group(1))) {
|
if (truthy(v.group(1))) {
|
||||||
return true;
|
return true;
|
||||||
@@ -372,11 +381,21 @@ public final class HiddenTextNormalizer {
|
|||||||
return false;
|
return false;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** truthy по Part 1 §17.18.69 ST_OnOff: false/0/off — выключено, прочее — включено. */
|
/** truthy по Part 1 §22.9.2.7 ST_OnOff: false/0/off — выключено, прочее — включено. */
|
||||||
private static boolean truthy(String val) {
|
private static boolean truthy(String val) {
|
||||||
return !"false".equalsIgnoreCase(val) && !"0".equals(val) && !"off".equalsIgnoreCase(val);
|
return !"false".equalsIgnoreCase(val) && !"0".equals(val) && !"off".equalsIgnoreCase(val);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** Явный falsy {@code w:vanish} (val=false/0/off) — перекрытие стилевого. */
|
||||||
|
private static final Pattern FALSY_VANISH =
|
||||||
|
Pattern.compile("<w:vanish\\b[^>]*w:val=\"(?:false|0|off)\"",
|
||||||
|
Pattern.CASE_INSENSITIVE);
|
||||||
|
|
||||||
|
/** Есть ли в регионе явный falsy {@code w:vanish} (val=false/0/off). */
|
||||||
|
private static boolean hasExplicitFalsyVanish(String region) {
|
||||||
|
return FALSY_VANISH.matcher(region).find();
|
||||||
|
}
|
||||||
|
|
||||||
/** Есть ли защищённый элемент в содержимом рана [from, to). */
|
/** Есть ли защищённый элемент в содержимом рана [from, to). */
|
||||||
private static boolean hasProtected(String xml, int from, int to) {
|
private static boolean hasProtected(String xml, int from, int to) {
|
||||||
for (String p : PROTECTED) {
|
for (String p : PROTECTED) {
|
||||||
|
|||||||
@@ -27,9 +27,10 @@ import java.util.zip.ZipOutputStream;
|
|||||||
* в невидимый DejaVu — FOP рисует «тофу» прямо в тексте.</li>
|
* в невидимый DejaVu — FOP рисует «тофу» прямо в тексте.</li>
|
||||||
* </ul>
|
* </ul>
|
||||||
*
|
*
|
||||||
* Zero-width знаки, значимые для shaping и переносов (U+00A0, U+00AD,
|
* NBSP (U+00A0, ширина пробела — не zero-width) и zero-width знаки, значимые
|
||||||
* U+200B, U+200C, U+200D), НЕ трогаем: во всех шрифтах бандла они
|
* для shaping и переносов (U+00AD, U+200B, U+200C, U+200D), НЕ трогаем:
|
||||||
* нулевой ширины и пустых строк не создают.
|
* во всех шрифтах бандла NBSP широк, остальное нулевой ширины, и ни то ни
|
||||||
|
* другое пустых строк не создаёт.
|
||||||
*
|
*
|
||||||
* Правим байты zip до JAXB-разбора, как остальные нормализаторы; запускается
|
* Правим байты zip до JAXB-разбора, как остальные нормализаторы; запускается
|
||||||
* до {@link GlyphCoverageNormalizer}, чтобы тот не искал шрифт для уже
|
* до {@link GlyphCoverageNormalizer}, чтобы тот не искал шрифт для уже
|
||||||
@@ -38,7 +39,7 @@ import java.util.zip.ZipOutputStream;
|
|||||||
* Регрессия — WordPdfConverterTest#invisibleChars_noEmptyLines,
|
* Регрессия — WordPdfConverterTest#invisibleChars_noEmptyLines,
|
||||||
* WordPdfConverterTest#invisibleChars_arimoBoxesNotDrawn.
|
* WordPdfConverterTest#invisibleChars_arimoBoxesNotDrawn.
|
||||||
*/
|
*/
|
||||||
public final class InvisibleCharNormalizer {
|
final class InvisibleCharNormalizer {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Коды на вырезание: явные переносы FOP (U+0085, U+2028, U+2029),
|
* Коды на вырезание: явные переносы FOP (U+0085, U+2028, U+2029),
|
||||||
@@ -86,9 +87,6 @@ public final class InvisibleCharNormalizer {
|
|||||||
private InvisibleCharNormalizer() {
|
private InvisibleCharNormalizer() {
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
|
|
||||||
public static final DocxNormalizer STEP = InvisibleCharNormalizer::normalize;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Вырезает невидимые символы из текстовых узлов XML-частей docx
|
* Вырезает невидимые символы из текстовых узлов XML-частей docx
|
||||||
* (word/*.xml).
|
* (word/*.xml).
|
||||||
@@ -96,7 +94,7 @@ public final class InvisibleCharNormalizer {
|
|||||||
* @param docx байты .docx (zip)
|
* @param docx байты .docx (zip)
|
||||||
* @return те же или переупакованные байты
|
* @return те же или переупакованные байты
|
||||||
*/
|
*/
|
||||||
public static byte[] normalize(byte[] docx) throws IOException {
|
static byte[] normalize(byte[] docx) throws IOException {
|
||||||
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
||||||
boolean changed = false;
|
boolean changed = false;
|
||||||
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
||||||
|
|||||||
@@ -0,0 +1,268 @@
|
|||||||
|
package ru.pjandro.wordpdf.internal;
|
||||||
|
|
||||||
|
import ru.pjandro.wordpdf.internal.chart.MathModel;
|
||||||
|
|
||||||
|
import java.util.ArrayList;
|
||||||
|
import java.util.HashMap;
|
||||||
|
import java.util.HashSet;
|
||||||
|
import java.util.List;
|
||||||
|
import java.util.Map;
|
||||||
|
import java.util.Set;
|
||||||
|
import java.util.regex.Matcher;
|
||||||
|
import java.util.regex.Pattern;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Байтовый скан формул OMML (§22.1): блок {@code m:oMathPara}/{@code m:oMath},
|
||||||
|
* содержащий math-элемент вне {@link MathModel#SUPPORTED}, заменяется раном с
|
||||||
|
* конкатенацией текста {@code m:t} (как штатный фолбэк docx4j
|
||||||
|
* {@code XsltFOFunctions.mathText}) — формула видна текстом, а не теряется.
|
||||||
|
*
|
||||||
|
* <p>Зачем скан до загрузки docx4j: собственный растер формул
|
||||||
|
* ({@code MathModel}/{@code MathRenderer} в {@code DrawingPreRenderer})
|
||||||
|
* уронил бы unsupported-конструкцию в {@code MathUnsupportedException} и
|
||||||
|
* деградировал тем же текстом — но скан даёт детерминизм «формула целиком
|
||||||
|
* текстом» для байтового уровня пайплайна и не зависит от JAXB-биндинга.
|
||||||
|
* Рантайм-деградация остаётся второй сетью (биндинг может не смонтировать
|
||||||
|
* неизвестный элемент, который скан увидел).
|
||||||
|
*
|
||||||
|
* <p>Скан namespace-aware: префиксы, привязанные к math-URI на корневом
|
||||||
|
* элементе (+ переопределения {@code xmlns} внутри блока), — unsupported
|
||||||
|
* проверяется только для тегов в math-namespace; префиксы чужих namespace'ов
|
||||||
|
* ( {@code w:rPr} внутри рана формулы) игнорируются. Непривязанный/отсутствующий
|
||||||
|
* map объявлений при наличии {@code :oMath} — консервативная обработка «как
|
||||||
|
* math» (риск потерять контент при недобитом биндинге сильнее избыточной
|
||||||
|
* деградации).
|
||||||
|
*
|
||||||
|
* <p>Позиция в цепочке — шестое правило, перед GlyphCoverage: flatten даёт
|
||||||
|
* обычный текст ранов, который следующий рерайт покрывает кириллицей бандла
|
||||||
|
* (раньше формулы с {@code м} теряли глифы именно из-за порядка —
|
||||||
|
* GlyphCoverage не видел текст внутри OMML). Блок para заменяется первым:
|
||||||
|
* {@code m:oMathPara} содержит {@code m:oMath}, иначе остался бы
|
||||||
|
* несбалансированный каркас.
|
||||||
|
*/
|
||||||
|
final class MathFallbackNormalizer {
|
||||||
|
|
||||||
|
/** Закрывающий символ открывающего тега (скан конца корня формулы). */
|
||||||
|
private static final char TAG_END = '>';
|
||||||
|
|
||||||
|
/** Math-namespace OMML (§22.1). */
|
||||||
|
private static final String MATH_NS =
|
||||||
|
"http://schemas.openxmlformats.org/officeDocument/2006/math";
|
||||||
|
|
||||||
|
/** Объявление {@code xmlns:prefix="uri"} (значение без кавычек). */
|
||||||
|
private static final Pattern XMLNS = Pattern.compile(
|
||||||
|
"xmlns:([A-Za-z_][\\w.-]*)=\"([^\"]*)\"");
|
||||||
|
|
||||||
|
/** Начало блока формулы; префикс обязателен (без него {@code :oMath} нет). */
|
||||||
|
private static final Pattern MATH_BLOCK = Pattern.compile(
|
||||||
|
"<([A-Za-z_][\\w.-]*):oMath(Para)?(?=[\\s/>])");
|
||||||
|
|
||||||
|
/** Элементный тег с префиксом {@code <p:name>} / {@code </p:name>}. */
|
||||||
|
private static final Pattern PREFIXED_TAG = Pattern.compile(
|
||||||
|
"</?([A-Za-z_][\\w.-]*):([A-Za-z_][\\w.-]*)");
|
||||||
|
|
||||||
|
/** Текстовый узел {@code <p:t>}; содержимое — уже экранированный XML. */
|
||||||
|
private static final Pattern MATH_TEXT = Pattern.compile(
|
||||||
|
"<([A-Za-z_][\\w.-]*):t(?:\\s[^>]*)?>(.*?)</\\1:t>", Pattern.DOTALL);
|
||||||
|
|
||||||
|
private MathFallbackNormalizer() {
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Рерайт одной XML-части: unsupported-формулы → текст. Формул нет /
|
||||||
|
* все поддерживаются / ничего не изменилось → {@code null}
|
||||||
|
* (пайплайн отдаёт тот же массив).
|
||||||
|
*/
|
||||||
|
static String rewrite(String xml) {
|
||||||
|
if (!xml.contains(":oMath")) {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
Map<String, String> rootNs = rootNamespaces(xml);
|
||||||
|
StringBuilder out = new StringBuilder();
|
||||||
|
int pos = 0;
|
||||||
|
boolean changed = false;
|
||||||
|
Matcher m = MATH_BLOCK.matcher(xml);
|
||||||
|
int search = 0;
|
||||||
|
while (m.find(search)) {
|
||||||
|
String prefix = m.group(1);
|
||||||
|
boolean para = m.group(2) != null;
|
||||||
|
int start = m.start();
|
||||||
|
int tagEnd = tagEnd(xml, start);
|
||||||
|
if (tagEnd < 0) {
|
||||||
|
break; // незакрытый тег — дело валидатора, скан останавливаем
|
||||||
|
}
|
||||||
|
Map<String, String> ns = mergedNamespaces(rootNs, xml.substring(start, tagEnd));
|
||||||
|
if (!isMath(ns, prefix)) {
|
||||||
|
search = tagEnd;
|
||||||
|
continue; // чужой namespace — не формула
|
||||||
|
}
|
||||||
|
int blockEnd;
|
||||||
|
int before = tagEnd - 2;
|
||||||
|
while (before > start && Character.isWhitespace(xml.charAt(before))) {
|
||||||
|
before--;
|
||||||
|
}
|
||||||
|
boolean selfClosing = xml.charAt(before) == '/';
|
||||||
|
if (selfClosing) {
|
||||||
|
blockEnd = tagEnd;
|
||||||
|
} else {
|
||||||
|
String closing = "</" + prefix + ":oMath" + (para ? "Para" : "") + ">";
|
||||||
|
int close = xml.indexOf(closing, tagEnd);
|
||||||
|
if (close < 0) {
|
||||||
|
break; // битый каркас — валидатор его и отвергнет
|
||||||
|
}
|
||||||
|
blockEnd = close + closing.length();
|
||||||
|
}
|
||||||
|
String block = xml.substring(start, blockEnd);
|
||||||
|
if (hasUnsupported(ns, block)) {
|
||||||
|
out.append(xml, pos, start).append(run(text(ns, block)));
|
||||||
|
pos = blockEnd;
|
||||||
|
changed = true;
|
||||||
|
search = blockEnd;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
search = tagEnd;
|
||||||
|
}
|
||||||
|
if (!changed) {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
return out.append(xml, pos, xml.length()).toString();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Объявления {@code xmlns:} фактического корневого элемента: пролог
|
||||||
|
* ({@code <?xml ...?>}, комментарии, DOCTYPE) пропускается — иначе
|
||||||
|
* карта осталась бы пустой на реальном XML-файле части, а пустая карта
|
||||||
|
* консервативно считает каждый префикс math-тегом и срезает боевые
|
||||||
|
* формулы (внутри {@code m:r}/{@code m:ctrlPr} Word пишет
|
||||||
|
* {@code w:rPr}/{@code w:rFonts} — имена вне SUPPORTED).
|
||||||
|
*/
|
||||||
|
private static Map<String, String> rootNamespaces(String xml) {
|
||||||
|
Map<String, String> map = new HashMap<>();
|
||||||
|
int pos = 0;
|
||||||
|
while (pos < xml.length()) {
|
||||||
|
int open = xml.indexOf('<', pos);
|
||||||
|
if (open < 0) {
|
||||||
|
return map;
|
||||||
|
}
|
||||||
|
if (xml.startsWith("<?", open)) {
|
||||||
|
int end = xml.indexOf("?>", open);
|
||||||
|
pos = end < 0 ? xml.length() : end + 2;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (xml.startsWith("<!--", open)) {
|
||||||
|
int end = xml.indexOf("-->", open);
|
||||||
|
pos = end < 0 ? xml.length() : end + 3;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (xml.startsWith("<!", open)) {
|
||||||
|
int end = xml.indexOf('>', open);
|
||||||
|
pos = end < 0 ? xml.length() : end + 1;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
int end = tagEnd(xml, open);
|
||||||
|
if (end < 0) {
|
||||||
|
return map;
|
||||||
|
}
|
||||||
|
Matcher m = XMLNS.matcher(xml.substring(open, end));
|
||||||
|
while (m.find()) {
|
||||||
|
map.put(m.group(1), m.group(2));
|
||||||
|
}
|
||||||
|
return map;
|
||||||
|
}
|
||||||
|
return map;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Корневые объявления + переопределения из заголовка блока. */
|
||||||
|
private static Map<String, String> mergedNamespaces(Map<String, String> root,
|
||||||
|
String openTag) {
|
||||||
|
Matcher m = XMLNS.matcher(openTag);
|
||||||
|
if (!m.find()) {
|
||||||
|
return root;
|
||||||
|
}
|
||||||
|
Map<String, String> map = new HashMap<>(root);
|
||||||
|
m.reset();
|
||||||
|
while (m.find()) {
|
||||||
|
map.put(m.group(1), m.group(2));
|
||||||
|
}
|
||||||
|
return map;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Привязан ли префикс к math-namespace: явная привязка — да; привязка к
|
||||||
|
* другому URI — нет; префикс не объявлен нигде — да (консервативно, см.
|
||||||
|
* javadoc класса), если только вообще нет ни одного объявления xmlns
|
||||||
|
* (тогда это не XML с map префиксов, а мусор — тоже «как math»).
|
||||||
|
*/
|
||||||
|
private static boolean isMath(Map<String, String> ns, String prefix) {
|
||||||
|
String bound = ns.get(prefix);
|
||||||
|
if (MATH_NS.equals(bound)) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
return bound == null;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Есть ли в блоке тег math-namespace вне {@link MathModel#SUPPORTED}. */
|
||||||
|
private static boolean hasUnsupported(Map<String, String> ns, String block) {
|
||||||
|
List<String> mathPrefixes = new ArrayList<>();
|
||||||
|
for (Map.Entry<String, String> e : ns.entrySet()) {
|
||||||
|
if (MATH_NS.equals(e.getValue())) {
|
||||||
|
mathPrefixes.add(e.getKey());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
Matcher m = PREFIXED_TAG.matcher(block);
|
||||||
|
while (m.find()) {
|
||||||
|
String prefix = m.group(1);
|
||||||
|
String name = m.group(2);
|
||||||
|
boolean mathTag = mathPrefixes.contains(prefix)
|
||||||
|
|| (mathPrefixes.isEmpty() && !ns.containsKey(prefix));
|
||||||
|
if (mathTag && !MathModel.SUPPORTED.contains(name)) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Текст формулы: конкатенация {@code m:t} math-префиксов (как mathText). */
|
||||||
|
private static String text(Map<String, String> ns, String block) {
|
||||||
|
Set<String> mathPrefixes = new HashSet<>();
|
||||||
|
for (Map.Entry<String, String> e : ns.entrySet()) {
|
||||||
|
if (MATH_NS.equals(e.getValue())) {
|
||||||
|
mathPrefixes.add(e.getKey());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
StringBuilder sb = new StringBuilder();
|
||||||
|
Matcher m = MATH_TEXT.matcher(block);
|
||||||
|
while (m.find()) {
|
||||||
|
String prefix = m.group(1);
|
||||||
|
if (mathPrefixes.contains(prefix)
|
||||||
|
|| (mathPrefixes.isEmpty() && !ns.containsKey(prefix))) {
|
||||||
|
sb.append(m.group(2));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return sb.toString();
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Конец открывающего тега (индекс после {@code >}), кавычки-осведомлённый. */
|
||||||
|
private static int tagEnd(String xml, int start) {
|
||||||
|
char quote = 0;
|
||||||
|
for (int i = start + 1; i < xml.length(); i++) {
|
||||||
|
char c = xml.charAt(i);
|
||||||
|
if (quote != 0) {
|
||||||
|
if (c == quote) {
|
||||||
|
quote = 0;
|
||||||
|
}
|
||||||
|
} else if (c == '"' || c == '\'') {
|
||||||
|
quote = c;
|
||||||
|
} else if (c == TAG_END) {
|
||||||
|
return i + 1;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Ран с текстом формулы; пустая формула удаляется. */
|
||||||
|
private static String run(String text) {
|
||||||
|
return text.isEmpty() ? ""
|
||||||
|
: "<w:r><w:t xml:space=\"preserve\">" + text + "</w:t></w:r>";
|
||||||
|
}
|
||||||
|
}
|
||||||
+4
-6
@@ -16,7 +16,8 @@ import java.util.zip.ZipOutputStream;
|
|||||||
*
|
*
|
||||||
* Word рисует после номера лейбла разделитель по {@code w:suff}: tab —
|
* Word рисует после номера лейбла разделитель по {@code w:suff}: tab —
|
||||||
* табуляция до позиционного отступа, space — обычный пробел, nothing — ничего
|
* табуляция до позиционного отступа, space — обычный пробел, nothing — ничего
|
||||||
* (Part 1 §17.3.1.28). docx4j/export-fo разделитель не эмитит вовсе: в FO
|
* (Part 1 §17.9.28, тип — ST_LevelSuffix §17.18.46). docx4j/export-fo
|
||||||
|
* разделитель не эмитит вовсе: в FO
|
||||||
* уходит только текст лейбла («1.»), хинт {@code docx4j:label-suffix} —
|
* уходит только текст лейбла («1.»), хинт {@code docx4j:label-suffix} —
|
||||||
* заготовка без обработчика (дамп n4.fo аудита раскладки). Для suff=tab это
|
* заготовка без обработчика (дамп n4.fo аудита раскладки). Для suff=tab это
|
||||||
* отдельный Class C-остаток (нужна per-item ширина), а suff=space чинится
|
* отдельный Class C-остаток (нужна per-item ширина), а suff=space чинится
|
||||||
@@ -29,7 +30,7 @@ import java.util.zip.ZipOutputStream;
|
|||||||
* заканчивающийся пробелом lvlText не дублируется. suff=tab/absent/nothing —
|
* заканчивающийся пробелом lvlText не дублируется. suff=tab/absent/nothing —
|
||||||
* не трогаем. Нечего менять → тот же массив.
|
* не трогаем. Нечего менять → тот же массив.
|
||||||
*/
|
*/
|
||||||
public final class NumberingSuffixNormalizer {
|
final class NumberingSuffixNormalizer {
|
||||||
|
|
||||||
private static final Pattern SUFF_SPACE =
|
private static final Pattern SUFF_SPACE =
|
||||||
Pattern.compile("<w:suff\\b[^>]*w:val=\"space\"[^>]*/>");
|
Pattern.compile("<w:suff\\b[^>]*w:val=\"space\"[^>]*/>");
|
||||||
@@ -38,16 +39,13 @@ public final class NumberingSuffixNormalizer {
|
|||||||
private NumberingSuffixNormalizer() {
|
private NumberingSuffixNormalizer() {
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
|
|
||||||
public static final DocxNormalizer STEP = NumberingSuffixNormalizer::normalize;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Дописывает пробел в lvlText у уровней с suff=space.
|
* Дописывает пробел в lvlText у уровней с suff=space.
|
||||||
*
|
*
|
||||||
* @param docx байты .docx (zip)
|
* @param docx байты .docx (zip)
|
||||||
* @return те же или переупакованные байты
|
* @return те же или переупакованные байты
|
||||||
*/
|
*/
|
||||||
public static byte[] normalize(byte[] docx) throws IOException {
|
static byte[] normalize(byte[] docx) throws IOException {
|
||||||
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
||||||
boolean changed = false;
|
boolean changed = false;
|
||||||
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
||||||
|
|||||||
@@ -1,9 +1,10 @@
|
|||||||
package ru.pjandro.wordpdf.internal;
|
package ru.pjandro.wordpdf.internal;
|
||||||
|
|
||||||
import ru.pjandro.wordpdf.DrawingFoundException;
|
import ru.pjandro.wordpdf.OleFoundException;
|
||||||
|
|
||||||
import java.io.ByteArrayOutputStream;
|
import java.io.ByteArrayOutputStream;
|
||||||
import java.io.IOException;
|
import java.io.IOException;
|
||||||
|
import java.io.InputStream;
|
||||||
import java.nio.charset.StandardCharsets;
|
import java.nio.charset.StandardCharsets;
|
||||||
import java.util.ArrayList;
|
import java.util.ArrayList;
|
||||||
import java.util.HashMap;
|
import java.util.HashMap;
|
||||||
@@ -41,13 +42,14 @@ import org.apache.commons.compress.utils.SeekableInMemoryByteChannel;
|
|||||||
* по ECMA-376 §15.2.10 у каждого внедрённого объекта обязан быть «associated
|
* по ECMA-376 §15.2.10 у каждого внедрённого объекта обязан быть «associated
|
||||||
* image, which appears in the document as a placeholder» — именно его показывает
|
* image, which appears in the document as a placeholder» — именно его показывает
|
||||||
* Word вместо объекта, — поэтому {@code w:object} заменяется его статичным
|
* Word вместо объекта, — поэтому {@code w:object} заменяется его статичным
|
||||||
* представлением (картинкой-плейсхолдером, §17.3.3.3); без плейсхолдера блок
|
* представлением (картинкой-плейсхолдером, §17.3.3.19; картинка — §17.3.3.9);
|
||||||
|
* без плейсхолдера блок
|
||||||
* удаляется. OLE-бинарники при этом никогда не читаются — байты только
|
* удаляется. OLE-бинарники при этом никогда не читаются — байты только
|
||||||
* удаляются, так что содержимое объекта (вплоть до враждебного архива) на
|
* удаляются, так что содержимое объекта (вплоть до враждебного архива) на
|
||||||
* вывод не влияет.</p>
|
* вывод не влияет.</p>
|
||||||
*
|
*
|
||||||
* <p>Отличие от остальных нормализаторов пакета: принимает флаг
|
* <p>Отличие от остальных нормализаторов пакета: принимает флаг
|
||||||
* {@code errorOnOle} и умеет бросать {@link DrawingFoundException}
|
* {@code errorOnOle} и умеет бросать {@link OleFoundException}
|
||||||
* (при включённом флаге документ отвергается вместо вычистки), и правит
|
* (при включённом флаге документ отвергается вместо вычистки), и правит
|
||||||
* не только {@code word/*.xml}, но и {@code [Content_Types].xml} с
|
* не только {@code word/*.xml}, но и {@code [Content_Types].xml} с
|
||||||
* {@code *.rels}. Хука {@code rewrite(String)} нет — нормализатор
|
* {@code *.rels}. Хука {@code rewrite(String)} нет — нормализатор
|
||||||
@@ -74,6 +76,9 @@ public final class OleObjectNormalizer {
|
|||||||
/** Сегмент «наверх» в относительном Target rels. */
|
/** Сегмент «наверх» в относительном Target rels. */
|
||||||
private static final String PARENT_DIR = "..";
|
private static final String PARENT_DIR = "..";
|
||||||
|
|
||||||
|
/** Сегмент «текущий каталог» в относительном Target rels. */
|
||||||
|
private static final String CURRENT_DIR = ".";
|
||||||
|
|
||||||
private static final Pattern DEFAULT_TYPE = Pattern.compile(
|
private static final Pattern DEFAULT_TYPE = Pattern.compile(
|
||||||
"<Default\\b[^>]*\\bExtension=\"([^\"]*)\"[^>]*\\bContentType=\"([^\"]*)\"[^>]*/>"
|
"<Default\\b[^>]*\\bExtension=\"([^\"]*)\"[^>]*\\bContentType=\"([^\"]*)\"[^>]*/>"
|
||||||
+ "|<Default\\b[^>]*\\bContentType=\"([^\"]*)\"[^>]*\\bExtension=\"([^\"]*)\"[^>]*/>");
|
+ "|<Default\\b[^>]*\\bContentType=\"([^\"]*)\"[^>]*\\bExtension=\"([^\"]*)\"[^>]*/>");
|
||||||
@@ -135,9 +140,46 @@ public final class OleObjectNormalizer {
|
|||||||
|
|
||||||
private static final Logger LOG = Logger.getLogger(OleObjectNormalizer.class.getName());
|
private static final Logger LOG = Logger.getLogger(OleObjectNormalizer.class.getName());
|
||||||
|
|
||||||
|
/** Детект `w:object` по байтам: ASCII-литерал в UTF-8 не может
|
||||||
|
* встретиться внутри многобайтовой последовательности, поэтому поиск
|
||||||
|
* по сырым байтам эквивалентен `new String(...).contains(...)`. */
|
||||||
|
private static final byte[] OBJECT_NEEDLE = "<w:object".getBytes(StandardCharsets.US_ASCII);
|
||||||
|
|
||||||
private OleObjectNormalizer() {
|
private OleObjectNormalizer() {
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Поиск ASCII-литерала в потоке окном 8 KiB с перекрытием
|
||||||
|
* {@code needle.length - 1} байт на границе окна — без материализации
|
||||||
|
* всей XML-части (document.xml десятки МБ дублировались в память ради
|
||||||
|
* поиска 9-байтного литерала).
|
||||||
|
*/
|
||||||
|
private static boolean containsAscii(InputStream in, byte[] needle) throws IOException {
|
||||||
|
try (in) {
|
||||||
|
byte[] window = new byte[8192];
|
||||||
|
int carried = 0; // байт перенесённого хвоста предыдущего окна
|
||||||
|
int read;
|
||||||
|
while ((read = in.read(window, carried, window.length - carried)) > 0) {
|
||||||
|
int limit = carried + read;
|
||||||
|
for (int i = 0; i + needle.length <= limit; i++) {
|
||||||
|
boolean hit = true;
|
||||||
|
for (int j = 0; j < needle.length; j++) {
|
||||||
|
if (window[i + j] != needle[j]) {
|
||||||
|
hit = false;
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (hit) {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
carried = Math.min(needle.length - 1, limit);
|
||||||
|
System.arraycopy(window, limit - carried, window, 0, carried);
|
||||||
|
}
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Вычистляет из docx OLE-объекты: бинарные `.bin`-части с OLE-типом (или
|
* Вычистляет из docx OLE-объекты: бинарные `.bin`-части с OLE-типом (или
|
||||||
* ложным XML-типом), ссылки на них и oleObject-ссылки (включая External) в
|
* ложным XML-типом), ссылки на них и oleObject-ссылки (включая External) в
|
||||||
@@ -183,8 +225,7 @@ public final class OleObjectNormalizer {
|
|||||||
oleParts.add(name);
|
oleParts.add(name);
|
||||||
}
|
}
|
||||||
} else if (!hasObjectMarkup && name.startsWith("word/") && name.endsWith(".xml")
|
} else if (!hasObjectMarkup && name.startsWith("word/") && name.endsWith(".xml")
|
||||||
&& new String(zf.getInputStream(entry).readAllBytes(),
|
&& containsAscii(zf.getInputStream(entry), OBJECT_NEEDLE)) {
|
||||||
StandardCharsets.UTF_8).contains("<w:object")) {
|
|
||||||
// сам w:object — уже OLE: без bin-части он всё равно роняет docx4j
|
// сам w:object — уже OLE: без bin-части он всё равно роняет docx4j
|
||||||
// (NPE chunkType is null) и обязан быть переписан
|
// (NPE chunkType is null) и обязан быть переписан
|
||||||
hasObjectMarkup = true;
|
hasObjectMarkup = true;
|
||||||
@@ -194,7 +235,7 @@ public final class OleObjectNormalizer {
|
|||||||
return docx;
|
return docx;
|
||||||
}
|
}
|
||||||
if (errorOnOle) {
|
if (errorOnOle) {
|
||||||
throw new DrawingFoundException(DrawingFoundException.Kind.OLE);
|
throw new OleFoundException();
|
||||||
}
|
}
|
||||||
for (String part : oleParts) {
|
for (String part : oleParts) {
|
||||||
LOG.warning("Удалён OLE-объект: " + part);
|
LOG.warning("Удалён OLE-объект: " + part);
|
||||||
@@ -222,7 +263,7 @@ public final class OleObjectNormalizer {
|
|||||||
if (fixed != null) {
|
if (fixed != null) {
|
||||||
data = fixed.getBytes(StandardCharsets.UTF_8);
|
data = fixed.getBytes(StandardCharsets.UTF_8);
|
||||||
}
|
}
|
||||||
} else if (name.equals(CONTENT_TYPES_ENTRY)) {
|
} else if (CONTENT_TYPES_ENTRY.equals(name)) {
|
||||||
String fixed = stripOverrides(
|
String fixed = stripOverrides(
|
||||||
new String(data, StandardCharsets.UTF_8), oleParts);
|
new String(data, StandardCharsets.UTF_8), oleParts);
|
||||||
if (fixed != null) {
|
if (fixed != null) {
|
||||||
@@ -336,7 +377,7 @@ public final class OleObjectNormalizer {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
for (String s : target.split("/")) {
|
for (String s : target.split("/")) {
|
||||||
if (s.isEmpty() || ".".equals(s)) {
|
if (s.isEmpty() || CURRENT_DIR.equals(s)) {
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
if (PARENT_DIR.equals(s)) {
|
if (PARENT_DIR.equals(s)) {
|
||||||
@@ -352,7 +393,7 @@ public final class OleObjectNormalizer {
|
|||||||
|
|
||||||
/**
|
/**
|
||||||
* Заменяет в word/*.xml каждый w:object его статичным представлением
|
* Заменяет в word/*.xml каждый w:object его статичным представлением
|
||||||
* (плейсхолдером, ECMA-376 §15.2.10/§17.3.3.3): блок с `w:control`
|
* (плейсхолдером, ECMA-376 §15.2.10/§17.3.3.19): блок с `w:control`
|
||||||
* (ActiveX) удаляется целиком — property bag всё равно остаётся сиротой;
|
* (ActiveX) удаляется целиком — property bag всё равно остаётся сиротой;
|
||||||
* блок с `w:drawing` (ветка mc:Choice) заменяется этим drawing дословно;
|
* блок с `w:drawing` (ветка mc:Choice) заменяется этим drawing дословно;
|
||||||
* блок с `v:imagedata r:id` заменяется inline-DrawingML на ту же
|
* блок с `v:imagedata r:id` заменяется inline-DrawingML на ту же
|
||||||
|
|||||||
@@ -10,8 +10,9 @@ import java.util.zip.ZipInputStream;
|
|||||||
import java.util.zip.ZipOutputStream;
|
import java.util.zip.ZipOutputStream;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Разбор руби-разметки ({@code w:rubyBase}/{@code w:rt}/{@code w:rubyPr},
|
* Разбор руби-разметки ({@code w:ruby}/{@code w:rubyBase}/{@code w:rt}/
|
||||||
* Part 1 §17.3.3.19/.20/.21) в байтах до загрузки docx4j.
|
* {@code w:rubyPr}/{@code w:rubyAlign}, Part 1 §17.3.3.25/.27/.24/.28/.26)
|
||||||
|
* в байтах до загрузки docx4j.
|
||||||
*
|
*
|
||||||
* <p>Джинябиндованные схемы docx4j 17.3.2 {@code w:rubyBase}/{@code w:rt}
|
* <p>Джинябиндованные схемы docx4j 17.3.2 {@code w:rubyBase}/{@code w:rt}
|
||||||
* в {@code w:r} <b>не содержат</b> (unmarshaller сообщает «unexpected
|
* в {@code w:r} <b>не содержат</b> (unmarshaller сообщает «unexpected
|
||||||
@@ -20,11 +21,13 @@ import java.util.zip.ZipOutputStream;
|
|||||||
* (в отличие от {@code w:moveFrom}/{@code w:moveTo}/{@code w:bdo}/{@code w:dir},
|
* (в отличие от {@code w:moveFrom}/{@code w:moveTo}/{@code w:bdo}/{@code w:dir},
|
||||||
* которые схема знает). Единственный слой починки — байтовый нормализатор.
|
* которые схема знает). Единственный слой починки — байтовый нормализатор.
|
||||||
*
|
*
|
||||||
* <p>Деградация принята: база ({@code w:rubyBase}/{@code w:rubyBaseText})
|
* <p>Деградация принята: база ({@code w:rubyBase}) разворачивается в обычные
|
||||||
* разворачивается в обычные раны ранa — текст печатается; надстрочница
|
* раны ранa — текст печатается; надстрочница ({@code w:rt}) и форматирование
|
||||||
* ({@code w:rt}) и форматирование руби ({@code w:rubyPr}, {@code w:rubyAlign})
|
* руби ({@code w:rubyPr}, {@code w:rubyAlign}) удаляются вместе с содержимым
|
||||||
* удаляются вместе с содержимым — ruby-разметки в XSL-FO у FOP нет, а потеря
|
* — ruby-разметки в XSL-FO у FOP нет, а потеря текста хуже потери аннотации.
|
||||||
* текста хуже потери аннотации.
|
* Снимается и обёртка {@code w:ruby}: схемно-валидная разметка (транзишнл
|
||||||
|
* CT_R: {@code w:r} → {@code w:ruby} → rubyPr/rt/rubyBase, wml.xsd) иначе
|
||||||
|
* достаёт catch-all-шаблону XSLT и база теряется молча.
|
||||||
*
|
*
|
||||||
* <p>В конвейере подключается десятым рерайтом в {@link DocxRewritePipeline}
|
* <p>В конвейере подключается десятым рерайтом в {@link DocxRewritePipeline}
|
||||||
* (после Hidden; порядок 1–8 не перенумеровать); в
|
* (после Hidden; порядок 1–8 не перенумеровать); в
|
||||||
@@ -33,7 +36,7 @@ import java.util.zip.ZipOutputStream;
|
|||||||
*
|
*
|
||||||
* <p>Регрессия — WordPdfConverterTest#rubyBase_textPrinted.
|
* <p>Регрессия — WordPdfConverterTest#rubyBase_textPrinted.
|
||||||
*/
|
*/
|
||||||
public final class RubyNormalizer {
|
final class RubyNormalizer {
|
||||||
|
|
||||||
private RubyNormalizer() {
|
private RubyNormalizer() {
|
||||||
}
|
}
|
||||||
@@ -46,18 +49,21 @@ public final class RubyNormalizer {
|
|||||||
private static final Pattern RUBY_PR_BLOCK =
|
private static final Pattern RUBY_PR_BLOCK =
|
||||||
Pattern.compile("<w:rubyPr(?:\\s[^>]*)?(?:/>|>.*?</w:rubyPr>)", Pattern.DOTALL);
|
Pattern.compile("<w:rubyPr(?:\\s[^>]*)?(?:/>|>.*?</w:rubyPr>)", Pattern.DOTALL);
|
||||||
|
|
||||||
/** Одиночный {@code w:rubyPr}. */
|
/** Одиночный {@code w:rubyAlign}. */
|
||||||
private static final Pattern RUBY_ALIGN =
|
private static final Pattern RUBY_ALIGN =
|
||||||
Pattern.compile("<w:rubyAlign(?:\\s[^>]*)?(?:/>|>\\s*</w:rubyAlign>)", Pattern.DOTALL);
|
Pattern.compile("<w:rubyAlign(?:\\s[^>]*)?(?:/>|>\\s*</w:rubyAlign>)", Pattern.DOTALL);
|
||||||
|
|
||||||
private static final Pattern RUBY_BASE_OPEN =
|
private static final Pattern RUBY_BASE_OPEN =
|
||||||
Pattern.compile("<w:rubyBase(?:\\s[^>]*)?>");
|
Pattern.compile("<w:rubyBase(?:\\s[^>]*)?>");
|
||||||
private static final Pattern RUBY_BASE_TEXT_OPEN =
|
|
||||||
Pattern.compile("<w:rubyBaseText(?:\\s[^>]*)?>");
|
/** Обёртка {@code w:ruby} (снимается: ран разворачивается в обычные раны). */
|
||||||
|
private static final Pattern RUBY_OPEN =
|
||||||
|
Pattern.compile("<w:ruby(?:\\s[^>]*)?>");
|
||||||
|
private static final String RUBY_CLOSE = "</w:ruby>";
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Рерайт одной XML-строки: разворачивает {@code w:rubyBase}/
|
* Рерайт одной XML-строки: разворачивает {@code w:rubyBase}, снимает
|
||||||
* {@code w:rubyBaseText}, вырезает {@code w:rt}/{@code w:rubyPr}/
|
* обёртку {@code w:ruby}, вырезает {@code w:rt}/{@code w:rubyPr}/
|
||||||
* {@code w:rubyAlign}. Руби-токенов нет / ничего не поменялось → {@code null}.
|
* {@code w:rubyAlign}. Руби-токенов нет / ничего не поменялось → {@code null}.
|
||||||
*/
|
*/
|
||||||
static String rewrite(String xml) {
|
static String rewrite(String xml) {
|
||||||
@@ -67,10 +73,10 @@ public final class RubyNormalizer {
|
|||||||
String out = RT_BLOCK.matcher(xml).replaceAll("");
|
String out = RT_BLOCK.matcher(xml).replaceAll("");
|
||||||
out = RUBY_PR_BLOCK.matcher(out).replaceAll("");
|
out = RUBY_PR_BLOCK.matcher(out).replaceAll("");
|
||||||
out = RUBY_ALIGN.matcher(out).replaceAll("");
|
out = RUBY_ALIGN.matcher(out).replaceAll("");
|
||||||
out = RUBY_BASE_TEXT_OPEN.matcher(out).replaceAll("");
|
|
||||||
out = out.replace("</w:rubyBaseText>", "");
|
|
||||||
out = RUBY_BASE_OPEN.matcher(out).replaceAll("");
|
out = RUBY_BASE_OPEN.matcher(out).replaceAll("");
|
||||||
out = out.replace("</w:rubyBase>", "");
|
out = out.replace("</w:rubyBase>", "");
|
||||||
|
out = RUBY_OPEN.matcher(out).replaceAll("");
|
||||||
|
out = out.replace(RUBY_CLOSE, "");
|
||||||
return out.equals(xml) ? null : out;
|
return out.equals(xml) ? null : out;
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -78,7 +84,7 @@ public final class RubyNormalizer {
|
|||||||
* Индивидуальный контракт {@link DocxNormalizer} (тесты); в конвейере
|
* Индивидуальный контракт {@link DocxNormalizer} (тесты); в конвейере
|
||||||
* {@link DocxRewritePipeline} вызывает {@link #rewrite} в общем проходе.
|
* {@link DocxRewritePipeline} вызывает {@link #rewrite} в общем проходе.
|
||||||
*/
|
*/
|
||||||
public static byte[] normalize(byte[] docx) throws IOException {
|
static byte[] normalize(byte[] docx) throws IOException {
|
||||||
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
||||||
boolean changed = false;
|
boolean changed = false;
|
||||||
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
||||||
|
|||||||
@@ -26,14 +26,17 @@ import java.util.zip.ZipOutputStream;
|
|||||||
* {@code w14:fillToRect w14:t="130%"} — JAXB падает на
|
* {@code w14:fillToRect w14:t="130%"} — JAXB падает на
|
||||||
* {@code NumberFormatException: Not a number: 130%};</li>
|
* {@code NumberFormatException: Not a number: 130%};</li>
|
||||||
* <li>текстовые проценты в {@code wp14:pctWidth}/{@code wp14:pctHeight};</li>
|
* <li>текстовые проценты в {@code wp14:pctWidth}/{@code wp14:pctHeight};</li>
|
||||||
* <li>границы и отступы в элементах {@code w:start}/{@code w:end}
|
* <li>границы и отступы в элементах {@code w:start}/{@code w:end} — в
|
||||||
* (в transitional они называются {@code w:left}/{@code w:right}) —
|
* strict-схеме это единственные имена, transitional-схема допускает
|
||||||
* JAXB сообщает «unexpected element» и границы теряются;</li>
|
* обе пары детей (wml.xsd CT_TcMar/CT_TblCellMar), но strict-часть их
|
||||||
|
* не пишет — JAXB transitional-модели сообщает «unexpected element»
|
||||||
|
* и границы теряются;</li>
|
||||||
* <li>атрибуты {@code w:start}/{@code w:end} у {@code w:ind} и значения
|
* <li>атрибуты {@code w:start}/{@code w:end} у {@code w:ind} и значения
|
||||||
* {@code start}/{@code end} у {@code w:jc}/{@code w:tab} — в strict-модели
|
* {@code start}/{@code end} у {@code w:jc}/{@code w:tab} — в strict-модели
|
||||||
* это единственные имена, а transitional-модель docx4j их не принимает
|
* это единственные имена, а transitional-модель docx4j их не принимает
|
||||||
* (значения {@code w:tab} — и подавно: enum {@code STTabJc} в docx4j
|
* (значения {@code w:tab} — и подавно: enum {@code STTabJc} в docx4j
|
||||||
* 17.3.2 содержит только left/right).</li>
|
* 17.3.2 содержит только left/center/right; в спековом ST_TabJc
|
||||||
|
* §17.18.84 start/end есть, но JAXB-enum их не принимает).</li>
|
||||||
* </ul>
|
* </ul>
|
||||||
*
|
*
|
||||||
* <p>Полный strict→transitional рерайт не делается: mc-preprocessor уже
|
* <p>Полный strict→transitional рерайт не делается: mc-preprocessor уже
|
||||||
@@ -72,12 +75,14 @@ import java.util.zip.ZipOutputStream;
|
|||||||
* RTL; ST_Jc §17.18.44); RTL вне контура конвейера (FOP без complex-script,
|
* RTL; ST_Jc §17.18.44); RTL вне контура конвейера (FOP без complex-script,
|
||||||
* direction docx4j не выставляет — start и так рендерился как left).</li>
|
* direction docx4j не выставляет — start и так рендерился как left).</li>
|
||||||
* <li>значения {@code start}/{@code end} у {@code w:tab} правятся всегда
|
* <li>значения {@code start}/{@code end} у {@code w:tab} правятся всегда
|
||||||
* (enum без start/end).</li>
|
* (enum {@code STTabJc} docx4j — left/center/right, без start/end;
|
||||||
|
* спека ST_TabJc §17.18.84 их содержит, но JAXB-биндинг их не
|
||||||
|
* принимает).</li>
|
||||||
* </ul>
|
* </ul>
|
||||||
*
|
*
|
||||||
* Регрессия — WordPdfConverterTest#strictOoxml_convertsNotRejected.
|
* Регрессия — WordPdfConverterTest#strictOoxml_convertsNotRejected.
|
||||||
*/
|
*/
|
||||||
public final class StrictOoxmlNormalizer {
|
final class StrictOoxmlNormalizer {
|
||||||
|
|
||||||
/** Открывающий тег элемента префикса {@code a:} (DrawingML). */
|
/** Открывающий тег элемента префикса {@code a:} (DrawingML). */
|
||||||
private static final Pattern A_TAG = Pattern.compile("<a:[A-Za-z]+\\b[^>]*>");
|
private static final Pattern A_TAG = Pattern.compile("<a:[A-Za-z]+\\b[^>]*>");
|
||||||
@@ -121,9 +126,6 @@ public final class StrictOoxmlNormalizer {
|
|||||||
private StrictOoxmlNormalizer() {
|
private StrictOoxmlNormalizer() {
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
|
|
||||||
public static final DocxNormalizer STEP = StrictOoxmlNormalizer::normalize;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Приводит strict-OOXML в XML-частях docx (word/*.xml) к виду, который
|
* Приводит strict-OOXML в XML-частях docx (word/*.xml) к виду, который
|
||||||
* разбирает JAXB-модель transitional (детали — в javadoc класса).
|
* разбирает JAXB-модель transitional (детали — в javadoc класса).
|
||||||
@@ -131,7 +133,7 @@ public final class StrictOoxmlNormalizer {
|
|||||||
* @param docx байты .docx (zip)
|
* @param docx байты .docx (zip)
|
||||||
* @return те же или переупакованные байты
|
* @return те же или переупакованные байты
|
||||||
*/
|
*/
|
||||||
public static byte[] normalize(byte[] docx) throws IOException {
|
static byte[] normalize(byte[] docx) throws IOException {
|
||||||
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
||||||
boolean changed = false;
|
boolean changed = false;
|
||||||
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
||||||
@@ -219,13 +221,14 @@ public final class StrictOoxmlNormalizer {
|
|||||||
|
|
||||||
/**
|
/**
|
||||||
* Атрибуты {@code w:start→w:left}/{@code w:end→w:right} только внутри
|
* Атрибуты {@code w:start→w:left}/{@code w:end→w:right} только внутри
|
||||||
* открывающего тега {@code w:ind} (MS-OI29500 §2.1.174a: start/end как
|
* открывающего тега {@code w:ind} (MS-OI29500 §2.1.44 (ind) плюс
|
||||||
* псевдонимы left/right в strict — единственный носитель w:ind) и только
|
* strict wml.xsd: {@code CT_Ind} знает только start/end — единственный
|
||||||
|
* носитель w:ind в strict) и только
|
||||||
* при отсутствии в нём {@code w:left}/{@code w:right}: CT_Ind
|
* при отсутствии в нём {@code w:left}/{@code w:right}: CT_Ind
|
||||||
* (transitional) допускает обе пары, дубль атрибута — не well-formed
|
* (transitional) допускает обе пары, дубль атрибута — не well-formed
|
||||||
* XML; литеральный текст {@code w:val}-вида в {@code w:t} не
|
* XML; литеральный текст {@code w:val}-вида в {@code w:t} не
|
||||||
* затрагивается. У {@code w:pgNumType} атрибут {@code w:start} — старт
|
* затрагивается. У {@code w:pgNumType} атрибут {@code w:start} — старт
|
||||||
* нумерации страниц, легален в transitional (Part 1 §17.13.7), — не
|
* нумерации страниц, легален в transitional (Part 1 §17.6.12), — не
|
||||||
* трогается (регрессия — pgNumTypeStartAttrUntouched).
|
* трогается (регрессия — pgNumTypeStartAttrUntouched).
|
||||||
*/
|
*/
|
||||||
private static String renameStartEndAttrs(String xml) {
|
private static String renameStartEndAttrs(String xml) {
|
||||||
|
|||||||
@@ -42,7 +42,7 @@ import java.util.zip.ZipOutputStream;
|
|||||||
*
|
*
|
||||||
* Как и {@link DocxOnOffNormalizer}, правим байты zip до JAXB-разбора.
|
* Как и {@link DocxOnOffNormalizer}, правим байты zip до JAXB-разбора.
|
||||||
*/
|
*/
|
||||||
public final class SymbolFontNormalizer {
|
final class SymbolFontNormalizer {
|
||||||
|
|
||||||
/** Семейство, на которое заменяются символьные шрифты (есть в jar). */
|
/** Семейство, на которое заменяются символьные шрифты (есть в jar). */
|
||||||
static final String REPLACEMENT_FAMILY = "DejaVu Sans";
|
static final String REPLACEMENT_FAMILY = "DejaVu Sans";
|
||||||
@@ -51,8 +51,9 @@ public final class SymbolFontNormalizer {
|
|||||||
* Имя шрифта (lowercase) -> таблица из 256 слотов по 4 hex-цифры:
|
* Имя шрифта (lowercase) -> таблица из 256 слотов по 4 hex-цифры:
|
||||||
* младший байт кода из PUA -> Unicode-код цели (0 — соответствия нет).
|
* младший байт кода из PUA -> Unicode-код цели (0 — соответствия нет).
|
||||||
* Источник — SymbolMapper из docx4j 17.x; сгенерировано, см. javadoc
|
* Источник — SymbolMapper из docx4j 17.x; сгенерировано, см. javadoc
|
||||||
* класса. Коды вне U+F000–U+F0FF (обычная ASCII-часть символьного
|
* класса. Прямые коды {@code w:sym} (≤0xFF, вне PUA) маппятся по той же
|
||||||
* шрифта) не переписываются.
|
* таблице как индекс символной cmap (§17.3.3.30); слот без маппинга, код
|
||||||
|
* >0xFF вне PUA или отсутствие font-map — элемент сохраняется как есть.
|
||||||
*/
|
*/
|
||||||
private static final Map<String, String> SYMBOL_MAPS = buildMaps();
|
private static final Map<String, String> SYMBOL_MAPS = buildMaps();
|
||||||
|
|
||||||
@@ -70,16 +71,13 @@ public final class SymbolFontNormalizer {
|
|||||||
private SymbolFontNormalizer() {
|
private SymbolFontNormalizer() {
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
|
|
||||||
public static final DocxNormalizer STEP = SymbolFontNormalizer::normalize;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Заменяет символьные шрифты в XML-частях docx (word/*.xml).
|
* Заменяет символьные шрифты в XML-частях docx (word/*.xml).
|
||||||
*
|
*
|
||||||
* @param docx байты .docx (zip)
|
* @param docx байты .docx (zip)
|
||||||
* @return те же или переупакованные байты
|
* @return те же или переупакованные байты
|
||||||
*/
|
*/
|
||||||
public static byte[] normalize(byte[] docx) throws IOException {
|
static byte[] normalize(byte[] docx) throws IOException {
|
||||||
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
||||||
boolean changed = false;
|
boolean changed = false;
|
||||||
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
||||||
@@ -311,14 +309,20 @@ public final class SymbolFontNormalizer {
|
|||||||
char mapped = 0;
|
char mapped = 0;
|
||||||
if (charHex != null && fontMap != null) {
|
if (charHex != null && fontMap != null) {
|
||||||
char code = (char) Integer.parseInt(charHex, 16);
|
char code = (char) Integer.parseInt(charHex, 16);
|
||||||
if (code >= 0xF000 && code <= 0xF0FF) {
|
// PUA-форма (U+F0xx) и прямая (код ≤0xFF — индекс в символной
|
||||||
mapped = mapped(fontMap, code & 0xFF);
|
// cmap, §17.3.3.30) маппятся по одной таблице
|
||||||
}
|
int slot = (code >= 0xF000 && code <= 0xF0FF) ? code & 0xFF
|
||||||
|
: (code <= 0xFF ? code : -1);
|
||||||
|
mapped = slot >= 0 ? mapped(fontMap, slot) : 0;
|
||||||
}
|
}
|
||||||
if (mapped != 0) {
|
if (mapped != 0) {
|
||||||
sb.append(openTag).append(fallbackRPr)
|
sb.append(openTag).append(fallbackRPr)
|
||||||
.append("<w:t xml:space=\"preserve\">").append(mapped)
|
.append("<w:t xml:space=\"preserve\">").append(mapped)
|
||||||
.append("</w:t></w:r>");
|
.append("</w:t></w:r>");
|
||||||
|
} else if (charHex != null) {
|
||||||
|
// неразрешимый, но схемно-валидный w:sym (§17.3.3.30) —
|
||||||
|
// сохраняем verbatim: удалять валидный контент нельзя
|
||||||
|
sb.append(openTag).append(rPr).append(m.group()).append("</w:r>");
|
||||||
}
|
}
|
||||||
pos = m.end();
|
pos = m.end();
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -14,7 +14,9 @@ import java.util.zip.ZipOutputStream;
|
|||||||
* Свёртка {@code w:tblPr/w:jc} (center/right) с ненулевым {@code w:tblInd} в
|
* Свёртка {@code w:tblPr/w:jc} (center/right) с ненулевым {@code w:tblInd} в
|
||||||
* абсолютный {@code w:tblInd} — до загрузки docx4j.
|
* абсолютный {@code w:tblInd} — до загрузки docx4j.
|
||||||
*
|
*
|
||||||
* Word (Part 1 §17.4.50 в чтении MS-OI29500 §2.1.155): при {@code w:jc}≠left
|
* Word (MS-OI29500 §2.1.155; Part 1 §17.4.28 {@code w:jc} + §17.4.50
|
||||||
|
* {@code w:tblInd} описывают без аддитивной семантики — «сдвиг от поля после
|
||||||
|
* центрирования/прижимания» есть измеренное поведение Word): при {@code w:jc}≠left
|
||||||
* таблица центрируется/прижимается, а {@code w:tblInd} добавляется сдвигом от
|
* таблица центрируется/прижимается, а {@code w:tblInd} добавляется сдвигом от
|
||||||
* поля. docx4j же при {@code w:jc}≠left {@code w:tblInd} игнорирует буквально
|
* поля. docx4j же при {@code w:jc}≠left {@code w:tblInd} игнорирует буквально
|
||||||
* (аудит раскладки ECMA-376, матрица B3) — таблица рендерилась без учёта
|
* (аудит раскладки ECMA-376, матрица B3) — таблица рендерилась без учёта
|
||||||
@@ -31,12 +33,17 @@ import java.util.zip.ZipOutputStream;
|
|||||||
* <p>Пропускается (не ломая существующее поведение): документы без
|
* <p>Пропускается (не ломая существующее поведение): документы без
|
||||||
* единственного body-level {@code w:sectPr} (несколько секций — полоса
|
* единственного body-level {@code w:sectPr} (несколько секций — полоса
|
||||||
* неоднозначна), {@code w:tblW type="pct"} и таблицы с gridCol без целого
|
* неоднозначна), {@code w:tblW type="pct"} и таблицы с gridCol без целого
|
||||||
* {@code w:w} (фактическая ширина неизвестна), {@code w:tblInd} не-dxa и
|
* {@code w:w} (фактическая ширина неизвестна), {@code w:tblInd} с явным
|
||||||
|
* {@code w:type}≠dxa (опущенный type — dxa, §17.4.87) и
|
||||||
* {@code w:tblPr} с {@code w:tblCellSpacing} без {@code w:tblInd} (вставить
|
* {@code w:tblPr} с {@code w:tblCellSpacing} без {@code w:tblInd} (вставить
|
||||||
* тег в корректную позицию CT_TblPrBase некуда). Дефолты при отсутствии
|
* тег в корректную позицию CT_TblPrBase некуда). Дефолты при отсутствии
|
||||||
* pgSz/pgMar — 11906 и 1440/1440: измеренное поведение docx4j при отсутствующем
|
* pgSz/pgMar — 11906 и 1440/1440: ECMA дефолтов {@code w:pgSz}/{@code w:pgMar}
|
||||||
* {@code w:pgMar} (левый край текста = 72pt = 1440 twips), а не ECMA-дефолт
|
* не фиксирует (§17.6.13/§17.6.11), а 11906/1440 — измеренное поведение
|
||||||
* 1800 — нормализатор обязан считать ту же полосу, что рендерит стек.
|
* docx4j при отсутствующем {@code w:pgMar} (левый край текста = 72pt =
|
||||||
|
* 1440 twips) — нормализатор обязан считать ту же полосу, что рендерит стек.
|
||||||
|
* Band берётся из сырого {@code word/document.xml}: геометрия инвариантна
|
||||||
|
* к рерайтам (Strict-схема у {@code CT_PageMar} не имеет start/end, rule 1
|
||||||
|
* {@code w:pgSz}/{@code w:pgMar} не трогает).
|
||||||
*
|
*
|
||||||
* <p>{@link #normalize} трогает только {@code word/document.xml} (признак —
|
* <p>{@link #normalize} трогает только {@code word/document.xml} (признак —
|
||||||
* {@code <w:body}); нечего менять → тот же массив. {@link #rewritePart} —
|
* {@code <w:body}); нечего менять → тот же массив. {@link #rewritePart} —
|
||||||
@@ -46,7 +53,7 @@ import java.util.zip.ZipOutputStream;
|
|||||||
* WordPdfConverterTest#tableIndentCentered_shiftedLikeWord,
|
* WordPdfConverterTest#tableIndentCentered_shiftedLikeWord,
|
||||||
* #headerTableIndent_centeredInHeader.
|
* #headerTableIndent_centeredInHeader.
|
||||||
*/
|
*/
|
||||||
public final class TableIndentNormalizer {
|
final class TableIndentNormalizer {
|
||||||
|
|
||||||
/** Дефолт pgSz w:w (A4 portrait, twips) при отсутствии атрибута. */
|
/** Дефолт pgSz w:w (A4 portrait, twips) при отсутствии атрибута. */
|
||||||
private static final int DEFAULT_PG_W = 11906;
|
private static final int DEFAULT_PG_W = 11906;
|
||||||
@@ -57,13 +64,14 @@ public final class TableIndentNormalizer {
|
|||||||
private static final String DOCUMENT_ENTRY = "word/document.xml";
|
private static final String DOCUMENT_ENTRY = "word/document.xml";
|
||||||
|
|
||||||
private static final Pattern PG_SZ_W = Pattern.compile("<w:pgSz\\b[^>]*w:w=\"(\\d+)\"");
|
private static final Pattern PG_SZ_W = Pattern.compile("<w:pgSz\\b[^>]*w:w=\"(\\d+)\"");
|
||||||
// strict-OOXML пишет поля как w:start/w:end; band считается из СЫРОГО
|
// полоса считается из СЫРОГО document.xml; чередование left|start не
|
||||||
// document.xml (до rule 1, которая их переименует) — чередование
|
// нужен: CT_PageMar не имеет start/end ни в strict-, ни в transitional-
|
||||||
// обязательно, иначе полоса строгого документа молча возьмётся из дефолтов
|
// схеме (wml.xsd), StrictOoxmlNormalizer w:pgSz/w:pgMar не трогает —
|
||||||
|
// геометрия инвариантна к рерайтам
|
||||||
private static final Pattern PG_MAR_LEFT =
|
private static final Pattern PG_MAR_LEFT =
|
||||||
Pattern.compile("<w:pgMar\\b[^>]*w:(?:left|start)=\"(\\d+)\"");
|
Pattern.compile("<w:pgMar\\b[^>]*w:left=\"(\\d+)\"");
|
||||||
private static final Pattern PG_MAR_RIGHT =
|
private static final Pattern PG_MAR_RIGHT =
|
||||||
Pattern.compile("<w:pgMar\\b[^>]*w:(?:right|end)=\"(\\d+)\"");
|
Pattern.compile("<w:pgMar\\b[^>]*w:right=\"(\\d+)\"");
|
||||||
private static final Pattern JC =
|
private static final Pattern JC =
|
||||||
Pattern.compile("<w:jc\\b[^>]*w:val=\"(center|right)\"[^>]*/>");
|
Pattern.compile("<w:jc\\b[^>]*w:val=\"(center|right)\"[^>]*/>");
|
||||||
private static final Pattern TBL_IND = Pattern.compile("<w:tblInd\\b[^>]*/>");
|
private static final Pattern TBL_IND = Pattern.compile("<w:tblInd\\b[^>]*/>");
|
||||||
@@ -74,16 +82,13 @@ public final class TableIndentNormalizer {
|
|||||||
private TableIndentNormalizer() {
|
private TableIndentNormalizer() {
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Шаг конвейера WordPdfConverter#normalizers: этот нормализатор как DocxNormalizer. */
|
|
||||||
public static final DocxNormalizer STEP = TableIndentNormalizer::normalize;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Переписывает jc+tblInd в абсолютный tblInd в {@code word/document.xml}.
|
* Переписывает jc+tblInd в абсолютный tblInd в {@code word/document.xml}.
|
||||||
*
|
*
|
||||||
* @param docx байты .docx (zip)
|
* @param docx байты .docx (zip)
|
||||||
* @return те же или переупакованные байты
|
* @return те же или переупакованные байты
|
||||||
*/
|
*/
|
||||||
public static byte[] normalize(byte[] docx) throws IOException {
|
static byte[] normalize(byte[] docx) throws IOException {
|
||||||
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
ByteArrayOutputStream out = new ByteArrayOutputStream(docx.length);
|
||||||
boolean changed = false;
|
boolean changed = false;
|
||||||
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(docx));
|
||||||
@@ -186,10 +191,18 @@ public final class TableIndentNormalizer {
|
|||||||
if (hasInd) {
|
if (hasInd) {
|
||||||
String indTag = ind.group();
|
String indTag = ind.group();
|
||||||
Matcher indW = TBL_IND_W.matcher(indTag);
|
Matcher indW = TBL_IND_W.matcher(indTag);
|
||||||
if (!indW.find() || !indTag.contains("w:type=\"dxa\"")) {
|
// CT_TblWidth (§17.4.87): опущенный w:type = dxa;
|
||||||
continue; // не-dxa — величина сдвига неизвестна
|
// явный не-dxa (pct и т.п.) — величина сдвига неизвестна
|
||||||
|
boolean nonDxa = indTag.contains("w:type=") && !indTag.contains("w:type=\"dxa\"");
|
||||||
|
if (!indW.find() || nonDxa) {
|
||||||
|
continue;
|
||||||
}
|
}
|
||||||
x = Integer.parseInt(indW.group(1));
|
x = Integer.parseInt(indW.group(1));
|
||||||
|
} else if (pr.contains("<w:tblInd")) {
|
||||||
|
// парный (не самозакрывающийся) w:tblInd — паттерн видит
|
||||||
|
// только самозакрытый; вставка нового тега оставила бы старый
|
||||||
|
// → дубль элемента (maxOccurs=1 у CT_TblPrBase), консервативно
|
||||||
|
continue;
|
||||||
} else if (pr.contains("<w:tblCellSpacing")) {
|
} else if (pr.contains("<w:tblCellSpacing")) {
|
||||||
// tblInd по CT_TblPrBase идёт ПОСЛЕ tblCellSpacing — вставить
|
// tblInd по CT_TblPrBase идёт ПОСЛЕ tblCellSpacing — вставить
|
||||||
// тег в корректную позицию некуда, консервативно пропускаем
|
// тег в корректную позицию некуда, консервативно пропускаем
|
||||||
|
|||||||
+5
-5
@@ -11,7 +11,7 @@ import java.util.List;
|
|||||||
|
|
||||||
/**
|
/**
|
||||||
* Объёмные декартовы графики: c:bar3DChart, c:line3DChart, c:area3DChart
|
* Объёмные декартовы графики: c:bar3DChart, c:line3DChart, c:area3DChart
|
||||||
* (ECMA-376 §21.2.2.19/.101/.122). Камера — та же, что у поверхности
|
* (ECMA-376 §21.2.2.15/.96/.4). Камера — та же, что у поверхности
|
||||||
* ({@link Surface3dPainter#project}): u — категория (ширина), v — ряд
|
* ({@link Surface3dPainter#project}): u — категория (ширина), v — ряд
|
||||||
* (глубина), w — значение (высота); вписка равномерным масштабом в поля
|
* (глубина), w — значение (высота); вписка равномерным масштабом в поля
|
||||||
* {@link Surface3dPainter#GUTTER_LEFT} и т.д.
|
* {@link Surface3dPainter#GUTTER_LEFT} и т.д.
|
||||||
@@ -21,8 +21,8 @@ import java.util.List;
|
|||||||
* §2.1.1474(a)); торец затемняется (псевдо-свет, калибровка — Cartesian3dPainterTest).
|
* §2.1.1474(a)); торец затемняется (псевдо-свет, калибровка — Cartesian3dPainterTest).
|
||||||
* line3D: полилиния ряда на своей глубине, лента-толщина не имитируется;
|
* line3D: полилиния ряда на своей глубине, лента-толщина не имитируется;
|
||||||
* area3D: стена ряда от пола до значений, полупрозрачная, как AREA.
|
* area3D: стена ряда от пола до значений, полупрозрачная, как AREA.
|
||||||
* c:shape (§21.2.2.177, ST_Shape §21.2.3.44): box/cone/coneToMax/cylinder/pyramid/
|
* c:shape (§21.2.2.177, ST_Shape §21.2.3.42): box/cone/coneToMax/cylinder/pyramid/
|
||||||
* pyramidToMax; c:shape ряда переопределяет форму диаграммы (MS-OI29500 §2.1.1545(a/b)),
|
* pyramidToMax; c:shape ряда переопределяет форму диаграммы (MS-OI29500 §2.1.1546(a/b)),
|
||||||
* ToMax-формы сужаются к верху пропорционально val/max (семантика Excel — ECMA геометрию
|
* ToMax-формы сужаются к верху пропорционально val/max (семантика Excel — ECMA геометрию
|
||||||
* не нормирует); неизвестное значение — box. c:barDir="bar" — горизонтальная ориентация
|
* не нормирует); неизвестное значение — box. c:barDir="bar" — горизонтальная ориентация
|
||||||
* боксов (Word UI не сочетает barDir=bar с формами).
|
* боксов (Word UI не сочетает barDir=bar с формами).
|
||||||
@@ -343,7 +343,7 @@ final class Cartesian3dPainter {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Грани колонки в модельных координатах (§21.2.3.44 ST_Shape); все вершины
|
/** Грани колонки в модельных координатах (§21.2.3.42 ST_Shape); все вершины
|
||||||
* проецируются в nodes — по ним происходит вписка. Неизвестная форма — box. */
|
* проецируются в nodes — по ним происходит вписка. Неизвестная форма — box. */
|
||||||
private static List<Face> buildFaces(Color color, String shape, double t,
|
private static List<Face> buildFaces(Color color, String shape, double t,
|
||||||
double u0, double u1, double v0, double v1,
|
double u0, double u1, double v0, double v1,
|
||||||
@@ -600,7 +600,7 @@ final class Cartesian3dPainter {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/** Подписи: значения — вдоль переднего левого ребра, категории — нижнего,
|
/** Подписи: значения — вдоль переднего левого ребра, категории — нижнего,
|
||||||
* ряды — правого; c:delete (§21.2.2.38) убирает подписи оси.
|
* ряды — правого; c:delete (§21.2.2.40) убирает подписи оси.
|
||||||
* Регрессия — Cartesian3dPainterTest#bar3d_seriesAxisLabelsDrawn. */
|
* Регрессия — Cartesian3dPainterTest#bar3d_seriesAxisLabelsDrawn. */
|
||||||
private static void drawLabels(Graphics2D g, ChartSpec spec, List<Double> tickValues,
|
private static void drawLabels(Graphics2D g, ChartSpec spec, List<Double> tickValues,
|
||||||
List<Surface3dPainter.Node> valueAnchors, int nCat,
|
List<Surface3dPainter.Node> valueAnchors, int nCat,
|
||||||
|
|||||||
@@ -70,12 +70,12 @@ final class CartesianPainter {
|
|||||||
"percentStacked".equalsIgnoreCase(lineGrouping))
|
"percentStacked".equalsIgnoreCase(lineGrouping))
|
||||||
: null;
|
: null;
|
||||||
|
|
||||||
// Разделение серий по осям значений: ссылочное равенство с secondaryValAxis
|
// Разделение серий по осям значений: та же ось по c:axId
|
||||||
// (назначается ChartSpec.parse по c:axId, §21.2.2.9).
|
// (назначается ChartSpec.parse, §21.2.2.9; {@link ChartSpec#sameAxis}).
|
||||||
List<Integer> primIdx = new ArrayList<>();
|
List<Integer> primIdx = new ArrayList<>();
|
||||||
List<Integer> secIdx = new ArrayList<>();
|
List<Integer> secIdx = new ArrayList<>();
|
||||||
for (int si = 0; si < spec.series.size(); si++) {
|
for (int si = 0; si < spec.series.size(); si++) {
|
||||||
if (secAxis != null && spec.series.get(si).valAxis == secAxis) {
|
if (ChartSpec.sameAxis(spec.series.get(si).valAxis, secAxis)) {
|
||||||
secIdx.add(si);
|
secIdx.add(si);
|
||||||
} else {
|
} else {
|
||||||
primIdx.add(si);
|
primIdx.add(si);
|
||||||
@@ -278,9 +278,9 @@ final class CartesianPainter {
|
|||||||
return gr != null ? gr : spec.grouping;
|
return gr != null ? gr : spec.grouping;
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Серия на вторичной оси значений (ссылочное равенство с secondaryValAxis). */
|
/** Серия на вторичной оси значений (та же ось по c:axId, §21.2.2.9; {@link ChartSpec#sameAxis}). */
|
||||||
private static boolean onSecondary(ChartSpec.Series s, ChartSpec spec) {
|
private static boolean onSecondary(ChartSpec.Series s, ChartSpec spec) {
|
||||||
return spec.secondaryValAxis != null && s.valAxis == spec.secondaryValAxis;
|
return ChartSpec.sameAxis(s.valAxis, spec.secondaryValAxis);
|
||||||
}
|
}
|
||||||
|
|
||||||
private static List<Integer> intersect(List<Integer> family, List<Integer> prim) {
|
private static List<Integer> intersect(List<Integer> family, List<Integer> prim) {
|
||||||
|
|||||||
+98
-3
@@ -2,10 +2,13 @@ package ru.pjandro.wordpdf.internal.chart;
|
|||||||
|
|
||||||
import org.docx4j.convert.out.fo.FOConversionImageHandler;
|
import org.docx4j.convert.out.fo.FOConversionImageHandler;
|
||||||
import org.docx4j.model.images.AbstractWordXmlPicture;
|
import org.docx4j.model.images.AbstractWordXmlPicture;
|
||||||
|
import org.docx4j.model.images.PictureCompression;
|
||||||
import org.docx4j.openpackaging.exceptions.Docx4JException;
|
import org.docx4j.openpackaging.exceptions.Docx4JException;
|
||||||
import org.docx4j.openpackaging.parts.WordprocessingML.BinaryPart;
|
import org.docx4j.openpackaging.parts.WordprocessingML.BinaryPart;
|
||||||
import org.docx4j.relationships.Relationship;
|
import org.docx4j.relationships.Relationship;
|
||||||
|
|
||||||
|
import java.nio.ByteBuffer;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Image-обработчик FO-экспорта, отключающий docx4j «Compress Pictures»
|
* Image-обработчик FO-экспорта, отключающий docx4j «Compress Pictures»
|
||||||
* (CR-029) для наших chart-PNG.
|
* (CR-029) для наших chart-PNG.
|
||||||
@@ -25,13 +28,26 @@ import org.docx4j.relationships.Relationship;
|
|||||||
* {@code /word/media/chart-*} возвращаем null (нет варианта), картинка
|
* {@code /word/media/chart-*} возвращаем null (нет варианта), картинка
|
||||||
* уходит в PDF как есть.
|
* уходит в PDF как есть.
|
||||||
*
|
*
|
||||||
* Медиа документов (фото/скрины) — не наши части, им остаётся штатный
|
* Медиа документов (фото/скрины) — не наши части, но и для них штатный путь
|
||||||
* docx4j-режим CR-029.
|
* дорог: {@code PictureCompression.compress} декодирует полный растр (ImageIO)
|
||||||
|
* ДО любых решений, а для не-JPEG без кропа с ppi {@code <=} threshold (и без размера
|
||||||
|
* в макете) результат всегда null — декод впустую. Здесь такое решение
|
||||||
|
* принимается по 26 байтам заголовка (PNG/GIF/BMP), растр не декодируется
|
||||||
|
* вовсе. JPEG сознательно не ускоряем: Word при ppi {@code <=} threshold перекодирует
|
||||||
|
* его «для размера», вывод должен остаться побайтно прежним.
|
||||||
*
|
*
|
||||||
* Регрессия — WordPdfConverterTest#chartMedia_notDownsampled.
|
* Регрессии — WordPdfConverterTest#chartMedia_notDownsampled,
|
||||||
|
* ChartImageHandlerTest#plainPngBelowThreshold_returnsNull,
|
||||||
|
* ChartImageHandlerTest#jpegBelowThreshold_stillDelegates,
|
||||||
|
* ChartImageHandlerTest#pngAboveThreshold_stillDelegates.
|
||||||
*/
|
*/
|
||||||
public final class ChartImageHandler extends FOConversionImageHandler {
|
public final class ChartImageHandler extends FOConversionImageHandler {
|
||||||
|
|
||||||
|
private static final int[] PNG_SIGNATURE =
|
||||||
|
{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A};
|
||||||
|
private static final int[] GIF_SIGNATURE = {0x47, 0x49, 0x46, 0x38};
|
||||||
|
private static final int[] BMP_SIGNATURE = {0x42, 0x4D};
|
||||||
|
|
||||||
@Override
|
@Override
|
||||||
protected String compressedVariant(AbstractWordXmlPicture picture,
|
protected String compressedVariant(AbstractWordXmlPicture picture,
|
||||||
Relationship relationship, BinaryPart part)
|
Relationship relationship, BinaryPart part)
|
||||||
@@ -41,6 +57,85 @@ public final class ChartImageHandler extends FOConversionImageHandler {
|
|||||||
.startsWith(DrawingPreRenderer.CHART_MEDIA_URI_PREFIX)) {
|
.startsWith(DrawingPreRenderer.CHART_MEDIA_URI_PREFIX)) {
|
||||||
return null;
|
return null;
|
||||||
}
|
}
|
||||||
|
// Быстрый путь: null идентичен тому, что super вернул бы после
|
||||||
|
// полного декода. PictureCompression.compress для не-JPEG без кропа
|
||||||
|
// возвращает null, когда ресемпл не нужен: ppi по заголовку не выше
|
||||||
|
// threshold (формула — дословно из compress) или размер в макете
|
||||||
|
// задан нулём/не задан (кроп при этом исключён, reencoding требует
|
||||||
|
// JPEG). Кроп, high-fidelity, JPEG и нераспознанный формат — super.
|
||||||
|
if (picture != null && picture.isForXslFo() && part != null
|
||||||
|
&& (!cropsPictures() || picture.getCrop().isNone())) {
|
||||||
|
PictureCompression.Resolution resolution =
|
||||||
|
PictureCompression.resolution(picture.getWmlPackage(), pictureResolution);
|
||||||
|
if (!resolution.isHighFidelity() && noResampleNeeded(part.getBuffer(),
|
||||||
|
picture.getWidthInPoints(), picture.getHeightInPoints(),
|
||||||
|
resolution.threshold)) {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
return super.compressedVariant(picture, relationship, part);
|
return super.compressedVariant(picture, relationship, part);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Истинно, когда по 26 байтам заголовка контейнера картинка — из быстрого
|
||||||
|
* списка (PNG/GIF/BMP) и ресемпл ей не нужен: нативный ppi при заданном
|
||||||
|
* макетном размере не выше {@code threshold} (формула — дословно из
|
||||||
|
* {@code PictureCompression.compress}), либо размер в макете не задан
|
||||||
|
* (без кропа и без JPEG super тоже приходит к null). Ложь — формат вне
|
||||||
|
* списка (JPEG — решение пользователя, TIFF/EMF/WMF/…), заголовок
|
||||||
|
* неполный/неправдоподобный или буфер части пуст: решение отдаём super.
|
||||||
|
* Байты читаются абсолютными индексами — позиция общего {@link ByteBuffer}
|
||||||
|
* части не мутируется.
|
||||||
|
*/
|
||||||
|
private static boolean noResampleNeeded(ByteBuffer bb, double widthPt, double heightPt,
|
||||||
|
int threshold) {
|
||||||
|
if (bb == null) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
final int len = bb.limit();
|
||||||
|
final int width;
|
||||||
|
final int height;
|
||||||
|
// PNG: сигнатура, затем длина блока, «IHDR» со смещения 12,
|
||||||
|
// ширина/высота big-endian в 16/20.
|
||||||
|
if (len >= 24 && magic(bb, 0, PNG_SIGNATURE) && be32(bb, 12) == 0x49484452) {
|
||||||
|
width = be32(bb, 16);
|
||||||
|
height = be32(bb, 20);
|
||||||
|
// GIF: «GIF8», ширина/высота little-endian в 6/8 (le32-чтение
|
||||||
|
// с 8 идёт до байта 11 включительно).
|
||||||
|
} else if (len >= 12 && magic(bb, 0, GIF_SIGNATURE)) {
|
||||||
|
width = le32(bb, 6) & 0xFFFF;
|
||||||
|
height = le32(bb, 8) & 0xFFFF;
|
||||||
|
// BMP: «BM», ширина/высота BITMAPINFOHEADER little-endian в 18/22
|
||||||
|
// (высота отрицательная для top-down — берём модуль).
|
||||||
|
} else if (len >= 26 && magic(bb, 0, BMP_SIGNATURE)) {
|
||||||
|
width = le32(bb, 18);
|
||||||
|
height = Math.abs(le32(bb, 22));
|
||||||
|
} else {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
if (width <= 0 || height <= 0) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
return widthPt <= 0 || heightPt <= 0
|
||||||
|
|| Math.max(width / (widthPt / 72d), height / (heightPt / 72d)) <= threshold;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static boolean magic(ByteBuffer bb, int at, int[] bytes) {
|
||||||
|
for (int i = 0; i < bytes.length; i++) {
|
||||||
|
if ((bb.get(at + i) & 0xFF) != bytes[i]) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static int be32(ByteBuffer bb, int at) {
|
||||||
|
return ((bb.get(at) & 0xFF) << 24) | ((bb.get(at + 1) & 0xFF) << 16)
|
||||||
|
| ((bb.get(at + 2) & 0xFF) << 8) | (bb.get(at + 3) & 0xFF);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static int le32(ByteBuffer bb, int at) {
|
||||||
|
return (bb.get(at) & 0xFF) | ((bb.get(at + 1) & 0xFF) << 8)
|
||||||
|
| ((bb.get(at + 2) & 0xFF) << 16) | ((bb.get(at + 3) & 0xFF) << 24);
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -52,6 +52,10 @@ final class ChartRenderer {
|
|||||||
/** Порог «значение целое» при форматировании подписей. */
|
/** Порог «значение целое» при форматировании подписей. */
|
||||||
private static final double INTEGER_EPSILON = 1e-9;
|
private static final double INTEGER_EPSILON = 1e-9;
|
||||||
|
|
||||||
|
/** Позиции легенды (ECMA-376 §21.2.2.95 legendPos, ST_LegendPos §21.2.3.24): снизу/сверху. */
|
||||||
|
private static final String LEGEND_BOTTOM = "b";
|
||||||
|
private static final String LEGEND_TOP = "t";
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Верхняя граница числа делений: {@code c:majorUnit} (ECMA-376 §21.2.2.103) —
|
* Верхняя граница числа делений: {@code c:majorUnit} (ECMA-376 §21.2.2.103) —
|
||||||
* double без нижней границы; Word пишет «круглые» значения, а враждебный docx —
|
* double без нижней границы; Word пишет «круглые» значения, а враждебный docx —
|
||||||
@@ -110,12 +114,12 @@ final class ChartRenderer {
|
|||||||
// дорисовывается поверх после художника. Регрессия — ChartRendererTest#overlayLegend_drawnOverPlot.
|
// дорисовывается поверх после художника. Регрессия — ChartRendererTest#overlayLegend_drawnOverPlot.
|
||||||
double legendH = legend == null || spec.legendOverlay ? 0 : legend.height;
|
double legendH = legend == null || spec.legendOverlay ? 0 : legend.height;
|
||||||
Rectangle2D box0 = box;
|
Rectangle2D box0 = box;
|
||||||
if (legend != null && !spec.legendOverlay && "b".equals(spec.legendPos)) {
|
if (legend != null && !spec.legendOverlay && LEGEND_BOTTOM.equals(spec.legendPos)) {
|
||||||
legend.draw(g, box.getX(), box.getY() + box.getHeight() - legendH,
|
legend.draw(g, box.getX(), box.getY() + box.getHeight() - legendH,
|
||||||
box.getWidth());
|
box.getWidth());
|
||||||
box = new Rectangle2D.Double(box.getX(), box.getY(),
|
box = new Rectangle2D.Double(box.getX(), box.getY(),
|
||||||
box.getWidth(), box.getHeight() - legendH);
|
box.getWidth(), box.getHeight() - legendH);
|
||||||
} else if (legend != null && !spec.legendOverlay && "t".equals(spec.legendPos)) {
|
} else if (legend != null && !spec.legendOverlay && LEGEND_TOP.equals(spec.legendPos)) {
|
||||||
legend.draw(g, box.getX(), box.getY(), box.getWidth());
|
legend.draw(g, box.getX(), box.getY(), box.getWidth());
|
||||||
box = new Rectangle2D.Double(box.getX(), box.getY() + legendH,
|
box = new Rectangle2D.Double(box.getX(), box.getY() + legendH,
|
||||||
box.getWidth(), box.getHeight() - legendH);
|
box.getWidth(), box.getHeight() - legendH);
|
||||||
@@ -144,7 +148,7 @@ final class ChartRenderer {
|
|||||||
default -> LOG.warn("тип графика {} не поддерживается — пустой PNG", spec.type);
|
default -> LOG.warn("тип графика {} не поддерживается — пустой PNG", spec.type);
|
||||||
}
|
}
|
||||||
if (legend != null && spec.legendOverlay) {
|
if (legend != null && spec.legendOverlay) {
|
||||||
double y = "t".equals(spec.legendPos)
|
double y = LEGEND_TOP.equals(spec.legendPos)
|
||||||
? box0.getY() : box0.getY() + box0.getHeight() - legend.height;
|
? box0.getY() : box0.getY() + box0.getHeight() - legend.height;
|
||||||
legend.draw(g, box0.getX(), y, box0.getWidth());
|
legend.draw(g, box0.getX(), y, box0.getWidth());
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -117,7 +117,7 @@ final class ChartSpec {
|
|||||||
final List<Double> xValues = new ArrayList<>();
|
final List<Double> xValues = new ArrayList<>();
|
||||||
/** bubble: размеры пузырей (c:bubbleSize). */
|
/** bubble: размеры пузырей (c:bubbleSize). */
|
||||||
final List<Double> bubbleSizes = new ArrayList<>();
|
final List<Double> bubbleSizes = new ArrayList<>();
|
||||||
/** c:shape ряда bar3D (MS-OI29500 §2.1.1545(b)); null = дефолт диаграммы ({@link #shape3d}). */
|
/** c:shape ряда bar3D (MS-OI29500 §2.1.1546(b)); null = дефолт диаграммы ({@link #shape3d}). */
|
||||||
String shape3d;
|
String shape3d;
|
||||||
/** Способ отрисовки ряда в combo-диаграмме (несколько групп в одном c:plotArea,
|
/** Способ отрисовки ряда в combo-диаграмме (несколько групп в одном c:plotArea,
|
||||||
* ECMA-376 §21.2.2.145): BAR/BAR_HORIZONTAL/LINE/AREA по группе-источнику.
|
* ECMA-376 §21.2.2.145): BAR/BAR_HORIZONTAL/LINE/AREA по группе-источнику.
|
||||||
@@ -396,7 +396,7 @@ final class ChartSpec {
|
|||||||
break;
|
break;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
if (va == null || va == spec.valAxis) {
|
if (va == null || sameAxis(va, spec.valAxis)) {
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
if (spec.secondaryValAxis == null) {
|
if (spec.secondaryValAxis == null) {
|
||||||
@@ -409,6 +409,14 @@ final class ChartSpec {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** Та же ось по c:axId (§21.2.2.9): id уникален в диаграмме, оси с id ≥ 0 лежат
|
||||||
|
* в {@code axesById} по одному на id — для осей, назначенных из карты при разборе,
|
||||||
|
* эквивалентно ссылочному равенству. Прямое сравнение осей через == запрещено
|
||||||
|
* PMD CompareObjectsWithEquals; null и id < 0 — никогда «та же». */
|
||||||
|
static boolean sameAxis(AxisSpec a, AxisSpec b) {
|
||||||
|
return a != null && b != null && a.axId >= 0 && a.axId == b.axId;
|
||||||
|
}
|
||||||
|
|
||||||
private static void readChartFrame(CTChartSpace space, ChartSpec spec, DrawMlColor colors) {
|
private static void readChartFrame(CTChartSpace space, ChartSpec spec, DrawMlColor colors) {
|
||||||
CTShapeProperties sp = space.getSpPr();
|
CTShapeProperties sp = space.getSpPr();
|
||||||
if (sp == null) {
|
if (sp == null) {
|
||||||
|
|||||||
@@ -29,12 +29,13 @@ import java.util.Map;
|
|||||||
* Палитра цветов DrawingML: цвета схемы из word/theme/theme1.xml плюс
|
* Палитра цветов DrawingML: цвета схемы из word/theme/theme1.xml плюс
|
||||||
* разбор {@code a:color} (srgbClr / scrgbClr / hslClr / sysClr /
|
* разбор {@code a:color} (srgbClr / scrgbClr / hslClr / sysClr /
|
||||||
* schemeClr / prstClr) с полным набором трансформаций EG_ColorTransform
|
* schemeClr / prstClr) с полным набором трансформаций EG_ColorTransform
|
||||||
* (§20.1.2.3.2-28: lum/sat/hue Mod/Off и абсолютные, tint/shade,
|
* (§20.1.2.3.2-34: lum/sat/hue Mod/Off и абсолютные, tint §20.1.2.3.34 /
|
||||||
|
* shade §20.1.2.3.31,
|
||||||
* alpha/alphaMod/alphaOff, red/green/blue + Mod/Off, comp, inv, gray,
|
* alpha/alphaMod/alphaOff, red/green/blue + Mod/Off, comp, inv, gray,
|
||||||
* gamma/invGamma).
|
* gamma/invGamma).
|
||||||
*
|
*
|
||||||
* tint/shade — модуляция светлоты в HSL (L' = L·p + (1−p) / L·p,
|
* tint/shade — модуляция светлоты в HSL (L' = L·p + (1−p) / L·p,
|
||||||
* MS-OI29500 §17.3.2.6(a) — поведение Word); ECMA-примеры именно для
|
* MS-OI29500 §2.1.72 — поведение Word); ECMA-примеры именно для
|
||||||
* tint/shade (00BC00) противоречат его же примерам семейства lum/sat —
|
* tint/shade (00BC00) противоречат его же примерам семейства lum/sat —
|
||||||
* расхождение на стороне спецификации.
|
* расхождение на стороне спецификации.
|
||||||
*
|
*
|
||||||
@@ -432,7 +433,7 @@ final class DrawMlColor {
|
|||||||
rgb = toRgb(hsl);
|
rgb = toRgb(hsl);
|
||||||
}
|
}
|
||||||
// §20.1.2.3.31/.34: Office-семантика — модуляция
|
// §20.1.2.3.31/.34: Office-семантика — модуляция
|
||||||
// светлоты в HSL (MS-OI29500 §17.3.2.6(a)), не
|
// светлоты в HSL (MS-OI29500 §2.1.72), не
|
||||||
// гамма-микс; ECMA-примеры tint/shade противоречат
|
// гамма-микс; ECMA-примеры tint/shade противоречат
|
||||||
// собственному семейству lum/sat (§20.1.2.3.19-28).
|
// собственному семейству lum/sat (§20.1.2.3.19-28).
|
||||||
case "tint" -> {
|
case "tint" -> {
|
||||||
|
|||||||
@@ -7,7 +7,7 @@ import org.docx4j.dml.CTTextParagraph;
|
|||||||
import org.docx4j.dml.CTTextParagraphProperties;
|
import org.docx4j.dml.CTTextParagraphProperties;
|
||||||
import org.docx4j.dml.CTTextSpacing;
|
import org.docx4j.dml.CTTextSpacing;
|
||||||
import org.docx4j.dml.TextFont;
|
import org.docx4j.dml.TextFont;
|
||||||
import ru.pjandro.wordpdf.fonts.BundledFontMapper;
|
import ru.pjandro.wordpdf.fonts.BundledFontAliases;
|
||||||
import ru.pjandro.wordpdf.fonts.BundledFonts;
|
import ru.pjandro.wordpdf.fonts.BundledFonts;
|
||||||
|
|
||||||
import ru.pjandro.wordpdf.fonts.GlyphFont;
|
import ru.pjandro.wordpdf.fonts.GlyphFont;
|
||||||
@@ -23,7 +23,7 @@ import java.util.List;
|
|||||||
* (a:defRPr / a:rPr: sz, b, i, solidFill, latin) и разбивка на строки.
|
* (a:defRPr / a:rPr: sz, b, i, solidFill, latin) и разбивка на строки.
|
||||||
*
|
*
|
||||||
* Шрифты берутся из того же бандла, что и у текста PDF
|
* Шрифты берутся из того же бандла, что и у текста PDF
|
||||||
* ({@link BundledFontMapper#bundledFamily}), поэтому подпись диаграммы
|
* ({@link BundledFontAliases#bundledFamily}), поэтому подпись диаграммы
|
||||||
* рисуется тем же Carlito/Tinos, что и абзацы документа.
|
* рисуется тем же Carlito/Tinos, что и абзацы документа.
|
||||||
*/
|
*/
|
||||||
final class DrawMlText {
|
final class DrawMlText {
|
||||||
@@ -43,7 +43,7 @@ final class DrawMlText {
|
|||||||
|
|
||||||
/**
|
/**
|
||||||
* Один абзац: текст + начертание + выравнивание + межстрочный интервал
|
* Один абзац: текст + начертание + выравнивание + межстрочный интервал
|
||||||
* из {@code a:lnSpc} (ECMA-376 §21.1.2.4): {@code spacingPct} — доля
|
* из {@code a:lnSpc} (ECMA-376 §21.1.2.2.5): {@code spacingPct} — доля
|
||||||
* одинарного (a:spcPct/100000), {@code spacingPts} — фиксированная
|
* одинарного (a:spcPct/100000), {@code spacingPts} — фиксированная
|
||||||
* высота строки в pt (a:spcPts/100); оба null — одинарный.
|
* высота строки в pt (a:spcPts/100); оба null — одинарный.
|
||||||
*/
|
*/
|
||||||
@@ -57,6 +57,8 @@ final class DrawMlText {
|
|||||||
|
|
||||||
/** Значения выравнивания DrawingML (a:pPr/@algn, a:bodyPr/@anchor). */
|
/** Значения выравнивания DrawingML (a:pPr/@algn, a:bodyPr/@anchor). */
|
||||||
private static final String ALIGN_CTR = "ctr";
|
private static final String ALIGN_CTR = "ctr";
|
||||||
|
private static final String ALIGN_RIGHT = "r";
|
||||||
|
private static final String ALIGN_FAR = "far";
|
||||||
private static final String VALIGN_BOTTOM = "b";
|
private static final String VALIGN_BOTTOM = "b";
|
||||||
|
|
||||||
/** Длина строки, дальше которую рез не идёт (прогресс гарантирован 1 символом). */
|
/** Длина строки, дальше которую рез не идёт (прогресс гарантирован 1 символом). */
|
||||||
@@ -82,7 +84,7 @@ final class DrawMlText {
|
|||||||
String fallbackFam, double fallbackSize, Color fallbackColor) {
|
String fallbackFam, double fallbackSize, Color fallbackColor) {
|
||||||
Style base = new Style(fallbackSize, false, false, fallbackColor,
|
Style base = new Style(fallbackSize, false, false, fallbackColor,
|
||||||
fallbackFam == null ? BundledFonts.FALLBACK_FAMILY
|
fallbackFam == null ? BundledFonts.FALLBACK_FAMILY
|
||||||
: BundledFontMapper.bundledFamily(fallbackFam));
|
: BundledFontAliases.bundledFamily(fallbackFam));
|
||||||
if (txPr == null || txPr.getP().isEmpty()) {
|
if (txPr == null || txPr.getP().isEmpty()) {
|
||||||
return base;
|
return base;
|
||||||
}
|
}
|
||||||
@@ -168,7 +170,7 @@ final class DrawMlText {
|
|||||||
case "+mj-lt", "+mj-ea", "+mj-cs" -> colors.majorFontName();
|
case "+mj-lt", "+mj-ea", "+mj-cs" -> colors.majorFontName();
|
||||||
default -> typeface;
|
default -> typeface;
|
||||||
};
|
};
|
||||||
return BundledFontMapper.bundledFamily(name != null ? name : fallbackFam);
|
return BundledFontAliases.bundledFamily(name != null ? name : fallbackFam);
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -241,7 +243,7 @@ final class DrawMlText {
|
|||||||
String align = line.align() != null ? line.align() : defAlign;
|
String align = line.align() != null ? line.align() : defAlign;
|
||||||
if (ALIGN_CTR.equals(align)) {
|
if (ALIGN_CTR.equals(align)) {
|
||||||
x += (box.getWidth() - line.width()) / 2.0;
|
x += (box.getWidth() - line.width()) / 2.0;
|
||||||
} else if ("r".equals(align) || "far".equals(align)) {
|
} else if (ALIGN_RIGHT.equals(align) || ALIGN_FAR.equals(align)) {
|
||||||
x += box.getWidth() - line.width();
|
x += box.getWidth() - line.width();
|
||||||
}
|
}
|
||||||
fontFor(line.style()).draw(g, line.text(), x, y + line.ascent(),
|
fontFor(line.style()).draw(g, line.text(), x, y + line.ascent(),
|
||||||
@@ -253,7 +255,7 @@ final class DrawMlText {
|
|||||||
/**
|
/**
|
||||||
* Высота строки абзаца: a:lnSpc/a:spcPts — фиксированная в pt,
|
* Высота строки абзаца: a:lnSpc/a:spcPts — фиксированная в pt,
|
||||||
* a:spcPct — доля одинарного (ascent+descent+leading), ничего —
|
* a:spcPct — доля одинарного (ascent+descent+leading), ничего —
|
||||||
* одинарный (ECMA-376 §21.1.2.4 CT_TextLineSpacing).
|
* одинарный (ECMA-376 §21.1.2.2.5 CT_TextLineSpacing).
|
||||||
*/
|
*/
|
||||||
private static double lineFor(Paragraph p, double single) {
|
private static double lineFor(Paragraph p, double single) {
|
||||||
if (p.spacingPts() != null) {
|
if (p.spacingPts() != null) {
|
||||||
|
|||||||
+309
-22
@@ -22,6 +22,8 @@ import org.docx4j.dml.diagram2008.CTDrawing;
|
|||||||
import org.docx4j.dml.picture.Pic;
|
import org.docx4j.dml.picture.Pic;
|
||||||
import org.docx4j.dml.wordprocessingDrawing.Anchor;
|
import org.docx4j.dml.wordprocessingDrawing.Anchor;
|
||||||
import org.docx4j.dml.wordprocessingDrawing.Inline;
|
import org.docx4j.dml.wordprocessingDrawing.Inline;
|
||||||
|
import org.docx4j.math.CTOMath;
|
||||||
|
import org.docx4j.math.CTOMathPara;
|
||||||
import org.docx4j.openpackaging.contenttype.ContentTypes;
|
import org.docx4j.openpackaging.contenttype.ContentTypes;
|
||||||
import org.docx4j.openpackaging.exceptions.Docx4JException;
|
import org.docx4j.openpackaging.exceptions.Docx4JException;
|
||||||
import org.docx4j.openpackaging.exceptions.InvalidFormatException;
|
import org.docx4j.openpackaging.exceptions.InvalidFormatException;
|
||||||
@@ -32,19 +34,34 @@ import org.docx4j.openpackaging.parts.PartName;
|
|||||||
import org.docx4j.openpackaging.parts.ThemePart;
|
import org.docx4j.openpackaging.parts.ThemePart;
|
||||||
import org.docx4j.openpackaging.parts.WordprocessingML.BinaryPartAbstractImage;
|
import org.docx4j.openpackaging.parts.WordprocessingML.BinaryPartAbstractImage;
|
||||||
import org.docx4j.openpackaging.parts.relationships.RelationshipsPart;
|
import org.docx4j.openpackaging.parts.relationships.RelationshipsPart;
|
||||||
|
import org.docx4j.wml.CTSignedHpsMeasure;
|
||||||
import org.docx4j.wml.Drawing;
|
import org.docx4j.wml.Drawing;
|
||||||
|
import org.docx4j.wml.Jc;
|
||||||
|
import org.docx4j.wml.JcEnumeration;
|
||||||
|
import org.docx4j.wml.P;
|
||||||
|
import org.docx4j.wml.PPr;
|
||||||
|
import org.docx4j.wml.R;
|
||||||
|
import org.docx4j.wml.RPr;
|
||||||
|
import org.docx4j.wml.Text;
|
||||||
import org.slf4j.Logger;
|
import org.slf4j.Logger;
|
||||||
import org.slf4j.LoggerFactory;
|
import org.slf4j.LoggerFactory;
|
||||||
|
import ru.pjandro.wordpdf.ChartsFoundException;
|
||||||
import ru.pjandro.wordpdf.ConvertOptions;
|
import ru.pjandro.wordpdf.ConvertOptions;
|
||||||
import ru.pjandro.wordpdf.DrawingFoundException;
|
import ru.pjandro.wordpdf.ConversionException;
|
||||||
|
import ru.pjandro.wordpdf.SmartArtFoundException;
|
||||||
|
|
||||||
import javax.imageio.ImageIO;
|
import javax.imageio.ImageIO;
|
||||||
|
import javax.xml.namespace.QName;
|
||||||
import java.awt.image.BufferedImage;
|
import java.awt.image.BufferedImage;
|
||||||
import java.io.ByteArrayInputStream;
|
import java.io.ByteArrayInputStream;
|
||||||
import java.io.ByteArrayOutputStream;
|
import java.io.ByteArrayOutputStream;
|
||||||
|
import java.io.IOException;
|
||||||
import java.lang.reflect.Method;
|
import java.lang.reflect.Method;
|
||||||
|
import java.math.BigInteger;
|
||||||
import java.util.ArrayList;
|
import java.util.ArrayList;
|
||||||
|
import java.util.Collections;
|
||||||
import java.util.HashSet;
|
import java.util.HashSet;
|
||||||
|
import java.util.IdentityHashMap;
|
||||||
import java.util.List;
|
import java.util.List;
|
||||||
import java.util.Set;
|
import java.util.Set;
|
||||||
|
|
||||||
@@ -58,8 +75,20 @@ import java.util.Set;
|
|||||||
* пакета и до создания FOSettings, иначе FOP увидит исходные chart/diagram
|
* пакета и до создания FOSettings, иначе FOP увидит исходные chart/diagram
|
||||||
* и молча их выбросит (notImplemented в шаблоне).
|
* и молча их выбросит (notImplemented в шаблоне).
|
||||||
*
|
*
|
||||||
|
* <p>Третий объект — формулы OMML (§22.1): {@code m:oMathPara}/{@code m:oMath}
|
||||||
|
* доходят сюда нетронутыми (docx2fo.xslt кладёт их в
|
||||||
|
* {@code fo:instream-foreign-object} с MathML, который FOP+jeuclid на
|
||||||
|
* без-fontconfig хостах роняет конвертацию, а на остальных рисует чужими
|
||||||
|
* системными шрифтами). Каждая формула рендерится своим растером
|
||||||
|
* ({@link MathModel} → {@link MathRenderer}) и заменяется inline-картинкой
|
||||||
|
* на месте; unsupported/битая формула деградирует раном с текстом
|
||||||
|
* {@code m:t}. Байтовый скан {@code MathFallbackNormalizer} (правило 6)
|
||||||
|
* срезает unsupported-конструкции до загрузки docx4j — этот путь остаётся
|
||||||
|
* безопасной сетью.
|
||||||
|
*
|
||||||
* Error-флаги {@link ConvertOptions}: при выключенном render-флаге и
|
* Error-флаги {@link ConvertOptions}: при выключенном render-флаге и
|
||||||
* включённом error-флаге находка объекта — {@link DrawingFoundException}
|
* включённом error-флаге находка объекта — {@link ChartsFoundException} или
|
||||||
|
* {@link SmartArtFoundException}
|
||||||
* (бросок здесь, на шаге 3.5, до XSLT/FOP). Регрессия —
|
* (бросок здесь, на шаге 3.5, до XSLT/FOP). Регрессия —
|
||||||
* WordPdfConverterTest#drawingErrors_errorFlagRejectsCharts, фикстура
|
* WordPdfConverterTest#drawingErrors_errorFlagRejectsCharts, фикстура
|
||||||
* samples/charts-smartart.docx.
|
* samples/charts-smartart.docx.
|
||||||
@@ -76,6 +105,15 @@ public final class DrawingPreRenderer {
|
|||||||
"http://schemas.openxmlformats.org/drawingml/2006/picture";
|
"http://schemas.openxmlformats.org/drawingml/2006/picture";
|
||||||
private static final String DIAGRAM_DRAWING_REL =
|
private static final String DIAGRAM_DRAWING_REL =
|
||||||
"http://schemas.microsoft.com/office/2007/relationships/diagramDrawing";
|
"http://schemas.microsoft.com/office/2007/relationships/diagramDrawing";
|
||||||
|
/** {@code m:} — namespace OMML (§22.1); {@code w:} — wordprocessingML. */
|
||||||
|
private static final String MATH_URI =
|
||||||
|
"http://schemas.openxmlformats.org/officeDocument/2006/math";
|
||||||
|
/** Local name элемента {@code m:oMath} (диспетч JAXBElement по имени тега). */
|
||||||
|
private static final String LOCAL_OMATH = "oMath";
|
||||||
|
/** Local name элемента {@code m:oMathPara} (формула отдельным абзацем). */
|
||||||
|
private static final String LOCAL_OMATH_PARA = "oMathPara";
|
||||||
|
private static final String WML_URI =
|
||||||
|
"http://schemas.openxmlformats.org/wordprocessingml/2006/main";
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Верхняя граница {@code wp:extent} в EMU: максимальная страница Word —
|
* Верхняя граница {@code wp:extent} в EMU: максимальная страница Word —
|
||||||
@@ -98,10 +136,25 @@ public final class DrawingPreRenderer {
|
|||||||
|
|
||||||
/**
|
/**
|
||||||
* Рендерит диаграммы/SmartArt пакета в PNG и подменяет их картинками —
|
* Рендерит диаграммы/SmartArt пакета в PNG и подменяет их картинками —
|
||||||
* объекты конвертируются всегда. Бросается {@link DrawingFoundException},
|
* объекты конвертируются всегда. Бросается {@link ChartsFoundException} или
|
||||||
|
* {@link SmartArtFoundException},
|
||||||
* когда для объектов включён error-флаг ({@link ConvertOptions}).
|
* когда для объектов включён error-флаг ({@link ConvertOptions}).
|
||||||
*/
|
*/
|
||||||
public static void run(WordprocessingMLPackage pkg, ConvertOptions options) {
|
public static void run(WordprocessingMLPackage pkg, ConvertOptions options) {
|
||||||
|
run(pkg, options, MAX_CHART_PNG_BYTES_TOTAL);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Потолок суммарного размера chart-PNG на документ: пер-объектные гейты
|
||||||
|
* ({@code MAX_EXTENT_EMU}, {@code MAX_PIXELS}) ограничивают один объект,
|
||||||
|
* но тысячи chart-частей × MB PNG оседали бы в heap как media-части
|
||||||
|
* (много-ГБ пик с входа ≤5 MiB). Превышение — деградация «объект удалён
|
||||||
|
* + warn», конвертация продолжается.
|
||||||
|
*/
|
||||||
|
private static final long MAX_CHART_PNG_BYTES_TOTAL = 128L * 1024 * 1024;
|
||||||
|
|
||||||
|
/** Тестовый шов: бюджет задаётся явно (публичный {@link #run} — с константой). */
|
||||||
|
static void run(WordprocessingMLPackage pkg, ConvertOptions options, long maxPngBytesTotal) {
|
||||||
ThemePart themePart = null;
|
ThemePart themePart = null;
|
||||||
for (Part p : new ArrayList<>(pkg.getParts().getParts().values())) {
|
for (Part p : new ArrayList<>(pkg.getParts().getParts().values())) {
|
||||||
if (p instanceof ThemePart tp) {
|
if (p instanceof ThemePart tp) {
|
||||||
@@ -116,7 +169,9 @@ public final class DrawingPreRenderer {
|
|||||||
// ConcurrentModificationException.
|
// ConcurrentModificationException.
|
||||||
List<Part> parts = new ArrayList<>(pkg.getParts().getParts().values());
|
List<Part> parts = new ArrayList<>(pkg.getParts().getParts().values());
|
||||||
Set<Part> handled = new HashSet<>();
|
Set<Part> handled = new HashSet<>();
|
||||||
|
Set<List<?>> visitedContents = Collections.newSetFromMap(new IdentityHashMap<>());
|
||||||
int[] idSeq = {1000};
|
int[] idSeq = {1000};
|
||||||
|
long[] pngTotal = {0};
|
||||||
for (Part p : parts) {
|
for (Part p : parts) {
|
||||||
if (!handled.add(p)) {
|
if (!handled.add(p)) {
|
||||||
continue;
|
continue;
|
||||||
@@ -125,7 +180,8 @@ public final class DrawingPreRenderer {
|
|||||||
if (content.isEmpty()) {
|
if (content.isEmpty()) {
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
walk(p, content, pkg, colors, idSeq, options);
|
walk(p, content, pkg, colors, idSeq, pngTotal, maxPngBytesTotal, options,
|
||||||
|
visitedContents, null);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -151,20 +207,61 @@ public final class DrawingPreRenderer {
|
|||||||
}
|
}
|
||||||
|
|
||||||
private static void walk(Part part, List<?> content, WordprocessingMLPackage pkg,
|
private static void walk(Part part, List<?> content, WordprocessingMLPackage pkg,
|
||||||
DrawMlColor colors, int[] idSeq, ConvertOptions options) {
|
DrawMlColor colors, int[] idSeq, long[] pngTotal,
|
||||||
for (Object o : content) {
|
long maxPngBytesTotal, ConvertOptions options,
|
||||||
|
Set<List<?>> visitedContents, P ownerPara) {
|
||||||
|
// Посещённые списки — по идентичности (IdentityHashMap): рефлексивный
|
||||||
|
// getContent (ребёнок возвращает список родителя) не зацикливает обход.
|
||||||
|
// Сравнение списков через ==/!= запрещено PMD CompareObjectsWithEquals.
|
||||||
|
if (!visitedContents.add(content)) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
for (int i = 0; i < content.size(); i++) {
|
||||||
|
Object o = content.get(i);
|
||||||
Object v = o instanceof JAXBElement ? ((JAXBElement<?>) o).getValue() : o;
|
Object v = o instanceof JAXBElement ? ((JAXBElement<?>) o).getValue() : o;
|
||||||
if (v instanceof Drawing drawing) {
|
if (v instanceof Drawing drawing) {
|
||||||
replaceDrawing(part, drawing, pkg, colors, idSeq, options);
|
replaceDrawing(part, drawing, pkg, colors, idSeq, pngTotal,
|
||||||
|
maxPngBytesTotal, options);
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
|
if (o instanceof JAXBElement<?> el && el.getName() != null
|
||||||
|
&& MATH_URI.equals(el.getName().getNamespaceURI())) {
|
||||||
|
String local = el.getName().getLocalPart();
|
||||||
|
if (LOCAL_OMATH.equals(local) && v instanceof CTOMath math) {
|
||||||
|
i = splice(content, i, mathReplacements(math, false, part, pkg,
|
||||||
|
idSeq, pngTotal, maxPngBytesTotal));
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (LOCAL_OMATH_PARA.equals(local) && v instanceof CTOMathPara para) {
|
||||||
|
i = splice(content, i, mathParaReplacements(para, ownerPara, part,
|
||||||
|
pkg, idSeq, pngTotal, maxPngBytesTotal));
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
P para = v instanceof P p ? p : ownerPara;
|
||||||
List<?> nested = invokeList(v, "getContent");
|
List<?> nested = invokeList(v, "getContent");
|
||||||
if (!nested.isEmpty() && nested != content) {
|
if (!nested.isEmpty()) {
|
||||||
walk(part, nested, pkg, colors, idSeq, options);
|
walk(part, nested, pkg, colors, idSeq, pngTotal, maxPngBytesTotal,
|
||||||
|
options, visitedContents, para);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* In-place замена элемента {@code index} живого списка дерева на {@code reps}
|
||||||
|
* (формула → картинка/текст). Живые списки docx4j — изменяемые
|
||||||
|
* {@code ArrayList}; немодифицируемый список (нетипичный биндинг) —
|
||||||
|
* {@link UnsupportedOperationException}, который вызывающий не ловит:
|
||||||
|
* это ошибка программы, а не враждебный вход (валидатор пропускает только
|
||||||
|
* OOXML-валидные пакеты). Raw-сигнатура — единственный способ mutate
|
||||||
|
* {@code List<?>} без {@code @SuppressWarnings}.
|
||||||
|
*/
|
||||||
|
private static int splice(List content, int index, List reps) {
|
||||||
|
content.remove(index);
|
||||||
|
content.addAll(index, reps);
|
||||||
|
return index + reps.size() - 1;
|
||||||
|
}
|
||||||
|
|
||||||
private static List<?> invokeList(Object target, String getter) {
|
private static List<?> invokeList(Object target, String getter) {
|
||||||
try {
|
try {
|
||||||
Method m = target.getClass().getMethod(getter);
|
Method m = target.getClass().getMethod(getter);
|
||||||
@@ -176,7 +273,8 @@ public final class DrawingPreRenderer {
|
|||||||
}
|
}
|
||||||
|
|
||||||
private static void replaceDrawing(Part part, Drawing drawing, WordprocessingMLPackage pkg,
|
private static void replaceDrawing(Part part, Drawing drawing, WordprocessingMLPackage pkg,
|
||||||
DrawMlColor colors, int[] idSeq, ConvertOptions options) {
|
DrawMlColor colors, int[] idSeq, long[] pngTotal,
|
||||||
|
long maxPngBytesTotal, ConvertOptions options) {
|
||||||
for (Object wrapper : drawing.getAnchorOrInline()) {
|
for (Object wrapper : drawing.getAnchorOrInline()) {
|
||||||
Graphic graphic;
|
Graphic graphic;
|
||||||
long cx;
|
long cx;
|
||||||
@@ -207,10 +305,10 @@ public final class DrawingPreRenderer {
|
|||||||
boolean isChart = CHART_ELEMENT.equals(name);
|
boolean isChart = CHART_ELEMENT.equals(name);
|
||||||
boolean isDiagram = DIAGRAM_ELEMENT.equals(name);
|
boolean isDiagram = DIAGRAM_ELEMENT.equals(name);
|
||||||
if (isChart && options.errorOnCharts()) {
|
if (isChart && options.errorOnCharts()) {
|
||||||
throw new DrawingFoundException(DrawingFoundException.Kind.CHARTS);
|
throw new ChartsFoundException();
|
||||||
}
|
}
|
||||||
if (isDiagram && options.errorOnSmartArt()) {
|
if (isDiagram && options.errorOnSmartArt()) {
|
||||||
throw new DrawingFoundException(DrawingFoundException.Kind.SMARTART);
|
throw new SmartArtFoundException();
|
||||||
}
|
}
|
||||||
if (cx <= 0 || cy <= 0 || cx > MAX_EXTENT_EMU || cy > MAX_EXTENT_EMU) {
|
if (cx <= 0 || cy <= 0 || cx > MAX_EXTENT_EMU || cy > MAX_EXTENT_EMU) {
|
||||||
LOG.warn("drawing вне допустимого wp:extent (cx={}, cy={}) — объект оставлен как есть",
|
LOG.warn("drawing вне допустимого wp:extent (cx={}, cy={}) — объект оставлен как есть",
|
||||||
@@ -234,10 +332,169 @@ public final class DrawingPreRenderer {
|
|||||||
}
|
}
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
swapForPicture(part, gd, img, cx, cy, idSeq, pkg);
|
swapForPicture(part, gd, img, cx, cy, idSeq, pkg, pngTotal, maxPngBytesTotal);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Одна {@code m:oMath} → замены на позиции формулы: inline
|
||||||
|
* {@code w:drawing} с pic:pic (успех) или ран с конкатенацией
|
||||||
|
* {@code m:t} (деградация: unsupported-конструкция — безопасная сеть
|
||||||
|
* после байтового скана MathFallbackNormalizer, пустая/битая формула,
|
||||||
|
* переполнение бюджета PNG). OOM — {@link ConversionException}, не
|
||||||
|
* деградация (тот же контракт, что у графиков).
|
||||||
|
*/
|
||||||
|
private static List<Object> mathReplacements(CTOMath math, boolean display,
|
||||||
|
Part part, WordprocessingMLPackage pkg,
|
||||||
|
int[] idSeq, long[] pngTotal,
|
||||||
|
long maxPngBytesTotal) {
|
||||||
|
try {
|
||||||
|
MathRenderer.MathImage mi = MathRenderer.render(MathModel.build(math, display));
|
||||||
|
if (mi.image() == null) {
|
||||||
|
return textRuns(MathModel.mathText(math));
|
||||||
|
}
|
||||||
|
byte[] png;
|
||||||
|
try {
|
||||||
|
ByteArrayOutputStream bos = new ByteArrayOutputStream();
|
||||||
|
ImageIO.write(mi.image(), "png", bos);
|
||||||
|
png = bos.toByteArray();
|
||||||
|
} finally {
|
||||||
|
mi.image().flush();
|
||||||
|
}
|
||||||
|
if (png.length == 0) {
|
||||||
|
LOG.warn("PNG формулы пуст — формула деградирована в текст");
|
||||||
|
return textRuns(MathModel.mathText(math));
|
||||||
|
}
|
||||||
|
if (pngTotal[0] + png.length > maxPngBytesTotal) {
|
||||||
|
LOG.warn("суммарный размер PNG превысил {} байт — формула деградирована в текст",
|
||||||
|
maxPngBytesTotal);
|
||||||
|
return textRuns(MathModel.mathText(math));
|
||||||
|
}
|
||||||
|
pngTotal[0] += png.length;
|
||||||
|
String relId = addChartMedia(pkg, part, png);
|
||||||
|
long cx = Math.round(mi.widthPt() * 12700.0);
|
||||||
|
long cy = Math.round(mi.heightPt() * 12700.0);
|
||||||
|
Drawing pic = mathPicture(idSeq, relId, cx, cy);
|
||||||
|
if (display) {
|
||||||
|
return List.of(pic);
|
||||||
|
}
|
||||||
|
// FOP ставит инлайн-картинку НИЖНИМ краем на базовую линию
|
||||||
|
// строки, поэтому формула «всплывала» на descent+PAD над
|
||||||
|
// текстом. Word роняет базовую линию формулы на базовую
|
||||||
|
// линию строки — компенсируем смещением ранa вниз:
|
||||||
|
// w:rPr/w:position (полупункты, отрицательное опускает,
|
||||||
|
// §17.3.2.24) через AUDIT-FIX baseline-shift вендорного
|
||||||
|
// XSLT. belowBaselinePt > PAD всегда (канва ≥ габариту +
|
||||||
|
// 2·PAD), нулевого смещения не бывает. Регрессия —
|
||||||
|
// WordPdfConverterTest#ommlMathInline_sitsOnTextBaseline.
|
||||||
|
R run = new R();
|
||||||
|
RPr rpr = new RPr();
|
||||||
|
CTSignedHpsMeasure pos = new CTSignedHpsMeasure();
|
||||||
|
pos.setVal(BigInteger.valueOf(-Math.round(2 * mi.belowBaselinePt())));
|
||||||
|
rpr.setPosition(pos);
|
||||||
|
run.setRPr(rpr);
|
||||||
|
run.getContent().add(pic);
|
||||||
|
return List.of(run);
|
||||||
|
} catch (MathUnsupportedException e) {
|
||||||
|
LOG.info("формула не поддерживается рендером — деградация в текст: {}",
|
||||||
|
e.getMessage());
|
||||||
|
return textRuns(MathModel.mathText(math));
|
||||||
|
} catch (OutOfMemoryError e) {
|
||||||
|
LOG.error("память исчерпана при рендере формулы", e);
|
||||||
|
throw new ConversionException("Память исчерпана при рендере формулы", e);
|
||||||
|
} catch (Docx4JException | IOException | RuntimeException e) {
|
||||||
|
LOG.warn("рендер формулы упал: {}", e.toString());
|
||||||
|
return textRuns(MathModel.mathText(math));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Блок {@code m:oMathPara} (§22.1.3.13): все формулы блока — display.
|
||||||
|
* Word кладёт {@code oMathPara} либо в блок-контейнер (§22.1.3 —
|
||||||
|
* наблюдаемая раскладка Word-файлов), либо в {@code w:p}; в первом
|
||||||
|
* случае формулы заворачиваются в новый центрированный {@code w:p},
|
||||||
|
* во втором — вставляются на место блока, а содержащему абзацу
|
||||||
|
* выставляется {@code jc=center} (семантика центрированной
|
||||||
|
* формулы-абзаца; prose в том же абзаце — враждебный вход, центрируется
|
||||||
|
* тоже — зарегистрированная деградация).
|
||||||
|
*/
|
||||||
|
private static List<Object> mathParaReplacements(CTOMathPara para, P ownerPara,
|
||||||
|
Part part, WordprocessingMLPackage pkg,
|
||||||
|
int[] idSeq, long[] pngTotal,
|
||||||
|
long maxPngBytesTotal) {
|
||||||
|
List<Object> inner = new ArrayList<>();
|
||||||
|
for (CTOMath m : para.getOMath()) {
|
||||||
|
inner.addAll(mathReplacements(m, true, part, pkg, idSeq, pngTotal,
|
||||||
|
maxPngBytesTotal));
|
||||||
|
}
|
||||||
|
if (ownerPara != null) {
|
||||||
|
centerParagraph(ownerPara);
|
||||||
|
return inner;
|
||||||
|
}
|
||||||
|
if (inner.isEmpty()) {
|
||||||
|
return List.of();
|
||||||
|
}
|
||||||
|
P p = new P();
|
||||||
|
PPr ppr = new PPr();
|
||||||
|
Jc jc = new Jc();
|
||||||
|
jc.setVal(JcEnumeration.CENTER);
|
||||||
|
ppr.setJc(jc);
|
||||||
|
p.setPPr(ppr);
|
||||||
|
p.getContent().addAll(inner);
|
||||||
|
return List.of(p);
|
||||||
|
}
|
||||||
|
|
||||||
|
/** {@code jc=center} на абзаце (создаёт {@code w:pPr}, если нет). */
|
||||||
|
private static void centerParagraph(P para) {
|
||||||
|
PPr ppr = para.getPPr();
|
||||||
|
if (ppr == null) {
|
||||||
|
ppr = new PPr();
|
||||||
|
para.setPPr(ppr);
|
||||||
|
}
|
||||||
|
Jc jc = new Jc();
|
||||||
|
jc.setVal(JcEnumeration.CENTER);
|
||||||
|
ppr.setJc(jc);
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Inline {@code w:drawing} с pic:Pic заданного размера (EMU). */
|
||||||
|
private static Drawing mathPicture(int[] idSeq, String relId, long cx, long cy) {
|
||||||
|
Drawing drawing = new Drawing();
|
||||||
|
Inline inline = new Inline();
|
||||||
|
inline.setDistT(0L);
|
||||||
|
inline.setDistB(0L);
|
||||||
|
inline.setDistL(0L);
|
||||||
|
inline.setDistR(0L);
|
||||||
|
CTPositiveSize2D extent = new CTPositiveSize2D();
|
||||||
|
extent.setCx(cx);
|
||||||
|
extent.setCy(cy);
|
||||||
|
inline.setExtent(extent);
|
||||||
|
CTNonVisualDrawingProps docPr = new CTNonVisualDrawingProps();
|
||||||
|
docPr.setId(idSeq[0]++);
|
||||||
|
docPr.setName("Формула " + docPr.getId());
|
||||||
|
inline.setDocPr(docPr);
|
||||||
|
Graphic graphic = new Graphic();
|
||||||
|
GraphicData gd = new GraphicData();
|
||||||
|
gd.setUri(PICTURE_URI);
|
||||||
|
gd.getAny().add(buildPic(idSeq, relId, cx, cy, "Формула"));
|
||||||
|
graphic.setGraphicData(gd);
|
||||||
|
inline.setGraphic(graphic);
|
||||||
|
drawing.getAnchorOrInline().add(inline);
|
||||||
|
return drawing;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Ран с текстом (деградация формулы); пустой текст — пустой список. */
|
||||||
|
private static List<Object> textRuns(String text) {
|
||||||
|
if (text.isEmpty()) {
|
||||||
|
return List.of();
|
||||||
|
}
|
||||||
|
R run = new R();
|
||||||
|
Text t = new Text();
|
||||||
|
t.setValue(text);
|
||||||
|
t.setSpace("preserve");
|
||||||
|
run.getContent().add(new JAXBElement<>(new QName(WML_URI, "t"), Text.class, t));
|
||||||
|
return List.of(run);
|
||||||
|
}
|
||||||
|
|
||||||
private static BufferedImage renderChart(Part part, CTRelId ref,
|
private static BufferedImage renderChart(Part part, CTRelId ref,
|
||||||
DrawMlColor colors, long cx, long cy) {
|
DrawMlColor colors, long cx, long cy) {
|
||||||
Part target = resolve(part, ref.getId());
|
Part target = resolve(part, ref.getId());
|
||||||
@@ -248,8 +505,15 @@ public final class DrawingPreRenderer {
|
|||||||
try {
|
try {
|
||||||
ChartSpec spec = ChartSpec.parse(space, colors);
|
ChartSpec spec = ChartSpec.parse(space, colors);
|
||||||
return ChartRenderer.render(spec, cx / 12700.0, cy / 12700.0, colors);
|
return ChartRenderer.render(spec, cx / 12700.0, cy / 12700.0, colors);
|
||||||
} catch (RuntimeException | OutOfMemoryError e) {
|
} catch (OutOfMemoryError e) {
|
||||||
// OOM — второй эшелон после MAX_EXTENT_EMU/MAX_POINTS: враждебный
|
// OOM — не «деградация объекта»: состояние heap после него
|
||||||
|
// ненадёжно, продолжение рендера следующих объектов — второй
|
||||||
|
// OOM вместо одного детерминированного 500.
|
||||||
|
LOG.error("память исчерпана при рендере графика r:id={}", ref.getId(), e);
|
||||||
|
throw new ConversionException(
|
||||||
|
"Память исчерпана при рендере объектов рисования", e);
|
||||||
|
} catch (RuntimeException e) {
|
||||||
|
// второй эшелон после MAX_EXTENT_EMU/MAX_POINTS: враждебный
|
||||||
// chart-XML не должен валить всю конвертацию, деградация = объект удалён.
|
// chart-XML не должен валить всю конвертацию, деградация = объект удалён.
|
||||||
LOG.warn("рендер графика r:id={} упал: {}", ref.getId(), e.toString());
|
LOG.warn("рендер графика r:id={} упал: {}", ref.getId(), e.toString());
|
||||||
return null;
|
return null;
|
||||||
@@ -265,7 +529,11 @@ public final class DrawingPreRenderer {
|
|||||||
}
|
}
|
||||||
try {
|
try {
|
||||||
return SmartArtRenderer.render(drawing, colors, cx / 12700.0, cy / 12700.0);
|
return SmartArtRenderer.render(drawing, colors, cx / 12700.0, cy / 12700.0);
|
||||||
} catch (RuntimeException | OutOfMemoryError e) {
|
} catch (OutOfMemoryError e) {
|
||||||
|
LOG.error("память исчерпана при рендере SmartArt", e);
|
||||||
|
throw new ConversionException(
|
||||||
|
"Память исчерпана при рендере объектов рисования", e);
|
||||||
|
} catch (RuntimeException e) {
|
||||||
LOG.warn("рендер SmartArt упал: {}", e.toString());
|
LOG.warn("рендер SmartArt упал: {}", e.toString());
|
||||||
return null;
|
return null;
|
||||||
}
|
}
|
||||||
@@ -309,7 +577,8 @@ public final class DrawingPreRenderer {
|
|||||||
*/
|
*/
|
||||||
private static void swapForPicture(Part part, GraphicData gd, BufferedImage img,
|
private static void swapForPicture(Part part, GraphicData gd, BufferedImage img,
|
||||||
long cx, long cy, int[] idSeq,
|
long cx, long cy, int[] idSeq,
|
||||||
WordprocessingMLPackage pkg) {
|
WordprocessingMLPackage pkg,
|
||||||
|
long[] pngTotal, long maxPngBytesTotal) {
|
||||||
byte[] png;
|
byte[] png;
|
||||||
try {
|
try {
|
||||||
ByteArrayOutputStream bos = new ByteArrayOutputStream();
|
ByteArrayOutputStream bos = new ByteArrayOutputStream();
|
||||||
@@ -325,6 +594,13 @@ public final class DrawingPreRenderer {
|
|||||||
gd.getAny().clear(); // контракт: упавший рендер — объект удалён
|
gd.getAny().clear(); // контракт: упавший рендер — объект удалён
|
||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
if (pngTotal[0] + png.length > maxPngBytesTotal) {
|
||||||
|
LOG.warn("суммарный размер chart-PNG превысил {} байт — объект удалён",
|
||||||
|
maxPngBytesTotal);
|
||||||
|
gd.getAny().clear(); // деградация «объект удалён + warn»
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
pngTotal[0] += png.length;
|
||||||
String relId;
|
String relId;
|
||||||
try {
|
try {
|
||||||
relId = addChartMedia(pkg, part, png);
|
relId = addChartMedia(pkg, part, png);
|
||||||
@@ -334,11 +610,25 @@ public final class DrawingPreRenderer {
|
|||||||
return;
|
return;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
Pic pic = buildPic(idSeq, relId, cx, cy, "Диаграмма");
|
||||||
|
|
||||||
|
gd.setUri(PICTURE_URI);
|
||||||
|
gd.getAny().clear();
|
||||||
|
gd.getAny().add(pic);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* {@code pic:pic} на готовый media-r:id: id/имя из счётчика {@code idSeq}
|
||||||
|
* (общего для картинок диаграмм и формул), геометрия — входной extent
|
||||||
|
* (EMU), превью не нужно.
|
||||||
|
*/
|
||||||
|
private static Pic buildPic(int[] idSeq, String relId, long cx, long cy,
|
||||||
|
String namePrefix) {
|
||||||
Pic pic = new Pic();
|
Pic pic = new Pic();
|
||||||
org.docx4j.dml.picture.CTPictureNonVisual nv = new org.docx4j.dml.picture.CTPictureNonVisual();
|
org.docx4j.dml.picture.CTPictureNonVisual nv = new org.docx4j.dml.picture.CTPictureNonVisual();
|
||||||
CTNonVisualDrawingProps props = new CTNonVisualDrawingProps();
|
CTNonVisualDrawingProps props = new CTNonVisualDrawingProps();
|
||||||
props.setId(idSeq[0]++);
|
props.setId(idSeq[0]++);
|
||||||
props.setName("Диаграмма " + props.getId());
|
props.setName(namePrefix + " " + props.getId());
|
||||||
nv.setCNvPr(props);
|
nv.setCNvPr(props);
|
||||||
nv.setCNvPicPr(new CTNonVisualPictureProperties());
|
nv.setCNvPicPr(new CTNonVisualPictureProperties());
|
||||||
pic.setNvPicPr(nv);
|
pic.setNvPicPr(nv);
|
||||||
@@ -368,10 +658,7 @@ public final class DrawingPreRenderer {
|
|||||||
geom.setAvLst(new CTGeomGuideList());
|
geom.setAvLst(new CTGeomGuideList());
|
||||||
spPr.setPrstGeom(geom);
|
spPr.setPrstGeom(geom);
|
||||||
pic.setSpPr(spPr);
|
pic.setSpPr(spPr);
|
||||||
|
return pic;
|
||||||
gd.setUri(PICTURE_URI);
|
|
||||||
gd.getAny().clear();
|
|
||||||
gd.getAny().add(pic);
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,75 @@
|
|||||||
|
package ru.pjandro.wordpdf.internal.chart;
|
||||||
|
|
||||||
|
import java.awt.Color;
|
||||||
|
import java.awt.Graphics2D;
|
||||||
|
import java.awt.RenderingHints;
|
||||||
|
import java.awt.image.BufferedImage;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Растеризация разобранной формулы: дерево {@link MathModel.Box} → PNG
|
||||||
|
* в координатах pt×dpi/72 (тот же растер-контракт, что у график:
|
||||||
|
* {@link ChartRenderer#DPI}, понижение dpi по {@link ChartRenderer#fitDpi}
|
||||||
|
* при превышении площади). Фон прозрачный (ARGB), сглаживание включено —
|
||||||
|
* глифы рисуются контурами fontbox, шрифтов хоста не касается.
|
||||||
|
*
|
||||||
|
* <p>Пустая формула (нулевые метрики) → {@link MathImage} с нулевыми
|
||||||
|
* размерами и {@code image == null}: вызывающий заменяет её текстом
|
||||||
|
* {@code m:t} либо убирает вовсе. {@code OutOfMemoryError} при раздутии
|
||||||
|
* битмапа НЕ перехватывается — это {@code ConversionException} (500) выше
|
||||||
|
* по стеку, не деградация (контракт chart-модели).
|
||||||
|
*/
|
||||||
|
final class MathRenderer {
|
||||||
|
|
||||||
|
/** Минимальный размер растра формулы, pt (тонкий индекс не «схлопнется»). */
|
||||||
|
static final double MIN_WIDTH_PT = 4.0;
|
||||||
|
|
||||||
|
/** Минимальная высота растра формулы, pt. */
|
||||||
|
static final double MIN_HEIGHT_PT = 12.0;
|
||||||
|
|
||||||
|
/** Отступ вокруг габарита формулы, pt (обрезка сглаженных краёв). */
|
||||||
|
static final double PAD_PT = 1.0;
|
||||||
|
|
||||||
|
private MathRenderer() {
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Растр формулы: PNG-носитель, габарит в pt (для extcx/extcy) и
|
||||||
|
* {@code belowBaselinePt} — расстояние от базовой линии формулы до
|
||||||
|
* нижнего края растра (высота минус верхний отступ и ascent; при
|
||||||
|
* клампе к MIN_HEIGHT — с запасом снизу).
|
||||||
|
*/
|
||||||
|
record MathImage(BufferedImage image, double widthPt, double heightPt,
|
||||||
|
double belowBaselinePt) {
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Растр бокса; пустой бокс → {@code image == null}, размеры 0. */
|
||||||
|
static MathImage render(MathModel.Box root) {
|
||||||
|
if (root.isEmpty()) {
|
||||||
|
return new MathImage(null, 0, 0, 0);
|
||||||
|
}
|
||||||
|
double widthPt = Math.max(MIN_WIDTH_PT, root.width + 2 * PAD_PT);
|
||||||
|
double heightPt = Math.max(MIN_HEIGHT_PT, root.ascent + root.descent + 2 * PAD_PT);
|
||||||
|
double dpi = ChartRenderer.fitDpi(widthPt, heightPt);
|
||||||
|
int w = Math.max(1, (int) Math.round(widthPt * dpi / 72.0));
|
||||||
|
int h = Math.max(1, (int) Math.round(heightPt * dpi / 72.0));
|
||||||
|
BufferedImage img = new BufferedImage(w, h, BufferedImage.TYPE_INT_ARGB);
|
||||||
|
Graphics2D g = img.createGraphics();
|
||||||
|
try {
|
||||||
|
g.setRenderingHint(RenderingHints.KEY_ANTIALIASING,
|
||||||
|
RenderingHints.VALUE_ANTIALIAS_ON);
|
||||||
|
g.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING,
|
||||||
|
RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
|
||||||
|
g.setRenderingHint(RenderingHints.KEY_STROKE_CONTROL,
|
||||||
|
RenderingHints.VALUE_STROKE_PURE);
|
||||||
|
g.setColor(new Color(0, 0, 0, 0));
|
||||||
|
double k = dpi / 72.0;
|
||||||
|
g.scale(k, k);
|
||||||
|
double x = (widthPt - root.width) / 2.0;
|
||||||
|
double baseline = PAD_PT + root.ascent;
|
||||||
|
root.paint(g, x, baseline);
|
||||||
|
} finally {
|
||||||
|
g.dispose();
|
||||||
|
}
|
||||||
|
return new MathImage(img, widthPt, heightPt, heightPt - PAD_PT - root.ascent);
|
||||||
|
}
|
||||||
|
}
|
||||||
+20
@@ -0,0 +1,20 @@
|
|||||||
|
package ru.pjandro.wordpdf.internal.chart;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Конструкция OMML, которую формульный рендер не раскладывает: math-элемент
|
||||||
|
* вне {@link MathModel#SUPPORTED}, math-узел не JAXBElement или структурная
|
||||||
|
* поломка (например, {@code w:br} внутри math-рана).
|
||||||
|
*
|
||||||
|
* <p>Сигнал деградации, не отказа: {@code DrawingPreRenderer} заменяет
|
||||||
|
* формулу её текстом {@code m:t} вместо растра (контент не теряется).
|
||||||
|
* Бросается на разборе ({@link MathModel#build}), тем же критерием
|
||||||
|
* срезается раньше — на байтовом уровне в {@code MathFallbackNormalizer}.
|
||||||
|
*/
|
||||||
|
final class MathUnsupportedException extends RuntimeException {
|
||||||
|
|
||||||
|
private static final long serialVersionUID = 1L;
|
||||||
|
|
||||||
|
MathUnsupportedException(String what) {
|
||||||
|
super(what);
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -11,11 +11,11 @@ import java.util.List;
|
|||||||
import java.util.Set;
|
import java.util.Set;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Комбинированная диаграмма (c:ofPieChart, ECMA-376 §21.2.2.108): главный
|
* Комбинированная диаграмма (c:ofPieChart, ECMA-376 §21.2.2.126): главный
|
||||||
* пирог из первичных точек + вторичная круговая (c:ofPieType="pie") либо
|
* пирог из первичных точек + вторичная круговая (c:ofPieType="pie") либо
|
||||||
* вертикальный стек ("bar") из вторичных. Разбиение по c:splitType
|
* вертикальный стек ("bar") из вторичных. Разбиение по c:splitType
|
||||||
* (auto|cust|percent|pos|val, §21.2.2.155; семантика splitPos —
|
* (auto|cust|percent|pos|val, §21.2.2.196; семантика splitPos —
|
||||||
* MS-OI29500 §2.1.1554a/b): auto/pos — последние ceil(n/3) (или splitPos)
|
* MS-OI29500 §2.1.1553): auto/pos — последние ceil(n/3) (или splitPos)
|
||||||
* точек, val/percent — точки ниже splitPos, cust — c:secondPiePt.
|
* точек, val/percent — точки ниже splitPos, cust — c:secondPiePt.
|
||||||
* Вторичных точек нет → обычная круговая через {@link PiePainter}.
|
* Вторичных точек нет → обычная круговая через {@link PiePainter}.
|
||||||
* «Other»-сектор (MS-OI29500 §2.1.1507(a)) замыкает главный пирог и обращён к
|
* «Other»-сектор (MS-OI29500 §2.1.1507(a)) замыкает главный пирог и обращён к
|
||||||
@@ -37,7 +37,7 @@ final class OfPiePainter {
|
|||||||
* калибровка — OfPiePainterTest). */
|
* калибровка — OfPiePainterTest). */
|
||||||
private static final double GAP_FIT = 0.25;
|
private static final double GAP_FIT = 0.25;
|
||||||
|
|
||||||
/** c:ofPieType="bar" — вторичная часть столбчатая (§21.2.2.134). */
|
/** c:ofPieType="bar" — вторичная часть столбчатая (§21.2.2.127). */
|
||||||
private static final String SECONDARY_BAR = "bar";
|
private static final String SECONDARY_BAR = "bar";
|
||||||
|
|
||||||
private OfPiePainter() {
|
private OfPiePainter() {
|
||||||
|
|||||||
@@ -9,9 +9,9 @@ import java.util.ArrayList;
|
|||||||
import java.util.List;
|
import java.util.List;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Лепестковая диаграмма (c:radarChart, ECMA-376 §21.2.2.143): категории —
|
* Лепестковая диаграмма (c:radarChart, ECMA-376 §21.2.2.153): категории —
|
||||||
* спицы от 12 часов по часовой, значения — радиус по оси значений.
|
* спицы от 12 часов по часовой, значения — радиус по оси значений.
|
||||||
* c:radarStyle (§21.2.2.119): standard — контур, marker — контур + маркеры,
|
* c:radarStyle (§21.2.2.154): standard — контур, marker — контур + маркеры,
|
||||||
* filled — полупрозрачная заливка без контура (вид как у AREA).
|
* filled — полупрозрачная заливка без контура (вид как у AREA).
|
||||||
* Сетка — концентрические многоугольники по делениям оси значений (паутина
|
* Сетка — концентрические многоугольники по делениям оси значений (паутина
|
||||||
* прямыми звеньями, как в Word) и спицы.
|
* прямыми звеньями, как в Word) и спицы.
|
||||||
|
|||||||
@@ -15,9 +15,9 @@ import java.util.List;
|
|||||||
* ChartSpecTest#scatterFirstValAxisIsX).
|
* ChartSpecTest#scatterFirstValAxisIsX).
|
||||||
*
|
*
|
||||||
* scatter: маркеры по c:marker ряда, линия по c:scatterStyle (line/smooth —
|
* scatter: маркеры по c:marker ряда, линия по c:scatterStyle (line/smooth —
|
||||||
* ECMA-376 §21.2.2.136, сглаживание — кривая Жозефа де Кастельно не
|
* ECMA-376 §21.2.2.162, сглаживание — кривая Жозефа де Кастельно не
|
||||||
* имитируется, ломаная с JOIN_ROUND). bubble: круги без обводки, радиус
|
* имитируется, ломаная с JOIN_ROUND). bubble: круги без обводки, радиус
|
||||||
* sqrt(|size|/maxSize) при c:sizeRepresents="area" (§21.2.2.128) и линейно
|
* sqrt(|size|/maxSize) при c:sizeRepresents="area" (§21.2.2.193) и линейно
|
||||||
* при "w", масштаб c:bubbleScale. Ограничения: c:bubble3D рисуется плоско.
|
* при "w", масштаб c:bubbleScale. Ограничения: c:bubble3D рисуется плоско.
|
||||||
*
|
*
|
||||||
* Регрессия — ScatterPainterTest, фикстура samples/chart-types.docx
|
* Регрессия — ScatterPainterTest, фикстура samples/chart-types.docx
|
||||||
|
|||||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user