beginning

2026-07-12 19:51:00 +03:00
parent 940d25435e
commit 5afea8238c
3 changed files with 473 additions and 169 deletions
@@ -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` | `<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`