187 lines
5.5 KiB
Markdown
187 lines
5.5 KiB
Markdown
# 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`
|