# CashFlow Forecast

Личная финансовая модель с прогнозом денежных потоков, сценарным анализом.

Python + Pydantic + JSON + Excel.

## Установка

```bash
git clone <repo>
cd cashflow-forecast
python -m venv .venv
source .venv/bin/activate    # Linux/Mac
# .venv\Scripts\activate     # Windows
pip install -e .
```

## Использование

```bash
# Инициализация пустой модели
cf init

# Прогноз на 12 месяцев
cf forecast --months 12

# Сценарии
cf scenario baseline
cf scenario optimistic
cf scenario pessimistic

# What-if анализ
cf whatif --income 1.2 --expense 0.9 --growth 1.0 --months 12

# Сравнение всех сценариев
cf compare --months 12

# Сводка модели
cf info

# Редактирование модели
cf config account-add --name "Main" --balance 5000
cf config transaction-add --account Main --amount -1200 --category rent
cf config rate-set USD RUB 80.0

# Импорт/экспорт Excel
cf import-xlsx data.xlsx
cf export-xlsx exports/report.xlsx
```

### Пример: создание тестовых данных

Подготовьте Excel-файл с листами: `Accounts`, `Transactions`, `Recurring`, `Assets`, `Liabilities`. Заголовки колонок соответствуют полям моделей. Затем импортируйте:

```bash
cf import-xlsx my_finances.xlsx
cf forecast --months 12
```

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

Проект разделён на три слоя по принципам Clean Architecture:

```
┌─────────────────────────────────────────────┐
│          domain/ — бизнес-модели             │
│  Account, Transaction, Asset, Liability,   │
│  Recurring, Scenario, FinancialModel,      │
│  ExchangeRate, CurrencyConverter            │
│  (pydantic.BaseModel, Decimal)              │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│   application/ — прикладные сервисы         │
│  ForecastService, ScenarioService,         │
│  ModelRepository (Protocol)                 │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│  infrastructure/ — внешний мир              │
│  cli/ (Typer), ai/ (Assistant),             │
│  repositories/ (JsonFile, Excel)            │
└─────────────────────────────────────────────┘
```

## Структура проекта

```
cashflow-forecast/
├── domain/                    # Бизнес-модели (pydantic + Decimal)
│   ├── account.py             # Account
│   ├── transaction.py         # Transaction
│   ├── recurring.py           # RecurringCashflow
│   ├── asset.py               # Asset
│   ├── liability.py           # Liability
│   ├── scenario.py            # ForecastScenario
│   ├── currency.py            # ExchangeRate + CurrencyConverter
│   └── model.py               # FinancialModel (корень)
│
├── application/               # Прикладные сервисы
│   ├── forecast.py            # ForecastService — прогноз
│   ├── scenarios.py           # ScenarioService — сценарии + what-if
│   └── repositories/
│       └── model_repository.py  # ModelRepository Protocol
│
├── infrastructure/            # Адаптеры к внешнему миру
│   ├── cli/                   # Typer CLI (cf ...)
│   │   ├── app.py             # Entry point
│   │   ├── commands/          # 9 файлов команд + config sub-typer
│   │   ├── paths.py           # DATA_DIR, MODEL_PATH
│   │   ├── services.py        # Composition root + helpers
│   │   └── i18n.py            # ru/en переводы
│   ├── ai/                    # AI-ассистент (заглушка)
│   │   ├── prompts.py
│   │   └── assistant.py       # AssistantService
│   └── repositories/          # Реализации ModelRepository
│       ├── json_file_repository.py
│       └── excel_repository.py
│
├── tests/                     # pytest, 67 тестов
│   ├── conftest.py
│   ├── test_model.py
│   ├── test_forecast.py
│   ├── test_scenarios.py
│   ├── test_currency.py
│   ├── test_ai.py
│   ├── test_cli.py
│   ├── test_excel_sync.py     # Тесты ExcelRepository
│   ├── test_i18n.py
│   └── test_repositories.py   # Тесты репозиториев
│
├── data/                      # JSON-модели (runtime, версионируется SCHEMA_VERSION=1)
├── exports/                   # Экспортированные .xlsx
├── .agent/                    # Артефакты MetaAgent v3.0
├── pyproject.toml             # Зависимости + entry point `cf`
└── README.arch.md             # Оригинальная архитектурная концепция
```

## Разработка

```bash
# Тесты
pytest

# Линтер (если доступен ruff)
ruff check .

# Автоформат
ruff format .
```

### Зависимости

- Python >= 3.11
- openpyxl — работа с Excel
- typer — CLI
- rich — форматирование вывода
- pydantic >= 2.0 — валидация моделей
- pytest — тесты
- ruff — линтер (опционально)

## Архитектурные решения

- **Слои**: `domain/` (модели), `application/` (сервисы), `infrastructure/` (адаптеры).
- **Pydantic v2**: все модели — `pydantic.BaseModel` с валидацией (balance >= 0, amount != 0, и т.п.).
- **Decimal**: все денежные поля — `Decimal`, арифметика без потери точности.
- **Repository pattern**: `ModelRepository` Protocol, реализации `JsonFileRepository` и `ExcelRepository`.
- **DI**: Composition root в `infrastructure/cli/services.py:build_services()`.
- **Schema versioning**: `FinancialModel.to_dict()` пишет `version: 1`; `from_dict()` поддерживает legacy v0.
- **i18n**: `infrastructure/cli/i18n.py`, ru (default) + en (fallback).

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

- **AI-ассистент** — заглушка (`ai_response: None`). Промпты готовы, но не подключены к API.
- **Хранилище** — JSON-файлы (не подходит для многопользовательской работы).
- **Excel** — только `.xlsx` через openpyxl.
- **Лицензия** — не выбрана.
- **CI/CD** — не настроен.