Make admin and API errors visible and traceable
Return structured JSON errors with request IDs, log unexpected exceptions with tracebacks, and show HTTP and network failures in the admin UI without losing unsaved source. Preserve publication errors when release listing also fails, handle cancelled preview promises, and add regression tests, browser failure scenarios, and updated API documentation.
This commit is contained in:
File diff suppressed because it is too large
Load Diff
@@ -45,7 +45,27 @@ HTML-операции нового редактора: `/admin/editor/pages/{id}
|
||||
|
||||
Снимок содержит kind/id/path/source/etag/model/schema/issues/revision; результат превью — URL, snapshot, expires_at и revision. ETag — `sha256:` от исходных байтов; проверка актуальной схемы и CAS выполняются под одним SiteLock вместе с history/atomic write. Изменение code/layouts/schemas через content scope запрещено, в том числе через symlink/traversal. Ошибка аудита после записи возвращает признак committed с сохранённым снимком и не выдаётся за отклонённый Save.
|
||||
|
||||
Ошибки API имеют `error: {code, message, issues, …}`; 409 дополнительно содержит submitted/current, 422 validation — неприменимый buffer либо диагностику. Лимит JSON-запроса — 1 MiB; source ограничен DTO и безопасным YAML-парсером. Неожиданная ошибка API возвращается без трассировки и секретов.
|
||||
Ошибки API имеют `error: {code, message, request_id, issues, …}` с соответствующим HTTP-статусом; 409 дополнительно содержит submitted/current, 422 validation — неприменимый buffer либо диагностику. Лимит JSON-запроса — 1 MiB; source ограничен DTO и безопасным YAML-парсером. Неожиданная ошибка API возвращается без трассировки и внутренних путей.
|
||||
|
||||
Пример ответа HTTP 500 на `/admin/api/v1/publish`:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "storage_error",
|
||||
"message": "Ошибка доступа к файлам сервера. Проверьте права и свободное место. Проверьте текущую версию перед повтором операции.",
|
||||
"request_id": "c4a857fd62774d688c5135d104ce3a51"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`X-Request-ID` присутствует в ответах приложения; ID сохраняется при внутреннем вызове API. Коды: `internal_error` — неожиданное исключение; `storage_error` — ошибка файловой системы; `request_validation`/`validation` — запрос/контент; `conflict` — несовпадение версии; `preview_unavailable` — недоступный snapshot. Серверный клиент преобразует отказ транспорта в HTTP 503 `api_unavailable`, некорректный ответ — в HTTP 502 `invalid_api_response`.
|
||||
|
||||
Неожиданные исключения пишутся через `logger.exception` в `uvicorn.error`: `request_failed request_id=… method=POST path=/admin/api/v1/publish code=storage_error`, затем traceback с исходным исключением и местом ошибки. Обработанные HTTP-ошибки дают `request_error` со статусом и кодом. Тело запроса, Authorization, cookies и query string не добавляются в эти записи. В Docker смотреть `docker logs --since 10m flexly-cms`; ID из интерфейса позволяет найти соответствующий стек.
|
||||
|
||||
HTML UI показывает сообщение, код и ID запроса. На публикации ошибку видно и без JavaScript; htmx показывает постоянное уведомление, которое закрывается пользователем. Подготовленная страница ошибки может заменить boosted-страницу; исходник документа при 5xx не заменяется. Отказ сети и timeout также видимы, автоматического повтора мутаций нет. Если после ошибки публикации недоступен список релизов, исходная ошибка операции сохраняется.
|
||||
|
||||
Проверка отказов на временной копии сайта: `PYTHONPATH=src python scripts/qa_errors_001.py`. Сценарий проверяет UI 500, общий ID с traceback, мобильное уведомление, сохранность несохранённого исходника при серверном и сетевом сбое и восстановление Save/Publish после устранения сбоя. Выход — `/tmp/cms-errors-qa/`; браузер — `QA_BROWSER=firefox`, каталог — `QA_ERRORS_OUT=/tmp/cms-errors-firefox`.
|
||||
|
||||
Схема и локальная страница документации доступны после входа: `/admin/api/v1/openapi.json`, `/admin/api/v1/docs`; сокращённые `/admin/api/openapi.json`, `/admin/api/docs` также работают. Воспроизводимый экспорт без секретов и работающего сайта:
|
||||
|
||||
|
||||
@@ -6,6 +6,16 @@
|
||||
|
||||
Ниже сохранены результаты функциональной реализации A–F. Действующий контракт и инструкции запуска: [runtime.md](runtime.md). Машиночитаемые результаты: [qa-results.json](qa-results.json), JSON-контракт: [openapi.json](openapi.json).
|
||||
|
||||
## Обработка ошибок — 13.11.2026
|
||||
|
||||
- Общая HTTP-граница возвращает JSON `error.code/message/request_id` для API, записывает неожиданные исключения со стеком в `uvicorn.error`. HTML-запрос и вложенные ASGI API-вызовы имеют один ID; тело запроса, cookies, Authorization и query string не добавляются в записи. Код и ID доступны в UI и заголовках ответа.
|
||||
- Проверена настоящая ошибка файловой системы при сборке (`dist` занят файлом), а также инъекции `PermissionError`/`RuntimeError`: JSON 500, HTML-страница публикации и traceback содержат согласованный ID. Если загрузка релизов после неудачной операции тоже падает, сохраняется исходная ошибка, а недоступный список не выдаётся за пустой.
|
||||
- **258 unit/integration-тестов — OK**. Регрессия запущена на временной копии studio-site; недоступный для чтения рабочий `pages/index.md` заменён версией из HEAD только во временной фикстуре. Пользовательские примеры и рабочие данные не изменены.
|
||||
- **Chromium и Firefox: по 6 групп сценариев ошибок — OK**: ошибка публикации видна в странице/уведомлении на 1440 и 390 px; стек содержит ID из UI; 500 Save и обрыв сети сохраняют точный исходник и доступность редактора; последующие Save и Publish успешны. Нативных диалогов и необработанных JS-исключений нет. Исправлен также необработанный Promise отменённого preview-запроса при уходе со страницы.
|
||||
- Обычная браузерная регрессия ai-studio в Chromium: **18 групп, 14 страниц × 5 ширин — OK**; проверены каталог, выбор секций, preview, сохранение, вход и выход.
|
||||
- Ruff для изменённых Python-модулей/тестов/QA, `node --check` admin/editor JS, `git diff --check` — OK. Экспорт OpenAPI совпадает с runtime; ErrorBody включает обязательный `request_id`.
|
||||
- Повторяемый сценарий: `PYTHONPATH=src python scripts/qa_errors_001.py`; отчёты и снимки — `/tmp/cms-errors-qa/`, Firefox — `/tmp/cms-errors-qa-firefox/`. Изменения на пользовательском сервере не разворачивались: для применения нужна пересборка образа и пересоздание контейнера. Причина исторической 500 на сервере по одной строке access log не установлена; новый обработчик сохраняет исходное исключение при повторении.
|
||||
|
||||
## Выполненные проверки
|
||||
|
||||
| Проверка | Результат |
|
||||
|
||||
Reference in New Issue
Block a user