# Руководство ревьюера Ordinis

Это руководство — для **ревьюеров schema drafts**: тех, кто принимает или
отклоняет предложения изменить схему справочников.

Если ты **оператор** (заводишь записи) — смотри
[руководство оператора](../operator/index.md).

## Когда нужен ревью

Изменения схемы справочника (добавление поля, изменение типа, новое
ограничение) **не применяются автоматически**. Оператор создаёт **schema
draft** — предложение, которое проходит через ревью:

```
DRAFT → REVIEW_PENDING → APPROVED → PUBLISHED
         ↘ REJECTED   ↘ CHANGES_REQUESTED
              ↘ WITHDRAWN
```

Ты как ревьюер решаешь: безопасно ли применить это изменение? Не сломает
ли оно существующих записей? Не сломает ли консьюмеров (Альтум, BI и пр.)?

## Что внутри

- [Ревью schema drafts](schema-drafts.md) — пошаговая инструкция, как
  смотреть diff, какие проверки делать, как принимать решение

## Какая роль нужна

Для approve / reject schema drafts требуется realm role
`ordinis:schema:reviewer`. Для финального publish — `ordinis:schema:publisher`
(обычно более узкая группа). Полная матрица — см.
[Роли доступа](../operator/rbac.md) в руководстве оператора.

## Когда чаще всего стоит REJECT или REQUEST_CHANGES

| Сценарий | Что делать |
|---|---|
| Меняется тип существующего поля (string → number) | **REJECT** — поломает существующие записи. Если очень нужно, делать через миграцию данных, не через draft |
| Удаляется обязательное поле | **REJECT** или **REQUEST_CHANGES** с альтернативой (мигрировать данные) |
| Добавляется обязательное поле без default | **REQUEST_CHANGES** — нужен default или поле должно быть опциональным |
| Добавляется FK без проверки целостности | **REQUEST_CHANGES** — попроси добавить orphan check |
| Меняется `enum` (удаляется значение) | **REQUEST_CHANGES** — закрой все записи с этим значением сначала |
| Просто добавляется опциональное поле | Обычно **APPROVE** — безопасно |
| Косметика (description, examples) | **APPROVE** — это документация |

## Когда APPROVE

- Добавление опционального поля
- Расширение `enum` (новое значение)
- Уточнение `description` / `examples`
- Добавление формата валидации (`format: date`) к ранее не-валидируемому полю,
  если все существующие данные ему соответствуют

## Базовые принципы

1. **Не ломай существующие записи.** Если изменение делает 1+ запись
   невалидной — это breaking change, нужна data migration.

2. **Не ломай downstream.** Если поле читают Альтум / геопортал / BI — спроси
   их перед изменением имени или типа.

3. **Документируй причину.** Approve / reject комментарий — это аудит.
   Через год кто-то будет смотреть «почему мы так сделали».

4. **Сомневаешься — REQUEST_CHANGES.** Это не отказ, это просьба автора
   уточнить. Лучше потратить день на обсуждение, чем неделю на rollback.

## Связанные материалы

- [Обзор API](../integration/api/index.md) — чтобы понять, как изменение
  отразится на потребителях
- [Bitemporal модель](../integration/api/bitemporal.md) — как работают
  периоды действия (важно для миграций)
- [Cross-references](../integration/api/x-references.md) — как изменения
  FK влияют на зависимые справочники