# 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` | `<name>` | Сценарий baseline/optimistic/pessimistic |
| `whatif` | `--income 1.0 --expense 1.0 --growth 1.0` | What-if анализ |
| `compare` | `--months 12` | Сравнение сценариев |
| `import` | `<path.xlsx>` | Импорт из Excel |
| `export` | `<path.xlsx>` | Экспорт в 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 <command>        # запуск 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`