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:
2026-11-13 09:55:55 +03:00
parent 88ac95dd19
commit 231490bb7c
19 changed files with 1714 additions and 67 deletions
+1
View File
@@ -27,6 +27,7 @@
- В каталоге Fragment сохраняй `name`, `description` и категории из дизайна: «Список коллекций», «Текстовая секция», «Markdown body», «Карточки». Под названием показывай назначение из `fragment.yaml:description`, передаваемое через API; ID доступен для поиска и в title. `section` содержит свой текст и поддерживает слоты, `richtext` по умолчанию выводит `page.body`. Изменения builtin/API/шаблонов требуют пересборки Docker-образа; одного bind-mount сайта недостаточно.
- В админских формах сохраняй `action`, `method`, имена полей, `csrf`, `etag` (параметр сервиса — `if_match`) и передачу ошибок. Запись контента проходит через `ContentService`: блокировка, проверка версии, валидация, история, атомарная запись.
- Для нового UI HTML и JSON имеют отдельные маршруты. Серверный клиент вызывает API через `httpx.ASGITransport`; внутренние credentials не попадают в браузер, автор и эпоха проверяются на API-границе. Буфер/превью не сохраняют контент до явного Save.
- Ошибки JSON API возвращай как `error: {code, message, request_id, …}` с корректным HTTP-статусом. Общая граница — `web/error_handling.py`: неожиданные исключения записываются со стеком в `uvicorn.error`, метод, путь и ID связывают HTML-запрос с внутренним API. Не добавляй в лог тело запроса, cookies и Authorization. В htmx ошибки HTTP/сети показываются через уведомление из дизайна; 5xx не должны заменять несохранённый исходник редактора. Проверка отказов — `PYTHONPATH=src python scripts/qa_errors_001.py`.
- Сохраняй autoescape, санитайзер Markdown и CSP. JS для админки подключай внешним локальным файлом. Пассивное превью не исполняет скрипты. Интерактивное использует `web/preview_app.py` на отдельном origin, nonce bridge и защищённые immutable snapshots; JS сайта не запускается. Обычная сборка не получает служебную разметку.
- Приём публичных форм пока возвращает HTTP 501; MCP и changeset — заготовки. Не показывай успешную отправку без работающего обработчика.
- Проверяй мобильную и широкую версии, клавиатурную навигацию, фокус, подписи полей и контраст. Анимации учитывают `prefers-reduced-motion`.