Перейти к основному содержимому

ADR-0036: Feature Flags, Release Safety И Operational Dashboards

Статус​

Принято.

Контекст​

Pin выпускает изменения в multi-tenant enterprise platform, где одна ошибка может затронуть деньги, KYC/AML, игровые расчеты, partner payouts, permissions или tenant isolation. Обычный deploy без controlled rollout не дает достаточной защиты: поведение включается сразу для всех brands, incident triage зависит от ручного поиска, а rollback может быть опаснее forward-fix при migrations, ledger postings и event contracts.

Платформе нужен единый стандарт feature flags, dark launch, gradual rollout, kill switch, release evidence и operational dashboards. Этот стандарт должен связывать release process с SLO, RED metrics, business metrics, alerts, runbooks и владельцами доменов.

Решение​

  1. Ввести обязательные operational dashboards из docs/02-architecture/observability-dashboard-catalog.md.
  2. Использовать feature flags как release safety mechanism, а не как замену доменной модели или permission catalog.
  3. Считать risky flags любые flags, влияющие на Accounting, Payments, GameHost, Incentive liability, Identity, KYC/AML, Partner payouts, tenant isolation, permissions и provider callbacks.
  4. Требовать для risky flags owner, approver, expiry date, cleanup task, fallback behavior, tests, dashboards, alerts и runbook.
  5. Выполнять production rollout по стадиям: disabled deploy, dark launch, internal, canary, tenant/brand scoped rollout, full enablement.
  6. Поддерживать kill switch для critical side effect paths: payments, withdrawals, game settlement, incentive activation, KYC/AML provider, partner payouts и risky permission policy.
  7. Фиксировать release package: git sha, migrations, API/event changes, changed permissions, active flags, rollback/forward-fix notes и operational evidence links.
  8. Для money/security/compliance changes использовать manual approval от domain owner и Finance/Security/Compliance/Ops owner там, где применимо.

Последствия​

  • Deploy и enablement становятся разными действиями.
  • Каждый critical release получает наблюдаемость до включения поведения для пользователей.
  • Incident response опирается на dashboard, alert, runbook и owner, а не на устные знания команды.
  • Risky flags не могут жить бессрочно; они удаляются после rollout или переводятся в typed configuration/policy.
  • Rollback запрещено использовать как универсальное действие, если оно может повредить ledger, audit, KYC evidence, provider callbacks или event compatibility.
  • CI/release gates должны проверять наличие docs, tests, dashboard/runbook references и approval для risky changes.

Альтернативы​

АльтернативаПочему Не Выбрана
Включать поведение сразу после deployСлишком высокий blast radius для multi-tenant платформы и финансовых flows.
Использовать flags без expiry и ownerСоздает скрытые permanent branches и непроверяемое поведение.
Полагаться только на инфраструктурные dashboardsНе покрывает business metrics: ledger imbalance, payout failures, KYC backlog, incentive liability.
Всегда делать rollbackНебезопасно для migrations, immutable ledger, audit evidence и event-driven consumers.

Связанные Документы​

  • docs/02-architecture/observability.md
  • docs/02-architecture/observability-dashboard-catalog.md
  • docs/03-domain/domain-invariants-catalog.md
  • docs/08-devops/rollout-and-feature-flag-rules.md
  • docs/08-devops/ci-quality-gates.md