Compare commits

4 Commits

Author SHA1 Message Date
Pjandro b558fe1c30 docs: README — короткая точка входа, AGENTS — строка docs-*
PR checks / web (pull_request) Successful in 10s
PR checks / java (pull_request) Successful in 5m51s
PR checks / macos-sim (pull_request) Successful in 7m8s
- README сокращён: human-контент перенесён на сайт документации;
  остались структура, бутстрап, команды, задачи mise, ссылки на документацию.
- AGENTS.md: команды docs-* в Development Commands.
2026-11-22 21:39:08 +03:00
Pjandro 187938c4db build: mise-задачи docs-* и gitignore сайта
- docs-install/docs-serve/docs-build/docs-javadoc/docs-deploy;
  публикация: javadoc → strict-build → rsync в ~/srv/wordpdf-docs (:9012).
- gitignore: site/, docs/.venv/, docs/apidocs/.
2026-11-22 21:39:08 +03:00
Pjandro 0e9266450c build: maven-javadoc-plugin для публичного API core
- Корневой pom: версия 3.12.0 + pluginManagement (outputDirectory закреплён
  на target/site, цель — только javadoc:javadoc, лайфцикл verify не меняется).
- wordpdf-core объявляет плагин без executions; wordpdf-app javadoc не генерирует.
- Правки javadoc-комментарий по ошибкам doclint: {@code <=} в ChartImageHandler,
  полные имена {@link ru.pjandro.wordpdf.ConversionException} в DocToDocx.
2026-11-22 21:39:08 +03:00
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00
35 changed files with 1723 additions and 327 deletions
+5
View File
@@ -44,3 +44,8 @@ DEPLOY.md
# Mise: локальный бинарь mise (bootstrap.sh / bootstrap.ps1)
/.mise/
# Сайт документации: сборка, venv, копия javadoc
site/
docs/.venv/
docs/apidocs/
+1
View File
@@ -76,6 +76,7 @@ curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
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)
```
+31 -321
View File
@@ -6,22 +6,6 @@
идёт тем же конвейером. Шрифты упакованы в 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,330 +15,56 @@ java-word-pdf/
└── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)
```
Ключевые классы (`wordpdf-core`):
## Быстрый старт
|Класс|Назначение|
|---|---|
|`ru.pjandro.wordpdf.WordPdfConverter`|публичный API: `convert(byte[], String, ConvertOptions)` — .docx/.doc по сигнатуре байтов, байты PDF на выходе; `warmup()` — прогрев ядра|
|`ru.pjandro.wordpdf.WordPdfValidator`|валидация входа и lightweight-оценка страниц без рендера (`checkInput`/`validate`; подсчёт страниц — внутренний метод)|
|`ru.pjandro.wordpdf.ConvertOptions`|опции конвертации (record `errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages`); дефолтов в ядре нет — значения задаёт вызывающий|
|`ru.pjandro.wordpdf.ConversionException`|ошибки конвертации; подтипы `ValidationException` (некорректный вход) и `ChartsFoundException`/`SmartArtFoundException`/`OleFoundException` (по error-флагам)|
|`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:
Первая настройка — project-local mise (ставит temurin-17, maven 3.9.16, node 24,
python 3.15 в кеш mise, в систему ничего не идёт) + `npm ci` SPA:
```bash
sh bootstrap.sh # Linux / macOS
```
```powershell
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
```
Дальше команды — через обёртку `./mise.sh` (Linux/macOS) или `.\mise.ps1` (Windows):
Дальше всё через обёртку `./mise.sh` (Windows: `.\mise.ps1`):
```bash
./mise.sh run verify # полный гейт перед push: тесты + PMD + JaCoCo
./mise.sh exec -- mvn -v # любая команда с инструментами проекта в PATH
./mise.sh tasks # список задач с описаниями
./mise.sh run app-package && ./mise.sh run app-run # бэкенд на :8080, ключ выключен
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-nofontconfig`|`mvn clean verify` в контейнере без fontconfig (гейт CI; требует podman/docker)|
|`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|
|`verify-nofontconfig`|тот же verify в контейнере без fontconfig (гейт CI; требует podman/docker)|
|`mem-bench`|замер памяти конвейера (TSV пиков + JFR)|
|`app-package` / `app-run`|исполняемый jar бэкенда / бэкенд на :8080|
|`web-install` / `web-build` / `web-lint` / `web-dev`|SPA: `npm ci` / гейт `tsc -b && vite build` / oxlint / :5173|
|`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 в шелле и работать напрямую
(`mvn`, `npm`, `python`): `eval "$(./.mise/bin/mise activate bash)"`.
## Сборка
## Документация
Требуется **Java 17** и **Maven** (бэкенд), **Node.js `^20.19.0 || >=22.12.0`**
(engines Vite 8; mise ставит Node 24) — всё это ставит project-local mise
(см. «Инструменты проекта (mise)» выше). Команды ниже запускайте через
`./mise.sh exec -- …` (Windows: `.\mise.ps1 exec -- …`) либо после активации mise в шелле.
```bash
mvn clean verify # все модули + тесты
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
```
Результат: `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 страниц) —
дефолт эндпоинта; query/form-параметры `maxMb`/`maxPages` переопределяют его
в обе стороны (значения ≤ 0 → 400). Остальные пороги (распаковка архива,
XML-части, площади растров, число записей zip) выводятся из лимитов входа.
|Код|Смысл|
|---|---|
|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)|
Ошибки — 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` в контейнере без fontconfig + сводка покрытия комментарием в 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 требующих его пропускаются.
- **Сайт документации** (пользователю / REST API / библиотека / архитектура /
разработчику / эксплуатация): `http://192.168.88.23:9012/`
— исходники в `docs/`, публикация `./mise.sh run docs-deploy`,
javadoc — там же по `/apidocs/`.
- Веб-конвертер (прод): `https://pjandro.ru/pdf-converter/`.
- Внутренние справочники для правки кода — `docs/agent/` (pipeline, doc-bridge,
chart, render-limitations, testing, ci-cd, repo-map), нормативные спецификации
форматов — `docs/standards/`.
- Правила репозитория — `AGENTS.md`.
+52
View File
@@ -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.
+45
View File
@@ -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).
+55
View File
@@ -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`|
+74
View File
@@ -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).
+53
View File
@@ -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. Проверка размера входа
выполняется синхронно, до постановки в очередь.
+47
View File
@@ -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
мгновенно — текущая конвертация дожигается, следующий запрос ждёт её в очереди.
+62
View File
@@ -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).
+61
View File
@@ -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).
+63
View File
@@ -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`).
+40
View File
@@ -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).
+68
View File
@@ -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).
+64
View File
@@ -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).
+83
View File
@@ -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.
+71
View File
@@ -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).
+64
View File
@@ -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) — для глубокой правки кода.
+39
View File
@@ -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.
+75
View File
@@ -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.
+66
View File
@@ -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`|нет|
+72
View File
@@ -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` из транзитивных зависимостей.
+52
View File
@@ -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).
+54
View File
@@ -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).
+88
View File
@@ -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 как статика.
+61
View File
@@ -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|
+74
View File
@@ -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) маршрутизируется по байтам — это
не ошибка.
+1
View File
@@ -0,0 +1 @@
mkdocs-material==9.8.2
+56
View File
@@ -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).
+30
View File
@@ -54,3 +54,33 @@ run = "npm run dev"
description = "Прод-автотесты; обязателен WORDPDF_BASE_URL (факультативно WORDPDF_API_KEY)"
dir = "prod-autotests"
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
View File
@@ -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
+23
View File
@@ -39,6 +39,8 @@
<!-- Покрытие: последняя стабильная на Maven Central -->
<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 не споткнётся
о неразвёрнутый @{argLine}; prepare-agent перезаписывает его -->
<argLine></argLine>
@@ -156,6 +158,27 @@
<artifactId>maven-jar-plugin</artifactId>
<version>3.5.1</version>
</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>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
+9
View File
@@ -143,6 +143,15 @@
</execution>
</executions>
</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>
</build>
</project>
@@ -30,10 +30,10 @@ import java.nio.ByteBuffer;
*
* Медиа документов (фото/скрины) — не наши части, но и для них штатный путь
* дорог: {@code PictureCompression.compress} декодирует полный растр (ImageIO)
* ДО любых решений, а для не-JPEG без кропа с ppi <= threshold (и без размера
* ДО любых решений, а для не-JPEG без кропа с ppi {@code <=} threshold (и без размера
* в макете) результат всегда null — декод впустую. Здесь такое решение
* принимается по 26 байтам заголовка (PNG/GIF/BMP), растр не декодируется
* вовсе. JPEG сознательно не ускоряем: Word при ppi <= threshold перекодирует
* вовсе. JPEG сознательно не ускоряем: Word при ppi {@code <=} threshold перекодирует
* его «для размера», вывод должен остаться побайтно прежним.
*
* Регрессии — WordPdfConverterTest#chartMedia_notDownsampled,
@@ -67,7 +67,7 @@ import java.util.regex.Pattern;
*
* <p>Контракт ошибок: любой некорректный вход (не CFB, не Word, шифрование,
* Word 6/95, обрезка, цикл в цепочках, страницы сверх лимита) —
* {@link ConversionException}.</p>
* {@link ru.pjandro.wordpdf.ConversionException}.</p>
*/
public final class DocToDocx {
@@ -122,7 +122,8 @@ public final class DocToDocx {
* @param docBytes контейнер Word 97–2003
* @param maxMb лимит размера входа (МБ) — из него порог пиксельной
* площади растра ({@code WordPdfValidator.maxImagePixels})
* @throws ConversionException на некорректном/зашифрованном/чужом входе
* @throws ru.pjandro.wordpdf.ConversionException
* на некорректном/зашифрованном/чужом входе
*/
public static byte[] convert(byte[] docBytes, long maxMb) {
long maxPixels = WordPdfValidator.maxImagePixels(maxMb);
@@ -226,7 +227,8 @@ public final class DocToDocx {
* Нижняя оценка числа страниц бинарного .doc (кэш PageCount + явные
* разрывы) — для {@code WordPdfValidator.checkPageCountDoc}.
*
* @throws ConversionException на некорректном/зашифрованном/чужом входе
* @throws ru.pjandro.wordpdf.ConversionException
* на некорректном/зашифрованном/чужом входе
*/
public static int countPages(byte[] docBytes) {
return DocFile.open(docBytes).countPages();