docs: сайт документации на MkDocs Material

- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
Pjandro
2026-11-22 21:39:08 +03:00
parent ae7c8b755a
commit b3511f8b74
27 changed files with 1616 additions and 0 deletions
+52
View File
@@ -0,0 +1,52 @@
# Аутентификация
## Ключ доступа
Все запросы, кроме открытых путей, требуют заголовок:
```
X-API-Key: <ключ>
```
Ключ сверяется со свойством сервера `wordpdf.api-key` (env `WORDPDF_API_KEY`).
Сравнение — `MessageDigest.isEqual` (защита от timing-атак). **Пустое свойство =
аутентификация выключена** — так работают `java -jar` и dev-стенд (:9011).
Без ключа или с неверным:
```
HTTP 401
{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}
```
## Открытые пути
Без ключа всегда доступны (матч по **префиксу со слэшем**, без учёта
forwarded-contextPath):
|Префикс|Что|
|---|---|
|`/actuator/`|health-checks Spring Boot|
|`/swagger-ui`|Swagger UI|
|`/v3/api-docs`|OpenAPI-спек|
!!! warning "Точечные сегменты обходят открытие"
Пути с точечными сегментами (`..` или их URL-код `%2e`) **никогда** не считаются
открытыми: запрос вида `/actuator/../api/v1/convert` потребует ключ даже на
открытом префиксе. Это защита от обхода фильтра через нормализацию пути.
## Где задаётся ключ
|Среда|Как|
|---|---|
|`java -jar`|`wordpdf.api-key=` пусто — auth выключен; включить: `--wordpdf.api-key=…` или env `WORDPDF_API_KEY`|
|prod-like стенд (:9010)|обязателен `.env` с `WORDPDF_API_KEY` (fail-closed: без него стек не поднимется), шаблон — `.env.example`|
|прод|env-переменная контейнера из Gitea Secret (в репозитории и на диске ключа нет)|
Сгенерировать ключ: `openssl rand -hex 32`.
## Как фронтенд узнаёт про ключ
SPA при старте опрашивает сервис (`probeApiKey()`, `GET /api/v1/convert`): 401 —
сервер требует ключ, показывается экран ввода; иначе — интерфейс открывается сразу.
Введённый ключ хранится в `localStorage` браузера и стирается при ответе 401.
+45
View File
@@ -0,0 +1,45 @@
# Эндпоинт конвертации
```
POST /api/v1/convert
```
Тело запроса — `multipart/form-data` с обязательным полем **`file`**: файл `.docx`
(OOXML) или `.doc` (Word 97–2003, переносится мостом в .docx в памяти). Файлы других
расширений отклоняются 400.
## Факультативные query/form-параметры
Параметры можно передать в query-строке или как form-поля.
|Параметр|Тип|Дефолт|Действие|
|---|---|---|---|
|`errorOnCharts`|Boolean|`false`|при `true` диаграммы в документе отменяют конвертацию (422); диаграммы конвертируются в растры всегда|
|`errorOnSmartArt`|Boolean|`false`|при `true` SmartArt отменяет конвертацию (422)|
|`errorOnOle`|Boolean|`false`|при `true` OLE-объекты отменяют конвертацию (422); при `false` OLE-объекты тихо удаляются, картинка-плейсхолдер сохраняется|
|`maxMb`|число|свойство сервера `wordpdf.max-mb` (5)|лимит размера входа в МБ; переопределяет серверный дефолт **в обе стороны**; `≤ 0` → 400|
|`maxPages`|число|свойство сервера `wordpdf.max-pages` (100)|лимит числа страниц; переопределяет в обе стороны; `≤ 0` → 400|
!!! note "На `.doc` error-флаги не срабатывают"
Плейсхолдеры диаграмм/SmartArt/OLE в бинарном формате — это BLIP-растры, мост
вставляет их картинками; векторные EMF/WMF/PICT пропускаются с warn. Флаги
работают только для `.docx`.
## Успешный ответ
```
HTTP 200
Content-Type: application/pdf
Content-Disposition: attachment; filename*=UTF-8''Документ.pdf
```
Имя файла берётся из `Content-Disposition` загруженного файла, санитизируется
(разрешены буквы, цифры, пробел и `._-`; кириллица разрешена; пустое имя → `document`)
и используется единожды для имени файла, заголовка ответа и заголовка PDF.
## Обработка
Задача ставится в однопоточную очередь воркеров (16 мест). Проверка размера —
синхронно до очереди. Конвертация дольше `wordpdf.convert-timeout` (2m) → 504,
очередь полна → 503. Полная таблица ответов — [Коды ошибок](errors.md),
пороги — [Лимиты](limits.md).
+55
View File
@@ -0,0 +1,55 @@
# Коды ошибок
Ошибки — JSON вида `{"error": "..."}`.
## Полная таблица
|Код|Смысл|
|---|---|
|200|PDF в теле ответа|
|400|некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше лимита размера (`maxMb` или `wordpdf.max-mb`) / больше лимита страниц (`maxPages` или `wordpdf.max-pages`) / `maxMb`≤0 / `maxPages`≤0), отсутствующая часть `file`, некорректное значение error-флага|
|401|нет или неверен `X-API-Key`|
|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)|
|405|не-POST|
|413|тело запроса больше контейнерного лимита multipart (100 МБ; авторитетный лимит входа — `wordpdf.max-mb`, он даёт 400 раньше)|
|415|не-multipart тело|
|422|сработал error-флаг: в документе найдены диаграммы / SmartArt / OLE-объекты|
|500|ошибка ядра/рендера|
|503|очередь конвертации (16 мест) переполнена — повторить позже|
|504|конвертация дольше `wordpdf.convert-timeout` (по умолчанию 2m)|
## Фиксированные тексты
Тексты ниже — контракт с фронтендом, они не меняются:
|Код|Тело|
|---|---|
|401|`{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}`|
|404|`{"error":"Не найдено"}`|
|405|`{"error":"Метод не поддерживается"}`|
|415|`{"error":"Неподдерживаемый тип содержимого"}`|
|422 (диаграммы)|`{"error":"Конвертация отменена: в документе найдены диаграммы"}`|
|422 (SmartArt)|`{"error":"Конвертация отменена: в документе найден SmartArt"}`|
|422 (OLE)|`{"error":"Конвертация отменена: в документе найдены OLE-объекты"}`|
|500|`{"error":"Не удалось конвертировать документ"}`|
Другие 400-тексты параметризованы, например: `Файл не передан (multipart-поле «file»
обязательно)`, `Поддерживаются только .docx и .doc: <имя>`, `Файл больше <N> МБ: …`,
`Некорректное значение параметра «<имя>»`.
!!! info "500 — деталь только в лог"
Сообщения ядра (`ConversionException` и др.) логируются на сервере, наружу
всегда уходит фиксированный текст — внутренние детали не текут клиенту.
## Исключение → обработчик (для отладки)
|HTTP|Источник|
|---|---|
|400|`ValidationException`, `BadRequestException`, `MethodArgumentTypeMismatchException`, `MissingServletRequestPartException`|
|401|`ApiKeyFilter` (пишет ответ сам, до диспетчера)|
|404 / 405 / 415|`NoResourceFoundException` / `HttpRequestMethodNotSupportedException` / `HttpMediaTypeNotSupportedException`|
|413|`MaxUploadSizeExceededException`|
|422|`DrawingRejectedException`|
|500|`ConversionFailedException`|
|503|`ConversionRejectedException`|
|504|`ConversionTimeoutException`|
+74
View File
@@ -0,0 +1,74 @@
# Примеры клиентов
Базовый адрес зависит от стенда: прод `https://pjandro.ru/pdf-converter/api/v1/convert`,
prod-like локально `http://localhost:9010/api/v1/convert`, dev `http://<LAN-IP>:9011/api/v1/convert`,
`java -jar` — `http://localhost:8080/api/v1/convert`.
## curl
Без ключа (сервер с выключенной аутентификацией):
```bash
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
```
С ключом и error-флагом:
```bash
curl -H "X-API-Key: $WORDPDF_API_KEY" \
-F "file=@Отчёт.docx" \
"https://pjandro.ru/pdf-converter/api/v1/convert?errorOnOle=true&maxMb=10" \
-o out.pdf
```
## JavaScript (fetch)
```js
const form = new FormData();
form.append("file", fileInput.files[0], fileInput.files[0].name);
const resp = await fetch("/api/v1/convert", {
method: "POST",
headers: apiKey ? { "X-API-Key": apiKey } : {},
body: form,
});
if (!resp.ok) {
const { error } = await resp.json().catch(() => ({ error: resp.statusText }));
throw new Error(error);
}
// имя файла из Content-Disposition: attachment; filename*=UTF-8''%D0%9E%D1%82%D1%87%D1%91%D1%82.pdf
const cd = resp.headers.get("Content-Disposition") ?? "";
const m = cd.match(/filename\*=UTF-8''([^;]+)/i);
const name = m ? decodeURIComponent(m[1]) : "document.pdf";
const blobUrl = URL.createObjectURL(await resp.blob());
const a = Object.assign(document.createElement("a"), { href: blobUrl, download: name });
a.click();
URL.revokeObjectURL(blobUrl);
```
Обработка 401 — стереть сохранённый ключ и показать экран ввода; 422 — показать
`error` из тела (документ содержит диаграммы/SmartArt/OLE).
## Python (requests)
Таймаут обязан быть больше серверных 2 минут на чтение:
```python
import requests
resp = requests.post(
"https://pjandro.ru/pdf-converter/api/v1/convert",
headers={"X-API-Key": API_KEY} if API_KEY else {},
files={"file": open("doc.docx", "rb")},
params={"errorOnCharts": "false"},
timeout=(10, 180), # connect 10 c, read 180 c — больше серверных 2m
)
resp.raise_for_status()
with open("doc.pdf", "wb") as f:
f.write(resp.content)
```
Так же устроены прод-автотесты репозитория (`prod-autotests/`, pytest + requests).
+53
View File
@@ -0,0 +1,53 @@
# REST API
Базовый путь — корень сервера; единственный эндпоинт:
```
POST /api/v1/convert
```
Quickstart — конвертировать документ и сохранить PDF (ключ доступа, если сервер его
требует, — в заголовке `X-API-Key`):
```bash
curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \
https://pjandro.ru/pdf-converter/api/v1/convert -o doc.pdf
```
Локальный бэкенд (`java -jar`, порт 8080, ключ выключен):
```bash
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
```
Успешный ответ — `200`, тело — байты PDF (`Content-Type: application/pdf`,
`Content-Disposition: attachment; filename*=UTF-8''…`).
## Документация в самом сервисе
|Что|Путь|Когда доступно|
|---|---|---|
|Swagger UI|`/swagger-ui.html`|пока включён springdoc|
|OpenAPI (JSON)|`/v3/api-docs`|пока включён springdoc|
На `java -jar` и dev-стенде (:9011) springdoc включён; на проде он также открыт
(проверяется автотестом `test_swagger_ui_open_without_key`). В локальном prod-like
compose-стеке springdoc выключен env-ами `SPRINGDOC_API_DOCS_ENABLED=false` и
`SPRINGDOC_SWAGGER_UI_ENABLED=false` (в этом случае `/v3/api-docs` отвечает 404).
## Разделы
- [Аутентификация](authentication.md) — ключ `X-API-Key`.
- [Эндпоинт конвертации](convert-endpoint.md) — параметры и ответ.
- [Коды ошибок](errors.md) — полная таблица и тексты.
- [Лимиты](limits.md) — размер, страницы, очередь, таймаут.
- [Примеры клиентов](examples.md) — curl, JavaScript, Python.
## Как устроена обработка
Конвертации сериализуются **одним воркером**: ядро мутирует глобальный реестр шрифтов,
поэтому все конвертации идут последовательно (очередь — 16 мест, переполнение → 503).
Головой очереди на старте стоит `warmup()` — прогрев ядра (~1,5–2,5 с), чтобы первый
запрос после деплоя не платил за инициализацию JAXB/XSLT/FOP. Проверка размера входа
выполняется синхронно, до постановки в очередь.
+47
View File
@@ -0,0 +1,47 @@
# Лимиты
## Лимиты входа
|Свойство|Env|Дефолт|Смысл|
|---|---|---|---|
|`wordpdf.max-mb`|`WORDPDF_MAX_MB`|5|максимальный размер файла в МБ (MiB)|
|`wordpdf.max-pages`|`WORDPDF_MAX_PAGES`|100|максимальное число страниц|
Это **дефолт эндпоинта**: параметры запроса `maxMb`/`maxPages` переопределяют его
в обе стороны (значения `≤ 0` → 400; верхнего серверного потолка нет — защитные
пороги растут вместе с лимитами). Значение свойства сервера `≤ 0` — падение
приложения на старте (`IllegalStateException`).
## Производные защитные пороги
Остальные пороги выводятся из лимитов входа (`WordPdfValidator`), проверяются
до рендера, одним lightweight-сканом:
- распакованный размер архива;
- суммарный распакованный размер XML-частей;
- число записей zip и защита от дубликатов записей;
- площади растровых изображений (пиксели);
- размер `[Content_Types].xml` (жёсткие 8 МБ).
Превышение любого — `400` (в библиотеке — `ValidationException`).
## Потолок инфраструктуры — 100 МБ
`spring.servlet.multipart.max-file-size`/`max-request-size` = 100MB — потолок
контейнера, зеркалит `client_max_body_size 100m` nginx-шлюза. Тело больше — 413.
Логический лимит входа (`wordpdf.max-mb`, дефолт 5 МБ) отсекает раньше и даёт 400;
413 возможен только когда серверный лимит поднят администратором выше дефолта.
Части загрузки больше 2 МБ (`file-size-threshold=2MB`) сбрасываются на диск Tomcat —
heap держит только копию байтов одной сериализованной конвертации.
## Очередь и таймаут
|Параметр|Значение|Поведение|
|---|---|---|
|ёмкость очереди|16 мест|переполнение → **503** (повторить позже)|
|`wordpdf.convert-timeout`|`2m` (env `WORDPDF_CONVERT_TIMEOUT`)|конвертация дольше → **504** (задача отменяется)|
Конвертации исполняются строго последовательно одним воркером (ядро мутирует
глобальный реестр шрифтов); при таймауте `future.cancel(true)` не останавливает FOP
мгновенно — текущая конвертация дожигается, следующий запрос ждёт её в очереди.