feat(topbar): «Что нового» button + 2026-05-12 state.md update
This commit is contained in:
Александр Зимин
@@ -0,0 +1,144 @@
|
||||
# Разбор ошибок валидации
|
||||
|
||||
Ordinis старается давать понятные ошибки, но иногда нужна расшифровка.
|
||||
Эта страница — справочник самых частых.
|
||||
|
||||
## Формат ошибок
|
||||
|
||||
В UI ошибки появляются:
|
||||
- **Инлайн под полем формы** — для конкретных полей (red text)
|
||||
- **Тост в правом верхнем** — для общих ошибок (например, сеть)
|
||||
- **Полноэкранный экран** — для серьёзных проблем (500 / 503)
|
||||
|
||||
Каждая ошибка имеет:
|
||||
- **Код** (`webhook_status_invalid`, `record_not_active`) — машинный идентификатор
|
||||
- **Сообщение** — человеческое описание на русском
|
||||
- **Trace ID** (для серверных ошибок) — для передачи в ops
|
||||
|
||||
## Самые частые ошибки
|
||||
|
||||
### 422: «Поле X обязательно»
|
||||
|
||||
Что значит: схема справочника требует это поле, но ты его не заполнил.
|
||||
|
||||
Что делать: заполни и сохрани. Если поле кажется ненужным — это вопрос
|
||||
к схеме справочника, обсуди с ревьюером (см. [schema drafts](../reviewer/schema-drafts.md)).
|
||||
|
||||
### 422: «Тип значения не соответствует схеме»
|
||||
|
||||
Что значит: например, в поле `mass_kg` (number) введён текст.
|
||||
|
||||
Что делать: проверь тип в hint'е под полем. Числовые поля принимают только
|
||||
цифры (точка как разделитель десятых для дробей: `1234.5`).
|
||||
|
||||
### 422: «FK не найден»
|
||||
|
||||
Что значит: значение в поле со ссылкой (`x-references`) указывает на
|
||||
запись, которой нет в целевом справочнике.
|
||||
|
||||
Что делать:
|
||||
1. Открой целевой справочник (имя есть в hint'е поля)
|
||||
2. Проверь, есть ли там запись с этим бизнес-ключом
|
||||
3. Если нет — сначала добавь запись туда, потом возвращайся
|
||||
4. Если есть, но закрыта — нужно её **активировать** или создать новую
|
||||
|
||||
### 409: «Бизнес-ключ уже существует»
|
||||
|
||||
Что значит: ты пытаешься создать запись с `code`, который уже занят
|
||||
активной записью того же справочника.
|
||||
|
||||
Что делать:
|
||||
- Выбери другой `code`
|
||||
- Или: найди существующую запись и обнови её, а не создавай новую
|
||||
- Или: закрой существующую (если она устарела) и создай заново
|
||||
|
||||
### 409: «Период действия пересекается»
|
||||
|
||||
Что значит: bitemporal модель не разрешает двум версиям одной записи
|
||||
быть активными одновременно.
|
||||
|
||||
Что делать:
|
||||
1. Найди активную версию того же бизнес-ключа
|
||||
2. **Закрой её** (`valid_to = момент новой версии`), потом создавай новую
|
||||
3. Или: укажи `valid_from` новой версии так, чтобы периоды не пересекались
|
||||
|
||||
См. [Закрытие записи](close-record.md).
|
||||
|
||||
### 403: «Нет доступа»
|
||||
|
||||
Что значит: у твоего пользователя нет прав на эту операцию или scope.
|
||||
|
||||
Что делать:
|
||||
- Если справочник `RESTRICTED` — нужны права администратора, спроси у
|
||||
руководителя
|
||||
- Если `INTERNAL` — нужен внутренний токен (не публичный)
|
||||
- Если операция «approve schema draft» — это право ревьюера, не оператора
|
||||
(см. [reviewer guide](../reviewer/index.md))
|
||||
|
||||
### 401: «Требуется вход»
|
||||
|
||||
Что значит: твоя сессия истекла или нет валидного токена.
|
||||
|
||||
Что делать: войди заново через Keycloak. После logout / refresh всё должно
|
||||
работать.
|
||||
|
||||
### 503: «Сервер временно недоступен»
|
||||
|
||||
Что значит: backend временно не отвечает (rolling restart, плановое
|
||||
обслуживание, или сетевой сбой).
|
||||
|
||||
Что делать:
|
||||
1. Подожди 30-60 секунд, нажми **«Повторить»**
|
||||
2. Если повторяется > 5 минут — свяжись с ops
|
||||
3. Никакие данные не пропали — сервер вернётся, твои изменения сохранены
|
||||
локально пока не отправил
|
||||
|
||||
### Network error / «Нет соединения»
|
||||
|
||||
Что значит: твой браузер не может достучаться до сервера. Чаще всего
|
||||
проблема в твоей сети, не в Ordinis.
|
||||
|
||||
Что делать:
|
||||
1. Проверь соединение (открой любой другой сайт)
|
||||
2. Если корпоративная сеть — проверь VPN / прокси
|
||||
3. Если изменения не сохранились — они **не пропадут**, попробуй
|
||||
повторить когда соединение вернётся
|
||||
|
||||
### «AxiosError: Request failed with status code 503» (raw)
|
||||
|
||||
Что значит: техническая ошибка, которая «убежала» в UI без friendly
|
||||
обёртки. Это **баг UI**, не баг данных.
|
||||
|
||||
Что делать: сделай скриншот, передай в support с trace ID (если есть).
|
||||
|
||||
## Schema validation на стороне сервера
|
||||
|
||||
Когда ты сохраняешь запись, сервер валидирует её по JSON Schema справочника.
|
||||
Если ошибка — увидишь подробности:
|
||||
|
||||
```
|
||||
Validation failed:
|
||||
- /satellite_type: must be one of ['OPERATIONAL', 'TESTING', 'DECOMMISSIONED']
|
||||
- /mass_kg: must be number, got string
|
||||
- /name: required property missing
|
||||
```
|
||||
|
||||
Каждая строка — отдельная проблема. Поправь все, сохрани заново.
|
||||
|
||||
## Если не помогает
|
||||
|
||||
1. **Скриншот** — снимок экрана со всеми видимыми деталями ошибки
|
||||
2. **Trace ID** — если есть в сообщении, скопируй
|
||||
3. **Время** — точное время, когда возникла
|
||||
4. **Что ты делал** — последняя последовательность действий
|
||||
5. Передай это команде поддержки. По этим данным они смогут восстановить
|
||||
контекст через [журнал аудита](audit-log.md) и серверные логи.
|
||||
|
||||
## Что НЕ нужно делать
|
||||
|
||||
- ❌ **Очищать кэш браузера / cookies** — это сломает сессию, ошибку не уберёт
|
||||
- ❌ **Открывать в инкогнито** — то же самое
|
||||
- ❌ **Менять JSON вручную в DevTools** — данные не сохранятся всё равно,
|
||||
но можешь напугать себя
|
||||
- ❌ **Заводить дубликат записи «чтобы попробовать»** — если первая не
|
||||
сохранилась, она и не сохранилась, дубликат не появится
|
||||
Reference in New Issue
Block a user