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
+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`|