docs: полная синхронизация документации с кодом
PR checks / web (pull_request) Successful in 31s
PR checks / java (pull_request) Successful in 59s
Main: tests, deploy, autotests / web (push) Successful in 30s
Main: tests, deploy, autotests / java (push) Successful in 57s
Main: tests, deploy, autotests / images-web (push) Successful in 30s
Main: tests, deploy, autotests / images-app (push) Successful in 40s
Main: tests, deploy, autotests / deploy (push) Successful in 1m30s
Main: tests, deploy, autotests / autotests (push) Successful in 41s
Main: tests, deploy, autotests / rollback (push) Has been skipped
PR checks / web (pull_request) Successful in 31s
PR checks / java (pull_request) Successful in 59s
Main: tests, deploy, autotests / web (push) Successful in 30s
Main: tests, deploy, autotests / java (push) Successful in 57s
Main: tests, deploy, autotests / images-web (push) Successful in 30s
Main: tests, deploy, autotests / images-app (push) Successful in 40s
Main: tests, deploy, autotests / deploy (push) Successful in 1m30s
Main: tests, deploy, autotests / autotests (push) Successful in 41s
Main: tests, deploy, autotests / rollback (push) Has been skipped
README: X-API-Key/401, полная таблица статусов, gateway-топология :9010/:9011, лимиты 100 МБ multipart и конфигурируемые wordpdf.max-mb/max-pages, пайплайн из 7 правил DocxRewritePipeline + OLE, ConvertOptions/WordPdfValidator, секция CI/CD. AGENTS.md: заголовок диаграммы по ECMA (autoTitleDeleted, §21.2.2.7), потолок растра MAX_PIXELS/fitDpi, стриминговый checkPageCount, 535 @Test (core 493), регрессии ChartSpecTest, сноска «README устарел» удалена. GITEA-vars.md: падающие job'ы — images-app/images-web первыми. wordpdf-web: охват vite-прокси, комментарий VITE_BASE (печёт CI-job images-web).
This commit was merged in pull request #67.
This commit is contained in:
@@ -11,6 +11,8 @@ LibreOffice/Aspose. Шрифты упакованы в jar — конверта
|
||||
в docx4j/FOP.
|
||||
- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами
|
||||
(см. «Шрифты» ниже).
|
||||
- Диаграммы и SmartArt растеризуются в PNG собственным Java2D-движком — без Word/LibreOffice.
|
||||
- OLE-внедрения вычищаются перед загрузкой; картинка-плейсхолдер из документа сохраняется.
|
||||
- Клиентская библиотека (`wordpdf-core`), REST API (`wordpdf-app`, Spring Boot)
|
||||
и веб-интерфейс (`wordpdf-web`, React SPA).
|
||||
|
||||
@@ -25,14 +27,17 @@ java-word-pdf/
|
||||
|
||||
Ключевые классы (`wordpdf-core`):
|
||||
|
||||
| Класс | Назначение |
|
||||
|Класс|Назначение|
|
||||
|---|---|
|
||||
| `ru.pjandro.wordpdf.WordPdfConverter` | публичный API: `convert(byte[], String)` — байты на входе, байты PDF на выходе |
|
||||
| `ru.pjandro.wordpdf.ConversionException` | исключение конвертации |
|
||||
| `ru.pjandro.wordpdf.fonts.BundledFonts` | выгрузка TTF из jar и регистрация в docx4j |
|
||||
| `ru.pjandro.wordpdf.fonts.BundledFontMapper` | маппинг имён шрифтов документа → TTF |
|
||||
| `ru.pjandro.wordpdf.internal.DocxOnOffNormalizer` | нормализация `w:val="off"/"on"` перед загрузкой |
|
||||
| `ru.pjandro.wordpdf.internal.FopFallbackFonts` | декларация fallback-семейства в FOP-конфиге |
|
||||
|`ru.pjandro.wordpdf.WordPdfConverter`|публичный API: `convert(byte[], String[, ConvertOptions])` — байты на входе, байты PDF на выходе|
|
||||
|`ru.pjandro.wordpdf.WordPdfValidator`|валидация входа и lightweight-оценка страниц по zip без рендера (`checkInput`/`checkPageCount`/`validate`)|
|
||||
|`ru.pjandro.wordpdf.ConvertOptions`|опции конвертации (record `errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages`; `ConvertOptions.defaults()`)|
|
||||
|`ru.pjandro.wordpdf.ConversionException`|ошибки конвертации; подтипы `ValidationException` (некорректный вход) и `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}`)|
|
||||
|`ru.pjandro.wordpdf.fonts.BundledFonts`|выгрузка TTF из jar и регистрация в docx4j|
|
||||
|`ru.pjandro.wordpdf.fonts.BundledFontMapper`|маппинг имён шрифтов документа → TTF|
|
||||
|`ru.pjandro.wordpdf.internal.DocxRewritePipeline`|семь правил нормализации XML-частей одним zip-проходом|
|
||||
|`ru.pjandro.wordpdf.internal.FopFallbackFonts`|декларация fallback-семейства в FOP-конфиге|
|
||||
|`ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer`|диаграммы/SmartArt → PNG до XSL-FO|
|
||||
|
||||
## Инструменты проекта (mise)
|
||||
|
||||
@@ -77,10 +82,10 @@ powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
|
||||
|
||||
## Сборка
|
||||
|
||||
Требуется **Java 17** и **Maven** (бэкенд), **Node.js ≥ 20.19** (веб-интерфейс) — всё
|
||||
это ставит project-local mise (см. «Инструменты проекта (mise)» выше). Команды ниже
|
||||
запускайте через `./mise.sh exec -- …` (Windows: `.\mise.ps1 exec -- …`) либо после
|
||||
активации mise в шелле.
|
||||
Требуется **Java 17** и **Maven** (бэкенд), **Node.js `^20.19.0 || >=22.12.0`**
|
||||
(engines Vite 8; mise ставит Node 24) — всё это ставит project-local mise
|
||||
(см. «Инструменты проекта (mise)» выше). Команды ниже запускайте через
|
||||
`./mise.sh exec -- …` (Windows: `.\mise.ps1 exec -- …`) либо после активации mise в шелле.
|
||||
|
||||
```bash
|
||||
mvn clean verify # все модули + тесты
|
||||
@@ -97,38 +102,67 @@ mvn -pl wordpdf-app -am package # исполняемый jar бэкенд
|
||||
|
||||
```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
|
||||
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) и синхронно
|
||||
возвращает байты PDF (`application/pdf`, attachment).
|
||||
возвращает байты PDF (`application/pdf`, `Content-Disposition: attachment;
|
||||
filename*=UTF-8''…` — имя файла санитизировано, кириллица разрешена).
|
||||
|
||||
**Ключ доступа.** Заголовок `X-API-Key` сверяется со свойством `wordpdf.api-key`
|
||||
(env `WORDPDF_API_KEY`); пустое свойство — аутентификация выключена (`java -jar`,
|
||||
dev-стенд). Без ключа открыты `/actuator/`, `/swagger-ui`, `/v3/api-docs`; без ключа
|
||||
или с неверным — 401 `{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}`.
|
||||
|
||||
**Факультативные query/form-параметры** `errorOnCharts`/`errorOnSmartArt`/`errorOnOle`
|
||||
(Boolean, дефолт `false`): при `true` соответствующие объекты в документе отменяют
|
||||
конвертацию с 422. Диаграммы/SmartArt конвертируются в растры всегда; OLE-объекты
|
||||
при `errorOnOle=false` тихо удаляются.
|
||||
|
||||
**Лимиты входа** задаёт только конфигурация сервера: `wordpdf.max-mb`/`wordpdf.max-pages`
|
||||
(env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`, дефолты 5 МБ / 100 страниц); параметрами
|
||||
запроса не переопределяются.
|
||||
|
||||
|Код|Смысл|
|
||||
|---|---|
|
||||
|200|PDF в теле ответа|
|
||||
|400|некорректный вход: не .docx / пустой / не zip / > 5 МБ / > 100 страниц|
|
||||
|413|тело запроса больше контейнерного лимита multipart (6 МБ)|
|
||||
|503|очередь конвертации занята — повторить позже|
|
||||
|504|конвертация дольше таймаута (`wordpdf.convert-timeout`, по умолчанию 2m)|
|
||||
|400|некорректный вход (не .docx / пустой / не zip / больше `wordpdf.max-mb` / больше `wordpdf.max-pages` страниц), отсутствующая часть `file`, некорректное значение error-флага|
|
||||
|401|нет или неверен `X-API-Key`|
|
||||
|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)|
|
||||
|405|не-POST|
|
||||
|413|тело запроса больше контейнерного лимита multipart (100 МБ; авторитетный лимит входа — `wordpdf.max-mb`, он даёт 400 раньше)|
|
||||
|415|не-multipart тело|
|
||||
|422|сработал error-флаг: в документе найдены диаграммы / SmartArt / OLE-объекты|
|
||||
|500|ошибка ядра/рендера|
|
||||
|503|очередь конвертации (16 мест) переполнена — повторить позже|
|
||||
|504|конвертация дольше `wordpdf.convert-timeout` (по умолчанию 2m)|
|
||||
|
||||
Ошибки — JSON `{"error": "..."}`. Интерактивная документация:
|
||||
Swagger UI — `/swagger-ui.html`, OpenAPI — `/v3/api-docs`.
|
||||
Ошибки — JSON `{"error": "..."}`. Конвертации сериализуются одним воркером: ядро
|
||||
мутирует глобальный реестр шрифтов. Интерактивная документация: 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` по содержимому, размер больше 5 МБ, страниц
|
||||
больше ста) бросают `ConversionException`. Работа с файлами — забота
|
||||
вызывающего: ядро пути не принимает.
|
||||
больше ста) бросают `ValidationException` (подтип `ConversionException`). Те же
|
||||
проверки без рендера доступны отдельно: `WordPdfValidator.validate(bytes, options)`.
|
||||
Работа с файлами — забота вызывающего: ядро пути не принимает.
|
||||
|
||||
#### Зависимость commons-compress (интеграция в чужой проект)
|
||||
|
||||
@@ -177,16 +211,25 @@ dependencies {
|
||||
### Веб-интерфейс и контейнеры (podman)
|
||||
|
||||
```bash
|
||||
cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32
|
||||
podman-compose up -d --build
|
||||
```
|
||||
|
||||
Всё на `http://localhost:8080/`: nginx-контейнер `web` раздаёт SPA и проксирует
|
||||
`/api`, `/swagger-ui`, `/v3/api-docs` на бэкенд (контейнер `app` наружу не
|
||||
публикуется).
|
||||
Наружный вход — 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 # http://<LAN-IP>:9011
|
||||
```
|
||||
|
||||
Dev-режим без контейнеров: бэкенд `java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar`
|
||||
(порт 8080) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173`
|
||||
(Vite проксирует `/api` на 8080, CORS не нужен).
|
||||
(порт 8080, ключ выключен) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173`
|
||||
(Vite проксирует `/api`, `/swagger-ui`, `/v3/api-docs` на 8080, CORS не нужен).
|
||||
|
||||
## Шрифты
|
||||
|
||||
@@ -225,20 +268,24 @@ Dev-режим без контейнеров: бэкенд `java -jar wordpdf-ap
|
||||
## Как это работает
|
||||
|
||||
```
|
||||
docx ──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
|
||||
──> XSL-FO (XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
|
||||
docx ──> валидация входа ──> нормализация байтов ──> docx4j (WordprocessingMLPackage)
|
||||
──> диаграммы → PNG ──> XSL-FO (XSLT) ──> Apache FOP ──> PDF (embedded-шрифты)
|
||||
```
|
||||
|
||||
1. Байты `.docx` нормализуются, пока docx4j не увидел документ:
|
||||
`DocxOnOffNormalizer` (docx4j теряет `w:val="off"/"on"` при JAXB-разборе,
|
||||
из-за чего regular-раны могли рендериться жирным курсивом),
|
||||
`SymbolFontNormalizer` (маркеры из Symbol/Wingdings вместо «#») и
|
||||
`FieldNormalizer` (поля `PAGE`/`NUMPAGES` пересчитываются, а не печатают
|
||||
кэш из docx) и `GlyphCoverageNormalizer` (раны со знаками вне их шрифта).
|
||||
2. Документ загружается в `WordprocessingMLPackage`, привязывается
|
||||
`BundledFontMapper`, диаграммы и SmartArt предварительно растеризуются
|
||||
в PNG (`DrawingPreRenderer`).
|
||||
3. Экспорт в XSL-FO (XSLT-проход + `WordLayoutFixups`), затем `Apache FOP`
|
||||
1. Вход проверяется до рендера: размер → zip-подпись → контейнер → число страниц
|
||||
(`WordPdfValidator`, lightweight StAX-оценка по zip без зависимости от 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), невидимые символы,
|
||||
раны со знаками вне их шрифта. Затем вычищаются OLE-объекты
|
||||
(`OleObjectNormalizer`, картинка-плейсхолдер сохраняется).
|
||||
3. Документ загружается в `WordprocessingMLPackage`, привязывается
|
||||
`BundledFontMapper`.
|
||||
4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi
|
||||
(`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет.
|
||||
5. Экспорт в XSL-FO (XSLT-проход + `WordLayoutFixups`), затем `Apache FOP`
|
||||
рендерит PDF, встраивая используемые подмножества шрифтов.
|
||||
|
||||
## Ограничения
|
||||
@@ -255,9 +302,24 @@ docx ──> нормализация байтов ──> docx4j (Wordprocessin
|
||||
|
||||
## Тесты
|
||||
|
||||
Тесты используют готовые `.docx` из `wordpdf-core/src/test/resources/samples/`
|
||||
(генерируются POI) и проверяют извлечённый PDFBox'ом текст и встраивание
|
||||
шрифтов. Запуск: `mvn test`.
|
||||
Тесты используют 13 закоммиченных `.docx`-фикстур из
|
||||
`wordpdf-core/src/test/resources/samples/` (в тестах не генерируются; пересоздание —
|
||||
test-утилита `SampleDocxGenerator`) и проверяют извлечённый PDFBox'ом текст и
|
||||
встраивание шрифтов. Запуск: `mvn test`; полный гейт перед push —
|
||||
`./mise.sh run verify` (тесты + PMD + JaCoCo).
|
||||
|
||||
API (`wordpdf-app`) проверяется `MockMvc`-сквозняками (`ConvertControllerTest`)
|
||||
на тех же фикстурах — ядро отдаёт их test-jar'ом.
|
||||
|
||||
## CI/CD и деплой
|
||||
|
||||
- Pull request → Gitea Actions (`pr.yml`): Java — `mvn clean verify` + сводка покрытия комментарием в PR; Web — `npm ci`, build, lint.
|
||||
- Push в `main` → `main.yml`: тесты → сборка и push образов `wordpdf-app`/`wordpdf-web` в реестр → deploy (job рендерит прод-конфиги, `podman-compose pull && up -d --force-recreate`, health-гейты, автооткат при провале) → prod-автотесты против живого стенда.
|
||||
- Координаты прод-сервера и креды вне репозитория — Gitea Actions Variables/Secrets (настройка: `GITEA-vars.md`). Наружный вход стенда — путь `/pdf-converter/` за пользовательским nginx.
|
||||
- Локальный прогон prod-автотестов (из `prod-autotests/`):
|
||||
|
||||
```bash
|
||||
WORDPDF_BASE_URL=<стенд> WORDPDF_API_KEY=<ключ> mise exec -- python -m pytest -q .
|
||||
```
|
||||
|
||||
21 проверка; без ключа 17 требующих его пропускаются.
|
||||
|
||||
Reference in New Issue
Block a user