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
+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
мгновенно — текущая конвертация дожигается, следующий запрос ждёт её в очереди.