Александр Зимин
145 lines
7.8 KiB
Markdown
145 lines
7.8 KiB
Markdown
# Разбор ошибок валидации
|
|
|
|
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** — данные не сохранятся всё равно,
|
|
но можешь напугать себя
|
|
- ❌ **Заводить дубликат записи «чтобы попробовать»** — если первая не
|
|
сохранилась, она и не сохранилась, дубликат не появится
|