diff --git a/AGENTS.md b/AGENTS.md index 2d29437..b77219e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,6 +76,7 @@ curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf podman-compose -f compose.dev.yml up -d --build --force-recreate # dev-стенд :9011, без ключа podman-compose up -d --build # prod-like стенд :9010 — fail-closed: нужен .env с WORDPDF_API_KEY (шаблон .env.example) ./mise.sh run prod-tests # pytest; обязателен WORDPDF_BASE_URL +./mise.sh run docs-install|docs-serve|docs-build|docs-javadoc|docs-deploy # сайт документации (MkDocs Material): venv+pip | preview :8000 | strict-сборка в site/ | javadoc core | публикация в ~/srv/wordpdf-docs (юнит wordpdf-docs.service, :9012) python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx # XSD (lxml) ``` diff --git a/README.md b/README.md index de4787a..2047411 100644 --- a/README.md +++ b/README.md @@ -6,22 +6,6 @@ идёт тем же конвейером. Шрифты упакованы в jar — конвертация не зависит от шрифтов, установленных в системе (работает «из коробки» на голом сервере). -## Возможности - -- Поддержка RU/EN: кириллица и латиница встраиваются в PDF (embedded-подмножества). -- Самодостаточность: TTF выгружаются из jar в временный каталог и регистрируются - в docx4j/FOP. -- Частые MS-шрифты подменяются метрически совместимыми open-source аналогами - (см. «Шрифты» ниже). -- Диаграммы и SmartArt растеризуются в PNG собственным Java2D-движком — без Word/LibreOffice. -- Бинарный `.doc` (Word 97–2003): текст, стили, таблицы, списки, колонтитуки, - картинки — собственный мост `internal/doc` без внешних зависимостей; - error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры - уже растры → вставляются картинками; EMF/WMF/PICT пропускаются с warn). -- OLE-внедрения вычищаются перед загрузкой; картинка-плейсхолдер из документа сохраняется. -- Клиентская библиотека (`wordpdf-core`), REST API (`wordpdf-app`, Spring Boot) - и веб-интерфейс (`wordpdf-web`, React SPA). - ## Структура ``` @@ -31,330 +15,56 @@ java-word-pdf/ └── wordpdf-web/ веб-интерфейс (React + TypeScript + Vite + Tailwind, вне Maven) ``` -Ключевые классы (`wordpdf-core`): +## Быстрый старт -|Класс|Назначение| -|---|---| -|`ru.pjandro.wordpdf.WordPdfConverter`|публичный API: `convert(byte[], String, ConvertOptions)` — .docx/.doc по сигнатуре байтов, байты PDF на выходе; `warmup()` — прогрев ядра| -|`ru.pjandro.wordpdf.WordPdfValidator`|валидация входа и lightweight-оценка страниц без рендера (`checkInput`/`validate`; подсчёт страниц — внутренний метод)| -|`ru.pjandro.wordpdf.ConvertOptions`|опции конвертации (record `errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages`); дефолтов в ядре нет — значения задаёт вызывающий| -|`ru.pjandro.wordpdf.ConversionException`|ошибки конвертации; подтипы `ValidationException` (некорректный вход) и `ChartsFoundException`/`SmartArtFoundException`/`OleFoundException` (по error-флагам)| -|`ru.pjandro.wordpdf.fonts.BundledFonts`|выгрузка TTF из jar и регистрация в docx4j| -|`ru.pjandro.wordpdf.fonts.BundledFontMapper`|маппинг имён шрифтов документа → TTF| -|`ru.pjandro.wordpdf.internal.DocxRewritePipeline`|правила 1–10 нормализации XML-частей одним zip-проходом (+ `OleObjectNormalizer`, правило 11)| -|`ru.pjandro.wordpdf.internal.doc.DocToDocx`|мост бинарного `.doc` → in-memory `.docx` (`convert`/`countPages`)| -|`ru.pjandro.wordpdf.internal.FopFallbackFonts`|декларация fallback-семейства в FOP-конфиге| -|`ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer`|диаграммы/SmartArt → PNG до XSL-FO| - -## Инструменты проекта (mise) - -Java, Maven, Node и Python для разработки ставит project-local mise: сам бинарь — -в `./.mise/bin` (gitignored), кеш инструментов — в user-директории mise, в систему -ничего не устанавливается. Версии зафиксированы в корневом `mise.toml` -(temurin-17, maven 3.9.16, node 24, python 3.15). - -Первая настройка — скачивает mise, ставит инструменты и делает `npm ci` SPA: +Первая настройка — project-local mise (ставит temurin-17, maven 3.9.16, node 24, +python 3.15 в кеш mise, в систему ничего не идёт) + `npm ci` SPA: ```bash sh bootstrap.sh # Linux / macOS -``` - -```powershell powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows ``` -Дальше команды — через обёртку `./mise.sh` (Linux/macOS) или `.\mise.ps1` (Windows): +Дальше всё через обёртку `./mise.sh` (Windows: `.\mise.ps1`): ```bash -./mise.sh run verify # полный гейт перед push: тесты + PMD + JaCoCo -./mise.sh exec -- mvn -v # любая команда с инструментами проекта в PATH -./mise.sh tasks # список задач с описаниями +./mise.sh run verify # полный гейт перед push: тесты + PMD + JaCoCo +./mise.sh run app-package && ./mise.sh run app-run # бэкенд на :8080, ключ выключен +curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf ``` -Задачи проекта (`./mise.sh run <задача>`): +Стенды на контейнерах (podman), наружный вход — только nginx-gateway: + +```bash +cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32 +podman-compose up -d --build # prod-like :9010 (fail-closed: без ключа не встанет) +podman-compose -f compose.dev.yml up -d --build --force-recreate # dev :9011, без ключа +``` + +## Задачи проекта (`./mise.sh run <задача>`) |Задача|Содержание| |---|---| |`verify`|`mvn clean verify` — тесты + PMD + JaCoCo| -|`verify-nofontconfig`|`mvn clean verify` в контейнере без fontconfig (гейт CI; требует podman/docker)| -|`app-package`|исполняемый jar бэкенда| -|`app-run`|бэкенд на :8080, ключ выключен (после `app-package`)| -|`web-install`|`npm ci` в `wordpdf-web`| -|`web-build`|гейт SPA: `tsc -b && vite build`| -|`web-lint`|oxlint| -|`web-dev`|SPA на :5173, vite-proxy на :8080| +|`verify-nofontconfig`|тот же verify в контейнере без fontconfig (гейт CI; требует podman/docker)| +|`mem-bench`|замер памяти конвейера (TSV пиков + JFR)| +|`app-package` / `app-run`|исполняемый jar бэкенда / бэкенд на :8080| +|`web-install` / `web-build` / `web-lint` / `web-dev`|SPA: `npm ci` / гейт `tsc -b && vite build` / oxlint / :5173| |`prod-tests`|прод-автотесты; обязателен `WORDPDF_BASE_URL`, факультативно `WORDPDF_API_KEY`| +|`docs-install` / `docs-serve` / `docs-build`|сайт документации: venv+pip / preview :8000 / strict-сборка в `site/`| +|`docs-javadoc` / `docs-deploy`|javadoc core / публикация сайта на rpi (:9012)| Альтернатива обёртке — активировать mise в шелле и работать напрямую (`mvn`, `npm`, `python`): `eval "$(./.mise/bin/mise activate bash)"`. -## Сборка +## Документация -Требуется **Java 17** и **Maven** (бэкенд), **Node.js `^20.19.0 || >=22.12.0`** -(engines Vite 8; mise ставит Node 24) — всё это ставит project-local mise -(см. «Инструменты проекта (mise)» выше). Команды ниже запускайте через -`./mise.sh exec -- …` (Windows: `.\mise.ps1 exec -- …`) либо после активации mise в шелле. - -```bash -mvn clean verify # все модули + тесты -mvn -pl wordpdf-app -am package # исполняемый jar бэкенда -``` - -Результат: `wordpdf-app/target/wordpdf-app-<версия>.jar` (все зависимости -внутри). Для фронтенда — отдельные команды (вне Maven): `npm ci && npm run build` -в `wordpdf-web/` — по закоммиченному `package-lock.json` (то же делают задачи -mise `web-install`/`web-build`; результат — статика в `wordpdf-web/dist/`). - -## Использование - -### REST API - -```bash -java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar -curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \ - http://localhost:8080/api/v1/convert -o doc.pdf -``` - -`POST /api/v1/convert` принимает multipart-поле `file` (.docx или .doc) и синхронно -возвращает байты PDF (`application/pdf`, `Content-Disposition: attachment; -filename*=UTF-8''…` — имя файла санитизировано, кириллица разрешена). - -**Ключ доступа.** Заголовок `X-API-Key` сверяется со свойством `wordpdf.api-key` -(env `WORDPDF_API_KEY`); пустое свойство — аутентификация выключена (`java -jar`, -dev-стенд). Без ключа открыты `/actuator/`, `/swagger-ui`, `/v3/api-docs`; без ключа -или с неверным — 401 `{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}`. - -**Факультативные query/form-параметры** `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` -(Boolean, дефолт `false`): при `true` соответствующие объекты в документе отменяют -конвертацию с 422. Диаграммы/SmartArt конвертируются в растры всегда; OLE-объекты -при `errorOnOle=false` тихо удаляются. - -**Лимиты входа**: свойства `wordpdf.max-mb`/`wordpdf.max-pages` -(env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`, дефолты 5 МБ / 100 страниц) — -дефолт эндпоинта; query/form-параметры `maxMb`/`maxPages` переопределяют его -в обе стороны (значения ≤ 0 → 400). Остальные пороги (распаковка архива, -XML-части, площади растров, число записей zip) выводятся из лимитов входа. - -|Код|Смысл| -|---|---| -|200|PDF в теле ответа| -|400|некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше лимита размера (`maxMb` или `wordpdf.max-mb`) / больше лимита страниц (`maxPages` или `wordpdf.max-pages`) / `maxMb`≤0 / `maxPages`≤0), отсутствующая часть `file`, некорректное значение error-флага| -|401|нет или неверен `X-API-Key`| -|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)| -|405|не-POST| -|413|тело запроса больше контейнерного лимита multipart (100 МБ; авторитетный лимит входа — `wordpdf.max-mb`, он даёт 400 раньше)| -|415|не-multipart тело| -|422|сработал error-флаг: в документе найдены диаграммы / SmartArt / OLE-объекты| -|500|ошибка ядра/рендера| -|503|очередь конвертации (16 мест) переполнена — повторить позже| -|504|конвертация дольше `wordpdf.convert-timeout` (по умолчанию 2m)| - -Ошибки — JSON `{"error": "..."}`. Конвертации сериализуются одним воркером: ядро -мутирует глобальный реестр шрифтов; головой очереди на старте стоит `warmup()` — -первый запрос после деплоя идёт за прогретым ядром (~0,1–0,4 с вместо 1,4–1,9 с). -Интерактивная документация: Swagger UI — -`/swagger-ui.html`, OpenAPI — `/v3/api-docs` (доступны на `java -jar` и dev-стенде; -в compose-стеке springdoc выключён: `SPRINGDOC_API_DOCS_ENABLED=false`, -`SPRINGDOC_SWAGGER_UI_ENABLED=false`). - -### Библиотека - -```java -import ru.pjandro.wordpdf.WordPdfConverter; -import ru.pjandro.wordpdf.ConvertOptions; -import java.nio.file.Files; -import java.nio.file.Path; - -byte[] docx = Files.readAllBytes(Path.of("doc.docx")); -byte[] pdf = WordPdfConverter.convert(docx, "doc"); // заголовок PDF -// с опциями: errorOnCharts/errorOnSmartArt/errorOnOle, лимиты МБ/страниц -pdf = WordPdfConverter.convert(docx, "doc", new ConvertOptions(true, false, false, 5, 100)); -Files.write(Path.of("out.pdf"), pdf); -``` - -Ошибки валидации (содержимое не `.docx`/не `.doc` по сигнатуре, размер больше -5 МБ, страниц больше ста, зашифрованный `.doc`) бросают `ValidationException` -(подтип `ConversionException`). Формат определяется по сигнатуре байтов: -`PK\x03\x04` → .docx-путь, CFB-подпись `D0 CF 11 E0 A1 B1 1A E1` → мост → тот же -конвейер. Те же проверки без рендера доступны отдельно: -`WordPdfValidator.validate(bytes, options)`. -Работа с файлами — забота вызывающего: ядро пути не принимает. - -#### Зависимость commons-compress (интеграция в чужой проект) - -Ядру (через docx4j) нужен `org.apache.commons:commons-compress >= 1.25.0`, -рекомендована `1.28.0` — версию закрепляет POM ядра. Симптом старой версии в -classpath потребителя — `NoSuchMethodError: -org.apache.commons.compress.archivers.zip.ZipArchiveEntry -org.apache.commons.compress.archivers.zip.ZipArchiveInputStream.getNextEntry()`. -До входа в docx4j теперь срабатывает guard: `ConversionException` с текстом, -объясняющим, какую версию закрепить. - -**Maven.** BOM (например, Spring Boot 3.x) пинит свою версию commons-compress, -а `dependencyManagement` потребителя перекрывает транзитивные версии -(«nearest wins») — закреплять нужно именно в нём: - -```xml - - - - org.apache.commons - commons-compress - 1.28.0 - - - -``` - -Диагностика: `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://:9011 -``` - -(`--force-recreate` обязателен: без него podman-compose пересоберёт образ, но -контейнеры оставит на старом — будет крутиться jar прошлой сборки) - -Dev-режим без контейнеров: бэкенд `java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar` -(порт 8080, ключ выключен) + `npm run dev` в `wordpdf-web/` → `http://localhost:5173` -(Vite проксирует `/api`, `/swagger-ui`, `/v3/api-docs` на 8080, CORS не нужен). - -## Шрифты - -В `wordpdf-core/src/main/resources/fonts/` упакованы 30 TTF: 7 текстовых -семейств по 4 начертания плюс два покрывающих шрифта (только regular): - -| Семейство | Аналог MS-шрифта | -|---|---| -| Carlito | Calibri | -| Caladea | Cambria | -| Arimo | Arial | -| Tinos | Times New Roman | -| Cousine | Courier New | -| DejaVu Sans / DejaVu Serif | fallback | -| Noto Naskh Arabic | арабские дополнения U+07B1–U+08FF | -| Noto Sans Armenian | армянские знаки Unicode 16 | - -`BundledFontMapper` подставляет метрически совместимые аналоги при конвертации -(`Calibri → Carlito` и т.д.). Нераспознанные шрифты и символы, не найденные в -шрифте ранa (em-dash «—», кавычки, U+2000–U+2EFF), падают в **DejaVu Sans** -(гарантированная кириллица). Знак, которого нет ни в шрифте ранa, ни там, куда -его отправил docx4j, ищет себе место сам: `GlyphCoverageNormalizer` режет такой -ран и для каждой части назначает покрывающее семейство — serif-раны в -**DejaVu Serif**, sans — в **DejaVu Sans**, экзотика — в Noto. Все шрифты -встраиваются в PDF как подмножества. - -### Лицензии шрифтов - -- Arimo, Cousine, Tinos, Carlito, Caladea — **SIL OFL 1.1** - (см. `fonts/FONT-LICENSE.txt`). -- DejaVu Sans / DejaVu Serif — **SIL OFL 1.1 / Bitstream Vera** - (см. `fonts/DejaVu-LICENSE.txt`). -- Noto Naskh Arabic, Noto Sans Armenian — **SIL OFL 1.1** - (см. `fonts/Noto-LICENSE.txt`). - -## Как это работает - -``` -.docx/.doc ──> валидация входа ──> (.doc: мост → .docx в памяти) - ──> нормализация байтов ──> docx4j (WordprocessingMLPackage) - ──> диаграммы → PNG ──> XSL-FO (вендорный XSLT) ──> Apache FOP ──> PDF (embedded-шрифты) -``` - -1. Вход проверяется до рендера: размер → сигнатура (zip PK или CFB) → (.docx: - контейнер и страницы lightweight-StAX по zip; .doc: страницы по чистому - бинарному документу мостом) — `WordPdfValidator`, без зависимости от docx4j. -2. XML-части переписывает `DocxRewritePipeline` одним zip-проходом — десять - правил (порядок значим): strict→transitional (`w:start`/`w:end`, проценты), - `on/off` → `true/false` (иначе docx4j теряет значение, и regular-раны - рендерились жирным курсивом), маркеры Symbol/Wingdings → Unicode (вместо «#»), - поля `PAGE`/`NUMPAGES` → `w:fldSimple` (пересчитываются, а не печатают кэш - из docx), невидимые символы, раны со знаками вне их шрифта (резка по покрытию - глифов), `w:jc` center/right + `w:tblInd` → абсолютный отступ таблицы, - `w:suff="space"` → пробел в номере списка, скрытые раны (`w:vanish`), руби - (надстрочница вырезается). Затем вычищаются OLE-объекты (правило 11, - `OleObjectNormalizer`, картинка-плейсхолдер сохраняется). -3. Документ загружается в `WordprocessingMLPackage`, привязывается - `BundledFontMapper`. -4. Диаграммы и SmartArt предварительно растеризуются в PNG 300 dpi - (`DrawingPreRenderer`) — XSLT-экспорт docx4j их не умеет. -5. Экспорт в XSL-FO идёт вендорным стилем `xslt/docx2fo.xslt` (копия стилиста - docx4j-export-fo с AUDIT-FIX-патчами: `w:position` → `baseline-shift`, - `w:moveFrom`/`w:moveTo`/`w:bdo`/`w:dir`), перед рендером `LayoutPostRenderer` - компенсирует расхождение docx4j↔Word по padding таблиц; `Apache FOP` - (форк `docx4j-fo-renderer`) рендерит PDF, встраивая подмножества шрифтов. - -## Ограничения - -- Это **не** pixel-perfect рендер Word: раскладка, поля и некоторые эффекты - приближённые (ограничения FOP/docx4j, а не «мы что-то упустили»). -- Символы U+2000–U+2EFF (em-dash и т.п.) берутся из шрифта ранa, если в нём - есть глиф, иначе — из fallback-семейства DejaVu. -- Знаков, которых нет ни в одном шрифте бандла, это не касается: вместо них - остаётся `.notdef`. В эталонном экспорте Word (`develop/`, вне git) таких два — U+2188 (ↈ) - и U+218A (↊), они есть только в GNU FreeSerif под GPL, а бандл держится - целиком на SIL OFL. -- Поддержка таблиц/изображений — базовая (через docx4j/FOP). -- Часть расхождений с Word — неустранимые невозможности FOP/docx4j - (`jc="distribute"`, `suff="tab"`, кернинг, `framePr`, кэш `REF`/`SEQ`/`TOC`, - надстрочница руби) — полный перечень с доказательствами: - `docs/agent/render-limitations.md`. -- На `.doc` error-флаги диаграмм/SmartArt/OLE не срабатывают: BLIP-плейсхолдеры - бинарного формата — уже растры, они вставляются картинками; EMF/WMF/PICT - пропускаются с warn. - -## Тесты - -Тесты используют 25 закоммиченных фикстур (13 `.docx` + 12 `.doc`) из -`wordpdf-core/src/test/resources/samples/` (в тестах не генерируются; пересоздание — -test-утилита `SampleDocxGenerator`) и проверяют извлечённый PDFBox'ом текст и -встраивание шрифтов. Запуск: `mvn test`; полный гейт перед push — -`./mise.sh run verify` (тесты + PMD + JaCoCo). - -API (`wordpdf-app`) проверяется `MockMvc`-сквозняками (`ConvertControllerTest`) -на тех же фикстурах — ядро отдаёт их test-jar'ом. - -## CI/CD и деплой - -- Pull request → Gitea Actions (`pr.yml`): Java — единственный `mvn clean verify` в контейнере без fontconfig + сводка покрытия комментарием в PR; Web — `npm ci`, build, lint. -- Push в `main` → `main.yml`: тесты → сборка и push образов `wordpdf-app`/`wordpdf-web` в реестр → deploy (job рендерит прод-конфиги, `podman-compose pull && up -d --force-recreate`, health-гейты, автооткат при провале) → prod-автотесты против живого стенда. -- Координаты прод-сервера и креды вне репозитория — Gitea Actions Variables/Secrets (настройка: `GITEA-vars.md`). Наружный вход стенда — путь `/pdf-converter/` за пользовательским nginx. -- Локальный прогон prod-автотестов (задача `prod-tests`: `pip install` - зависимостей + `pytest -q .` в `prod-autotests/`): - -```bash -WORDPDF_BASE_URL=<стенд> WORDPDF_API_KEY=<ключ> ./mise.sh run prod-tests -``` - -31 проверка; без ключа 27 требующих его пропускаются. +- **Сайт документации** (пользователю / REST API / библиотека / архитектура / + разработчику / эксплуатация): `http://192.168.88.23:9012/` + — исходники в `docs/`, публикация `./mise.sh run docs-deploy`, + javadoc — там же по `/apidocs/`. +- Веб-конвертер (прод): `https://pjandro.ru/pdf-converter/`. +- Внутренние справочники для правки кода — `docs/agent/` (pipeline, doc-bridge, + chart, render-limitations, testing, ci-cd, repo-map), нормативные спецификации + форматов — `docs/standards/`. +- Правила репозитория — `AGENTS.md`.