# Протокол 02: Архитектурное проектирование (DESIGN)

## Цель

Спроектировать архитектуру, модули, данные и интерфейсы для greenfield/scaffold-проекта на основе требований из analysis-report.

## Вход

- `.agent/analysis-report.md` (project_type: greenfield или scaffold)
- `.agent/metaagent-request.md` (конфигурация сессии: adr, alternative_arch, risk_register)
- `.agent/checkpoints.json` (фаза design: pending)

## Правила

1. **Реалистичность** — архитектура должна быть реализуема исполнительным агентом за 1 сессию (до 10 задач)
2. **Документируемость** — каждый модуль, модель и интерфейс описывается в design-report.md
3. **Тестируемость** — каждый компонент проектируется с учётом того, как его тестировать
4. **Итеративность** — первая версия должна быть минимально рабочей (MVP), расширения — отдельными задачами

## Шаги

### 2.1. Технологический стек

Если стек не указан в README — предложить обоснованный выбор. Если указан — зафиксировать.

Для каждого компонента указать:
- Язык и версия
- Фреймворк / библиотека
- База данных (движок, схема)
- Инфраструктура (Docker, CI/CD, хостинг)

### 2.2. High-level архитектура

Описать общую структуру системы:

- **Архитектурный паттерн** — монолит, модульный монолит, микросервисы, слоистая, луковая и т.д.
- **Компоненты и их ответственность** — что делает каждый модуль/сервис
- **Схема взаимодействия** — текстовое описание потоков данных

Формат (text diagram):

```
[Client] → HTTP → [API Gateway] → [Auth Service]
                                         ↓
                              [Core Service] → [Database]
                                         ↓
                              [External API] → [3rd Party]
```

### 2.3. Модули проекта

Разбить систему на модули/пакеты. Для каждого:

| Поле | Описание |
|---|---|
| **Имя модуля** | `app/services/cashflow.py` |
| **Ответственность** | Что делает |
| **Ключевые классы/функции** | Только сигнатуры (без реализации) |
| **Зависимости** | Какие модули нужны этому |
| **Контракт** | Что экспортирует/предоставляет |

### 2.4. Модели данных

Описать основные сущности, их поля и связи:

```json
{
  "entity": "Transaction",
  "fields": [
    {"name": "id", "type": "UUID", "pk": true},
    {"name": "amount", "type": "Decimal"},
    {"name": "date", "type": "datetime"},
    {"name": "category_id", "type": "UUID", "fk": "Category"}
  ]
}
```

Если используется ORM — указать аннотации/декораторы.
Если БД — схему таблиц, индексы, ключи.

### 2.5. API интерфейсы

Если проектируется API — описать эндпоинты:

| Метод | Путь | Описание | Request | Response | Статусы |
|---|---|---|---|---|---|
| GET | /transactions | Список транзакций | ?page, ?limit | [Transaction] | 200 |
| POST | /transactions | Создать транзакцию | CreateTransactionDTO | Transaction | 201, 400 |

Если GUI — описать ключевые страницы/экраны.
Если CLI — описать команды.

### 2.6. Обработка ошибок

- Стратегия ошибок: исключения, Result-тип, коды ошибок
- Формат ошибок в API: `{ "error": "...", "code": "...", "details": {} }`
- Логирование: какой уровень для каких событий

### 2.7. Стратегия тестирования

- Какие тесты нужны (unit, integration, e2e)
- Как изолировать зависимости (mocks, fakes, testcontainers)
- Команда запуска тестов

### 2.8. Alternative Architecture (если config.alternative_arch = yes)

Описать **минимум одну принципиально иную архитектуру** и причину отказа:

| Критерий | Выбранная архитектура | Альтернатива |
|---|---|---|
| Название | Модульный монолит | Микросервисы / Событийная / и т.д. |
| Сложность реализации | Низкая | Высокая (3+ сервиса) |
| Масштабирование | Вертикальное | Горизонтальное |
| Почему не выбрана | — | Избыточно для MVP |

Это снижает риск архитектурной инерции: решение становится осознанным, а не единственным возможным.

### 2.9. ADR (если config.adr = yes)

Для каждого ключевого архитектурного решения (стек, БД, паттерн, структура модулей) создать отдельный ADR-файл:

```
.agent/layer-1/adr/001-технологический-стек.md
.agent/layer-1/adr/002-модульный-монолит.md
.agent/layer-1/adr/003-json-хранение.md
```

Формат — по шаблону `TEMPLATES/adr-NNNN.md`.

### 2.10. Risk Register (если config.risk_register = yes)

Создать `.agent/layer-1/risk-register.md` по шаблону `TEMPLATES/risk-register.md`:

| # | Assumption | Impact if wrong | Mitigation | Review trigger |
|---|---|---|---|---|

Задокументировать **неявные допущения**, на которых держится архитектура. Это даёт future-агентам знать, что можно пересматривать в первую очередь.

### 2.11. Группировка в задачи

На основе спроектированных модулей и моделей предварительно наметить группировку в задачи (по модулям). Это будет входом для DECOMPOSITION.

```
T1: Инициализация проекта + зависимости
T2: Модель данных (сущности, миграции)
T3: Cashflow Service (core logic)
T4: API endpoints
...и т.д.
```

## Выход

- `.agent/design-report.md` по шаблону `TEMPLATES/design-report.md`
- `.agent/layer-1/adr/*.md` (если adr=yes)
- `.agent/layer-1/risk-register.md` (если risk_register=yes)
- Предварительная группировка задач (для передачи в DECOMPOSITION)

Обновить checkpoints.json: `phases.design = "completed"`.

## Критерии завершения фазы

- [ ] Технологический стек определён
- [ ] High-level архитектура описана
- [ ] Модули и их ответственность описаны
- [ ] Модели данных спроектированы
- [ ] API/интерфейсы описаны (если применимо)
- [ ] Стратегия тестирования определена
- [ ] Alternative Architecture описана (если config требует)
- [ ] ADR созданы (если config требует)
- [ ] Risk Register создан (если config требует)
- [ ] Задачи предварительно сгруппированы
- [ ] `.agent/design-report.md` создан
- [ ] checkpoints.json обновлён