beginning
This commit is contained in:
@@ -1,193 +1,118 @@
|
||||
# CashFlow Forecast
|
||||
|
||||
Простой open-source проект для построения и анализа личной финансовой модели с использованием Spreadsheet, Python и AI.
|
||||
Личная финансовая модель с прогнозом денежных потоков, сценарным анализом и AI-ассистентом.
|
||||
|
||||
## Идея
|
||||
Python + JSON + Excel + AI.
|
||||
|
||||
Большинство приложений для учета финансов отвечают на вопрос:
|
||||
## Установка
|
||||
|
||||
> "Что произошло?"
|
||||
|
||||
Этот проект пытается ответить на другой вопрос:
|
||||
|
||||
> "Что произойдет дальше?"
|
||||
|
||||
Основная цель — построение прогнозной модели денежных потоков (Cash Flow Forecasting), позволяющей моделировать различные сценарии будущего.
|
||||
|
||||
## Принципы
|
||||
|
||||
- Spreadsheet используется как удобный визуальный редактор.
|
||||
- Python является вычислительным ядром системы.
|
||||
- JSON служит внутренним представлением модели данных.
|
||||
- AI используется как инструмент анализа и взаимодействия с моделью.
|
||||
- Все компоненты должны быть взаимозаменяемыми.
|
||||
|
||||
## Архитектура
|
||||
|
||||
```
|
||||
User
|
||||
│
|
||||
▼
|
||||
Spreadsheet (UI)
|
||||
│
|
||||
Synchronization Layer
|
||||
(Python)
|
||||
│
|
||||
▼
|
||||
Financial Model
|
||||
(JSON)
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
▼ ▼
|
||||
Forecast Engine AI Assistant
|
||||
Scenario Analysis Data Analysis
|
||||
```bash
|
||||
git clone <repo>
|
||||
cd cashflow-forecast
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Linux/Mac
|
||||
# .venv\Scripts\activate # Windows
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
Spreadsheet рассматривается как пользовательский интерфейс, а не как источник бизнес-логики.
|
||||
## Использование
|
||||
|
||||
## Основные сущности
|
||||
```bash
|
||||
# Инициализация пустой модели
|
||||
cf init
|
||||
|
||||
```
|
||||
Accounts
|
||||
Transactions
|
||||
Assets
|
||||
Liabilities
|
||||
Recurring Cashflows
|
||||
Forecast Scenarios
|
||||
Parameters
|
||||
# Прогноз на 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
|
||||
|
||||
# Импорт/экспорт Excel
|
||||
cf import data.xlsx
|
||||
cf export exports/report.xlsx
|
||||
|
||||
# AI-анализ (заглушка, генерация промпта)
|
||||
cf analyze
|
||||
```
|
||||
|
||||
### Account
|
||||
### Пример: создание тестовых данных
|
||||
|
||||
```
|
||||
id
|
||||
name
|
||||
currency
|
||||
balance
|
||||
Подготовьте Excel-файл с листами: `Accounts`, `Transactions`, `Recurring`, `Assets`, `Liabilities`. Заголовки колонок соответствуют полям моделей. Затем импортируйте:
|
||||
|
||||
```bash
|
||||
cf import my_finances.xlsx
|
||||
cf forecast --months 12
|
||||
```
|
||||
|
||||
### Transaction
|
||||
## Структура проекта
|
||||
|
||||
```
|
||||
id
|
||||
date
|
||||
account
|
||||
category
|
||||
amount
|
||||
description
|
||||
├── cashflow_model/ # Модели данных (dataclass + JSON)
|
||||
│ ├── account.py # Account
|
||||
│ ├── transaction.py # Transaction
|
||||
│ ├── recurring.py # RecurringCashflow
|
||||
│ ├── asset.py # Asset
|
||||
│ ├── liability.py # Liability
|
||||
│ ├── scenario.py # ForecastScenario
|
||||
│ └── model.py # FinancialModel (корень, save/load JSON)
|
||||
├── engine/ # Вычислительное ядро
|
||||
│ ├── forecast.py # ForecastService — прогноз
|
||||
│ └── scenarios.py # ScenarioService — сценарии + what-if
|
||||
├── sync/ # Синхронизация с Excel
|
||||
│ └── excel_sync.py # ExcelSync — import/export .xlsx
|
||||
├── ai/ # AI-ассистент
|
||||
│ ├── prompts.py # Шаблоны промптов
|
||||
│ └── assistant.py # AssistantService (заглушка)
|
||||
├── cli/ # CLI (Typer)
|
||||
│ └── main.py # Команды: cf init/forecast/scenario/...
|
||||
├── tests/ # Тесты pytest
|
||||
│ ├── conftest.py # Фикстуры
|
||||
│ ├── test_model.py
|
||||
│ ├── test_forecast.py
|
||||
│ ├── test_scenarios.py
|
||||
│ ├── test_excel_sync.py
|
||||
│ ├── test_ai.py
|
||||
│ └── test_cli.py
|
||||
├── data/ # JSON-модели
|
||||
├── exports/ # Экспортированные .xlsx
|
||||
├── .agent/ # Артефакты MetaAgent (планирование)
|
||||
├── pyproject.toml # Зависимости и конфигурация
|
||||
└── README.arch.md # Оригинальная архитектурная концепция
|
||||
```
|
||||
|
||||
### Recurring Cashflow
|
||||
## Разработка
|
||||
|
||||
```
|
||||
id
|
||||
start_date
|
||||
end_date
|
||||
frequency
|
||||
amount
|
||||
category
|
||||
```bash
|
||||
# Тесты
|
||||
pytest
|
||||
|
||||
# Линтер
|
||||
ruff check .
|
||||
|
||||
# Автоформат
|
||||
ruff format .
|
||||
```
|
||||
|
||||
### Asset
|
||||
### Зависимости
|
||||
|
||||
```
|
||||
id
|
||||
name
|
||||
value
|
||||
growth_rate
|
||||
```
|
||||
- Python >= 3.11
|
||||
- openpyxl — работа с Excel
|
||||
- typer — CLI
|
||||
- rich — форматирование вывода
|
||||
- pytest — тесты
|
||||
- ruff — линтер
|
||||
|
||||
### Liability
|
||||
## Известные ограничения (MVP)
|
||||
|
||||
```
|
||||
id
|
||||
name
|
||||
balance
|
||||
interest
|
||||
payment
|
||||
```
|
||||
|
||||
## Основной цикл
|
||||
|
||||
```
|
||||
Spreadsheet
|
||||
│
|
||||
▼
|
||||
Python Import
|
||||
│
|
||||
▼
|
||||
JSON Model
|
||||
│
|
||||
▼
|
||||
Forecast Calculation
|
||||
│
|
||||
▼
|
||||
Scenario Simulation
|
||||
│
|
||||
▼
|
||||
AI Analysis
|
||||
│
|
||||
▼
|
||||
Spreadsheet Export
|
||||
```
|
||||
|
||||
## Возможности
|
||||
|
||||
- прогноз денежных потоков;
|
||||
- моделирование бюджета;
|
||||
- сценарный анализ;
|
||||
- учет активов и обязательств;
|
||||
- прогноз ликвидности;
|
||||
- анализ финансовой устойчивости;
|
||||
- моделирование достижения финансовых целей;
|
||||
- анализ "что если" (What-if Analysis).
|
||||
|
||||
|
||||
## Будущие возможности
|
||||
|
||||
- Monte-Carlo Simulation;
|
||||
- FIRE Planning;
|
||||
- инвестиционный прогноз;
|
||||
- импорт банковских выписок;
|
||||
- импорт брокерских отчетов;
|
||||
- REST API;
|
||||
- Web UI;
|
||||
- Mobile App;
|
||||
- AI Financial Assistant.
|
||||
|
||||
|
||||
## Структура репозитория
|
||||
|
||||
```
|
||||
cashflow-forecast/
|
||||
|
||||
├── README.md
|
||||
├── spreadsheet/
|
||||
│ model.xlsx
|
||||
│
|
||||
├── data/
|
||||
│ model.json
|
||||
│
|
||||
├── sync/
|
||||
│ excel_sync.py
|
||||
│
|
||||
├── engine/
|
||||
│ forecast.py
|
||||
│ scenarios.py
|
||||
│
|
||||
├── ai/
|
||||
│ prompts.py
|
||||
│ assistant.py
|
||||
│
|
||||
├── exports/
|
||||
│
|
||||
└── docs/
|
||||
```
|
||||
|
||||
## Долгосрочная идея
|
||||
|
||||
На ранних этапах Spreadsheet используется как быстрый инструмент проектирования финансовой модели.
|
||||
|
||||
По мере развития проекта вычисления и логика постепенно переносятся в Python, а Spreadsheet превращается исключительно в средство отображения и редактирования данных.
|
||||
|
||||
Конечной целью является независимый интерактивный open-source инструмент для персонального финансового планирования и прогнозирования денежных потоков, в котором AI выступает естественным интерфейсом для анализа и построения сценариев.
|
||||
- **AI-ассистент** — заглушка. Промпты готовы, но не подключены к API.
|
||||
- **База данных** — JSON-файлы (не подходит для многопользовательской работы).
|
||||
- **Excel** — только `.xlsx` через openpyxl.
|
||||
- **Лицензия** — не выбрана.
|
||||
|
||||
Reference in New Issue
Block a user