Compare commits
4 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| b558fe1c30 | |||
| 187938c4db | |||
| 0e9266450c | |||
| b3511f8b74 |
@@ -44,3 +44,8 @@ DEPLOY.md
|
|||||||
# Mise: локальный бинарь mise (bootstrap.sh / bootstrap.ps1)
|
# Mise: локальный бинарь mise (bootstrap.sh / bootstrap.ps1)
|
||||||
/.mise/
|
/.mise/
|
||||||
|
|
||||||
|
# Сайт документации: сборка, venv, копия javadoc
|
||||||
|
site/
|
||||||
|
docs/.venv/
|
||||||
|
docs/apidocs/
|
||||||
|
|
||||||
|
|||||||
@@ -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 -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)
|
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 prod-tests # pytest; обязателен WORDPDF_BASE_URL
|
||||||
|
./mise.sh run docs-install|docs-serve|docs-build|docs-javadoc|docs-deploy # сайт документации (MkDocs Material): venv+pip | preview :8000 | strict-сборка в site/ | javadoc core | публикация в ~/srv/wordpdf-docs (юнит wordpdf-docs.service, :9012)
|
||||||
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD (lxml)
|
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD (lxml)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
@@ -6,22 +6,6 @@
|
|||||||
идёт тем же конвейером. Шрифты упакованы в jar — конвертация не зависит от
|
идёт тем же конвейером. Шрифты упакованы в jar — конвертация не зависит от
|
||||||
шрифтов, установленных в системе (работает «из коробки» на голом сервере).
|
шрифтов, установленных в системе (работает «из коробки» на голом сервере).
|
||||||
|
|
||||||
## Возможности
|
|
||||||
|
|
||||||
- Поддержка RU/EN: кириллица и латиница встраиваются в PDF (embedded-подмножества).
|
|
||||||
- Самодостаточность: TTF выгружаются из jar в временный каталог и регистрируются
|
|
||||||
в docx4j/FOP.
|
|
||||||
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
|
|
||||||
(см. «Шрифты» ниже).
|
|
||||||
- Диаграммы и SmartArt растеризуются в PNG собственным Java2D-движком — без Word/LibreOffice.
|
|
||||||
- Бинарный `.doc` (Word 97–2003): текст, стили, таблицы, списки, колонтитуки,
|
|
||||||
картинки — собственный мост `internal/doc` без внешних зависимостей;
|
|
||||||
error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры
|
|
||||||
уже растры → вставляются картинками; EMF/WMF/PICT пропускаются с warn).
|
|
||||||
- OLE-внедрения вычищаются перед загрузкой; картинка-плейсхолдер из документа сохраняется.
|
|
||||||
- Клиентская библиотека (`wordpdf-core`), REST API (`wordpdf-app`, Spring Boot)
|
|
||||||
и веб-интерфейс (`wordpdf-web`, React SPA).
|
|
||||||
|
|
||||||
## Структура
|
## Структура
|
||||||
|
|
||||||
```
|
```
|
||||||
@@ -31,330 +15,56 @@ java-word-pdf/
|
|||||||
└── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)
|
└── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven)
|
||||||
```
|
```
|
||||||
|
|
||||||
Ключевые классы (`wordpdf-core`):
|
## Быстрый старт
|
||||||
|
|
||||||
|Класс|Назначение|
|
Первая настройка — project-local mise (ставит temurin-17, maven 3.9.16, node 24,
|
||||||
|---|---|
|
python 3.15 в кеш mise, в систему ничего не идёт) + `npm ci` SPA:
|
||||||
|`ru.pjandro.wordpdf.WordPdfConverter`|публичный API: `convert(byte[], String, ConvertOptions)` — .docx/.doc по сигнатуре байтов, байты PDF на выходе; `warmup()` — прогрев ядра|
|
|
||||||
|`ru.pjandro.wordpdf.WordPdfValidator`|валидация входа и lightweight-оценка страниц без рендера (`checkInput`/`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:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
sh bootstrap.sh # Linux / macOS
|
sh bootstrap.sh # Linux / macOS
|
||||||
```
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
|
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
|
||||||
```
|
```
|
||||||
|
|
||||||
Дальше команды — через обёртку `./mise.sh` (Linux/macOS) или `.\mise.ps1` (Windows):
|
Дальше всё через обёртку `./mise.sh` (Windows: `.\mise.ps1`):
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./mise.sh run verify # полный гейт перед push: тесты + PMD + JaCoCo
|
./mise.sh run verify # полный гейт перед push: тесты + PMD + JaCoCo
|
||||||
./mise.sh exec -- mvn -v # любая команда с инструментами проекта в PATH
|
./mise.sh run app-package && ./mise.sh run app-run # бэкенд на :8080, ключ выключен
|
||||||
./mise.sh tasks # список задач с описаниями
|
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
||||||
```
|
```
|
||||||
|
|
||||||
Задачи проекта (`./mise.sh run <задача>`):
|
Стенды на контейнерах (podman), наружный вход — только nginx-gateway:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32
|
||||||
|
podman-compose up -d --build # prod-like :9010 (fail-closed: без ключа не встанет)
|
||||||
|
podman-compose -f compose.dev.yml up -d --build --force-recreate # dev :9011, без ключа
|
||||||
|
```
|
||||||
|
|
||||||
|
## Задачи проекта (`./mise.sh run <задача>`)
|
||||||
|
|
||||||
|Задача|Содержание|
|
|Задача|Содержание|
|
||||||
|---|---|
|
|---|---|
|
||||||
|`verify`|`mvn clean verify` — тесты + PMD + JaCoCo|
|
|`verify`|`mvn clean verify` — тесты + PMD + JaCoCo|
|
||||||
|`verify-nofontconfig`|`mvn clean verify` в контейнере без fontconfig (гейт CI; требует podman/docker)|
|
|`verify-nofontconfig`|тот же verify в контейнере без fontconfig (гейт CI; требует podman/docker)|
|
||||||
|`app-package`|исполняемый jar бэкенда|
|
|`mem-bench`|замер памяти конвейера (TSV пиков + JFR)|
|
||||||
|`app-run`|бэкенд на :8080, ключ выключен (после `app-package`)|
|
|`app-package` / `app-run`|исполняемый jar бэкенда / бэкенд на :8080|
|
||||||
|`web-install`|`npm ci` в `wordpdf-web`|
|
|`web-install` / `web-build` / `web-lint` / `web-dev`|SPA: `npm ci` / гейт `tsc -b && vite build` / oxlint / :5173|
|
||||||
|`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`|
|
|`prod-tests`|прод-автотесты; обязателен `WORDPDF_BASE_URL`, факультативно `WORDPDF_API_KEY`|
|
||||||
|
|`docs-install` / `docs-serve` / `docs-build`|сайт документации: venv+pip / preview :8000 / strict-сборка в `site/`|
|
||||||
|
|`docs-javadoc` / `docs-deploy`|javadoc core / публикация сайта на rpi (:9012)|
|
||||||
|
|
||||||
Альтернатива обёртке — активировать mise в шелле и работать напрямую
|
Альтернатива обёртке — активировать mise в шелле и работать напрямую
|
||||||
(`mvn`, `npm`, `python`): `eval "$(./.mise/bin/mise activate bash)"`.
|
(`mvn`, `npm`, `python`): `eval "$(./.mise/bin/mise activate bash)"`.
|
||||||
|
|
||||||
## Сборка
|
## Документация
|
||||||
|
|
||||||
Требуется **Java 17** и **Maven** (бэкенд), **Node.js `^20.19.0 || >=22.12.0`**
|
- **Сайт документации** (пользователю / REST API / библиотека / архитектура /
|
||||||
(engines Vite 8; mise ставит Node 24) — всё это ставит project-local mise
|
разработчику / эксплуатация): `http://192.168.88.23:9012/`
|
||||||
(см. «Инструменты проекта (mise)» выше). Команды ниже запускайте через
|
— исходники в `docs/`, публикация `./mise.sh run docs-deploy`,
|
||||||
`./mise.sh exec -- …` (Windows: `.\mise.ps1 exec -- …`) либо после активации mise в шелле.
|
javadoc — там же по `/apidocs/`.
|
||||||
|
- Веб-конвертер (прод): `https://pjandro.ru/pdf-converter/`.
|
||||||
```bash
|
- Внутренние справочники для правки кода — `docs/agent/` (pipeline, doc-bridge,
|
||||||
mvn clean verify # все модули + тесты
|
chart, render-limitations, testing, ci-cd, repo-map), нормативные спецификации
|
||||||
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
|
форматов — `docs/standards/`.
|
||||||
```
|
- Правила репозитория — `AGENTS.md`.
|
||||||
|
|
||||||
Результат: `wordpdf-app/target/wordpdf-app-<версия>.jar` (все зависимости
|
|
||||||
внутри). Для фронтенда — отдельные команды (вне Maven): `npm ci && npm run build`
|
|
||||||
в `wordpdf-web/` — по закоммиченному `package-lock.json` (то же делают задачи
|
|
||||||
mise `web-install`/`web-build`; результат — статика в `wordpdf-web/dist/`).
|
|
||||||
|
|
||||||
## Использование
|
|
||||||
|
|
||||||
### REST API
|
|
||||||
|
|
||||||
```bash
|
|
||||||
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
|
|
||||||
curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \
|
|
||||||
http://localhost:8080/api/v1/convert -o doc.pdf
|
|
||||||
```
|
|
||||||
|
|
||||||
`POST /api/v1/convert` принимает multipart-поле `file` (.docx или .doc) и синхронно
|
|
||||||
возвращает байты PDF (`application/pdf`, `Content-Disposition: attachment;
|
|
||||||
filename*=UTF-8''…` — имя файла санитизировано, кириллица разрешена).
|
|
||||||
|
|
||||||
**Ключ доступа.** Заголовок `X-API-Key` сверяется со свойством `wordpdf.api-key`
|
|
||||||
(env `WORDPDF_API_KEY`); пустое свойство — аутентификация выключена (`java -jar`,
|
|
||||||
dev-стенд). Без ключа открыты `/actuator/`, `/swagger-ui`, `/v3/api-docs`; без ключа
|
|
||||||
или с неверным — 401 `{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}`.
|
|
||||||
|
|
||||||
**Факультативные query/form-параметры** `errorOnCharts`/`errorOnSmartArt`/`errorOnOle`
|
|
||||||
(Boolean, дефолт `false`): при `true` соответствующие объекты в документе отменяют
|
|
||||||
конвертацию с 422. Диаграммы/SmartArt конвертируются в растры всегда; OLE-объекты
|
|
||||||
при `errorOnOle=false` тихо удаляются.
|
|
||||||
|
|
||||||
**Лимиты входа**: свойства `wordpdf.max-mb`/`wordpdf.max-pages`
|
|
||||||
(env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`, дефолты 5 МБ / 100 страниц) —
|
|
||||||
дефолт эндпоинта; 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 требующих его пропускаются.
|
|
||||||
|
|||||||
@@ -0,0 +1,52 @@
|
|||||||
|
# Аутентификация
|
||||||
|
|
||||||
|
## Ключ доступа
|
||||||
|
|
||||||
|
Все запросы, кроме открытых путей, требуют заголовок:
|
||||||
|
|
||||||
|
```
|
||||||
|
X-API-Key: <ключ>
|
||||||
|
```
|
||||||
|
|
||||||
|
Ключ сверяется со свойством сервера `wordpdf.api-key` (env `WORDPDF_API_KEY`).
|
||||||
|
Сравнение — `MessageDigest.isEqual` (защита от timing-атак). **Пустое свойство =
|
||||||
|
аутентификация выключена** — так работают `java -jar` и dev-стенд (:9011).
|
||||||
|
|
||||||
|
Без ключа или с неверным:
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP 401
|
||||||
|
{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Открытые пути
|
||||||
|
|
||||||
|
Без ключа всегда доступны (матч по **префиксу со слэшем**, без учёта
|
||||||
|
forwarded-contextPath):
|
||||||
|
|
||||||
|
|Префикс|Что|
|
||||||
|
|---|---|
|
||||||
|
|`/actuator/`|health-checks Spring Boot|
|
||||||
|
|`/swagger-ui`|Swagger UI|
|
||||||
|
|`/v3/api-docs`|OpenAPI-спек|
|
||||||
|
|
||||||
|
!!! warning "Точечные сегменты обходят открытие"
|
||||||
|
Пути с точечными сегментами (`..` или их URL-код `%2e`) **никогда** не считаются
|
||||||
|
открытыми: запрос вида `/actuator/../api/v1/convert` потребует ключ даже на
|
||||||
|
открытом префиксе. Это защита от обхода фильтра через нормализацию пути.
|
||||||
|
|
||||||
|
## Где задаётся ключ
|
||||||
|
|
||||||
|
|Среда|Как|
|
||||||
|
|---|---|
|
||||||
|
|`java -jar`|`wordpdf.api-key=` пусто — auth выключен; включить: `--wordpdf.api-key=…` или env `WORDPDF_API_KEY`|
|
||||||
|
|prod-like стенд (:9010)|обязателен `.env` с `WORDPDF_API_KEY` (fail-closed: без него стек не поднимется), шаблон — `.env.example`|
|
||||||
|
|прод|env-переменная контейнера из Gitea Secret (в репозитории и на диске ключа нет)|
|
||||||
|
|
||||||
|
Сгенерировать ключ: `openssl rand -hex 32`.
|
||||||
|
|
||||||
|
## Как фронтенд узнаёт про ключ
|
||||||
|
|
||||||
|
SPA при старте опрашивает сервис (`probeApiKey()`, `GET /api/v1/convert`): 401 —
|
||||||
|
сервер требует ключ, показывается экран ввода; иначе — интерфейс открывается сразу.
|
||||||
|
Введённый ключ хранится в `localStorage` браузера и стирается при ответе 401.
|
||||||
@@ -0,0 +1,45 @@
|
|||||||
|
# Эндпоинт конвертации
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/v1/convert
|
||||||
|
```
|
||||||
|
|
||||||
|
Тело запроса — `multipart/form-data` с обязательным полем **`file`**: файл `.docx`
|
||||||
|
(OOXML) или `.doc` (Word 97–2003, переносится мостом в .docx в памяти). Файлы других
|
||||||
|
расширений отклоняются 400.
|
||||||
|
|
||||||
|
## Факультативные query/form-параметры
|
||||||
|
|
||||||
|
Параметры можно передать в query-строке или как form-поля.
|
||||||
|
|
||||||
|
|Параметр|Тип|Дефолт|Действие|
|
||||||
|
|---|---|---|---|
|
||||||
|
|`errorOnCharts`|Boolean|`false`|при `true` диаграммы в документе отменяют конвертацию (422); диаграммы конвертируются в растры всегда|
|
||||||
|
|`errorOnSmartArt`|Boolean|`false`|при `true` SmartArt отменяет конвертацию (422)|
|
||||||
|
|`errorOnOle`|Boolean|`false`|при `true` OLE-объекты отменяют конвертацию (422); при `false` OLE-объекты тихо удаляются, картинка-плейсхолдер сохраняется|
|
||||||
|
|`maxMb`|число|свойство сервера `wordpdf.max-mb` (5)|лимит размера входа в МБ; переопределяет серверный дефолт **в обе стороны**; `≤ 0` → 400|
|
||||||
|
|`maxPages`|число|свойство сервера `wordpdf.max-pages` (100)|лимит числа страниц; переопределяет в обе стороны; `≤ 0` → 400|
|
||||||
|
|
||||||
|
!!! note "На `.doc` error-флаги не срабатывают"
|
||||||
|
Плейсхолдеры диаграмм/SmartArt/OLE в бинарном формате — это BLIP-растры, мост
|
||||||
|
вставляет их картинками; векторные EMF/WMF/PICT пропускаются с warn. Флаги
|
||||||
|
работают только для `.docx`.
|
||||||
|
|
||||||
|
## Успешный ответ
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP 200
|
||||||
|
Content-Type: application/pdf
|
||||||
|
Content-Disposition: attachment; filename*=UTF-8''Документ.pdf
|
||||||
|
```
|
||||||
|
|
||||||
|
Имя файла берётся из `Content-Disposition` загруженного файла, санитизируется
|
||||||
|
(разрешены буквы, цифры, пробел и `._-`; кириллица разрешена; пустое имя → `document`)
|
||||||
|
и используется единожды для имени файла, заголовка ответа и заголовка PDF.
|
||||||
|
|
||||||
|
## Обработка
|
||||||
|
|
||||||
|
Задача ставится в однопоточную очередь воркеров (16 мест). Проверка размера —
|
||||||
|
синхронно до очереди. Конвертация дольше `wordpdf.convert-timeout` (2m) → 504,
|
||||||
|
очередь полна → 503. Полная таблица ответов — [Коды ошибок](errors.md),
|
||||||
|
пороги — [Лимиты](limits.md).
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
# Коды ошибок
|
||||||
|
|
||||||
|
Ошибки — JSON вида `{"error": "..."}`.
|
||||||
|
|
||||||
|
## Полная таблица
|
||||||
|
|
||||||
|
|Код|Смысл|
|
||||||
|
|---|---|
|
||||||
|
|200|PDF в теле ответа|
|
||||||
|
|400|некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше лимита размера (`maxMb` или `wordpdf.max-mb`) / больше лимита страниц (`maxPages` или `wordpdf.max-pages`) / `maxMb`≤0 / `maxPages`≤0), отсутствующая часть `file`, некорректное значение error-флага|
|
||||||
|
|401|нет или неверен `X-API-Key`|
|
||||||
|
|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)|
|
||||||
|
|405|не-POST|
|
||||||
|
|413|тело запроса больше контейнерного лимита multipart (100 МБ; авторитетный лимит входа — `wordpdf.max-mb`, он даёт 400 раньше)|
|
||||||
|
|415|не-multipart тело|
|
||||||
|
|422|сработал error-флаг: в документе найдены диаграммы / SmartArt / OLE-объекты|
|
||||||
|
|500|ошибка ядра/рендера|
|
||||||
|
|503|очередь конвертации (16 мест) переполнена — повторить позже|
|
||||||
|
|504|конвертация дольше `wordpdf.convert-timeout` (по умолчанию 2m)|
|
||||||
|
|
||||||
|
## Фиксированные тексты
|
||||||
|
|
||||||
|
Тексты ниже — контракт с фронтендом, они не меняются:
|
||||||
|
|
||||||
|
|Код|Тело|
|
||||||
|
|---|---|
|
||||||
|
|401|`{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}`|
|
||||||
|
|404|`{"error":"Не найдено"}`|
|
||||||
|
|405|`{"error":"Метод не поддерживается"}`|
|
||||||
|
|415|`{"error":"Неподдерживаемый тип содержимого"}`|
|
||||||
|
|422 (диаграммы)|`{"error":"Конвертация отменена: в документе найдены диаграммы"}`|
|
||||||
|
|422 (SmartArt)|`{"error":"Конвертация отменена: в документе найден SmartArt"}`|
|
||||||
|
|422 (OLE)|`{"error":"Конвертация отменена: в документе найдены OLE-объекты"}`|
|
||||||
|
|500|`{"error":"Не удалось конвертировать документ"}`|
|
||||||
|
|
||||||
|
Другие 400-тексты параметризованы, например: `Файл не передан (multipart-поле «file»
|
||||||
|
обязательно)`, `Поддерживаются только .docx и .doc: <имя>`, `Файл больше <N> МБ: …`,
|
||||||
|
`Некорректное значение параметра «<имя>»`.
|
||||||
|
|
||||||
|
!!! info "500 — деталь только в лог"
|
||||||
|
Сообщения ядра (`ConversionException` и др.) логируются на сервере, наружу
|
||||||
|
всегда уходит фиксированный текст — внутренние детали не текут клиенту.
|
||||||
|
|
||||||
|
## Исключение → обработчик (для отладки)
|
||||||
|
|
||||||
|
|HTTP|Источник|
|
||||||
|
|---|---|
|
||||||
|
|400|`ValidationException`, `BadRequestException`, `MethodArgumentTypeMismatchException`, `MissingServletRequestPartException`|
|
||||||
|
|401|`ApiKeyFilter` (пишет ответ сам, до диспетчера)|
|
||||||
|
|404 / 405 / 415|`NoResourceFoundException` / `HttpRequestMethodNotSupportedException` / `HttpMediaTypeNotSupportedException`|
|
||||||
|
|413|`MaxUploadSizeExceededException`|
|
||||||
|
|422|`DrawingRejectedException`|
|
||||||
|
|500|`ConversionFailedException`|
|
||||||
|
|503|`ConversionRejectedException`|
|
||||||
|
|504|`ConversionTimeoutException`|
|
||||||
@@ -0,0 +1,74 @@
|
|||||||
|
# Примеры клиентов
|
||||||
|
|
||||||
|
Базовый адрес зависит от стенда: прод `https://pjandro.ru/pdf-converter/api/v1/convert`,
|
||||||
|
prod-like локально `http://localhost:9010/api/v1/convert`, dev `http://<LAN-IP>:9011/api/v1/convert`,
|
||||||
|
`java -jar` — `http://localhost:8080/api/v1/convert`.
|
||||||
|
|
||||||
|
## curl
|
||||||
|
|
||||||
|
Без ключа (сервер с выключенной аутентификацией):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
||||||
|
```
|
||||||
|
|
||||||
|
С ключом и error-флагом:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "X-API-Key: $WORDPDF_API_KEY" \
|
||||||
|
-F "file=@Отчёт.docx" \
|
||||||
|
"https://pjandro.ru/pdf-converter/api/v1/convert?errorOnOle=true&maxMb=10" \
|
||||||
|
-o out.pdf
|
||||||
|
```
|
||||||
|
|
||||||
|
## JavaScript (fetch)
|
||||||
|
|
||||||
|
```js
|
||||||
|
const form = new FormData();
|
||||||
|
form.append("file", fileInput.files[0], fileInput.files[0].name);
|
||||||
|
|
||||||
|
const resp = await fetch("/api/v1/convert", {
|
||||||
|
method: "POST",
|
||||||
|
headers: apiKey ? { "X-API-Key": apiKey } : {},
|
||||||
|
body: form,
|
||||||
|
});
|
||||||
|
|
||||||
|
if (!resp.ok) {
|
||||||
|
const { error } = await resp.json().catch(() => ({ error: resp.statusText }));
|
||||||
|
throw new Error(error);
|
||||||
|
}
|
||||||
|
|
||||||
|
// имя файла из Content-Disposition: attachment; filename*=UTF-8''%D0%9E%D1%82%D1%87%D1%91%D1%82.pdf
|
||||||
|
const cd = resp.headers.get("Content-Disposition") ?? "";
|
||||||
|
const m = cd.match(/filename\*=UTF-8''([^;]+)/i);
|
||||||
|
const name = m ? decodeURIComponent(m[1]) : "document.pdf";
|
||||||
|
|
||||||
|
const blobUrl = URL.createObjectURL(await resp.blob());
|
||||||
|
const a = Object.assign(document.createElement("a"), { href: blobUrl, download: name });
|
||||||
|
a.click();
|
||||||
|
URL.revokeObjectURL(blobUrl);
|
||||||
|
```
|
||||||
|
|
||||||
|
Обработка 401 — стереть сохранённый ключ и показать экран ввода; 422 — показать
|
||||||
|
`error` из тела (документ содержит диаграммы/SmartArt/OLE).
|
||||||
|
|
||||||
|
## Python (requests)
|
||||||
|
|
||||||
|
Таймаут обязан быть больше серверных 2 минут на чтение:
|
||||||
|
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
|
resp = requests.post(
|
||||||
|
"https://pjandro.ru/pdf-converter/api/v1/convert",
|
||||||
|
headers={"X-API-Key": API_KEY} if API_KEY else {},
|
||||||
|
files={"file": open("doc.docx", "rb")},
|
||||||
|
params={"errorOnCharts": "false"},
|
||||||
|
timeout=(10, 180), # connect 10 c, read 180 c — больше серверных 2m
|
||||||
|
)
|
||||||
|
resp.raise_for_status()
|
||||||
|
with open("doc.pdf", "wb") as f:
|
||||||
|
f.write(resp.content)
|
||||||
|
```
|
||||||
|
|
||||||
|
Так же устроены прод-автотесты репозитория (`prod-autotests/`, pytest + requests).
|
||||||
@@ -0,0 +1,53 @@
|
|||||||
|
# REST API
|
||||||
|
|
||||||
|
Базовый путь — корень сервера; единственный эндпоинт:
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/v1/convert
|
||||||
|
```
|
||||||
|
|
||||||
|
Quickstart — конвертировать документ и сохранить PDF (ключ доступа, если сервер его
|
||||||
|
требует, — в заголовке `X-API-Key`):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \
|
||||||
|
https://pjandro.ru/pdf-converter/api/v1/convert -o doc.pdf
|
||||||
|
```
|
||||||
|
|
||||||
|
Локальный бэкенд (`java -jar`, порт 8080, ключ выключен):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
|
||||||
|
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
||||||
|
```
|
||||||
|
|
||||||
|
Успешный ответ — `200`, тело — байты PDF (`Content-Type: application/pdf`,
|
||||||
|
`Content-Disposition: attachment; filename*=UTF-8''…`).
|
||||||
|
|
||||||
|
## Документация в самом сервисе
|
||||||
|
|
||||||
|
|Что|Путь|Когда доступно|
|
||||||
|
|---|---|---|
|
||||||
|
|Swagger UI|`/swagger-ui.html`|пока включён springdoc|
|
||||||
|
|OpenAPI (JSON)|`/v3/api-docs`|пока включён springdoc|
|
||||||
|
|
||||||
|
На `java -jar` и dev-стенде (:9011) springdoc включён; на проде он также открыт
|
||||||
|
(проверяется автотестом `test_swagger_ui_open_without_key`). В локальном prod-like
|
||||||
|
compose-стеке springdoc выключен env-ами `SPRINGDOC_API_DOCS_ENABLED=false` и
|
||||||
|
`SPRINGDOC_SWAGGER_UI_ENABLED=false` (в этом случае `/v3/api-docs` отвечает 404).
|
||||||
|
|
||||||
|
## Разделы
|
||||||
|
|
||||||
|
- [Аутентификация](authentication.md) — ключ `X-API-Key`.
|
||||||
|
- [Эндпоинт конвертации](convert-endpoint.md) — параметры и ответ.
|
||||||
|
- [Коды ошибок](errors.md) — полная таблица и тексты.
|
||||||
|
- [Лимиты](limits.md) — размер, страницы, очередь, таймаут.
|
||||||
|
- [Примеры клиентов](examples.md) — curl, JavaScript, Python.
|
||||||
|
|
||||||
|
## Как устроена обработка
|
||||||
|
|
||||||
|
Конвертации сериализуются **одним воркером**: ядро мутирует глобальный реестр шрифтов,
|
||||||
|
поэтому все конвертации идут последовательно (очередь — 16 мест, переполнение → 503).
|
||||||
|
Головой очереди на старте стоит `warmup()` — прогрев ядра (~1,5–2,5 с), чтобы первый
|
||||||
|
запрос после деплоя не платил за инициализацию JAXB/XSLT/FOP. Проверка размера входа
|
||||||
|
выполняется синхронно, до постановки в очередь.
|
||||||
@@ -0,0 +1,47 @@
|
|||||||
|
# Лимиты
|
||||||
|
|
||||||
|
## Лимиты входа
|
||||||
|
|
||||||
|
|Свойство|Env|Дефолт|Смысл|
|
||||||
|
|---|---|---|---|
|
||||||
|
|`wordpdf.max-mb`|`WORDPDF_MAX_MB`|5|максимальный размер файла в МБ (MiB)|
|
||||||
|
|`wordpdf.max-pages`|`WORDPDF_MAX_PAGES`|100|максимальное число страниц|
|
||||||
|
|
||||||
|
Это **дефолт эндпоинта**: параметры запроса `maxMb`/`maxPages` переопределяют его
|
||||||
|
в обе стороны (значения `≤ 0` → 400; верхнего серверного потолка нет — защитные
|
||||||
|
пороги растут вместе с лимитами). Значение свойства сервера `≤ 0` — падение
|
||||||
|
приложения на старте (`IllegalStateException`).
|
||||||
|
|
||||||
|
## Производные защитные пороги
|
||||||
|
|
||||||
|
Остальные пороги выводятся из лимитов входа (`WordPdfValidator`), проверяются
|
||||||
|
до рендера, одним lightweight-сканом:
|
||||||
|
|
||||||
|
- распакованный размер архива;
|
||||||
|
- суммарный распакованный размер XML-частей;
|
||||||
|
- число записей zip и защита от дубликатов записей;
|
||||||
|
- площади растровых изображений (пиксели);
|
||||||
|
- размер `[Content_Types].xml` (жёсткие 8 МБ).
|
||||||
|
|
||||||
|
Превышение любого — `400` (в библиотеке — `ValidationException`).
|
||||||
|
|
||||||
|
## Потолок инфраструктуры — 100 МБ
|
||||||
|
|
||||||
|
`spring.servlet.multipart.max-file-size`/`max-request-size` = 100MB — потолок
|
||||||
|
контейнера, зеркалит `client_max_body_size 100m` nginx-шлюза. Тело больше — 413.
|
||||||
|
Логический лимит входа (`wordpdf.max-mb`, дефолт 5 МБ) отсекает раньше и даёт 400;
|
||||||
|
413 возможен только когда серверный лимит поднят администратором выше дефолта.
|
||||||
|
|
||||||
|
Части загрузки больше 2 МБ (`file-size-threshold=2MB`) сбрасываются на диск Tomcat —
|
||||||
|
heap держит только копию байтов одной сериализованной конвертации.
|
||||||
|
|
||||||
|
## Очередь и таймаут
|
||||||
|
|
||||||
|
|Параметр|Значение|Поведение|
|
||||||
|
|---|---|---|
|
||||||
|
|ёмкость очереди|16 мест|переполнение → **503** (повторить позже)|
|
||||||
|
|`wordpdf.convert-timeout`|`2m` (env `WORDPDF_CONVERT_TIMEOUT`)|конвертация дольше → **504** (задача отменяется)|
|
||||||
|
|
||||||
|
Конвертации исполняются строго последовательно одним воркером (ядро мутирует
|
||||||
|
глобальный реестр шрифтов); при таймауте `future.cancel(true)` не останавливает FOP
|
||||||
|
мгновенно — текущая конвертация дожигается, следующий запрос ждёт её в очереди.
|
||||||
@@ -0,0 +1,62 @@
|
|||||||
|
# Диаграммы, SmartArt, формулы
|
||||||
|
|
||||||
|
XSLT-экспорт docx4j диаграммы не умеет, поэтому `DrawingPreRenderer` (шаг 3.5
|
||||||
|
конвейера) **до** генерации XSL-FO заменяет `c:chart` / `dgm:relIds` / `m:oMath`
|
||||||
|
на PNG-картинки (`pic:pic`). Рендер — собственный Java2D-движок (`internal/chart`,
|
||||||
|
21 класс), без Word/LibreOffice/JEuclid; текст рисуется глифами fontbox (`GlyphFont`),
|
||||||
|
поэтому fontconfig серверу не нужен.
|
||||||
|
|
||||||
|
## Диаграммы
|
||||||
|
|
||||||
|
- Выход: PNG **300 dpi** (`ChartRenderer.DPI = 300`), размеры из `wp:extent` (EMU→pt).
|
||||||
|
- Поддерживаемые типы (`ChartSpec.Type`): `PIE`, `PIE3D`, `DOUGHNUT`, `BAR`,
|
||||||
|
`BAR_HORIZONTAL`, `LINE`, `AREA`, `SURFACE3D`, `AREA3D`, `BAR3D`, `LINE3D`,
|
||||||
|
`RADAR`, `SCATTER`, `BUBBLE`, `STOCK`, `OF_PIE`, `SURFACE` (+ `UNSUPPORTED`).
|
||||||
|
- **Combo** («Комбинированная», §21.2.2.145): несколько групп в одном plotArea
|
||||||
|
(bar+line/area), привязка по `c:axId`, вторичная ось значений справа; серии
|
||||||
|
масштабируются по своей оси.
|
||||||
|
- Стекинг `stacked`/`percentStacked` — ряды накопленной суммой.
|
||||||
|
- Геометрия/камера 3-D и пропорции откалиброваны по эталонным экспортам Word
|
||||||
|
(пиксельные тесты с допусками).
|
||||||
|
|
||||||
|
## Умные границы (враждебный XML)
|
||||||
|
|
||||||
|
|Бюджет|Значение|Поведение при превышении|
|
||||||
|
|---|---|---|
|
||||||
|
|`ChartRenderer.MAX_PIXELS`|16 777 216 (4096², 64 МБ ARGB)|`fitDpi` понижает эффективный dpi (24″-график: 300→≈171 dpi), геометрия не меняется|
|
||||||
|
|`ChartSpec.MAX_POINTS`|100 000|отказ **до** предвыделения списка|
|
||||||
|
|`ChartRenderer.MAX_TICKS`|1000|безумный шаг оси заменяется «красивым» 1/2/5·10ⁿ|
|
||||||
|
|`DrawingPreRenderer.MAX_EXTENT_EMU`|22 000 000 (≈24″)|объект **остаётся как есть** + warn (не удаляется)|
|
||||||
|
|бюджет chart/math-PNG на документ|128 MiB|объект удаляется + warn|
|
||||||
|
|
||||||
|
## Модель деградации
|
||||||
|
|
||||||
|
Битая/неподдерживаемая часть роняет не конвертацию, а объект:
|
||||||
|
|
||||||
|
|Ситуация|Исход|
|
||||||
|
|---|---|
|
||||||
|
|битая chart-часть / превышение бюджета PNG|объект удалён + warn|
|
||||||
|
|неподдерживаемая/битая OMML-формула|**текст** (конкатенация `m:t`) + warn — текст терять хуже|
|
||||||
|
|`wp:extent` вне диапазона/ноль|объект остаётся + warn (FOP молча потеряет)|
|
||||||
|
|`OutOfMemoryError`|не деградация — `ConversionException` (REST 500)|
|
||||||
|
|
||||||
|
## SmartArt
|
||||||
|
|
||||||
|
`SmartArtRenderer` рисует диаграмму по разметке [MS-ODRAWXML]/§21.4: узлы, макет,
|
||||||
|
связи; тот же DPI/`fitDpi`.
|
||||||
|
|
||||||
|
## Формулы OMML
|
||||||
|
|
||||||
|
Собственный растер: `MathModel` разбирает OMML (§22.1) в дерево боксов,
|
||||||
|
`MathRenderer` рисует его только бандл-шрифтами. Конструкции вне списка `SUPPORTED`
|
||||||
|
деградируют в текст ещё на шаге нормализации (правило 6). Inline-формула опускается
|
||||||
|
на нижний запас рана — FOP ставит инлайн-графику нижним краем на базу строки.
|
||||||
|
|
||||||
|
## Контрафт media-частей
|
||||||
|
|
||||||
|
PNG-части получают имена `/word/media/chart-N.png` (константа
|
||||||
|
`CHART_MEDIA_URI_PREFIX`); по этому префиксу `ChartImageHandler` отключает
|
||||||
|
пересжатие картинок в FOP — переименование молча вернёт «мыльный» ресемпл.
|
||||||
|
|
||||||
|
Глубина (пейнтеры, калибровки, спецификационные секции) —
|
||||||
|
[chart.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/chart.md).
|
||||||
@@ -0,0 +1,61 @@
|
|||||||
|
# Мост .doc → .docx
|
||||||
|
|
||||||
|
Бинарный формат Word 97–2003 читается **собственным мостом** без внешних
|
||||||
|
зависимостей (POI остаётся test-scope): байты `.doc` парсятся по спецификациям
|
||||||
|
**[MS-DOC]** (сам документ) и **[MS-CFB]** (OLE2-контейнер), собираются in-memory
|
||||||
|
`.docx` — и дальше идут тем же конвейером, что и обычные docx.
|
||||||
|
|
||||||
|
## Точка входа
|
||||||
|
|
||||||
|
```java
|
||||||
|
DocToDocx.convert(byte[] docBytes, long maxMb) // → байты .docx (вызывает WordPdfConverter)
|
||||||
|
DocToDocx.countPages(byte[] docBytes) // → страницы по сырым байтам (вызывает валидатор)
|
||||||
|
```
|
||||||
|
|
||||||
|
Страницы `.doc` считаются **по сырым байтам до конвертации** (PageCount из
|
||||||
|
SummaryInformation, разрывы 0x0C, межсекционные разрывы, `pageBreakBefore`) —
|
||||||
|
тот же скан используется валидатором лимита страниц. Любой брак (не-CFB, шифрованный
|
||||||
|
документ, Word 6–95) → `ConversionException` (в REST — 400).
|
||||||
|
|
||||||
|
## Классы пакета `internal/doc` (18 top-level)
|
||||||
|
|
||||||
|
|Класс|Спецификация|Что делает|
|
||||||
|
|---|---|---|
|
||||||
|
|`CfbReader`|[MS-CFB] §2.2–2.6|FAT/DIFAT/miniFAT, directory; бюджеты против враждебного FAT, любой брак → `ConversionException`|
|
||||||
|
|`FibHeader`|[MS-DOC] §2.5.1|заголовок FIB: потоки 1Table/0Table, пары fc/lcb нужных индексов, сверка раскладок по nFib|
|
||||||
|
|`PieceTable`|§2.9.135|текст: куски CP1252/UTF-16LE, клампинг к `cbMac`, проверка aCP|
|
||||||
|
|`Grpprl`|§2.6.2|свойства форматирования (sprm'ы): bold/italic/шрифт/цвет/подсветка/заливка/отступы/табуляции|
|
||||||
|
|`ChpxIndex` / `PapxIndex`|§2.4.6|FKP-страницы символьных/абзацных свойств|
|
||||||
|
|`Styles`|§2.9.271|STSH: стилевые цепочки абзацев и символов (stk=1/2)|
|
||||||
|
|`Tables`|§2.6.3|TAP TTP-абзаца → сетка, границы, выравнивание таблицы|
|
||||||
|
|`Lists`|§2.9.200/.201|PlfLst/PlfLfo → `word/numbering.xml`|
|
||||||
|
|`Sections`|§2.8.26|PlcfSed → геометрия секций, ориентация, нумерация страниц, `titlePg`|
|
||||||
|
|`FontTable`|§2.9.286|SttbfFfn: индекс ftc → имя семейства|
|
||||||
|
|`SummaryInfo`|[MS-OLEPS]|`\x01SummaryInformation`: в т.ч. PageCount|
|
||||||
|
|`Headers`|§2.4.1|Plcfhdd: 6 колонтитуков на секцию → `headerN.xml`/`footerN.xml`|
|
||||||
|
|`OfficeArt`|[MS-ODRAW]|картинки: BLIP-хранилище (JPEG/PNG/TIFF/DIB/EMF/WMF/PICT)|
|
||||||
|
|`PrcData`|§2.9.210|разворачивание «огромных» grpprl, вынесенных за FKP-страницу|
|
||||||
|
|`DocToDocx`|—|оркестратор + вложенный `DocxBody` (сборка document.xml)|
|
||||||
|
|`DocxWriter`|—|мульти-частный zip: content-types, rels, numbering, headers, media|
|
||||||
|
|
||||||
|
17 из 18 классов package-private; наружу — только `DocToDocx`.
|
||||||
|
|
||||||
|
## Модель деградации (не падение)
|
||||||
|
|
||||||
|
|Объект в .doc|Поведение|
|
||||||
|
|---|---|
|
||||||
|
|OLE-внедрения (U+0001 в тексте)|плейсхолдер заменяется его же BLIP-картинкой|
|
||||||
|
|картинки JPEG/PNG/TIFF/DIB|переносятся дословно / через ImageIO в PNG|
|
||||||
|
|EMF/WMF/PICT|пропуск с warn (векторные растеризаторы не в контуре)|
|
||||||
|
|битые/неподдерживаемые конструкции|снисходительный разбор, объект исчезает или упрощается — текст не теряется|
|
||||||
|
|
||||||
|
Поэтому **error-флаги (`errorOnCharts`/`errorOnSmartArt`/`errorOnOle`) на `.doc` не
|
||||||
|
срабатывают**: OLE-вложения бинарного формата — это U+0001 с BLIP-плейсхолдером,
|
||||||
|
мост деградирует их в картинки, «OLE-объектов» в смысле docx-пути в результате нет.
|
||||||
|
|
||||||
|
## Сознательный остаток
|
||||||
|
|
||||||
|
Семантика рестартов списков (`fNoRestart`/`ilvlRestartLim`), `fLegal`,
|
||||||
|
AUTONUM-поля (трактуются как обычные списки), часть тонкостей объединённых ячеек —
|
||||||
|
осознанные упрощения вне контура; полный перечень —
|
||||||
|
[doc-bridge.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/doc-bridge.md).
|
||||||
@@ -0,0 +1,63 @@
|
|||||||
|
# Шрифты
|
||||||
|
|
||||||
|
Конвертация не зависит от шрифтов системы: **30 TTF упакованы в jar**
|
||||||
|
`wordpdf-core/src/main/resources/fonts/`, выгружаются во временный каталог и
|
||||||
|
регистрируются в docx4j/FOP. Реестр шрифтов после каждой конвертации возвращается
|
||||||
|
к бандлу — шрифты, встроенные в чужие docx, не влияют на последующие документы.
|
||||||
|
`java.awt.Font` не используется (метрики и глифы — fontbox напрямую), поэтому
|
||||||
|
**fontconfig серверу не нужен**.
|
||||||
|
|
||||||
|
## Бандл
|
||||||
|
|
||||||
|
7 текстовых семейств по 4 начертания + 2 покрывающих (только regular):
|
||||||
|
|
||||||
|
|Семейство|Аналог MS-шрифта|Назначение|
|
||||||
|
|---|---|---|
|
||||||
|
|Carlito|Calibri|метрически совместимая замена|
|
||||||
|
|Caladea|Cambria|метрически совместимая замена|
|
||||||
|
|Arimo|Arial|метрически совместимая замена|
|
||||||
|
|Tinos|Times New Roman|метрически совместимая замена|
|
||||||
|
|Cousine|Courier New|метрически совместимая замена|
|
||||||
|
|DejaVu Sans / DejaVu Serif|—|fallback с гарантированной кириллицей|
|
||||||
|
|Noto Naskh Arabic|—|арабские дополнения U+07B1–U+08FF|
|
||||||
|
|Noto Sans Armenian|—|армянские знаки Unicode 16|
|
||||||
|
|
||||||
|
## Алиасы (`BundledFontAliases`)
|
||||||
|
|
||||||
|
Имена шрифтов из документа подменяются аналогами при конвертации:
|
||||||
|
|
||||||
|
|Имя в docx|Физический шрифт|
|
||||||
|
|---|---|
|
||||||
|
|Calibri|Carlito|
|
||||||
|
|Cambria|Caladea|
|
||||||
|
|Arial|Arimo|
|
||||||
|
|Times New Roman|Tinos|
|
||||||
|
|Courier New|Cousine|
|
||||||
|
|
||||||
|
## Fallback-цепочка
|
||||||
|
|
||||||
|
1. **Ран** идёт своим шрифтом (по `w:rFonts` + алиасам).
|
||||||
|
2. Знака нет в шрифте рана (тире «—», кавычки, U+2000–U+2EFF) — ран падает в
|
||||||
|
**DejaVu Sans** (FOP-фолбэк-семейства задекларированы всецело, шаг 4 конвейера).
|
||||||
|
3. Serif-раны ищут покрытие сначала в serif-семействах (DejaVu Serif, Tinos, Caladea).
|
||||||
|
4. Знака нет и там — `GlyphCoverageNormalizer` (правило 7) режет ран и каждой части
|
||||||
|
назначает покрывающее семейство: serif → DejaVu Serif, sans → DejaVu Sans,
|
||||||
|
экзотика → Noto.
|
||||||
|
5. Знака нет ни в одном шрифте бандла — остаётся `.notdef` (пустой бокс).
|
||||||
|
|
||||||
|
Все шрифты встраиваются в PDF как **подмножества** (кириллица и латиница
|
||||||
|
воспроизводятся на любом просмотрщике).
|
||||||
|
|
||||||
|
## Лицензии
|
||||||
|
|
||||||
|
|Шрифты|Лицензия|
|
||||||
|
|---|---|
|
||||||
|
|Arimo, Cousine, Tinos, Carlito, Caladea|SIL OFL 1.1 (`fonts/FONT-LICENSE.txt`)|
|
||||||
|
|DejaVu Sans / DejaVu Serif|SIL OFL 1.1 / Bitstream Vera (`fonts/DejaVu-LICENSE.txt`)|
|
||||||
|
|Noto Naskh Arabic, Noto Sans Armenian|SIL OFL 1.1 (`fonts/Noto-LICENSE.txt`)|
|
||||||
|
|
||||||
|
GPL-шрифты в бандл не добавляем намеренно (из-за этого два символа эталона —
|
||||||
|
U+2188/U+218A — остаются `.notdef`; см. [Ограничения](limitations.md)).
|
||||||
|
|
||||||
|
Новый шрифт = файл в `resources/fonts/` + запись в `BundledFonts.ENTRIES`
|
||||||
|
(синхронность проверяет `BundledFontsTest`).
|
||||||
@@ -0,0 +1,40 @@
|
|||||||
|
# Ограничения рендера
|
||||||
|
|
||||||
|
Конвертер **не является pixel-perfect рендером Word**: часть расхождений —
|
||||||
|
неустранимые невозможности связки docx4j + Apache FOP, а не упущения проекта.
|
||||||
|
|
||||||
|
## Что конвертируется приближённо
|
||||||
|
|
||||||
|
- Раскладка, поля и некоторые эффекты могут отличаться от Word (ограничения
|
||||||
|
FOP/docx4j по построению).
|
||||||
|
- Символы U+2000–U+2EFF (тире, кавычки): из шрифта рана, если в нём есть глиф,
|
||||||
|
иначе — из fallback-семейства DejaVu.
|
||||||
|
- Знаков, которых нет ни в одном шрифте бандла, это не касается: вместо них
|
||||||
|
остаётся `.notdef` (пустой бокс). В эталонном наборе таких два: U+2188 (ↈ) и
|
||||||
|
U+218A (↊) — глифы есть только в GNU FreeSerif под GPL, а бандл держится целиком
|
||||||
|
на SIL OFL.
|
||||||
|
- Поддержка таблиц/изображений — базовая (уровень docx4j/FOP).
|
||||||
|
- На `.doc` error-флаги диаграмм/SmartArt/OLE не срабатывают: BLIP-плейсхолдеры
|
||||||
|
бинарного формата — уже растры (вставляются картинками), EMF/WMF/PICT пропускаются
|
||||||
|
с warn — [Мост .doc](doc-bridge.md).
|
||||||
|
|
||||||
|
## Стоп-лист «не чинить»
|
||||||
|
|
||||||
|
До любой попытки «починить» расхождение с Word — сверьтесь со списком: это
|
||||||
|
невозможности движка, попытка фикса хуже самого расхождения.
|
||||||
|
|
||||||
|
|Конструкция|Что происходит|Почему не чинится|
|
||||||
|
|---|---|---|
|
||||||
|
|`w:jc="distribute"`|рендерится как left|межсимвольного распределения в FOP нет; `text-align-last` в форке отсутствует|
|
||||||
|
|`w:suff="tab"`|игнорируется (label через hanging-tab)|нужна per-item ширина; совпадает с поведением docx4j|
|
||||||
|
|`w:lvlJc`|игнорируется|—|
|
||||||
|
|кернинг|не применяется|—|
|
||||||
|
|`framePr` (обтекание)|не поддерживается|—|
|
||||||
|
|кэш полей `REF`/`SEQ`/`TOC`|печатается кэш из docx|живой пересчёт вне контура (`PAGE`/`NUMPAGES`/`PAGEREF`/`DATE` — пересчитываются)|
|
||||||
|
|руби (надстрочница)|надстрочная часть вырезается, база печатается|ruby-разметки в FOP нет; потеря текста хуже потери аннотации|
|
||||||
|
|`ptab`|не поддерживается|—|
|
||||||
|
|U+2188/U+218A|`.notdef`|GPL-шрифты не добавляем намеренно|
|
||||||
|
|`lineRule="auto"`|—|не «чинить»: метрический шаг пинен тестом|
|
||||||
|
|
||||||
|
Полный перечень с доказательствами по ECMA-376 —
|
||||||
|
[render-limitations.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/render-limitations.md).
|
||||||
@@ -0,0 +1,68 @@
|
|||||||
|
# Архитектура
|
||||||
|
|
||||||
|
## Конвейер конвертации (шаги 0–7)
|
||||||
|
|
||||||
|
Единственный вход ядра — `WordPdfConverter.convert(byte[], String, ConvertOptions)`;
|
||||||
|
порядок шагов фиксирован и каждый обоснован:
|
||||||
|
|
||||||
|
|#|Шаг|Зачем|
|
||||||
|
|---|---|---|
|
||||||
|
|0|`DependencyGuard.check()`|API-проба commons-compress ≥ 1.25.0 — понятная ошибка вместо `NoSuchMethodError` внутри docx4j|
|
||||||
|
|1|`new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()`|реестр шрифтов = только бандл (+ встроенные в docx); системные сканы отключены гейт-свойствами; порядок строго такой, до `load()`|
|
||||||
|
|2|нормализаторы → `WordprocessingMLPackage.load`|12 правил переписывания байтов одним zip-проходом + OLE-вычистка (см. ниже)|
|
||||||
|
|3|`setFontMapper`|привязка имён шрифтов документа к физическим TTF|
|
||||||
|
|3.5|`DrawingPreRenderer.run`|диаграммы/SmartArt/OMML-формулы → PNG 300 dpi; **обязателен до `FOSettings`**, иначе FOP молча теряет диаграммы|
|
||||||
|
|4|`FOSettings` + `ChartImageHandler` + `FopFallbackFonts.declare`|FOP встраивает только задекларированные семейства; декларуются все бандл-семейства|
|
||||||
|
|4.25/4.5|`LayoutPostRenderer.register`, `setCustomXsltTemplates`|padding-компенсация таблиц; вендорный XSLT с AUDIT-FIX-патчами|
|
||||||
|
|5–6|общая `FopFactory` (DCL) → `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`|XSL-FO → PDF|
|
||||||
|
|7|`finally`|сброс temp-шрифтов, сброс общих кешей картинок (иначе ~1,5 ГБ за 30 конвертаций), возврат реестра к бандлу|
|
||||||
|
|
||||||
|
Нормализаторы правил 1–11 (один zip-проход, порядок значим): strict→transitional,
|
||||||
|
`on/off`→`true/false`, Symbol/Wingdings→Unicode, поля `PAGE`/`NUMPAGES` →
|
||||||
|
`w:fldSimple` (пересчёт вместо кэша), невидимые символы, OMML-фолбэк, резка ранов
|
||||||
|
по покрытию глифов, отступ таблиц, `suff="space"`, скрытый текст, руби. Правило 12 —
|
||||||
|
`OleObjectNormalizer` (отдельным байтовым проходом).
|
||||||
|
|
||||||
|
Полное «что делает каждый шаг и почему именно так» —
|
||||||
|
[pipeline.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/pipeline.md).
|
||||||
|
|
||||||
|
## Слои ядра (`wordpdf-core`)
|
||||||
|
|
||||||
|
|Слой|Содержимое|
|
||||||
|
|---|---|
|
||||||
|
|публичный API (`ru.pjandro.wordpdf`)|`WordPdfConverter`, `WordPdfValidator`, `ConvertOptions`, иерархия ошибок — см. [API библиотеки](../library/api.md)|
|
||||||
|
|`internal/`|нормализаторы (контракт `byte[] normalize(byte[])`), `FopFallbackFonts`, `LayoutPostRenderer`, `DependencyGuard`|
|
||||||
|
|`internal/doc/`|мост бинарного `.doc` → in-memory `.docx` — [Мост .doc](doc-bridge.md)|
|
||||||
|
|`internal/chart/`|Java2D-рендер диаграмм/SmartArt/формул → PNG — [Диаграммы](charts.md)|
|
||||||
|
|`fonts/`|бандл из 30 TTF, маппинг алиасов, `GlyphFont` (метрики/глифы через fontbox, без AWT) — [Шрифты](fonts.md)|
|
||||||
|
|
||||||
|
Всё, кроме публичного API, — package-private; контракт наружу не расширяется.
|
||||||
|
|
||||||
|
## Параллельность
|
||||||
|
|
||||||
|
`PhysicalFonts` docx4j — глобальный мутируемый реестр → **все конвертации
|
||||||
|
сериализованы монитором класса `WordPdfConverter.class`**. Приложение (`wordpdf-app`)
|
||||||
|
дополнительно держит однопоточный `ThreadPoolExecutor` с очередью 16 мест (переполнение
|
||||||
|
→ 503, timeout 2m → 504), головой очереди стоит `warmup()`.
|
||||||
|
|
||||||
|
## REST-конвейер приложения (`wordpdf-app`)
|
||||||
|
|
||||||
|
`POST /api/v1/convert` → `ApiKeyFilter` (401) → `ConvertController` (проверка
|
||||||
|
расширения/размера, параметры) → `ConversionService` (очередь, Future с таймаутом,
|
||||||
|
перевод исключений ядра в HTTP) → ядро. Обработчик исключений пишет JSON
|
||||||
|
`{"error": …}` — карта кодов в [REST API](../api/errors.md). В модуле 11 классов,
|
||||||
|
все package-private кроме `WordPdfApplication`.
|
||||||
|
|
||||||
|
## Веб-интерфейс (`wordpdf-web`)
|
||||||
|
|
||||||
|
React SPA; вся сеть — ровно две функции в `api.ts` (`convertDocx`, `probeApiKey`),
|
||||||
|
состояние — `useState` в `App.tsx`, store-библиотек нет. Запросы идут на тот же
|
||||||
|
путь `/api/...` относительно базы раздачи — CORS не нужен.
|
||||||
|
|
||||||
|
## Внешние поверхности
|
||||||
|
|
||||||
|
- `gateway/nginx.conf` — единственная наружная точка стендов (:9010/:9011):
|
||||||
|
`/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → app:8080, остальное → web;
|
||||||
|
[Эксплуатация: стенды](../operations/stack.md).
|
||||||
|
- Прод (`https://pjandro.ru/pdf-converter/`) рендерится job'ом `deploy` из
|
||||||
|
Gitea Variables — [Деплой](../operations/deployment.md).
|
||||||
@@ -0,0 +1,64 @@
|
|||||||
|
# Как контрибьютить
|
||||||
|
|
||||||
|
## Ветка и PR
|
||||||
|
|
||||||
|
Репозиторий: `git.pjandro.ru:pjandro/java-word-pdf`. Защищённые ветки — `main`,
|
||||||
|
`master`, `dev`: прямо в них не коммитим.
|
||||||
|
|
||||||
|
1. Ветка от свежей `main` (`git switch -c <name>`).
|
||||||
|
2. Коммиты логическими блоками.
|
||||||
|
3. Перед push — полный гейт: `./mise.sh run verify`.
|
||||||
|
4. `git push -u origin <name>` → pull request в дефолтную ветку.
|
||||||
|
5. CI на PR: `java` (единственный `mvn clean verify` в контейнере без fontconfig +
|
||||||
|
сводка покрытия комментарием) и `web` (`npm ci`, build, lint) — оба required.
|
||||||
|
`macos-sim` — не required.
|
||||||
|
|
||||||
|
## Конвенции кода
|
||||||
|
|
||||||
|
- Классы `final`, приватный конструктор, только `static` (stateless, DI в ядре нет);
|
||||||
|
в `internal/**` — package-private, `public` только вызываемым извне пакета.
|
||||||
|
- Ошибки публичного API — только `ConversionException` (и подтипы); в chart —
|
||||||
|
деградация вместо падения.
|
||||||
|
- Javadoc на русском: «зачем» + ссылка на секцию спецификации (§17.3.2.24,
|
||||||
|
[MS-DOC] §2.6.1…) + что сломается без шага + регрессия в формате
|
||||||
|
`Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx` (по этой строке
|
||||||
|
грепом восстанавливаются пары тестов).
|
||||||
|
- Модели — `record`; константы UPPER_SNAKE с javadoc-обоснованием числа.
|
||||||
|
- PMD-подавления (`@SuppressWarnings("PMD…")`, `// NOPMD`) запрещены.
|
||||||
|
- Логирование: `java.util.logging` — корневой пакет и `internal/`; SLF4J —
|
||||||
|
`internal/chart` и `wordpdf-app`; остальное молчит.
|
||||||
|
|
||||||
|
## Регрессивная конвенция (фикс бага)
|
||||||
|
|
||||||
|
Каждый фикс расхождения с Word оформляется полным набором:
|
||||||
|
|
||||||
|
```
|
||||||
|
нормализатор/рендерер → юнит на правило → тест во всём конвейере
|
||||||
|
→ javadoc-ссылка «Регрессия — Тест#имя, фикстура …»
|
||||||
|
```
|
||||||
|
|
||||||
|
Фикстуры для новых тестов не генерируются на лету и не перезаписываются:
|
||||||
|
`charts-smartart.docx` и `ole-embedded.docx` сделаны руками и **не перезаписываются
|
||||||
|
никогда**; все 12 `.doc` — эталоны заказчика.
|
||||||
|
|
||||||
|
## Критические инварианты (нарушение = битый вывод)
|
||||||
|
|
||||||
|
Прежде чем править ядро — прогнать глазами список (полный — `AGENTS.md`,
|
||||||
|
[repo-map](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/repo-map.md)):
|
||||||
|
|
||||||
|
- static-блок `WordPdfConverter` (sysprops `gsubFeatures=false`, отключение
|
||||||
|
сканов PhysicalFonts) — не удалять;
|
||||||
|
- `DrawingPreRenderer` обязан идти **до** `FOSettings`, иначе FOP молча теряет диаграммы;
|
||||||
|
- порядок нормализаторов правил 1–11 фиксирован;
|
||||||
|
- вендорный `docx2fo.xslt` — единственный XSL-стилист, дрейф-гейт
|
||||||
|
`vendoredXsltTracksJarCopy`;
|
||||||
|
- `slf4j-simple` обязателен в ядре;
|
||||||
|
- префикс `/word/media/chart-*` — контракт с `ChartImageHandler`;
|
||||||
|
- финальный `finally`-блок: temp-шрифты, кеши картинок, возврат реестра к бандлу.
|
||||||
|
|
||||||
|
## Документация сайта
|
||||||
|
|
||||||
|
Разделы сайта живут в `docs/` (кроме `docs/agent/`, `docs/standards/` — они не входят
|
||||||
|
в сайт). Правка/новая страница: обязательна запись в `nav` `mkdocs.yml` (иначе
|
||||||
|
strict-сборка падает). Проверка: `./mise.sh run docs-build`. Публикация —
|
||||||
|
[`docs-deploy`](../operations/docs-site.md).
|
||||||
@@ -0,0 +1,83 @@
|
|||||||
|
# Окружение разработчика
|
||||||
|
|
||||||
|
Требуется **Java 17**, **Maven 3.9.16**, **Node 24** (engines Vite: `^20.19.0 ||
|
||||||
|
>=22.12.0`), **Python 3.15** (прод-автотесты, сайт документации). Всё это ставит
|
||||||
|
project-local mise: сам бинарь — в `./.mise/bin` (gitignored), кеш инструментов —
|
||||||
|
в user-директории mise, **в систему ничего не устанавливается**. Версии пиныны
|
||||||
|
в `mise.toml`.
|
||||||
|
|
||||||
|
## Бутстрап (первая настройка)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sh bootstrap.sh # Linux / macOS: качает mise, ставит инструменты, npm ci SPA
|
||||||
|
```
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
|
||||||
|
```
|
||||||
|
|
||||||
|
Дальше команды — через обёртку `./mise.sh` (Windows: `.\mise.ps1`):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./mise.sh run verify # полный гейт перед push
|
||||||
|
./mise.sh exec -- mvn -v # любая команда с инструментами в PATH
|
||||||
|
./mise.sh tasks # список задач
|
||||||
|
```
|
||||||
|
|
||||||
|
Альтернатива — активировать mise в шелле и работать напрямую (`mvn`, `npm`, `python`):
|
||||||
|
`eval "$(./.mise/bin/mise activate bash)"`.
|
||||||
|
|
||||||
|
## Задачи mise
|
||||||
|
|
||||||
|
|Задача|Содержание|
|
||||||
|
|---|---|
|
||||||
|
|`verify`|`mvn clean verify` — тесты + PMD + JaCoCo (гейт перед push)|
|
||||||
|
|`verify-nofontconfig`|тот же verify в контейнере без fontconfig (как CI; требует podman/docker)|
|
||||||
|
|`mem-bench`|замер памяти конвейера (TSV пиков + JFR)|
|
||||||
|
|`app-package`|исполняемый jar бэкенда|
|
||||||
|
|`app-run`|бэкенд на :8080, ключ выключен (после `app-package`)|
|
||||||
|
|`web-install`|`npm ci` в `wordpdf-web`|
|
||||||
|
|`web-build`|гейт SPA: `tsc -b && vite build`|
|
||||||
|
|`web-lint`|oxlint|
|
||||||
|
|`web-dev`|SPA на :5173, vite-proxy на :8080|
|
||||||
|
|`prod-tests`|прод-автотесты; обязателен `WORDPDF_BASE_URL`, факультативно `WORDPDF_API_KEY`|
|
||||||
|
|`docs-install`|venv `docs/.venv` + `mkdocs-material`|
|
||||||
|
|`docs-serve`|локальный предпросмотр сайта на :8000 (live-reload)|
|
||||||
|
|`docs-build`|strict-сборка сайта в `site/` (битые ссылки/навигация = ошибка)|
|
||||||
|
|`docs-javadoc`|javadoc публичного API core в `wordpdf-core/target/site/apidocs`|
|
||||||
|
|`docs-deploy`|публикация сайта на rpi (:9012): javadoc + strict-build + rsync|
|
||||||
|
|
||||||
|
## Прямые команды (без задач)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mvn clean verify # все модули + тесты
|
||||||
|
mvn test -Djacoco.skip=true # тесты без агента покрытия
|
||||||
|
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
|
||||||
|
mvn -pl wordpdf-app -am test # -am обязателен: app берёт фикстуры из test-jar core
|
||||||
|
mvn -pl wordpdf-app -am package # исполняемый jar → wordpdf-app/target/
|
||||||
|
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен
|
||||||
|
|
||||||
|
npm ci && npm run build # в wordpdf-web/ (или задачи web-*)
|
||||||
|
npm run dev # SPA :5173, проксирует /api на :8080
|
||||||
|
```
|
||||||
|
|
||||||
|
## Стенды на контейнерах (podman)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# dev (:9011), без ключа, springdoc включён
|
||||||
|
podman-compose -f compose.dev.yml up -d --build --force-recreate
|
||||||
|
|
||||||
|
# prod-like (:9010), fail-closed: нужен .env с WORDPDF_API_KEY (шаблон .env.example)
|
||||||
|
cp .env.example .env # ключ: openssl rand -hex 32
|
||||||
|
podman-compose up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
`--force-recreate` для dev обязателен: без него podman-compose пересоберёт образ,
|
||||||
|
но контейнеры оставит на старом jar. Наружу публикуется только nginx-gateway
|
||||||
|
(9010/9011), 8080 наружу не выставляется. Подробности —
|
||||||
|
[Стенды](../operations/stack.md).
|
||||||
|
|
||||||
|
!!! info "«Запусти тестовый сервер»"
|
||||||
|
Так в проекте называют dev-стенд (`compose.dev.yml`, `http://<LAN-IP>:9011`),
|
||||||
|
а не `java -jar`. Готовность — контейнеры healthy (`podman-compose -f
|
||||||
|
compose.dev.yml ps`) + корень SPA отвечает 200.
|
||||||
@@ -0,0 +1,71 @@
|
|||||||
|
# Тесты
|
||||||
|
|
||||||
|
## Гейты
|
||||||
|
|
||||||
|
Полный гейт перед push — `./mise.sh run verify` (= `mvn clean verify`); на `verify`
|
||||||
|
висят и валят сборку:
|
||||||
|
|
||||||
|
|Гейт|Порог|
|
||||||
|
|---|---|
|
||||||
|
|surefire (тесты)|все зелёные, `-Djava.awt.headless=true`|
|
||||||
|
|PMD (`pmd-ruleset.xml`)|любой приоритет нарушения валит; `includeTests=true`; **подавления запрещены** — чинить кодом|
|
||||||
|
|JaCoCo LINE|≥ 0.90 (оба модуля)|
|
||||||
|
|JaCoCo BRANCH|≥ 0.85 (только `wordpdf-core`)|
|
||||||
|
|
||||||
|
Провал — HTML/XML-отчёт уже в `target/site/jacoco/`. CI-эквивалент без fontconfig —
|
||||||
|
`./mise.sh run verify-nofontconfig`. `mvn test` PMD/JaCoCo-гейты не запускает.
|
||||||
|
|
||||||
|
## Стек и конвенции
|
||||||
|
|
||||||
|
- **JUnit 6** (`org.junit.jupiter`), **только `Assertions`** — Mockito/AssertJ
|
||||||
|
запрещены, их нет в pom (в app-тестах допустим inline-Hamcrest
|
||||||
|
`org.hamcrest.Matchers.containsString` в `andExpect`).
|
||||||
|
- Только `@Test` (исключения: два `@BeforeAll` прогрева шрифтов, `@AfterEach
|
||||||
|
drainWorker` в `ConversionTimeoutTest`); ни `@Nested`, ни `@ParameterizedTest`,
|
||||||
|
ни `@Disabled`, ни `assertAll`.
|
||||||
|
- Тестовые классы package-private, зеркалят main-пакеты.
|
||||||
|
- Именование: регрессионные — `объект_условие` (`pageNumbers_recomputedNotCached`),
|
||||||
|
юниты — camelCase (`pageFieldBecomesFldSimple`).
|
||||||
|
- Сообщения ассертов — по-русски, с наблюдаемым значением; литерал слева.
|
||||||
|
- Тестовых утилит нет — хелперы намеренно дублируются в классах.
|
||||||
|
|
||||||
|
## Фикстуры
|
||||||
|
|
||||||
|
Только закоммиченные `wordpdf-core/src/test/resources/samples/`: **13 `.docx` +
|
||||||
|
12 `.doc`** (`.doc` — эталоны заказчика). В тестах фикстуры **не генерировать**;
|
||||||
|
XSD-невалидную `.docx`-фикстуру правят, а не код
|
||||||
|
(`python3 docs/standards/docx/validate-fixtures.py …`). Синтетика в памяти разрешена:
|
||||||
|
docx — `ZipOutputStream` из литеральных XML, `.doc` — крафт `POIFSFileSystem`.
|
||||||
|
|
||||||
|
Ловушка загрузки: **core** грузит classloader-ресурсом без ведущего слэша
|
||||||
|
(`getResourceAsStream("samples/…")`), **app** — class-relative со слэшем
|
||||||
|
(`/samples/…`, ресурсы из test-jar core; отсюда обязательный `-am`).
|
||||||
|
|
||||||
|
## Как проверяется PDF
|
||||||
|
|
||||||
|
**Текстом, не растеризацией**: PDFBox 3 `PDFTextStripper` (нормализация пробелов);
|
||||||
|
негативные маркеры — `#` (.notdef) и `Helvetica` (фолбэк-шрифт FOP); имя шрифта
|
||||||
|
символа — приём `fontNameOf`; встроенные подмножества — обход ресурсов страниц
|
||||||
|
(`EAAAAA+Carlito-Bold`). Пиксели (BufferedImage, отношения к эталонам Word 300 dpi
|
||||||
|
с допусками) — только юниты chart-пейнтеров.
|
||||||
|
|
||||||
|
## App-тесты
|
||||||
|
|
||||||
|
4 набора свойств = 4 Spring-контекста: `ConvertControllerTest` (пин пустого
|
||||||
|
`wordpdf.api-key=`), `ApiKeyFilterTest`, `ConvertLimitsTest`, `ConversionTimeoutTest`;
|
||||||
|
`ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring. Проверяют HTTP-код,
|
||||||
|
заголовки, текст ошибки. Ловушка: mise инжектирует корневой `.env` в окружение задач
|
||||||
|
— ambient `WORDPDF_API_KEY` дал бы 401 во всех MockMvc-тестах, поэтому ключ пинится
|
||||||
|
свойствами контекста.
|
||||||
|
|
||||||
|
## Прод-автотесты
|
||||||
|
|
||||||
|
`prod-autotests/` (pytest + requests): 31 проверка против **живого** стенда —
|
||||||
|
4 открытые + 27 `needs_key` (SKIP без ключа). Конфигурация только env:
|
||||||
|
`WORDPDF_BASE_URL` (обязателен), `WORDPDF_API_KEY`, `WORDPDF_MAX_MB`/`MAX_PAGES`,
|
||||||
|
`WORDPDF_SAMPLES_DIR`. Таймауты `(10, 180)` — больше серверных 2m. Запуск:
|
||||||
|
`WORDPDF_BASE_URL=… ./mise.sh run prod-tests` (в CI гоняются job'ом `autotests`
|
||||||
|
после deploy).
|
||||||
|
|
||||||
|
Глубина (счётчики, пары «нормализатор ↔ тест», пиксельные допуски) —
|
||||||
|
[testing.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/testing.md).
|
||||||
@@ -0,0 +1,64 @@
|
|||||||
|
# Word → PDF конвертер
|
||||||
|
|
||||||
|
Конвертация **.docx/.doc → PDF** на чистой Java: `docx4j` 17.3.2 + форк `Apache FOP`
|
||||||
|
(`org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6), **без LibreOffice и без Aspose**.
|
||||||
|
Бинарный `.doc` (Word 97–2003) читается собственным мостом [MS-DOC]/[MS-CFB]
|
||||||
|
и переносится в .docx в памяти — дальше идёт тем же конвейером. Шрифты упакованы
|
||||||
|
в jar: конвертация не зависит от шрифтов, установленных в системе, и работает
|
||||||
|
«из коробки» на голом сервере.
|
||||||
|
|
||||||
|
## Три поверхности
|
||||||
|
|
||||||
|
|Поверхность|Что это|Куда смотреть|
|
||||||
|
|---|---|---|
|
||||||
|
|Веб-интерфейс|React SPA: перетащил файл → предпросмотр PDF → скачивание. Публикация: `https://pjandro.ru/pdf-converter/`|[Пользователю](user.md)|
|
||||||
|
|REST API|`POST /api/v1/convert` (Spring Boot 4.1.1), ключ доступа, Swagger UI|[REST API](api/index.md)|
|
||||||
|
|Java-библиотека|`wordpdf-core`: `WordPdfConverter.convert(...)` — байты docx на входе, байты PDF на выходе|[Библиотека](library/getting-started.md)|
|
||||||
|
|
||||||
|
## Как это работает (схема)
|
||||||
|
|
||||||
|
```
|
||||||
|
.docx/.doc ──> валидация входа ──> (.doc: мост → .docx в памяти)
|
||||||
|
──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
|
||||||
|
──> диаграммы → PNG ──> XSL-FO (вендорный XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Вход проверяется до рендера (`WordPdfValidator`): размер → сигнатура байтов
|
||||||
|
(zip `PK\x03\x04` или CFB `D0 CF 11 E0`) → контейнер и страницы lightweight-сканом,
|
||||||
|
без зависимости от docx4j.
|
||||||
|
2. XML-части переписывает `DocxRewritePipeline` одним zip-проходом (12 правил
|
||||||
|
нормализации), затем OLE-объекты вычищает `OleObjectNormalizer`.
|
||||||
|
3. Документ загружается в `WordprocessingMLPackage`, привязывается `BundledFontMapper`.
|
||||||
|
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi собственным
|
||||||
|
Java2D-движком (`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
|
||||||
|
5. Экспорт в XSL-FO идёт вендорным стилем `docx2fo.xslt`; `Apache FOP` рендерит
|
||||||
|
PDF, встраивая подмножества шрифтов.
|
||||||
|
|
||||||
|
Полностью, с обоснованиями — [Архитектура](architecture/overview.md).
|
||||||
|
|
||||||
|
## Возможности
|
||||||
|
|
||||||
|
- RU/EN: кириллица и латиница встраиваются в PDF как embedded-подмножества.
|
||||||
|
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
|
||||||
|
([Шрифты](architecture/fonts.md)).
|
||||||
|
- Диаграммы (17 типов, включая комбинированные) и SmartArt — PNG без Word/LibreOffice
|
||||||
|
([Диаграммы](architecture/charts.md)).
|
||||||
|
- `.doc`: текст, стили, таблицы, списки, колонтитуки, картинки — собственный мост
|
||||||
|
([Мост .doc](architecture/doc-bridge.md)).
|
||||||
|
|
||||||
|
## Ключевые версии
|
||||||
|
|
||||||
|
|Компонент|Версия|
|
||||||
|
|---|---|
|
||||||
|
|Java|17 (temurin)|
|
||||||
|
|docx4j|17.3.2|
|
||||||
|
|Apache FOP (форк `docx4j-fo-renderer*`)|2.11-docx4j.6|
|
||||||
|
|commons-compress|1.28.0 (минимум 1.25.0)|
|
||||||
|
|Spring Boot|4.1.1|
|
||||||
|
|springdoc|3.1.1|
|
||||||
|
|SPA|React 19.2 + TypeScript ~6.0 + Vite 8.3|
|
||||||
|
|
||||||
|
## Ссылки
|
||||||
|
|
||||||
|
- [Javadoc публичного API `wordpdf-core`](/apidocs/index.html)
|
||||||
|
- [Внутренние справочники репозитория](internal-guides.md) — для глубокой правки кода.
|
||||||
@@ -0,0 +1,39 @@
|
|||||||
|
# Внутренние справочники репозитория
|
||||||
|
|
||||||
|
Сайт покрывает «как пользоваться и как устроено». Для **глубокой правки кода**
|
||||||
|
в репозитории живут авторитетные справочники (`docs/agent/`, читаются наравне
|
||||||
|
с `AGENTS.md`) и закоммиченные спецификации форматов (`docs/standards/`).
|
||||||
|
В этот сайт они не включены (огромные тексты спецификаций) — ссылки ведут на Gitea.
|
||||||
|
|
||||||
|
## Справочники `docs/agent/`
|
||||||
|
|
||||||
|
|Документ|Читать при|
|
||||||
|
|---|---|
|
||||||
|
|[pipeline.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/pipeline.md)|правке конвейера `WordPdfConverter`, нормализаторов, валидатора; шаги 0–7 с обоснованиями, правила 1–12|
|
||||||
|
|[doc-bridge.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/doc-bridge.md)|правке моста `internal/doc`; классы ↔ секции [MS-DOC]/[MS-CFB], остаток моста|
|
||||||
|
|[chart.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/chart.md)|правке `internal/chart`; пейнтеры, калибровки по Word, защитные лимиты, §ECMA-376|
|
||||||
|
|[render-limitations.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/render-limitations.md)|любой попытке «починить» расхождение с Word — сначала стоп-лист|
|
||||||
|
|[testing.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/testing.md)|добавлении/правке тестов; счётчики, пиксельные допуски, фикстуры, конвенции|
|
||||||
|
|[ci-cd.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/ci-cd.md)|правке workflow'ов, Containerfile'ов, деплоя|
|
||||||
|
|[repo-map.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/repo-map.md)|поиске «где живёт X»: полная карта каталогов/файлов, REST-карта, конвенции|
|
||||||
|
|
||||||
|
## Спецификации `docs/standards/`
|
||||||
|
|
||||||
|
Нормативные тексты форматов, закоммиченные в репозиторий
|
||||||
|
(навигатор — `docs/standards/README.md`, ссылка в коде — с номером секции):
|
||||||
|
|
||||||
|
|Каталог|Содержимое|
|
||||||
|
|---|---|
|
||||||
|
|`ooxml/`|ECMA-376 Part 1 (PDF + md), [MS-OI29500], [MS-ODRAWXML], полные наборы XSD strict/transitional|
|
||||||
|
|`binary/`|[MS-CFB], [MS-OSHARED], [MS-ODRAW], [MS-OLEPS], [MS-OFFCRYPTO], [MS-OVBA], [MS-WMF], [MS-EMF]|
|
||||||
|
|`doc/`|[MS-DOC] — бинарный формат Word 97–2003|
|
||||||
|
|`docx/`|XSD-валидация фикстур (`validate-fixtures.py`)|
|
||||||
|
|
||||||
|
## Корневые документы
|
||||||
|
|
||||||
|
- [`AGENTS.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/AGENTS.md) —
|
||||||
|
правила репозитория: конвейер, инварианты, команды, конвенции, гейты.
|
||||||
|
- [`README.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/README.md) —
|
||||||
|
короткая точка входа в проект.
|
||||||
|
- [`GITEA-vars.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/GITEA-vars.md) —
|
||||||
|
все Secrets/Variables CI и настройка branch protection.
|
||||||
@@ -0,0 +1,75 @@
|
|||||||
|
# API библиотеки
|
||||||
|
|
||||||
|
Публичный API мал и стабилен: два сервисных класса, один record, пять видов ошибок.
|
||||||
|
Javadoc каждого члена — [apidocs](/apidocs/index.html).
|
||||||
|
|
||||||
|
## `WordPdfConverter`
|
||||||
|
|
||||||
|
```java
|
||||||
|
public final class WordPdfConverter {
|
||||||
|
public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options)
|
||||||
|
throws ConversionException;
|
||||||
|
public static synchronized void warmup();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `convert` — единственный путь конвертации (двухаргументной перегрузки **нет**).
|
||||||
|
Принимает байты `.docx` или `.doc` (маршрутизация по сигнатуре), возвращает байты PDF.
|
||||||
|
`title` — заголовок PDF. `options == null` → `ValidationException`.
|
||||||
|
- `warmup()` — идемпотентный прогрев конвейера; не бросает.
|
||||||
|
|
||||||
|
## `WordPdfValidator`
|
||||||
|
|
||||||
|
Те же проверки входа **без рендера** — например, для валидации загрузки до очереди:
|
||||||
|
|
||||||
|
```java
|
||||||
|
public static void checkInput(byte[] docxBytes, long maxMb) throws ValidationException;
|
||||||
|
public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException;
|
||||||
|
```
|
||||||
|
|
||||||
|
Проверяются: непустота, размер (`maxMb`), сигнатура (zip/CFB), для docx — контейнер
|
||||||
|
(`[Content_Types].xml` с типом документа), производные пороги (распаковка, XML,
|
||||||
|
растры, записи zip), число страниц (lightweight-скан, без docx4j; для `.doc` —
|
||||||
|
по сырым байтам мостом).
|
||||||
|
|
||||||
|
## `ConvertOptions`
|
||||||
|
|
||||||
|
```java
|
||||||
|
public record ConvertOptions(boolean errorOnCharts, boolean errorOnSmartArt,
|
||||||
|
boolean errorOnOle, long maxMb, int maxPages) {}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Порядок полей фиксирован.** `maxMb`/`maxPages` должны быть больше 0. Дефолтов
|
||||||
|
в ядре нет — значения задаёт вызывающий. Диаграммы/SmartArt конвертируются всегда;
|
||||||
|
флаги только отменяют конвертацию находкой.
|
||||||
|
|
||||||
|
## Ошибки
|
||||||
|
|
||||||
|
```
|
||||||
|
ConversionException (RuntimeException)
|
||||||
|
├── ValidationException — вход некорректен (не docx/doc, размер, страницы, битый zip…)
|
||||||
|
├── ChartsFoundException — errorOnCharts и найдены диаграммы
|
||||||
|
├── SmartArtFoundException — errorOnSmartArt и найден SmartArt
|
||||||
|
└── OleFoundException — errorOnOle и найдены OLE-объекты
|
||||||
|
```
|
||||||
|
|
||||||
|
Ловите `ConversionException` — он покрывает всё; `ValidationException` — отдельно,
|
||||||
|
когда хотите различать «пользователь прислал мусор» и «конвертер не смог».
|
||||||
|
|
||||||
|
## Инвариант параллельности
|
||||||
|
|
||||||
|
`convert` **потокобезопасен, но сериализован**: все конвертации идут под монитором
|
||||||
|
класса `WordPdfConverter.class` — ядро мутирует глобальный реестр шрифтов docx4j
|
||||||
|
(`PhysicalFonts`). Параллельные вызовы корректны, но исполняются последовательно;
|
||||||
|
собственный пул/очередь с отказом при переполнении — забота вызывающего
|
||||||
|
(так делает `wordpdf-app`: один воркер, очередь 16).
|
||||||
|
|
||||||
|
## Шрифты и окружение
|
||||||
|
|
||||||
|
- Шрифты выгружаются из jar во временный каталог; реестр после каждой конвертации
|
||||||
|
возвращается к бандлу — встроенные в чужие docx шрифты не «травят» последующие
|
||||||
|
конвертации.
|
||||||
|
- `java.awt.Font` не используется (глифы — fontbox напрямую): **fontconfig хосту не нужен**,
|
||||||
|
контейнер без `/etc/fonts` работает.
|
||||||
|
- Нужен SLF4J-провайдер (см. [первые шаги](getting-started.md)) — иначе текст
|
||||||
|
предупреждений попадает в PDF.
|
||||||
@@ -0,0 +1,66 @@
|
|||||||
|
# Зависимости потребителя
|
||||||
|
|
||||||
|
## commons-compress: единственная ловушка интеграции
|
||||||
|
|
||||||
|
Ядру (транзитивно, через docx4j) нужен `org.apache.commons:commons-compress`
|
||||||
|
**≥ 1.25.0**, рекомендован **1.28.0** — версию закрепляет POM `wordpdf-core`.
|
||||||
|
Симптом старой версии в classpath потребителя:
|
||||||
|
|
||||||
|
```
|
||||||
|
NoSuchMethodError: org.apache.commons.compress.archivers.zip.ZipArchiveEntry
|
||||||
|
org.apache.commons.compress.archivers.zip.ZipArchiveInputStream.getNextEntry()
|
||||||
|
```
|
||||||
|
|
||||||
|
До входа в docx4j теперь срабатывает guard (`DependencyGuard`): вместо мутного
|
||||||
|
`NoSuchMethodError` внутри docx4j — `ConversionException` с текстом, объясняющим,
|
||||||
|
какую версию закрепить.
|
||||||
|
|
||||||
|
### Maven: закреплять в `dependencyManagement`
|
||||||
|
|
||||||
|
BOM (например, Spring Boot 3.x) пинит свою версию commons-compress, а
|
||||||
|
`dependencyManagement` потребителя перекрывает транзитивные версии («nearest wins»)
|
||||||
|
— закреплять нужно именно в нём:
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<dependencyManagement>
|
||||||
|
<dependencies>
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.apache.commons</groupId>
|
||||||
|
<artifactId>commons-compress</artifactId>
|
||||||
|
<version>1.28.0</version>
|
||||||
|
</dependency>
|
||||||
|
</dependencies>
|
||||||
|
</dependencyManagement>
|
||||||
|
```
|
||||||
|
|
||||||
|
Диагностика:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mvn dependency:tree -Dincludes=org.apache.commons:commons-compress
|
||||||
|
```
|
||||||
|
|
||||||
|
### Gradle: достаточно не понижать
|
||||||
|
|
||||||
|
По умолчанию Gradle выбирает максимальную версию и конфликт разрешает сам —
|
||||||
|
guard не сработает и не нужен. Понижает версию только явный `constraints` /
|
||||||
|
`platform` / `resolutionStrategy`: уберите понижение либо закрепите нужную версию:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
dependencies {
|
||||||
|
constraints {
|
||||||
|
implementation("org.apache.commons:commons-compress:1.28.0")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
(либо `resolutionStrategy.force("org.apache.commons:commons-compress:1.28.0")`).
|
||||||
|
Диагностика: `gradle dependencies --configuration runtimeClasspath`.
|
||||||
|
|
||||||
|
## Прочие транзитивные зависимости
|
||||||
|
|
||||||
|
|Артефакт|Зачем|Нужно ли трогать|
|
||||||
|
|---|---|---|
|
||||||
|
|`docx4j-export-fo` (+ форк FOP `docx4j-fo-renderer*`)|конвейер XSL-FO → PDF|нет|
|
||||||
|
|`slf4j-simple`|единственный SLF4J-провайдер из коробки — без провайдера docx4j пишет «TO HIDE THESE MESSAGES» в PDF|исключить, если у приложения свой провайдер|
|
||||||
|
|`jcl-over-slf4j`|мост commons-logging (pdfbox/fontbox) → slf4j|нет (`commons-logging` исключён)|
|
||||||
|
|`fontbox`|чтение TTF напрямую, без `java.awt.Font`|нет|
|
||||||
@@ -0,0 +1,72 @@
|
|||||||
|
# wordpdf-core: первые шаги
|
||||||
|
|
||||||
|
`wordpdf-core` — Java-библиотека конвертации `.docx`/`.doc` → PDF. Без LibreOffice,
|
||||||
|
без Aspose, без системных шрифтов: все TTF упакованы в jar.
|
||||||
|
|
||||||
|
## Подключение
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<dependency>
|
||||||
|
<groupId>ru.pjandro</groupId>
|
||||||
|
<artifactId>wordpdf-core</artifactId>
|
||||||
|
<version>1.0.0</version>
|
||||||
|
</dependency>
|
||||||
|
```
|
||||||
|
|
||||||
|
Требуется **Java 17**. Единственный обязательный аспект интеграции — версия
|
||||||
|
`commons-compress` (см. [Зависимости](dependencies.md)).
|
||||||
|
|
||||||
|
## Минимальный пример
|
||||||
|
|
||||||
|
```java
|
||||||
|
import ru.pjandro.wordpdf.WordPdfConverter;
|
||||||
|
import java.nio.file.Files;
|
||||||
|
import java.nio.file.Path;
|
||||||
|
|
||||||
|
byte[] docx = Files.readAllBytes(Path.of("doc.docx"));
|
||||||
|
byte[] pdf = WordPdfConverter.convert(docx, "doc",
|
||||||
|
new ru.pjandro.wordpdf.ConvertOptions(false, false, false, 5, 100));
|
||||||
|
Files.write(Path.of("out.pdf"), pdf);
|
||||||
|
```
|
||||||
|
|
||||||
|
Второй аргумент — заголовок PDF (пустой/`null` — без заголовка). Работа с файлами —
|
||||||
|
забота вызывающего: ядро пути не принимает, только байты.
|
||||||
|
|
||||||
|
Формат входа определяется **по сигнатуре байтов**, расширение имени файла ядру
|
||||||
|
неизвестно:
|
||||||
|
|
||||||
|
|Сигнатура|Маршрут|
|
||||||
|
|---|---|
|
||||||
|
|`PK\x03\x04`|zip → OOXML-путь (docx4j)|
|
||||||
|
|`D0 CF 11 E0 A1 B1 1A E1`|CFB → мост .doc → .docx в памяти → тот же конвейер|
|
||||||
|
|
||||||
|
## Опции конвертации
|
||||||
|
|
||||||
|
`ConvertOptions` — record из пяти полей (детали в [API библиотеки](api.md)):
|
||||||
|
error-флаги диаграмм/SmartArt/OLE и лимиты размера/страниц. Дефолтов в ядре нет —
|
||||||
|
все пять значений задаёт вызывающий:
|
||||||
|
|
||||||
|
```java
|
||||||
|
// отменить конвертацию, если в документе есть диаграммы; лимиты 10 МБ / 200 страниц
|
||||||
|
var opts = new ConvertOptions(true, false, false, 10, 200);
|
||||||
|
byte[] pdf = WordPdfConverter.convert(bytes, "Отчёт", opts);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Прогрев
|
||||||
|
|
||||||
|
Первая конвертация после старта JVM стоит ~1,3–1,7 с (инициализация JAXB/XSLT/FOP).
|
||||||
|
`WordPdfConverter.warmup()` прогоняет весь конвейер на минимальном встроенном docx
|
||||||
|
и идемпотентен (повторные вызовы — no-op); бросать не должен никогда — решение
|
||||||
|
о реакции на сбой прогревает код. Вызывайте на старте приложения, если не хотите,
|
||||||
|
чтобы первый пользователь платил за инициализацию:
|
||||||
|
|
||||||
|
```java
|
||||||
|
WordPdfConverter.warmup(); // ~1,5–2,5 с, один раз при старте
|
||||||
|
```
|
||||||
|
|
||||||
|
## Провайдер логов
|
||||||
|
|
||||||
|
В classpath потребителя **обязан быть SLF4J-провайдер**. Без него docx4j пишет
|
||||||
|
предупреждение «TO HIDE THESE MESSAGES…» **прямо в выходной PDF**. В jar `wordpdf-core`
|
||||||
|
для этого включён `slf4j-simple`; если ваше приложение приносит свой провайдер
|
||||||
|
(logback и т.п.) — исключите `slf4j-simple` из транзитивных зависимостей.
|
||||||
@@ -0,0 +1,52 @@
|
|||||||
|
# Конфигурация сервера (`wordpdf-app`)
|
||||||
|
|
||||||
|
## Свойства и env
|
||||||
|
|
||||||
|
|Свойство|Env|Дефолт|Смысл|
|
||||||
|
|---|---|---|---|
|
||||||
|
|`wordpdf.api-key`|`WORDPDF_API_KEY`|пусто|ключ заголовка `X-API-Key`; пусто = аутентификация выключена|
|
||||||
|
|`wordpdf.max-mb`|`WORDPDF_MAX_MB`|5 (литерал `@Value`)|дефолтный лимит размера входа, МБ (MiB); ≤ 0 на старте → `IllegalStateException`|
|
||||||
|
|`wordpdf.max-pages`|`WORDPDF_MAX_PAGES`|100 (литерал `@Value`)|дефолтный лимит страниц; ≤ 0 → падение на старте|
|
||||||
|
|`wordpdf.convert-timeout`|`WORDPDF_CONVERT_TIMEOUT`|`2m`|таймаут одной конвертации (Duration) → 504|
|
||||||
|
|`spring.servlet.multipart.max-file-size` / `max-request-size`|—|`100MB`|потолок контейнера, зеркалит nginx `client_max_body_size 100m`|
|
||||||
|
|`spring.servlet.multipart.file-size-threshold`|—|`2MB`|части больше — на диск Tomcat (heap держит только копию одной сериализованной конвертации)|
|
||||||
|
|`server.forward-headers-strategy`|—|`framework`|работа за префикс-срезающим прокси (`X-Forwarded-*`); `native` не понимает `X-Forwarded-Prefix`|
|
||||||
|
|`springdoc.api-docs.enabled`|`SPRINGDOC_API_DOCS_ENABLED`|`true`|OpenAPI-спек; `false` → `/v3/api-docs` отдаёт 404|
|
||||||
|
|`springdoc.swagger-ui.enabled`|`SPRINGDOC_SWAGGER_UI_ENABLED`|`true`|Swagger UI|
|
||||||
|
|`springdoc.swagger-ui.persist-authorization`|—|`true`|не требовать ключ заново после перезагрузки страницы UI|
|
||||||
|
|
||||||
|
Ограничитель очереди (16 мест) — константа `ConversionService.QUEUE_CAPACITY`,
|
||||||
|
не конфигурируется.
|
||||||
|
|
||||||
|
!!! warning "Не объявляйте `wordpdf.max-mb`/`max-pages` в `application.properties`"
|
||||||
|
Дефолты 5/100 живут литералами `@Value` в `ConvertController`. Пустое значение
|
||||||
|
ключа в properties **затенит** литерал и сломает старт. Либо не объявляйте
|
||||||
|
(тогда дефолт), либо конкретное число.
|
||||||
|
|
||||||
|
## Примеры запуска
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# ключ + лимиты через env
|
||||||
|
WORDPDF_API_KEY=$(openssl rand -hex 32) WORDPDF_MAX_MB=10 \
|
||||||
|
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
|
||||||
|
|
||||||
|
# или аргументами
|
||||||
|
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar \
|
||||||
|
--wordpdf.api-key=secret --wordpdf.convert-timeout=3m
|
||||||
|
```
|
||||||
|
|
||||||
|
В prod-like compose-стеке `WORDPDF_API_KEY` читается из `.env` (fail-closed:
|
||||||
|
`${WORDPDF_API_KEY:?}` — без него стек не поднимается), на проде ключ приходит
|
||||||
|
только из Gitea Secret через окружение контейнера.
|
||||||
|
|
||||||
|
## Что задала не я, а инфраструктура
|
||||||
|
|
||||||
|
|Параметр|Где|Значение|
|
||||||
|
|---|---|---|
|
||||||
|
|`client_max_body_size`|`gateway/nginx.conf`|`100m`|
|
||||||
|
|proxy_read timeout|`gateway/nginx.conf`|300 с|
|
||||||
|
|heap контейнера app|`Containerfile` (ENTRYPOINT)|`-Xms2g -Xmx2g`; лимит `mem_limit: 3g` — в compose|
|
||||||
|
|`VITE_BASE`|build-arg образа web|`/pdf-converter/` (путь публикации на проде)|
|
||||||
|
|
||||||
|
Значение `maxMb`/`maxPages` конкретного стенда прод-автотесты читают из
|
||||||
|
`WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES` (на проде — 5/100).
|
||||||
@@ -0,0 +1,54 @@
|
|||||||
|
# Деплой (прод)
|
||||||
|
|
||||||
|
Наружный вход прода — **`https://pjandro.ru/pdf-converter/`** (пользовательский
|
||||||
|
nginx режет префикс и проксирует на стек конвертера). Публикация полностью
|
||||||
|
автоматизрована: **push в `main` → Gitea Actions**.
|
||||||
|
|
||||||
|
## Пайплайн `main.yml`
|
||||||
|
|
||||||
|
```
|
||||||
|
java + web (тесты/гейты) ──> images-app + images-web (build+push в реестр)
|
||||||
|
──> deploy (рендер прод-стека, pull, up, health-гейты, автооткат)
|
||||||
|
──> autotests (pytest против живого прода; провал → rollback)
|
||||||
|
```
|
||||||
|
|
||||||
|
1. **`java` / `web`** — те же гейты, что на PR (`mvn clean verify` в контейнере
|
||||||
|
без fontconfig; `npm ci`/build/lint).
|
||||||
|
2. **`images-app` / `images-web`** — сборка Containerfile в Nexus-реестр, теги
|
||||||
|
`prod` + неизменяемый `sha-<7 символов>`; web печётся с
|
||||||
|
`VITE_BASE=/pdf-converter/` (путь публикации запекается в образ).
|
||||||
|
3. **`deploy`** — job **рендерит** `docker-compose.yml` и `nginx.conf` в директорию
|
||||||
|
деплоя из Gitea Variables (прод-хост не хранит ни конфигураций, ни секретов;
|
||||||
|
API-ключ — из Secret через окружение деплоя, на диск не пишется), затем
|
||||||
|
login/pull/`up -d --force-recreate app web`, гейты healthy + recreate gateway.
|
||||||
|
Единственное состояние на проде — `.rollback.env` (image id предыдущего рана).
|
||||||
|
4. **`autotests`** — 31 pytest-проверка против живого стенда; провал → откат
|
||||||
|
на образ из `.rollback.env`.
|
||||||
|
|
||||||
|
## Где креды и координаты
|
||||||
|
|
||||||
|
Всё вне репозитория — **Gitea Actions Variables/Secrets** (полный список и настройка
|
||||||
|
branch protection: [`GITEA-vars.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/GITEA-vars.md)).
|
||||||
|
Прод-ключ `WORDPDF_API_KEY` — только Secret. В репо и на диске прод-хоста ключа нет.
|
||||||
|
|
||||||
|
## Ручные операции
|
||||||
|
|
||||||
|
!!! warning "Перед ручным перезапуском прода"
|
||||||
|
Прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (живёт на прод-хосте,
|
||||||
|
вне репозитория) — там актуальные координаты и процедура. Ручных скриптов
|
||||||
|
деплоя в репозитории нет и не заводить.
|
||||||
|
|
||||||
|
Прод-образ/`compose` правятся только через CI-рендер; копий прод-стека на хосте
|
||||||
|
или в репо быть не должно.
|
||||||
|
|
||||||
|
## Проверка после деплоя
|
||||||
|
|
||||||
|
CI сам докладывает по job'ам (`/actions/runs/<id>/jobs`); руками:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -sf https://pjandro.ru/pdf-converter/actuator/health # 200 {"status":"UP"}
|
||||||
|
curl -s -o /dev/null -w '%{http_code}\n' https://pjandro.ru/pdf-converter/ # 200 SPA
|
||||||
|
```
|
||||||
|
|
||||||
|
Глубина (нюансы runner'ов, `DOCKER_BUILDKIT=0`, реестр, rollback-механика) —
|
||||||
|
[ci-cd.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/ci-cd.md).
|
||||||
@@ -0,0 +1,88 @@
|
|||||||
|
# Этот сайт документации
|
||||||
|
|
||||||
|
Статический сайт (MkDocs Material) собирается из `docs/` этого репозитория и
|
||||||
|
раздаётся nginx-контейнером на rpi-хосте LAN-сервера:
|
||||||
|
|
||||||
|
- адрес: **`http://192.168.88.23:9012/`** (LAN; наружу не публикуется);
|
||||||
|
- статика: `/home/pjandro/srv/wordpdf-docs/` (rsync без рестарта контейнера);
|
||||||
|
- javadoc публичного API: [`/apidocs/index.html`](/apidocs/index.html).
|
||||||
|
|
||||||
|
## Публикация (с хоста, из репозитория)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./mise.sh run docs-install # разово: venv docs/.venv + mkdocs-material
|
||||||
|
./mise.sh run docs-deploy # javadoc → strict-build → rsync в ~/srv/wordpdf-docs
|
||||||
|
```
|
||||||
|
|
||||||
|
`docs-deploy` выполняет фиксированный порядок: `mvn javadoc:javadoc` → копия
|
||||||
|
`wordpdf-core/target/site/apidocs` → `docs/apidocs` → `mkdocs build --strict` →
|
||||||
|
`rsync -a --delete site/ ~/srv/wordpdf-docs/`. **Рестарт сервиса не нужен** —
|
||||||
|
nginx раздаёт файлы с смонтированного тома. Strict-сборка ловит битые ссылки и
|
||||||
|
страницы вне `nav`.
|
||||||
|
|
||||||
|
Dev-цикл: `./mise.sh run docs-serve` → `http://127.0.0.1:8000/` (live-reload).
|
||||||
|
|
||||||
|
## Сервис отдачи
|
||||||
|
|
||||||
|
Rootless podman (nginx-контейнер) под user-systemd (`linger=yes`). Юнит
|
||||||
|
`~/.config/systemd/user/wordpdf-docs.service` (вне git; канон текста — здесь):
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[Unit]
|
||||||
|
Description=Word PDF — сайт документации (nginx static, :9012)
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
# podman run без -d — foreground, systemd видит основной процесс
|
||||||
|
ExecStart=/usr/bin/podman run --name wordpdf-docs --replace -p 9012:80 -v /home/pjandro/srv/wordpdf-docs:/usr/share/nginx/html:ro docker.io/library/nginx:alpine
|
||||||
|
ExecStopPost=/usr/bin/podman rm -f wordpdf-docs
|
||||||
|
Restart=on-failure
|
||||||
|
RestartSec=5
|
||||||
|
TimeoutStopSec=30
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=default.target
|
||||||
|
```
|
||||||
|
|
||||||
|
Разовая установка (на хосте `192.168.88.23`):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
podman pull docker.io/library/nginx:alpine
|
||||||
|
install -d /home/pjandro/srv/wordpdf-docs
|
||||||
|
systemctl --user daemon-reload
|
||||||
|
systemctl --user enable --now wordpdf-docs.service
|
||||||
|
```
|
||||||
|
|
||||||
|
Проверка/управление:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
systemctl --user status wordpdf-docs.service
|
||||||
|
journalctl --user -u wordpdf-docs.service -n 50
|
||||||
|
curl -sf -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9012/
|
||||||
|
```
|
||||||
|
|
||||||
|
Порт 9012: соседние 9010/9011 заняты стендами конвертера (конвенция сети), 8000 —
|
||||||
|
dev-preview. Наружу (wan) не публикуем; наружный nginx `pjandro.ru` при желании
|
||||||
|
добавит владелец сервера отдельно.
|
||||||
|
|
||||||
|
## Почему не Gitea Pages
|
||||||
|
|
||||||
|
Публиковать на инстансе `git.pjandro.ru` (Gitea 1.26.4) проверенным способом «Pages»
|
||||||
|
нельзя — встроенного Pages в этой сборке нет:
|
||||||
|
|
||||||
|
- в swagger инстанса отсутствует эндпоинт `/repos/{owner}/{repo}/pages`,
|
||||||
|
в config cheat sheet — `ENABLE_PAGES`/`PAGES_DOMAIN`;
|
||||||
|
- FAQ инстанса: «Gitea doesn't provide a built-in Pages server»;
|
||||||
|
- в Gitea Actions игнорируется `jobs.*.environment`, не поддерживаются scopes
|
||||||
|
`pages`/`deployments`; тандем `upload-pages-artifact` + `deploy-pages`
|
||||||
|
неработоспособен (`upload-artifact@v4` не поддерживается, `@v3` подвешивается).
|
||||||
|
|
||||||
|
Поэтому публикация — локальная задача `docs-deploy` на том же хосте, где живёт
|
||||||
|
сервис; CI не участвует (docs-файлы не требуют гейтов).
|
||||||
|
|
||||||
|
## Что входит в сайт / не входит
|
||||||
|
|
||||||
|
В сайт попадают все страницы `docs/`, **кроме** `docs/agent/`, `docs/standards/`
|
||||||
|
и `docs/requirements.txt` (`exclude_docs` в `mkdocs.yml`) — это внутренние
|
||||||
|
справочники и спецификации, на них ведут внешние ссылки на Gitea
|
||||||
|
([Внутренние справочники](../internal-guides.md)). Каталог `docs/apidocs/`
|
||||||
|
(gitignored) заполняется задачей `docs-deploy` и копируется mkdocs как статика.
|
||||||
@@ -0,0 +1,61 @@
|
|||||||
|
# Стенды и топология
|
||||||
|
|
||||||
|
Наружу публикуется **только nginx-gateway**; контейнер `app` (:8080) наружу не
|
||||||
|
выставляется никогда. Порты стендов зафиксированы конвенцией сети.
|
||||||
|
|
||||||
|
|Стенд|Файл|Вход|Ключ доступа|springdoc|
|
||||||
|
|---|---|---|---|---|
|
||||||
|
|prod|`docker-compose.yml` (рендерится CI)|`https://pjandro.ru/pdf-converter/`|обязателен (Gitea Secret)|открыт|
|
||||||
|
|prod-like (локально)|`compose.yml`|`http://localhost:9010/`|fail-closed: `.env` с `WORDPDF_API_KEY`|выключен env-ами|
|
||||||
|
|dev|`compose.dev.yml`|`http://<LAN-IP>:9011/`|выключен|включён|
|
||||||
|
|без контейнеров|`java -jar` + `npm run dev`|`:8080` + `:5173`|выключен|включён|
|
||||||
|
|
||||||
|
## Gateway (prod-like/dev)
|
||||||
|
|
||||||
|
`gateway/nginx.conf`: `client_max_body_size 100m`, таймауты прокси 300 с,
|
||||||
|
`resolver` привязан literal-ом к шлюзу docker-сети стенда (10.113.0.1 / 10.112.0.1 —
|
||||||
|
не путать при копировании).
|
||||||
|
|
||||||
|
Маршруты:
|
||||||
|
|
||||||
|
|Location|Куда|
|
||||||
|
|---|---|
|
||||||
|
|`/api/`|`app:8080` (URI передаётся как есть)|
|
||||||
|
|`/swagger-ui`, `/v3/api-docs`, `/actuator`|`app:8080`|
|
||||||
|
|`/` (остальное)|`web` — чистая статика SPA|
|
||||||
|
|
||||||
|
`proxy_pass` через переменную + `resolver` — чтобы DNS-имя контейнера резолвилось
|
||||||
|
на каждый запрос, а не один раз при старте nginx.
|
||||||
|
|
||||||
|
## Подъём
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# dev (:9011) — «тестовый сервер» проекта
|
||||||
|
podman-compose -f compose.dev.yml up -d --build --force-recreate
|
||||||
|
|
||||||
|
# prod-like (:9010) — нужен .env с WORDPDF_API_KEY (fail-closed), шаблон .env.example
|
||||||
|
cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32
|
||||||
|
podman-compose up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! warning "--force-recreate"
|
||||||
|
Без него podman-compose пересоберёт образ, но контейнеры оставит на старом —
|
||||||
|
будет крутиться jar прошлой сборки.
|
||||||
|
|
||||||
|
## Прод
|
||||||
|
|
||||||
|
Прод-стек (`docker-compose.yml` + прод `nginx.conf`) **не хранится ни на хосте, ни в
|
||||||
|
репозитории** — job `deploy` в CI рендерит их из Gitea Variables (ключ — из Secret,
|
||||||
|
на диск не пишется), затем pull/`up -d --force-recreate`/health-гейты/автооткат.
|
||||||
|
Копии прод-конфигов на хосте/в репо — нарушение конвенции. Подробности —
|
||||||
|
[Деплой](deployment.md).
|
||||||
|
|
||||||
|
## Порты (конвенция)
|
||||||
|
|
||||||
|
|Порт|Кто|
|
||||||
|
|---|---|
|
||||||
|
|9010|prod-like gateway|
|
||||||
|
|9011|dev gateway|
|
||||||
|
|9012|сайт документации (nginx static, [Docs-сайт](docs-site.md))|
|
||||||
|
|8080|`java -jar` бэкенд (только localhost)|
|
||||||
|
|5173|vite dev-сервер SPA|
|
||||||
@@ -0,0 +1,74 @@
|
|||||||
|
# Troubleshooting
|
||||||
|
|
||||||
|
Симптом → причина → действие. Только подтверждённое поведение стендов.
|
||||||
|
|
||||||
|
## 401 «Ключ доступа не передан или неверен»
|
||||||
|
|
||||||
|
- Забыт заголовок `X-API-Key` / ключ не совпадает со `WORDPDF_API_KEY` сервера.
|
||||||
|
- Prod-like стенд не поднимается без `.env` — это fail-closed (`${WORDPDF_API_KEY:?}`),
|
||||||
|
не баг.
|
||||||
|
- Запрос идёт через точечный сегмент (`/actuator/../api/...`) — открытые префиксы
|
||||||
|
с `..`/`%2e` ключем не обходятся, так и задумано.
|
||||||
|
- Фронт: экран ключа не появляется, хотя сервер его требует? Проверьте, что
|
||||||
|
`probeApiKey()` дошёл до сервера (network-вкладка); ключ из localStorage
|
||||||
|
стирается при 401.
|
||||||
|
|
||||||
|
## 422 «Конвертация отменена: … найдены диаграммы/SmartArt/OLE-объекты»
|
||||||
|
|
||||||
|
Не ошибка — сработал включённый error-флаг запроса. Снимите `errorOnCharts`/
|
||||||
|
`errorOnSmartArt`/`errorOnOle` (по умолчанию выключены). На `.doc` флаги не
|
||||||
|
срабатывают в принципе (плейсхолдеры — растры).
|
||||||
|
|
||||||
|
## 503
|
||||||
|
|
||||||
|
Очередь конвертации (16 мест) полна: воркер один, все конвертации сериализованы.
|
||||||
|
Повторите позже. Систематически — увеличивайте время ответа вниз (документы
|
||||||
|
поменьше) или масштабируйте количество экземпляров за балансировщиком (каждый
|
||||||
|
со своей очередью).
|
||||||
|
|
||||||
|
## 504
|
||||||
|
|
||||||
|
Конвертация дольше `wordpdf.convert-timeout` (2m). Уменьшите документ (много
|
||||||
|
больших растров/диаграмм) или поднимите таймаут серверу. Учтите: отменённая
|
||||||
|
конвертация дожигается, следующий запрос ждёт её в очереди.
|
||||||
|
|
||||||
|
## 413
|
||||||
|
|
||||||
|
Тело больше контейнерного потолка multipart (100 МБ) или nginx `client_max_body_size
|
||||||
|
100m` — обе границы стоят 100 МБ. Логический лимит входа (`wordpdf.max-mb`, дефолт
|
||||||
|
5 МБ) отсекает раньше и даёт 400, так что 413 — это когда серверный лимит поднят
|
||||||
|
выше 100 МБ бессмысленно либо запрос идёт мимо ожидаемого пути. Файл реально меньше,
|
||||||
|
но 413? Проверьте, не режет ли промежуточный прокси.
|
||||||
|
|
||||||
|
## В PDF напечатано «...TO HIDE THESE MESSAGES...»
|
||||||
|
|
||||||
|
В classpath нет SLF4J-провайдера — docx4j пишет предупреждения прямо в PDF.
|
||||||
|
Для библиотеки: оставить `slf4j-simple` (в транзитивах `wordpdf-core`) или принести
|
||||||
|
свой провайдер. Для app: `slf4j-simple` исключён в пользу logback — если логическая
|
||||||
|
конфигурация app сломана и SLF4J не инициализирован, верните провайдер.
|
||||||
|
|
||||||
|
## Картинки диаграмм «мыльные» (ресемпл)
|
||||||
|
|
||||||
|
Нарушен контракт префикса media-частей `/word/media/chart-*`: по нему
|
||||||
|
`ChartImageHandler` отключает пересжатие PNG в FOP. Если части переименованы
|
||||||
|
ручной правкой — верните префикс (`DrawingPreRenderer.CHART_MEDIA_URI_PREFIX`).
|
||||||
|
|
||||||
|
## Вместо знаков — `#` или пустые боксы
|
||||||
|
|
||||||
|
- `#` — глифа нет ни в шрифте ранa, ни в fallback, и не сработала резка по покрытию
|
||||||
|
(для docx-пута это регрессия — заведите issue с документом).
|
||||||
|
- Пустой бокс `.notdef` для U+2188/U+218A — известное ограничение OFL-бандла, не чинится.
|
||||||
|
- «Битый»/подменённый шрифт в целом — проверьте алиасы (`Calibri→Carlito` и т.д.,
|
||||||
|
[Шрифты](../architecture/fonts.md)): подмена метрически совместима и ожидаема.
|
||||||
|
|
||||||
|
## Стенд крутит старый код после пересборки
|
||||||
|
|
||||||
|
podman-compose пересобрал образ, но контейнеры остались на старом — перезапустите
|
||||||
|
с `--force-recreate` ([Стенды](stack.md)).
|
||||||
|
|
||||||
|
## `.doc` не конвертируется (400)
|
||||||
|
|
||||||
|
Проверьте сигнатуру: `D0 CF 11 E0 A1 B1 1A E1`. Word 6–95 и зашифрованные (Office 95
|
||||||
|
password) документы мостом не поддерживаются → 400/`ValidationException`. Расширение
|
||||||
|
`.doc` при zip-содержимом (переименованный docx) маршрутизируется по байтам — это
|
||||||
|
не ошибка.
|
||||||
@@ -0,0 +1 @@
|
|||||||
|
mkdocs-material==9.8.2
|
||||||
@@ -0,0 +1,56 @@
|
|||||||
|
# Пользователю
|
||||||
|
|
||||||
|
## Где открыть
|
||||||
|
|
||||||
|
Веб-конвертер: **`https://pjandro.ru/pdf-converter/`**. Работает в любом современном
|
||||||
|
браузере, установка не нужна.
|
||||||
|
|
||||||
|
## Как пользоваться
|
||||||
|
|
||||||
|
1. Перетащите файл `.docx` или `.doc` в зону загрузки (или выберите его через диалог).
|
||||||
|
2. Документ конвертируется на сервере; результат появляется во встроенном
|
||||||
|
предпросмотре PDF.
|
||||||
|
3. Нажмите «Скачать» — PDF сохранится под именем исходного файла с расширением `.pdf`
|
||||||
|
(кириллица в имени поддерживается).
|
||||||
|
|
||||||
|
В форме есть три переключателя («Диаграммы», «SmartArt», «OLE-объекты», по умолчанию
|
||||||
|
выключены): при включённом конвертация **отменится**, если документ содержит
|
||||||
|
соответствующие объекты, и интерфейс покажет понятное сообщение. По умолчанию
|
||||||
|
диаграммы и SmartArt конвертируются в картинки всегда, а OLE-объекты тихо удаляются
|
||||||
|
(картинка-плейсхолдер из документа сохраняется).
|
||||||
|
|
||||||
|
## Ключ доступа
|
||||||
|
|
||||||
|
Если сервер защищён ключом доступа, при первом открытии появится экран ввода ключа.
|
||||||
|
Ключ хранится в браузере (localStorage) и подставляется автоматически; при неверном
|
||||||
|
ключе стирается, и экран появляется снова. Если сервер ключ не требует, экран не
|
||||||
|
показывается вовсе.
|
||||||
|
|
||||||
|
## Поддерживаемые форматы
|
||||||
|
|
||||||
|
|Формат|Что это|
|
||||||
|
|---|---|
|
||||||
|
|`.docx`|OOXML (Word 2007 и новее), включая строгий (strict) OOXML|
|
||||||
|
|`.doc`|бинарный Word 97–2003; читается собственным мостом, без Word и LibreOffice|
|
||||||
|
|
||||||
|
Лимиты документа (размер, число страниц) задаёт сервер; конкретные значения зависят
|
||||||
|
от развёрнутого экземпляра.
|
||||||
|
|
||||||
|
## Что конвертируется точно, а что приближённо
|
||||||
|
|
||||||
|
Конвертер **не является pixel-perfect рендером Word**: это ограничения движка
|
||||||
|
FOP/docx4j, а не упущение проекта. Текст, стили, таблицы, списки, колонтитуки,
|
||||||
|
картинки, диаграммы и SmartArt воспроизводятся надёжно; раскладка, поля и некоторые
|
||||||
|
эффекты могут отличаться от Word.
|
||||||
|
|
||||||
|
Символы, которых нет в шрифте ранa (например, тире «—», кавычки), берутся из
|
||||||
|
fallback-семейства DejaVu с гарантированной кириллицей. Знаков, которых нет ни в одном
|
||||||
|
шрифте бандла, это не касается — для них останутся пустые боксы; в эталонном наборе
|
||||||
|
таких символа два (U+2188, U+218A — римские/осмы числительные, доступны только в
|
||||||
|
GPL-шрифтах).
|
||||||
|
|
||||||
|
На `.doc` переключатели «Диаграммы/SmartArt/OLE» не срабатывают: плейсхолдеры
|
||||||
|
бинарного формата — уже растры, они вставляются картинками; векторные EMF/WMF/PICT
|
||||||
|
пропускаются.
|
||||||
|
|
||||||
|
Полный перечень известных расхождений — [Ограничения рендера](architecture/limitations.md).
|
||||||
@@ -54,3 +54,33 @@ run = "npm run dev"
|
|||||||
description = "Прод-автотесты; обязателен WORDPDF_BASE_URL (факультативно WORDPDF_API_KEY)"
|
description = "Прод-автотесты; обязателен WORDPDF_BASE_URL (факультативно WORDPDF_API_KEY)"
|
||||||
dir = "prod-autotests"
|
dir = "prod-autotests"
|
||||||
run = "python -m pip install -q -r requirements.txt && python -m pytest -q ."
|
run = "python -m pip install -q -r requirements.txt && python -m pytest -q ."
|
||||||
|
|
||||||
|
[tasks.docs-install]
|
||||||
|
description = "Зависимости сайта документации: venv docs/.venv + mkdocs-material"
|
||||||
|
run = [
|
||||||
|
"[ -d docs/.venv ] || python -m venv docs/.venv",
|
||||||
|
"docs/.venv/bin/python -m pip install -q -r docs/requirements.txt",
|
||||||
|
]
|
||||||
|
|
||||||
|
[tasks.docs-serve]
|
||||||
|
description = "Локальный предпросмотр сайта на :8000 (live-reload)"
|
||||||
|
run = "docs/.venv/bin/mkdocs serve -a 127.0.0.1:8000"
|
||||||
|
|
||||||
|
[tasks.docs-build]
|
||||||
|
description = "Strict-сборка сайта в site/ (битые ссылки/навигация = ошибка)"
|
||||||
|
run = "docs/.venv/bin/mkdocs build --strict"
|
||||||
|
|
||||||
|
[tasks.docs-javadoc]
|
||||||
|
description = "Javadoc публичного API core в wordpdf-core/target/site/apidocs"
|
||||||
|
run = "mvn -q -pl wordpdf-core -am javadoc:javadoc"
|
||||||
|
|
||||||
|
[tasks.docs-deploy]
|
||||||
|
description = "Публикация сайта на rpi (:9012): javadoc + strict-build + rsync в ~/srv/wordpdf-docs"
|
||||||
|
run = [
|
||||||
|
"mvn -q -pl wordpdf-core -am javadoc:javadoc",
|
||||||
|
"rm -rf docs/apidocs",
|
||||||
|
"cp -r wordpdf-core/target/site/apidocs docs/apidocs",
|
||||||
|
"docs/.venv/bin/mkdocs build --strict",
|
||||||
|
"install -d /home/pjandro/srv/wordpdf-docs",
|
||||||
|
"rsync -a --delete site/ /home/pjandro/srv/wordpdf-docs/",
|
||||||
|
]
|
||||||
|
|||||||
+76
@@ -0,0 +1,76 @@
|
|||||||
|
site_name: «Word → PDF конвертер» — документация
|
||||||
|
site_description: "docx4j + Apache FOP на чистой Java: библиотека, REST API, веб-интерфейс"
|
||||||
|
docs_dir: docs
|
||||||
|
site_dir: site
|
||||||
|
exclude_docs: |
|
||||||
|
/agent/
|
||||||
|
/standards/
|
||||||
|
/requirements.txt
|
||||||
|
# javadoc-копия (docs/apidocs, заполняет docs-deploy) — статика вне навигации;
|
||||||
|
# её md-файлы (legal/*) mkdocs иначе показывает как страницы вне nav
|
||||||
|
not_in_nav: |
|
||||||
|
/apidocs/**/*.md
|
||||||
|
theme:
|
||||||
|
name: material
|
||||||
|
language: ru
|
||||||
|
palette:
|
||||||
|
- scheme: default
|
||||||
|
primary: indigo
|
||||||
|
toggle:
|
||||||
|
icon: material/weather-sunny
|
||||||
|
name: Тёмная тема
|
||||||
|
- scheme: slate
|
||||||
|
primary: indigo
|
||||||
|
toggle:
|
||||||
|
icon: material/weather-night
|
||||||
|
name: Светлая тема
|
||||||
|
features:
|
||||||
|
- navigation.sections
|
||||||
|
- navigation.top
|
||||||
|
- toc.follow
|
||||||
|
- search.suggest
|
||||||
|
markdown_extensions:
|
||||||
|
- admonition
|
||||||
|
- attr_list
|
||||||
|
- footnotes
|
||||||
|
- toc:
|
||||||
|
permalink: true
|
||||||
|
- pymdownx.details
|
||||||
|
- pymdownx.superfences
|
||||||
|
- pymdownx.highlight:
|
||||||
|
anchor_linenums: true
|
||||||
|
plugins:
|
||||||
|
- search:
|
||||||
|
lang: ru
|
||||||
|
nav:
|
||||||
|
- Главное: index.md
|
||||||
|
- Пользователю: user.md
|
||||||
|
- REST API:
|
||||||
|
- api/index.md
|
||||||
|
- Аутентификация: api/authentication.md
|
||||||
|
- Эндпоинт конвертации: api/convert-endpoint.md
|
||||||
|
- Коды ошибок: api/errors.md
|
||||||
|
- Лимиты: api/limits.md
|
||||||
|
- Примеры клиентов: api/examples.md
|
||||||
|
- Библиотека wordpdf-core:
|
||||||
|
- library/getting-started.md
|
||||||
|
- library/api.md
|
||||||
|
- library/dependencies.md
|
||||||
|
- Архитектура:
|
||||||
|
- architecture/overview.md
|
||||||
|
- architecture/doc-bridge.md
|
||||||
|
- architecture/charts.md
|
||||||
|
- architecture/fonts.md
|
||||||
|
- architecture/limitations.md
|
||||||
|
- Разработчику:
|
||||||
|
- development/setup.md
|
||||||
|
- development/testing.md
|
||||||
|
- development/contributing.md
|
||||||
|
- Эксплуатация:
|
||||||
|
- operations/stack.md
|
||||||
|
- operations/configuration.md
|
||||||
|
- operations/deployment.md
|
||||||
|
- operations/troubleshooting.md
|
||||||
|
- operations/docs-site.md
|
||||||
|
- "Отчёт: потребление памяти": MEM_USAGE_UPGRADE.md
|
||||||
|
- Внутренние справочники репозитория: internal-guides.md
|
||||||
@@ -39,6 +39,8 @@
|
|||||||
|
|
||||||
<!-- Покрытие: последняя стабильная на Maven Central -->
|
<!-- Покрытие: последняя стабильная на Maven Central -->
|
||||||
<jacoco.version>0.8.15</jacoco.version>
|
<jacoco.version>0.8.15</jacoco.version>
|
||||||
|
<!-- Javadoc публичного API core: последняя стабильная на Maven Central -->
|
||||||
|
<maven-javadoc-plugin.version>3.12.0</maven-javadoc-plugin.version>
|
||||||
<!-- Пустой дефолт: при -Djacoco.skip=true surefire не споткнётся
|
<!-- Пустой дефолт: при -Djacoco.skip=true surefire не споткнётся
|
||||||
о неразвёрнутый @{argLine}; prepare-agent перезаписывает его -->
|
о неразвёрнутый @{argLine}; prepare-agent перезаписывает его -->
|
||||||
<argLine></argLine>
|
<argLine></argLine>
|
||||||
@@ -156,6 +158,27 @@
|
|||||||
<artifactId>maven-jar-plugin</artifactId>
|
<artifactId>maven-jar-plugin</artifactId>
|
||||||
<version>3.5.1</version>
|
<version>3.5.1</version>
|
||||||
</plugin>
|
</plugin>
|
||||||
|
<!-- Javadoc: генерация только по явной цели javadoc:javadoc
|
||||||
|
(объявлен без executions в wordpdf-core) — поведение
|
||||||
|
mvn clean verify не затрагивает. -->
|
||||||
|
<plugin>
|
||||||
|
<groupId>org.apache.maven.plugins</groupId>
|
||||||
|
<artifactId>maven-javadoc-plugin</artifactId>
|
||||||
|
<version>${maven-javadoc-plugin.version}</version>
|
||||||
|
<configuration>
|
||||||
|
<encoding>UTF-8</encoding>
|
||||||
|
<doclint>all,-missing</doclint>
|
||||||
|
<show>protected</show>
|
||||||
|
<nohelp>true</nohelp>
|
||||||
|
<windowtitle>wordpdf-core API</windowtitle>
|
||||||
|
<doctitle>wordpdf-core API (javadoc)</doctitle>
|
||||||
|
<!-- пин вывода: у 3.12.0 дефолт target/reports (параметр
|
||||||
|
outputDirectory, поверх него плагин сам кладёт apidocs/),
|
||||||
|
фиксируем target/site → target/site/apidocs — оттуда
|
||||||
|
копирует задача docs-deploy -->
|
||||||
|
<outputDirectory>${project.build.directory}/site</outputDirectory>
|
||||||
|
</configuration>
|
||||||
|
</plugin>
|
||||||
<plugin>
|
<plugin>
|
||||||
<groupId>org.apache.maven.plugins</groupId>
|
<groupId>org.apache.maven.plugins</groupId>
|
||||||
<artifactId>maven-pmd-plugin</artifactId>
|
<artifactId>maven-pmd-plugin</artifactId>
|
||||||
|
|||||||
@@ -143,6 +143,15 @@
|
|||||||
</execution>
|
</execution>
|
||||||
</executions>
|
</executions>
|
||||||
</plugin>
|
</plugin>
|
||||||
|
<!-- Javadoc публичного API модуля (цель javadoc:javadoc, задача mise
|
||||||
|
docs-javadoc; результат target/site/apidocs попадает на сайт
|
||||||
|
документации). Без executions: в лайфцикл не вмешивается.
|
||||||
|
wordpdf-app javadoc не генерирует — единственного public-класса
|
||||||
|
WordPdfApplication недостаточно для раздела документации. -->
|
||||||
|
<plugin>
|
||||||
|
<groupId>org.apache.maven.plugins</groupId>
|
||||||
|
<artifactId>maven-javadoc-plugin</artifactId>
|
||||||
|
</plugin>
|
||||||
</plugins>
|
</plugins>
|
||||||
</build>
|
</build>
|
||||||
</project>
|
</project>
|
||||||
|
|||||||
@@ -30,10 +30,10 @@ import java.nio.ByteBuffer;
|
|||||||
*
|
*
|
||||||
* Медиа документов (фото/скрины) — не наши части, но и для них штатный путь
|
* Медиа документов (фото/скрины) — не наши части, но и для них штатный путь
|
||||||
* дорог: {@code PictureCompression.compress} декодирует полный растр (ImageIO)
|
* дорог: {@code PictureCompression.compress} декодирует полный растр (ImageIO)
|
||||||
* ДО любых решений, а для не-JPEG без кропа с ppi <= threshold (и без размера
|
* ДО любых решений, а для не-JPEG без кропа с ppi {@code <=} threshold (и без размера
|
||||||
* в макете) результат всегда null — декод впустую. Здесь такое решение
|
* в макете) результат всегда null — декод впустую. Здесь такое решение
|
||||||
* принимается по 26 байтам заголовка (PNG/GIF/BMP), растр не декодируется
|
* принимается по 26 байтам заголовка (PNG/GIF/BMP), растр не декодируется
|
||||||
* вовсе. JPEG сознательно не ускоряем: Word при ppi <= threshold перекодирует
|
* вовсе. JPEG сознательно не ускоряем: Word при ppi {@code <=} threshold перекодирует
|
||||||
* его «для размера», вывод должен остаться побайтно прежним.
|
* его «для размера», вывод должен остаться побайтно прежним.
|
||||||
*
|
*
|
||||||
* Регрессии — WordPdfConverterTest#chartMedia_notDownsampled,
|
* Регрессии — WordPdfConverterTest#chartMedia_notDownsampled,
|
||||||
|
|||||||
@@ -67,7 +67,7 @@ import java.util.regex.Pattern;
|
|||||||
*
|
*
|
||||||
* <p>Контракт ошибок: любой некорректный вход (не CFB, не Word, шифрование,
|
* <p>Контракт ошибок: любой некорректный вход (не CFB, не Word, шифрование,
|
||||||
* Word 6/95, обрезка, цикл в цепочках, страницы сверх лимита) —
|
* Word 6/95, обрезка, цикл в цепочках, страницы сверх лимита) —
|
||||||
* {@link ConversionException}.</p>
|
* {@link ru.pjandro.wordpdf.ConversionException}.</p>
|
||||||
*/
|
*/
|
||||||
public final class DocToDocx {
|
public final class DocToDocx {
|
||||||
|
|
||||||
@@ -122,7 +122,8 @@ public final class DocToDocx {
|
|||||||
* @param docBytes контейнер Word 97–2003
|
* @param docBytes контейнер Word 97–2003
|
||||||
* @param maxMb лимит размера входа (МБ) — из него порог пиксельной
|
* @param maxMb лимит размера входа (МБ) — из него порог пиксельной
|
||||||
* площади растра ({@code WordPdfValidator.maxImagePixels})
|
* площади растра ({@code WordPdfValidator.maxImagePixels})
|
||||||
* @throws ConversionException на некорректном/зашифрованном/чужом входе
|
* @throws ru.pjandro.wordpdf.ConversionException
|
||||||
|
* на некорректном/зашифрованном/чужом входе
|
||||||
*/
|
*/
|
||||||
public static byte[] convert(byte[] docBytes, long maxMb) {
|
public static byte[] convert(byte[] docBytes, long maxMb) {
|
||||||
long maxPixels = WordPdfValidator.maxImagePixels(maxMb);
|
long maxPixels = WordPdfValidator.maxImagePixels(maxMb);
|
||||||
@@ -226,7 +227,8 @@ public final class DocToDocx {
|
|||||||
* Нижняя оценка числа страниц бинарного .doc (кэш PageCount + явные
|
* Нижняя оценка числа страниц бинарного .doc (кэш PageCount + явные
|
||||||
* разрывы) — для {@code WordPdfValidator.checkPageCountDoc}.
|
* разрывы) — для {@code WordPdfValidator.checkPageCountDoc}.
|
||||||
*
|
*
|
||||||
* @throws ConversionException на некорректном/зашифрованном/чужом входе
|
* @throws ru.pjandro.wordpdf.ConversionException
|
||||||
|
* на некорректном/зашифрованном/чужом входе
|
||||||
*/
|
*/
|
||||||
public static int countPages(byte[] docBytes) {
|
public static int countPages(byte[] docBytes) {
|
||||||
return DocFile.open(docBytes).countPages();
|
return DocFile.open(docBytes).countPages();
|
||||||
|
|||||||
Reference in New Issue
Block a user