# ADR — записи архитектурных решений

← [Раздел](README.md) · [Главная](../README.md)

## Цель

Научиться фиксировать **архитектурные решения** в формате **ADR (Architecture Decision Record)**: контекст, выбор, последствия — чтобы через год понимать «почему так», а не переспоривать с нуля.

## Предварительно

- [C4-модель](c4-model.md)

## Время

**4–5 часов** (чтение + написание 2 ADR)

---

## Проблема «устного знания»

«Мы выбрали PostgreSQL в 2024, потому что…» — через два года в Slack уже никто не помнит. Новый разработчик предлагает Mongo «для скорости». Команда тратит неделю на спор.

**ADR** — короткий markdown в git: **неизменяемая история** (новое решение = новый ADR, старый помечается superseded).

---

## Структура ADR (шаблон)

```markdown
# ADR-0003: Использовать PostgreSQL как основное хранилище

## Статус
Принято | 2026-06-16

## Контекст
Нужно хранить пользователей, списки, пункты со связями.
Команда знает SQL. NFR: транзакции при совместном редактировании.

## Решение
Основная БД — PostgreSQL 16 (managed).
Миграции — инструмент X. Кэш — Redis отдельно.

## Рассмотренные альтернативы
- MongoDB: гибкая схема, слабее для JOIN отчётов
- SQLite: только для local dev

## Последствия
+ ACID, зрелые инструменты
+ Нужны миграции при смене схемы
- Вертикальный рост write до шардинга (позже)

## Связанные артефакты
C4 Container diagram v0.3, NFR-D1
```

---

## Статусы ADR

| Статус | Значение |
|--------|----------|
| **Предложено** | На обсуждении |
| **Принято** | Действует |
| **Устарело (Superseded)** | Заменено ADR-0007 |
| **Отклонено** | Не делали, но причины сохранены |

---

## Когда писать ADR

| Ситуация | ADR? |
|----------|------|
| Выбор БД, брокера, облака | Да |
| Публичный REST vs GraphQL | Да |
| Монолит vs микросервисы на старте | Да |
| Переименовать переменную | Нет |
| Цвет кнопки | Нет |

Правило: решение **дорого откатить** или **влияет на границы системы** → ADR.

---

## Пример ADR: синхронный vs async email

```markdown
# ADR-0004: Отправка приглашений через очередь

## Контекст
FR-4: email при share. SaaS latency до 2s. NFR-P1: API write p95 < 400ms.

## Решение
API публикует InviteCreated в очередь, worker шлёт email.
API возвращает 202 или 201 без ожидания SaaS.

## Альтернативы
- Sync в request: просто, но ломает latency и SLA при сбое SaaS

## Последствия
+ Стабильный API
+ Нужен мониторинг DLQ
- Eventual доставка письма (секунды)
```

Связь с [очередями](../02-komponenty/ocheredi-i-sobytiya.md).

---

## Хранение и нумерация

```
docs/
  adr/
    README.md          # индекс
    0001-monolith-mvp.md
    0002-rest-api.md
    0003-postgresql.md
```

| Правило | Зачем |
|---------|-------|
| Номер по порядку | Ссылки в PR и C4 |
| Дата в заголовке | Хронология |
| Не редактировать принятые | История правдива; supersede новым |

---

## ADR и код-ревью

В PR, меняющем архитектуру:

1. Ссылка на ADR в описании  
2. Обновление C4 Container при новом сервисе  
3. Reviewer проверяет соответствие решению  

---

## Коллективное принятие

| Шаг | Действие |
|-----|----------|
| 1 | Автор черновик ADR |
| 2 | Обсуждение 30–60 мин (архитектор, lead, ops) |
| 3 | Статус «Принято» после consensus |
| 4 | Анонс в команде |

Спор без ADR часто повторяется; с ADR — спор о **новых фактах**, не о памяти.

---

## Антипаттерны

| Плохо | Хорошо |
|-------|--------|
| ADR на 20 страниц | 1–2 экрана |
| «Потому что я так сказал» | Измеримый NFR в контексте |
| Удалить старый ADR | Superseded ссылкой |
| 50 ADR в первую неделю | Только значимые развилки |

---

## Практика

1. Напишите ADR-0001 «Монолит для MVP» с альтернативой микросервисов.  
2. Напишите ADR-0002 «REST + OpenAPI» для публичного API.  
3. Добавьте в индекс `docs/adr/README.md` таблицу статусов.

---

## Самопроверка

1. Зачем не удалять отклонённые ADR?  
2. Какие три секции обязательны в ADR?  
3. Когда ADR помечается Superseded?

---

## Дальше

→ [04 — Взаимодействие компонентов](../04-vzaimodeistvie/README.md)