nifodea/.agent/context/analysis-report.md

Analysis Report

Session ID: metaagent-005 Target repo: /home/oqyude/External/Git/nifodea Date: 2026-10-08 Project type: existing MetaAgent version: 3.0.0

---

1. Общая информация

Параметр	Значение
Название	CashFlow Forecast
Назначение	Личная финансовая модель с прогнозом денежных потоков, сценарным анализом, what-if и AI-ассистентом
Лицензия	не выбрана (есть файл LICENSE с шаблоном, требует ревизии)
CI/CD	отсутствует (нет .github/, .gitlab-ci.yml, Makefile)
Точка входа	cli/main.py → команда cf (через pyproject.toml [project.scripts])
Система сборки	pyproject.toml (setuptools, build-backend=setuptools.build_meta)
Версия	0.1.0

2. Стек технологий

Компонент	Значение
Язык	Python >= 3.11 (тестировалось на 3.14)
CLI-фреймворк	Typer >= 0.9 (через typer entry-point)
Файлы данных	JSON (через pathlib + json)
Excel I/O	openpyxl >= 3.1
Терминал-вывод	rich >= 13.0
Тесты	pytest 9.x
Линтер	ruff 0.16.x (line-length 120, rules E/F/I/N/W)
Пакетный менеджер	pip (через .venv)
UUID-генерация	uuid4 (для ID моделей)
Dataclass-сериализация	ручные to_dict / from_dict

3. Архитектура

Паттерн: модульный монолит (5 пакетов, чёткие границы ответственности).

┌─────────────────────────────────────────────┐
│ cli/ — Typer CLI (cf init/forecast/...)    │
└──────────────────┬──────────────────────────┘
                   │
       ┌───────────┼───────────┐
       ▼           ▼           ▼
   ┌───────┐  ┌─────────┐  ┌──────┐
   │ ai/   │  │ engine/ │  │sync/ │
   │prompts│  │forecast │  │excel │
   │asst   │  │scenario │  │      │
   └───┬───┘  └────┬────┘  └──┬───┘
       │           │          │
       └─────────┬─┴──────────┘
                 ▼
        ┌────────────────┐
        │ cashflow_model │  ← Account, Transaction, Recurring,
        │  (dataclasses) │    Asset, Liability, Scenario, Currency
        └────────────────┘

Принцип (из README.arch.md):

• Spreadsheet — UI (через sync/excel_sync.py)
• Python — вычислительное ядро (engine/)
• JSON — внутреннее представление (cashflow_model/)
• AI — инструмент анализа (ai/, пока stub)

4. Структура (depth=2)

nifodea/
├── AGENTS.md                       # MetaAgent context для агента
├── LICENSE                         # шаблон, не выбрана
├── README.md                       # инструкции пользователя
├── README.arch.md                  # архитектурная концепция
├── pyproject.toml                  # setuptools + deps + entry-point cf
├── .gitignore                      # python + .temp/ (MetaAgent)
│
├── cashflow_model/                 # 7 dataclass-моделей + Currency
│   ├── account.py, transaction.py, recurring.py, asset.py, liability.py
│   ├── scenario.py, currency.py, model.py (root), __init__.py
│
├── engine/                         # вычислительное ядро
│   ├── forecast.py (ForecastService)
│   ├── scenarios.py (ScenarioService + what-if)
│
├── sync/                           # Excel-импорт/экспорт
│   └── excel_sync.py
│
├── ai/                             # AI-ассистент (stub)
│   ├── prompts.py
│   └── assistant.py
│
├── cli/                            # Typer CLI
│   ├── main.py (~330 LOC, 8 команд)
│   ├── i18n.py (~350 LOC, ru/en)
│   └── config.py (~428 LOC)
│
├── tests/                          # pytest, 9 файлов
│   ├── conftest.py (фикстуры: sample_model, empty_model, sample_converter)
│   └── test_*.py (9 файлов)
│
├── data/                           # JSON-модели (runtime)
└── exports/                        # экспортированные .xlsx

5. Ключевые модули и их ответственность

Модуль	Ответственность	LOC
cashflow_model/model.py	Корневая модель FinancialModel (агрегатор + JSON save/load)	61
cashflow_model/currency.py	CurrencyConverter, ExchangeRate, символы валют	79
cashflow_model/*.py	Датаклассы: Account, Transaction, Recurring, Asset, Liability, Scenario	~150
engine/forecast.py	ForecastService.forecast_cashflow() — посуточный/помесячный прогноз	103
engine/scenarios.py	ScenarioService (baseline/optimistic/pessimistic) + what-if	87
sync/excel_sync.py	ExcelSync — импорт/экспорт .xlsx ↔ FinancialModel	135
ai/prompts.py	Шаблоны промптов для AI (analyze, advice, scenario_comparison)	21
ai/assistant.py	AssistantService — генерирует промпт, но НЕ вызывает API (stub)	69
cli/main.py	Typer-приложение: cf init/forecast/scenario/whatif/compare/import/export/analyze	330
cli/config.py	Загрузка/сохранение FinancialModel в data/, пути по умолчанию	428
cli/i18n.py	t()-обёртка, словари _r()/_e(), ru (default) / en (fallback)	350

Всего: ~2479 строк кода + 9 тестовых файлов.

6. Конвенции

Аспект	Соглашение
Стиль кода	snake_case (функции/переменные), PascalCase (классы), UPPER_SNAKE (константы)
Датаклассы	@dataclass + ручные to_dict / from_dict (без pydantic/attrs)
ID	uuid.UUID через field(default_factory=uuid4)
Суммы	float (без Decimal, есть риск округления)
Даты	ISO-строки "YYYY-MM-DD" (без datetime)
Исключения	Доменные классы: CurrencyError, AssistantError (наследуют Exception)
Логирование	rich.print для UI; явное логирование не используется
Валюты	По умолчанию RUB; поддержка USD, EUR, GBP, CNY, JPY, KZT, UAH
CLI-фреймворк	Typer (декораторы @app.command())
i18n	Кастомный t(key, **kwargs) с fallback на русский

7. Тесты

Параметр	Значение
Раннер	pytest 9.1
Расположение	tests/test_*.py
Фикстуры	sample_model, empty_model, sample_converter (в conftest.py)
Покрытие	9 тестовых модулей: model, currency, forecast, scenarios, excel_sync, ai, cli, i18n
Baseline	63/63 PASSED (4.64s)
Отчёт	.agent/context/baseline-test-report.log

8. Сборка / запуск

# Установка (editable)
.venv/bin/pip install -e .

# С дев-зависимостями (если добавить)
.venv/bin/pip install -e ".[dev]"

# Тесты
.venv/bin/pytest

# Линтер
.venv/bin/python -m ruff check .

# CLI
cf init
cf forecast --months 12
cf scenario baseline
cf compare --months 12

9. Известные ограничения (MVP)

Из README.md и README.arch.md:

• AI-ассистент — заглушка. AssistantService.analyze() возвращает dict с "ai_response": None. API не подключён. Примечание 2026-10-08: пользователь решил, что AI-интеграция не в скоупе — модуль ai/ остаётся как есть.
• Хранилище — JSON-файлы. Не подходит для многопользовательской работы.
• Excel — только .xlsx через openpyxl.
• Лицензия не выбрана.
• CI/CD отсутствует.
• Нет FUTURE/ для долгосрочных планов.
• Тесты не интеграционные с реальным Excel-файлом (только in-memory).

10. Будущие возможности (из README.arch.md)

• Monte-Carlo Simulation
• FIRE Planning
• Инвестиционный прогноз
• Импорт банковских выписок / брокерских отчётов
• REST API
• Web UI
• Mobile App
• AI Financial Assistant (полная реализация)

11. Git-состояние

Параметр	Значение
HEAD	12611ed metaagent update
Всего коммитов	8
Незакоммиченные изменения	есть (миграция .agent/ с v1.1 → v3.0) — задокументировано в .agent/migration-report.log
Ветка	(не проверено)

12. Что НЕ делает MetaAgent в этом проекте

• Не пишет production-код (по project-rules.md).
• Не удаляет файлы.
• Не коммитит в main/master.