oqyude
3ef10618dc
- pytest: 67/67 pass - Manual CLI test: init, forecast, scenario, whatif, compare, info, analyze all work; Excel round-trip (export → init → import) preserves data - README.md: обновлён под новую архитектуру domain/application/infrastructure с описанием слоёв, pydantic, Decimal, Repository, DI, schema versioning и расширенным списком команд (config sub-typer с account/transaction/etc) Tests: 67/67 pass. Project: refactor complete — все 5 направлений реализованы.
179 lines
7.4 KiB
Markdown
179 lines
7.4 KiB
Markdown
# 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** — не настроен.
|