> For the complete documentation index, see [llms.txt](https://akrisanov.gitbook.io/team-playbook/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://akrisanov.gitbook.io/team-playbook/engineering-practices/arkhitekturnyi-dizain.md).

# Архитектурный дизайн

| Статус документа         | Черновик / На ревью / Одобрен / В разработке / В архиве                     |
| ------------------------ | --------------------------------------------------------------------------- |
| Связанные задачи / эпики |                                                                             |
| Системные требования     | (опционально)                                                               |
| Автор(ы)                 |                                                                             |
| Ревьюверы                | *Ревью техлида направления обязательно в задачах, где меняется архитектура* |
| Статус ревью             | <ul><li>Approve Frontend</li><li>Approve Backend</li></ul>                  |

> Постарайтесь сделать документ не перегруженным лишними деталями.\
> Визуализация > текст, но для сложных диаграмм стоит добавлять текстовое описание.\
> Документ пишется на выпускаемую end-to-end функциональность и не зависит от типа задачи.

### Контекст

Какой бизнес-проблемой или фичей вызвано изменение? Как это связано с текущей архитектурой?

### Область реализации

Что входит в решение, а что исключается? Например:

**Входит:**

* Расчёт подписок с новыми тарифами
* Хранение истории расчётов

**Не входит:**

* Отображение расчётов в UI
* Изменения в биллинге

### Обоснование и связь с требованиями

Какие бизнес и системные требования покрываются этим дизайном.

### Архитектура

#### #Диаграмма компонентов

Можно по уровням: система / контейнер / компонент.

#### Компоненты и взаимодействие

| Компонент | Ответственность | Владелец        |
| --------- | --------------- | --------------- |
|           |                 | Команда A       |
|           |                 | Команда B       |
|           |                 | Внешняя система |

#### Изменения в базе данных

| Таблица | Тип | Изменения |
| ------- | --- | --------- |
|         |     |           |

#### Интерфейсы и события

| Тип      | Интерфейс / Событие          | Формат | Auth   |
| -------- | ---------------------------- | ------ | ------ |
| HTTP API | POST \<URL>                  | JSON   | Bearer |
| Event    | subscription.recalculated.v1 | avro   | —      |

### Поведение

Основные сценарии (в текстовом виде или как диаграмма последовательностей). Например:

1. Админ запускает пересчёт вручную
2. Сервис собирает все активные подписки
3. Для каждой подписки создаётся джоба расчёта
4. Джобы обрабатываются в воркере
5. После расчёта публикуется событие `subscription.recalculated`

*Допускаются ссылки на системные требования.*

### Ошибки и отказоустойчивость

Что происходит при сбоях:

* Как ретраится?
* Есть ли дедупликация?
* Где хранятся неуспешные расчёты?
* Какие алерты?

### Тестирование и мониторинг

👉🏻 Стратегия контроля качества

| Что     | Пример                                               |
| ------- | ---------------------------------------------------- |
| Тесты   | Интеграционный тест на пересчёт тарифа `Standard`    |
| Метрики | `subscription.calculation.duration`                  |
| Алерты  | Ошибки >5% за 10 минут по `calculation.failure.rate` |

### Прочие нефункциональные требования

👉🏻 Нефункциональные требования

*Допускается ссылка на системные требования.*

### План внедрения

Разбей внедрение по этапам, если оно сложное или нужно выкатывать по частям. Укажи зависимые команды, сервисы, окружения.

### Альтернативы и отклонённые варианты

Какие подходы рассматривались и почему были отклонены?

По возможности указывать как альтернативные решения влияют на сроки.

Пример:

* С рефакторингом задача затянется – может занять в районе 3х месяцев
* Без рефакторинга – 1 месяц, но будут жалобы от пользователей на медленную работу фильтров (1-2 минуты)

### Риски и меры

Что может пойти не так? Как можно минимизировать ущерб?