Files

T

Zimin A.N. 1dba9476db docs(rbac): добавить матрицу realm-ролей Keycloak

operator/rbac.md — новая страница с полной матрицей RBAC:
- Scope ACL (ordinis:client:public/internal/restricted)
- Workflow роли (schema:reviewer, schema:publisher, record:reviewer)
- Action matrix (endpoint → required scope + role)
- Типичные профили (consumer, maker, reviewer, publisher, admin)
- Composite role 'ordinis:admin' для one-shot assignment
- Keycloak setup инструкция (Admin Console шаги)
- Диагностика типичных 403 ошибок

toc.yaml — link в раздел Руководство оператора.
operator/index.md, reviewer/index.md — cross-references к rbac.md.

Покрывает Phase 1d enforcement (MR !162) — пользователи теперь
знают какие роли назначать в Keycloak realm 'nstart'.

2026-05-13 12:47:50 +03:00

4.8 KiB

Raw Blame History

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

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

Если ты оператор (заводишь записи) — смотри руководство оператора.

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

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

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

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

Что внутри

Ревью schema drafts — пошаговая инструкция, как смотреть diff, какие проверки делать, как принимать решение

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

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

Когда чаще всего стоит 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+ запись невалидной — это breaking change, нужна data migration.
Не ломай downstream. Если поле читают Альтум / геопортал / BI — спроси их перед изменением имени или типа.
Документируй причину. Approve / reject комментарий — это аудит. Через год кто-то будет смотреть «почему мы так сделали».
Сомневаешься — REQUEST_CHANGES. Это не отказ, это просьба автора уточнить. Лучше потратить день на обсуждение, чем неделю на rollback.

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

Обзор API — чтобы понять, как изменение отразится на потребителях
Bitemporal модель — как работают периоды действия (важно для миграций)
Cross-references — как изменения FK влияют на зависимые справочники

4.8 KiB Raw Blame History