nifodea/README.md

CashFlow Forecast

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

Python + Pydantic + JSON + Excel.

Установка

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

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

# Инициализация пустой модели
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. Заголовки колонок соответствуют полям моделей. Затем импортируйте:

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             # Оригинальная архитектурная концепция

Разработка

# Тесты
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 — не настроен.