From 5afea8238cdb9885d6bd60952a881c8780ca8fd3 Mon Sep 17 00:00:00 2001 From: oqyude Date: Sun, 12 Jul 2026 19:51:00 +0300 Subject: [PATCH] beginning --- AGENTS.md | 186 ++++++++++++++++++++++++++++++++++ README.arch.md | 193 ++++++++++++++++++++++++++++++++++++ README.md | 263 ++++++++++++++++++------------------------------- 3 files changed, 473 insertions(+), 169 deletions(-) create mode 100644 AGENTS.md create mode 100644 README.arch.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..191b7dc --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,186 @@ +# AGENTS.md — контекст для AI-сессий + +## Project Overview + +**CashFlow Forecast** — личная финансовая модель с прогнозом денежных потоков. Python CLI-инструмент. + +**Цель:** отвечать на вопрос "что произойдет дальше?" (forecast), а не "что произошло?" (accounting). + +**Стек:** Python 3.11+, JSON (хранение), openpyxl (Excel), typer (CLI), rich (вывод), pytest (тесты), ruff (линтер). + +**Тип проекта:** greenfield, MVP реализован. + +--- + +## Quick Start + +```bash +source .venv/bin/activate +cf init +cf forecast --months 12 +pytest +ruff check . +``` + +--- + +## Архитектура + +Модульный монолит (layered): + +``` +[CLI / Excel File] + | + v + sync/ --> cashflow_model/ --> engine/ --> ai/ + (Excel R/W) (Entity Model) (Forecast) (Prompts) + | | | + v v v + data/model.json data/model.json data/model.json +``` + +**Поток данных:** +1. Excel -> sync (импорт) -> JSON +2. JSON -> cashflow_model (dataclass) +3. engine (forecast) читает модель +4. ai (assistant) анализирует результаты +5. Результаты -> sync (экспорт) -> Excel + +--- + +## Модули + +| Модуль | Ответственность | Ключевые файлы | +|---|---|---| +| `cashflow_model/` | dataclass-сущности + JSON serialization | `model.py`, `account.py`, `transaction.py`, `recurring.py`, `asset.py`, `liability.py`, `scenario.py` | +| `engine/` | ForecastService, ScenarioService | `forecast.py`, `scenarios.py` | +| `sync/` | Excel <-> JSON | `excel_sync.py` | +| `ai/` | Промпты, AssistantService (заглушка) | `prompts.py`, `assistant.py` | +| `cli/` | Typer CLI | `main.py` | + +--- + +## Data Model + +### Account +| Поле | Тип | +|---|---| +| id | UUID | +| name | str | +| currency | str (default USD) | +| balance | float | + +### Transaction +| Поле | Тип | +|---|---| +| id | UUID | +| date | str (ISO) | +| account | str (UUID счёта) | +| category | str | +| amount | float (positive=income, negative=expense) | +| description | str | + +### RecurringCashflow +| Поле | Тип | +|---|---| +| id | UUID | +| start_date | str (ISO) | +| end_date | str (ISO, optional) | +| frequency | str (monthly/weekly/yearly) | +| amount | float | +| category | str | + +### Asset +| Поле | Тип | +|---|---| +| id | UUID | +| name | str | +| value | float | +| growth_rate | float (% годовых) | + +### Liability +| Поле | Тип | +|---|---| +| id | UUID | +| name | str | +| balance | float | +| interest | float (% годовых) | +| payment | float (ежемесячный) | + +### ForecastScenario +| Поле | Тип | +|---|---| +| id | UUID | +| name | str (baseline/optimistic/pessimistic) | +| income_multiplier | float | +| expense_multiplier | float | +| growth_multiplier | float | + +**FinancialModel** — корневой объект, содержит списки всех сущностей. Методы: `save(path)`, `load(path)`. JSON-файл в `data/model.json`. + +--- + +## CLI Reference + +Команда `cf` (entry point: `cli.main:app`): + +| Команда | Аргументы | Описание | +|---|---|---| +| `init` | — | Создать пустую модель | +| `forecast` | `--months 12` | Прогноз cashflow | +| `scenario` | `` | Сценарий baseline/optimistic/pessimistic | +| `whatif` | `--income 1.0 --expense 1.0 --growth 1.0` | What-if анализ | +| `compare` | `--months 12` | Сравнение сценариев | +| `import` | `` | Импорт из Excel | +| `export` | `` | Экспорт в Excel | +| `analyze` | `--months 12` | AI-анализ (промпт + заглушка) | + +--- + +## Coding Conventions + +- Python 3.11+, dataclass для моделей +- from_dict/to_dict для JSON-сериализации +- ruff (E, F, I, N, W), line-length=100 +- pytest для тестов +- typer + rich для CLI +- f-строки, без лишних комментариев +- Имена: snake_case, классы PascalCase + +--- + +## Commands + +```bash +pytest # запуск тестов (26 tests) +ruff check . # линтер +ruff format . # автоформат +cf # запуск CLI +``` + +--- + +## Known Issues / TODOs + +- AI-ассистент — заглушка (`ai/assistant.py`). Промпты готовы, нужно подключить API (OpenAI и т.д.) +- Нет лицензии — требуется выбрать +- JSON-файлы — нет конкурентного доступа +- Excel — только .xlsx (openpyxl), нет поддержки Google Sheets +- Нет веб-интерфейса, только CLI +- `engine/forecast.py` — упрощённый алгоритм (без Monte Carlo) + +--- + +## .agent/ directory + +Директория `.agent/` содержит артефакты MetaAgent — планирование, дизайн, декомпозицию задач. **Не удалять**. Там же `checkpoints.json` с состоянием задач. + +--- + +## Границы (Boundaries) + +**Что НЕ входит в задачу AI-агента:** +- Изменение архитектуры без обсуждения с пользователем +- Подключение внешних платных API без согласования +- Массовый рефакторинг без acceptance criteria +- Удаление `.agent/` или `README.arch.md` diff --git a/README.arch.md b/README.arch.md new file mode 100644 index 0000000..4326327 --- /dev/null +++ b/README.arch.md @@ -0,0 +1,193 @@ +# CashFlow Forecast + +Простой open-source проект для построения и анализа личной финансовой модели с использованием Spreadsheet, Python и 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 +``` + +Spreadsheet рассматривается как пользовательский интерфейс, а не как источник бизнес-логики. + +## Основные сущности + +``` +Accounts +Transactions +Assets +Liabilities +Recurring Cashflows +Forecast Scenarios +Parameters +``` + +### Account + +``` +id +name +currency +balance +``` + +### Transaction + +``` +id +date +account +category +amount +description +``` + +### Recurring Cashflow + +``` +id +start_date +end_date +frequency +amount +category +``` + +### Asset + +``` +id +name +value +growth_rate +``` + +### Liability + +``` +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 выступает естественным интерфейсом для анализа и построения сценариев. diff --git a/README.md b/README.md index 4326327..c38d2cb 100644 --- a/README.md +++ b/README.md @@ -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 +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. +- **Лицензия** — не выбрана.