From b3511f8b74b2af1d1048deb9b7ded08caeab6a59 Mon Sep 17 00:00:00 2001 From: Pjandro Date: Sun, 22 Nov 2026 21:39:08 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=81=D0=B0=D0=B9=D1=82=20=D0=B4=D0=BE?= =?UTF-8?q?=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=B0=D1=86=D0=B8=D0=B8=20?= =?UTF-8?q?=D0=BD=D0=B0=20MkDocs=20Material?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored). --- docs/api/authentication.md | 52 ++++++++++++++++++ docs/api/convert-endpoint.md | 45 +++++++++++++++ docs/api/errors.md | 55 +++++++++++++++++++ docs/api/examples.md | 74 +++++++++++++++++++++++++ docs/api/index.md | 53 ++++++++++++++++++ docs/api/limits.md | 47 ++++++++++++++++ docs/architecture/charts.md | 62 +++++++++++++++++++++ docs/architecture/doc-bridge.md | 61 +++++++++++++++++++++ docs/architecture/fonts.md | 63 +++++++++++++++++++++ docs/architecture/limitations.md | 40 ++++++++++++++ docs/architecture/overview.md | 68 +++++++++++++++++++++++ docs/development/contributing.md | 64 ++++++++++++++++++++++ docs/development/setup.md | 83 ++++++++++++++++++++++++++++ docs/development/testing.md | 71 ++++++++++++++++++++++++ docs/index.md | 64 ++++++++++++++++++++++ docs/internal-guides.md | 39 +++++++++++++ docs/library/api.md | 75 +++++++++++++++++++++++++ docs/library/dependencies.md | 66 ++++++++++++++++++++++ docs/library/getting-started.md | 72 ++++++++++++++++++++++++ docs/operations/configuration.md | 52 ++++++++++++++++++ docs/operations/deployment.md | 54 ++++++++++++++++++ docs/operations/docs-site.md | 88 ++++++++++++++++++++++++++++++ docs/operations/stack.md | 61 +++++++++++++++++++++ docs/operations/troubleshooting.md | 74 +++++++++++++++++++++++++ docs/requirements.txt | 1 + docs/user.md | 56 +++++++++++++++++++ mkdocs.yml | 76 ++++++++++++++++++++++++++ 27 files changed, 1616 insertions(+) create mode 100644 docs/api/authentication.md create mode 100644 docs/api/convert-endpoint.md create mode 100644 docs/api/errors.md create mode 100644 docs/api/examples.md create mode 100644 docs/api/index.md create mode 100644 docs/api/limits.md create mode 100644 docs/architecture/charts.md create mode 100644 docs/architecture/doc-bridge.md create mode 100644 docs/architecture/fonts.md create mode 100644 docs/architecture/limitations.md create mode 100644 docs/architecture/overview.md create mode 100644 docs/development/contributing.md create mode 100644 docs/development/setup.md create mode 100644 docs/development/testing.md create mode 100644 docs/index.md create mode 100644 docs/internal-guides.md create mode 100644 docs/library/api.md create mode 100644 docs/library/dependencies.md create mode 100644 docs/library/getting-started.md create mode 100644 docs/operations/configuration.md create mode 100644 docs/operations/deployment.md create mode 100644 docs/operations/docs-site.md create mode 100644 docs/operations/stack.md create mode 100644 docs/operations/troubleshooting.md create mode 100644 docs/requirements.txt create mode 100644 docs/user.md create mode 100644 mkdocs.yml diff --git a/docs/api/authentication.md b/docs/api/authentication.md new file mode 100644 index 0000000..c8c0804 --- /dev/null +++ b/docs/api/authentication.md @@ -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. diff --git a/docs/api/convert-endpoint.md b/docs/api/convert-endpoint.md new file mode 100644 index 0000000..cfb3c5c --- /dev/null +++ b/docs/api/convert-endpoint.md @@ -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). diff --git a/docs/api/errors.md b/docs/api/errors.md new file mode 100644 index 0000000..a9158d8 --- /dev/null +++ b/docs/api/errors.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: <имя>`, `Файл больше МБ: …`, +`Некорректное значение параметра «<имя>»`. + +!!! 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`| diff --git a/docs/api/examples.md b/docs/api/examples.md new file mode 100644 index 0000000..5a9c8e9 --- /dev/null +++ b/docs/api/examples.md @@ -0,0 +1,74 @@ +# Примеры клиентов + +Базовый адрес зависит от стенда: прод `https://pjandro.ru/pdf-converter/api/v1/convert`, +prod-like локально `http://localhost:9010/api/v1/convert`, dev `http://: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). diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..7c7931e --- /dev/null +++ b/docs/api/index.md @@ -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. Проверка размера входа +выполняется синхронно, до постановки в очередь. diff --git a/docs/api/limits.md b/docs/api/limits.md new file mode 100644 index 0000000..ddd063c --- /dev/null +++ b/docs/api/limits.md @@ -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 +мгновенно — текущая конвертация дожигается, следующий запрос ждёт её в очереди. diff --git a/docs/architecture/charts.md b/docs/architecture/charts.md new file mode 100644 index 0000000..bc60bcc --- /dev/null +++ b/docs/architecture/charts.md @@ -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). diff --git a/docs/architecture/doc-bridge.md b/docs/architecture/doc-bridge.md new file mode 100644 index 0000000..057dcc4 --- /dev/null +++ b/docs/architecture/doc-bridge.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). diff --git a/docs/architecture/fonts.md b/docs/architecture/fonts.md new file mode 100644 index 0000000..6489de7 --- /dev/null +++ b/docs/architecture/fonts.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`). diff --git a/docs/architecture/limitations.md b/docs/architecture/limitations.md new file mode 100644 index 0000000..e27ad66 --- /dev/null +++ b/docs/architecture/limitations.md @@ -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). diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md new file mode 100644 index 0000000..2e43d92 --- /dev/null +++ b/docs/architecture/overview.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). diff --git a/docs/development/contributing.md b/docs/development/contributing.md new file mode 100644 index 0000000..bb41386 --- /dev/null +++ b/docs/development/contributing.md @@ -0,0 +1,64 @@ +# Как контрибьютить + +## Ветка и PR + +Репозиторий: `git.pjandro.ru:pjandro/java-word-pdf`. Защищённые ветки — `main`, +`master`, `dev`: прямо в них не коммитим. + +1. Ветка от свежей `main` (`git switch -c `). +2. Коммиты логическими блоками. +3. Перед push — полный гейт: `./mise.sh run verify`. +4. `git push -u origin ` → 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). diff --git a/docs/development/setup.md b/docs/development/setup.md new file mode 100644 index 0000000..3b66329 --- /dev/null +++ b/docs/development/setup.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://:9011`), + а не `java -jar`. Готовность — контейнеры healthy (`podman-compose -f + compose.dev.yml ps`) + корень SPA отвечает 200. diff --git a/docs/development/testing.md b/docs/development/testing.md new file mode 100644 index 0000000..8f37e34 --- /dev/null +++ b/docs/development/testing.md @@ -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). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..2fdf14a --- /dev/null +++ b/docs/index.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) — для глубокой правки кода. diff --git a/docs/internal-guides.md b/docs/internal-guides.md new file mode 100644 index 0000000..4952f50 --- /dev/null +++ b/docs/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. diff --git a/docs/library/api.md b/docs/library/api.md new file mode 100644 index 0000000..700e62d --- /dev/null +++ b/docs/library/api.md @@ -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. diff --git a/docs/library/dependencies.md b/docs/library/dependencies.md new file mode 100644 index 0000000..214dc77 --- /dev/null +++ b/docs/library/dependencies.md @@ -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 + + + + org.apache.commons + commons-compress + 1.28.0 + + + +``` + +Диагностика: + +```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`|нет| diff --git a/docs/library/getting-started.md b/docs/library/getting-started.md new file mode 100644 index 0000000..54554c9 --- /dev/null +++ b/docs/library/getting-started.md @@ -0,0 +1,72 @@ +# wordpdf-core: первые шаги + +`wordpdf-core` — Java-библиотека конвертации `.docx`/`.doc` → PDF. Без LibreOffice, +без Aspose, без системных шрифтов: все TTF упакованы в jar. + +## Подключение + +```xml + + ru.pjandro + wordpdf-core + 1.0.0 + +``` + +Требуется **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` из транзитивных зависимостей. diff --git a/docs/operations/configuration.md b/docs/operations/configuration.md new file mode 100644 index 0000000..7279c49 --- /dev/null +++ b/docs/operations/configuration.md @@ -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). diff --git a/docs/operations/deployment.md b/docs/operations/deployment.md new file mode 100644 index 0000000..7d363a6 --- /dev/null +++ b/docs/operations/deployment.md @@ -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//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). diff --git a/docs/operations/docs-site.md b/docs/operations/docs-site.md new file mode 100644 index 0000000..daa4af8 --- /dev/null +++ b/docs/operations/docs-site.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 как статика. diff --git a/docs/operations/stack.md b/docs/operations/stack.md new file mode 100644 index 0000000..9ce45b5 --- /dev/null +++ b/docs/operations/stack.md @@ -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://: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| diff --git a/docs/operations/troubleshooting.md b/docs/operations/troubleshooting.md new file mode 100644 index 0000000..bc5f823 --- /dev/null +++ b/docs/operations/troubleshooting.md @@ -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) маршрутизируется по байтам — это +не ошибка. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..42f16a0 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +mkdocs-material==9.8.2 diff --git a/docs/user.md b/docs/user.md new file mode 100644 index 0000000..bf8cb3e --- /dev/null +++ b/docs/user.md @@ -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). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..8616d38 --- /dev/null +++ b/mkdocs.yml @@ -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