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
+74
View File
@@ -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) маршрутизируется по байтам — это
не ошибка.