# Design Report

## Session

- **Session ID:** `metaagent-001`
- **Target repo:** `S:\Git\nifodea`
- **Date:** 2026-07-12

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

| Компонент | Выбор | Обоснование |
|---|---|---|
| Язык | Python 3.11+ | Указан в README как вычислительное ядро; широкая экосистема для работы с данными |
| Фреймворк | Typer (CLI), openpyxl (Excel) | Typer — современный CLI-фреймворк; openpyxl — стандарт для .xlsx |
| База данных | JSON-файлы | README требует JSON как внутреннее представление; для MVP БД не нужна |
| Инфраструктура | pip + venv | Минимальная зависимость; .gitignore уже настроен под Python |
| Линтер | ruff | Стандарт для Python 2024+; быстрый, уже в .gitignore |
| Тесты | pytest | Стандартный тестовый раннер для Python |
| AI | Интерфейс через промпты | Для MVP — только промпты и абстракция, без подключения к API |

## 2. High-Level архитектура

**Паттерн:** Модульный монолит (Layered)

```
[CLI / Excel File]
       |
       ▼
  sync/  ──►  cashflow_model/  ──►  engine/  ──►  ai/
 (Excel R/W)    (Entity Model)     (Forecast)     (Prompts)
       |              |                |
       ▼              ▼                ▼
    data/model.json  data/model.json  data/model.json
```

**Поток данных:**
1. Пользователь редактирует Excel → sync читает и преобразует в JSON
2. JSON-модель загружается в Python-объекты (dataclass)
3. Forecast Engine вычисляет прогноз на основе модели
4. AI Assistant анализирует результаты через промпты
5. Результаты экспортируются обратно в Excel

## 3. Модули

| Модуль | Ответственность | Ключевые компоненты | Зависит от |
|---|---|---|---|
| `cashflow_model/` | Определение сущностей (dataclass), сериализация/десериализация JSON | `Account`, `Transaction`, `RecurringCashflow`, `Asset`, `Liability`, `ForecastScenario`, `FinancialModel` | — |
| `sync/` | Чтение и запись Excel (.xlsx), конвертация между Excel и JSON | `excel_sync.py` — импорт/экспорт | `cashflow_model` |
| `engine/` | Расчёт прогноза, сценарный анализ, what-if | `forecast.py` (прогноз), `scenarios.py` (сценарии) | `cashflow_model` |
| `ai/` | Промпты для AI-ассистента, форматирование контекста | `prompts.py` (шаблоны), `assistant.py` (интерфейс) | `cashflow_model`, `engine` |
| `cli/` | CLI-интерфейс (Typer) | `main.py` — точки входа | Все модули |

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

### Account

| Поле | Тип | Ограничения | Описание |
|---|---|---|---|
| id | UUID | pk | Уникальный идентификатор |
| name | str | required | Название счёта |
| currency | str | default="USD" | Валюта |
| balance | float | required | Текущий баланс |

### Transaction

| Поле | Тип | Ограничения | Описание |
|---|---|---|---|
| id | UUID | pk | Уникальный идентификатор |
| date | str (ISO date) | required | Дата операции |
| account | UUID | fk → Account | Счёт |
| category | str | required | Категория |
| amount | float | required | Сумма |
| description | str | optional | Описание |

### RecurringCashflow

| Поле | Тип | Ограничения | Описание |
|---|---|---|---|
| id | UUID | pk | Уникальный идентификатор |
| start_date | str (ISO date) | required | Дата начала |
| end_date | str (ISO date) | optional | Дата окончания |
| frequency | str | enum: monthly/weekly/yearly | Периодичность |
| amount | float | required | Сумма |
| category | str | required | Категория |

### Asset

| Поле | Тип | Ограничения | Описание |
|---|---|---|---|
| id | UUID | pk | Уникальный идентификатор |
| name | str | required | Название |
| value | float | required | Текущая стоимость |
| growth_rate | float | default=0.0 | Годовой темп роста (%) |

### Liability

| Поле | Тип | Ограничения | Описание |
|---|---|---|---|
| id | UUID | pk | Уникальный идентификатор |
| name | str | required | Название |
| balance | float | required | Текущий остаток |
| interest | float | required | Годовая ставка (%) |
| payment | float | required | Ежемесячный платёж |

**Связи:**
- Transaction → Account (многие к одному)
- RecurringCashflow → Account (многие к одному, опционально)
- FinancialModel включает все сущности + параметры

## 5. API / Интерфейсы

### CLI (Typer)

| Команда | Описание | Пример |
|---|---|---|
| `import <file.xlsx>` | Импорт данных из Excel в JSON | `cf import data.xlsx` |
| `export <file.xlsx>` | Экспорт из JSON в Excel | `cf export report.xlsx` |
| `forecast [--months 12]` | Запуск прогноза | `cf forecast --months 12` |
| `scenario <name>` | Применить сценарий | `cf scenario optimistic` |
| `analyze` | AI-анализ модели | `cf analyze` |
| `init` | Инициализация пустой модели | `cf init` |

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

- **Стратегия:** Исключения Python с кастомными типами (`ModelError`, `SyncError`, `ForecastError`)
- **Формат ошибок:** `{ "error": "<message>", "code": "<CODE>", "details": {} }`
- **Логирование:** logging с уровнями INFO/ERROR; CLI-вывод через Typer + rich

## 7. Тестирование

- **Unit-тесты:** pytest для каждого модуля (cashflow_model, engine, sync)
- **Integration-тесты:** чтение/запись Excel, полный цикл import → forecast → export
- **Mock-стратегия:** временные файлы для Excel/JSON тестов
- **Команда запуска:** `pytest`

## 8. Предварительная группировка задач

| Задача | Описание | Тип |
|---|---|---|
| T1 | Инициализация проекта + scaffold | config |
| T2 | Модель данных (dataclass + JSON serialization) | feature |
| T3 | Forecast Engine (базовый прогноз) | feature |
| T4 | Excel Sync (import/export) | feature |
| T5 | CLI (Typer) — все команды | feature |
| T6 | AI Assistant (промпты + интерфейс) | feature |
| T7 | Тесты на все модули | test |
| T8 | Финальная проверка и документация | docs |

## 9. Примечания

Для MVP берётся минимальный функционал: модель + forecast + excel sync + cli. AI — только интерфейс (заглушка с промптами). Сценарии — базовая реализация.