# Analysis Report

**Session ID:** `metaagent-005`
**Target repo:** `/home/oqyude/External/Git/nifodea`
**Date:** 2026-10-08
**Project type:** `existing`
**MetaAgent version:** 3.0.0

---

## 1. Общая информация

| Параметр | Значение |
|---|---|
| Название | CashFlow Forecast |
| Назначение | Личная финансовая модель с прогнозом денежных потоков, сценарным анализом, what-if и AI-ассистентом |
| Лицензия | не выбрана (есть файл `LICENSE` с шаблоном, требует ревизии) |
| CI/CD | отсутствует (нет `.github/`, `.gitlab-ci.yml`, `Makefile`) |
| Точка входа | `cli/main.py` → команда `cf` (через `pyproject.toml [project.scripts]`) |
| Система сборки | `pyproject.toml` (setuptools, build-backend=setuptools.build_meta) |
| Версия | 0.1.0 |

## 2. Стек технологий

| Компонент | Значение |
|---|---|
| Язык | Python >= 3.11 (тестировалось на 3.14) |
| CLI-фреймворк | Typer >= 0.9 (через `typer` entry-point) |
| Файлы данных | JSON (через `pathlib` + `json`) |
| Excel I/O | openpyxl >= 3.1 |
| Терминал-вывод | rich >= 13.0 |
| Тесты | pytest 9.x |
| Линтер | ruff 0.16.x (line-length 120, rules E/F/I/N/W) |
| Пакетный менеджер | pip (через `.venv`) |
| UUID-генерация | uuid4 (для ID моделей) |
| Dataclass-сериализация | ручные `to_dict` / `from_dict` |

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

**Паттерн:** модульный монолит (5 пакетов, чёткие границы ответственности).

```
┌─────────────────────────────────────────────┐
│ cli/ — Typer CLI (cf init/forecast/...)    │
└──────────────────┬──────────────────────────┘
                   │
       ┌───────────┼───────────┐
       ▼           ▼           ▼
   ┌───────┐  ┌─────────┐  ┌──────┐
   │ ai/   │  │ engine/ │  │sync/ │
   │prompts│  │forecast │  │excel │
   │asst   │  │scenario │  │      │
   └───┬───┘  └────┬────┘  └──┬───┘
       │           │          │
       └─────────┬─┴──────────┘
                 ▼
        ┌────────────────┐
        │ cashflow_model │  ← Account, Transaction, Recurring,
        │  (dataclasses) │    Asset, Liability, Scenario, Currency
        └────────────────┘
```

**Принцип** (из `README.arch.md`):
- Spreadsheet — UI (через `sync/excel_sync.py`)
- Python — вычислительное ядро (`engine/`)
- JSON — внутреннее представление (`cashflow_model/`)
- AI — инструмент анализа (`ai/`, пока stub)

## 4. Структура (depth=2)

```
nifodea/
├── AGENTS.md                       # MetaAgent context для агента
├── LICENSE                         # шаблон, не выбрана
├── README.md                       # инструкции пользователя
├── README.arch.md                  # архитектурная концепция
├── pyproject.toml                  # setuptools + deps + entry-point cf
├── .gitignore                      # python + .temp/ (MetaAgent)
│
├── cashflow_model/                 # 7 dataclass-моделей + Currency
│   ├── account.py, transaction.py, recurring.py, asset.py, liability.py
│   ├── scenario.py, currency.py, model.py (root), __init__.py
│
├── engine/                         # вычислительное ядро
│   ├── forecast.py (ForecastService)
│   ├── scenarios.py (ScenarioService + what-if)
│
├── sync/                           # Excel-импорт/экспорт
│   └── excel_sync.py
│
├── ai/                             # AI-ассистент (stub)
│   ├── prompts.py
│   └── assistant.py
│
├── cli/                            # Typer CLI
│   ├── main.py (~330 LOC, 8 команд)
│   ├── i18n.py (~350 LOC, ru/en)
│   └── config.py (~428 LOC)
│
├── tests/                          # pytest, 9 файлов
│   ├── conftest.py (фикстуры: sample_model, empty_model, sample_converter)
│   └── test_*.py (9 файлов)
│
├── data/                           # JSON-модели (runtime)
└── exports/                        # экспортированные .xlsx
```

## 5. Ключевые модули и их ответственность

| Модуль | Ответственность | LOC |
|---|---|---|
| `cashflow_model/model.py` | Корневая модель `FinancialModel` (агрегатор + JSON save/load) | 61 |
| `cashflow_model/currency.py` | `CurrencyConverter`, `ExchangeRate`, символы валют | 79 |
| `cashflow_model/*.py` | Датаклассы: Account, Transaction, Recurring, Asset, Liability, Scenario | ~150 |
| `engine/forecast.py` | `ForecastService.forecast_cashflow()` — посуточный/помесячный прогноз | 103 |
| `engine/scenarios.py` | `ScenarioService` (baseline/optimistic/pessimistic) + what-if | 87 |
| `sync/excel_sync.py` | `ExcelSync` — импорт/экспорт `.xlsx` ↔ `FinancialModel` | 135 |
| `ai/prompts.py` | Шаблоны промптов для AI (analyze, advice, scenario_comparison) | 21 |
| `ai/assistant.py` | `AssistantService` — генерирует промпт, но НЕ вызывает API (stub) | 69 |
| `cli/main.py` | Typer-приложение: `cf init/forecast/scenario/whatif/compare/import/export/analyze` | 330 |
| `cli/config.py` | Загрузка/сохранение `FinancialModel` в `data/`, пути по умолчанию | 428 |
| `cli/i18n.py` | `t()`-обёртка, словари `_r()`/`_e()`, ru (default) / en (fallback) | 350 |

**Всего:** ~2479 строк кода + 9 тестовых файлов.

## 6. Конвенции

| Аспект | Соглашение |
|---|---|
| Стиль кода | snake_case (функции/переменные), PascalCase (классы), UPPER_SNAKE (константы) |
| Датаклассы | `@dataclass` + ручные `to_dict` / `from_dict` (без `pydantic`/`attrs`) |
| ID | `uuid.UUID` через `field(default_factory=uuid4)` |
| Суммы | `float` (без `Decimal`, есть риск округления) |
| Даты | ISO-строки `"YYYY-MM-DD"` (без `datetime`) |
| Исключения | Доменные классы: `CurrencyError`, `AssistantError` (наследуют `Exception`) |
| Логирование | `rich.print` для UI; явное логирование не используется |
| Валюты | По умолчанию RUB; поддержка USD, EUR, GBP, CNY, JPY, KZT, UAH |
| CLI-фреймворк | Typer (декораторы `@app.command()`) |
| i18n | Кастомный `t(key, **kwargs)` с fallback на русский |

## 7. Тесты

| Параметр | Значение |
|---|---|
| Раннер | pytest 9.1 |
| Расположение | `tests/test_*.py` |
| Фикстуры | `sample_model`, `empty_model`, `sample_converter` (в `conftest.py`) |
| Покрытие | 9 тестовых модулей: model, currency, forecast, scenarios, excel_sync, ai, cli, i18n |
| Baseline | **63/63 PASSED** (4.64s) |
| Отчёт | `.agent/context/baseline-test-report.log` |

## 8. Сборка / запуск

```bash
# Установка (editable)
.venv/bin/pip install -e .

# С дев-зависимостями (если добавить)
.venv/bin/pip install -e ".[dev]"

# Тесты
.venv/bin/pytest

# Линтер
.venv/bin/python -m ruff check .

# CLI
cf init
cf forecast --months 12
cf scenario baseline
cf compare --months 12
```

## 9. Известные ограничения (MVP)

Из `README.md` и `README.arch.md`:

- **AI-ассистент — заглушка.** `AssistantService.analyze()` возвращает dict с `"ai_response": None`. API не подключён. *Примечание 2026-10-08: пользователь решил, что AI-интеграция не в скоупе — модуль `ai/` остаётся как есть.*
- **Хранилище — JSON-файлы.** Не подходит для многопользовательской работы.
- **Excel — только `.xlsx`** через openpyxl.
- **Лицензия не выбрана.**
- **CI/CD отсутствует.**
- **Нет `FUTURE/`** для долгосрочных планов.
- **Тесты не интеграционные** с реальным Excel-файлом (только in-memory).

## 10. Будущие возможности (из README.arch.md)

- Monte-Carlo Simulation
- FIRE Planning
- Инвестиционный прогноз
- Импорт банковских выписок / брокерских отчётов
- REST API
- Web UI
- Mobile App
- AI Financial Assistant (полная реализация)

## 11. Git-состояние

| Параметр | Значение |
|---|---|
| HEAD | `12611ed metaagent update` |
| Всего коммитов | 8 |
| Незакоммиченные изменения | есть (миграция `.agent/` с v1.1 → v3.0) — задокументировано в `.agent/migration-report.log` |
| Ветка | (не проверено) |

## 12. Что НЕ делает MetaAgent в этом проекте

- Не пишет production-код (по `project-rules.md`).
- Не удаляет файлы.
- Не коммитит в main/master.