🛡 Safe Evolution Architecture

🕰 Soft Deprecation

-- Помечаем но не удаляем
COMMENT ON COLUMN urls.old_field IS 'DEPRECATED since v1.5, use new_field';
-- Работает 3-6 месяцев, потом удаляем

🌊 Rolling Migration

Не разом 28 000 записей, а кусками:

UPDATE urls SET new_field = COMPUTE(old_field)
WHERE id IN (SELECT id FROM urls WHERE new_field IS NULL LIMIT 1000);
-- Запускаем в cron каждые 10 минут пока не обработано всё

👀 Shadow Reads / Writes

Новая логика пишет в новое место, старая продолжает работать. Сравниваем результаты N дней → переключаем.

-- Пишем в оба места
BEGIN;
  INSERT INTO urls_old (...) VALUES (...);
  INSERT INTO urls_new (...) VALUES (...);
COMMIT;

-- Читаем из старого, но в фоне проверяем что новое совпадает
-- Через 7 дней без расхождений — переключаем чтение на новое

🐤 Canary Releases

1. 5% трафика на новую версию — 1 день
2. 20% — 3 дня
3. 50% — 1 неделя
4. 100% — после 1 недели без инцидентов

↩️ Rollback план — ОБЯЗАТЕЛЬНО

Каждая миграция имеет обратную. Не имеет — не мерджим.

-- forward.sql
ALTER TABLE urls ADD COLUMN new_field text;

-- rollback.sql
ALTER TABLE urls DROP COLUMN new_field;

# ТЗ: Блок {NAME} v{X.Y.Z}

## 1. Цель и место в архитектуре
## 2. Контракт (exports/imports/events/health)
## 3. Схема БД (таблицы, индексы, FK, RLS)
## 4. Миграции (forward + rollback)
## 5. Взаимодействия с другими блоками
## 6. Graceful degradation
## 7. Тесты (unit/integration/contract/health)
## 8. Dashboards / Views
## 9. Операции (cron, handlers)
## 10. Безопасность (RLS, audit, sensitive)

---

## 5-Pass Review

- [ ] Pass 1 — Полнота       · дата · замечания · статус
- [ ] Pass 2 — Связи         · дата · замечания · статус
- [ ] Pass 3 — Backward compat · дата · замечания · статус
- [ ] Pass 4 — Безопасность  · дата · замечания · статус
- [ ] Pass 5 — Масштабируемость · дата · замечания · статус

**Итого:** готово к реализации / требует доработки

---

## Rollback план
## Canary план
## Метрики успеха