mdm-ordinis/docs/operator/errors.md

Разбор ошибок валидации

Ordinis старается давать понятные ошибки, но иногда нужна расшифровка. Эта страница — справочник самых частых.

Формат ошибок

В UI ошибки появляются:

• Инлайн под полем формы — для конкретных полей (red text)
• Тост в правом верхнем — для общих ошибок (например, сеть)
• Полноэкранный экран — для серьёзных проблем (500 / 503)

Каждая ошибка имеет:

• Код (webhook_status_invalid, record_not_active) — машинный идентификатор
• Сообщение — человеческое описание на русском
• Trace ID (для серверных ошибок) — для передачи в ops

Самые частые ошибки

422: «Поле X обязательно»

Что значит: схема справочника требует это поле, но ты его не заполнил.

Что делать: заполни и сохрани. Если поле кажется ненужным — это вопрос к схеме справочника, обсуди с ревьюером (см. schema drafts).

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 новой версии так, чтобы периоды не пересекались

См. Закрытие записи.

403: «Нет доступа»

Что значит: у твоего пользователя нет прав на эту операцию или scope.

Что делать:

• Если справочник RESTRICTED — нужны права администратора, спроси у руководителя
• Если INTERNAL — нужен внутренний токен (не публичный)
• Если операция «approve schema draft» — это право ревьюера, не оператора (см. reviewer guide)

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. Передай это команде поддержки. По этим данным они смогут восстановить контекст через журнал аудита и серверные логи.

Что НЕ нужно делать

• ❌ Очищать кэш браузера / cookies — это сломает сессию, ошибку не уберёт
• ❌ Открывать в инкогнито — то же самое
• ❌ Менять JSON вручную в DevTools — данные не сохранятся всё равно, но можешь напугать себя
• ❌ Заводить дубликат записи «чтобы попробовать» — если первая не сохранилась, она и не сохранилась, дубликат не появится