feat(topbar): «Что нового» button + 2026-05-12 state.md update

2026-05-12 17:05:24 +00:00
parent 58dd871808
commit a34c6d4c82
21 changed files with 1853 additions and 8 deletions
@@ -0,0 +1,70 @@
+# Руководство ревьюера Ordinis
+
+Это руководство — для **ревьюеров schema drafts**: тех, кто принимает или
+отклоняет предложения изменить схему справочников.
+
+Если ты **оператор** (заводишь записи) — смотри
+[руководство оператора](../operator/index.md).
+
+## Когда нужен ревью
+
+Изменения схемы справочника (добавление поля, изменение типа, новое
+ограничение) **не применяются автоматически**. Оператор создаёт **schema
+draft** — предложение, которое проходит через ревью:
+
+```
+DRAFT → REVIEW_PENDING → APPROVED → PUBLISHED
+         ↘ REJECTED   ↘ CHANGES_REQUESTED
+              ↘ WITHDRAWN
+```
+
+Ты как ревьюер решаешь: безопасно ли применить это изменение? Не сломает
+ли оно существующих записей? Не сломает ли консьюмеров (Альтум, BI и пр.)?
+
+## Что внутри
+
+- [Ревью schema drafts](schema-drafts.md) — пошаговая инструкция, как
+  смотреть diff, какие проверки делать, как принимать решение
+
+## Когда чаще всего стоит 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 влияют на зависимые справочники