nifodea/.agent/design-report.md

Design Report

Session

• Session ID: metaagent-001
• Target repo: S:\Git\nifodea
• Date: 2026-07-12

1. Технологический стек

Компонент	Выбор	Обоснование
Язык	Python 3.11+	Указан в README как вычислительное ядро; широкая экосистема для работы с данными
Фреймворк	Typer (CLI), openpyxl (Excel)	Typer — современный CLI-фреймворк; openpyxl — стандарт для .xlsx
База данных	JSON-файлы	README требует JSON как внутреннее представление; для MVP БД не нужна
Инфраструктура	pip + venv	Минимальная зависимость; .gitignore уже настроен под Python
Линтер	ruff	Стандарт для Python 2024+; быстрый, уже в .gitignore
Тесты	pytest	Стандартный тестовый раннер для Python
AI	Интерфейс через промпты	Для MVP — только промпты и абстракция, без подключения к API

2. High-Level архитектура

Паттерн: Модульный монолит (Layered)

[CLI / Excel File]
       |
       ▼
  sync/  ──►  cashflow_model/  ──►  engine/  ──►  ai/
 (Excel R/W)    (Entity Model)     (Forecast)     (Prompts)
       |              |                |
       ▼              ▼                ▼
    data/model.json  data/model.json  data/model.json

Поток данных:

1. Пользователь редактирует Excel → sync читает и преобразует в JSON
2. JSON-модель загружается в Python-объекты (dataclass)
3. Forecast Engine вычисляет прогноз на основе модели
4. AI Assistant анализирует результаты через промпты
5. Результаты экспортируются обратно в Excel

3. Модули

Модуль	Ответственность	Ключевые компоненты	Зависит от
cashflow_model/	Определение сущностей (dataclass), сериализация/десериализация JSON	Account, Transaction, RecurringCashflow, Asset, Liability, ForecastScenario, FinancialModel	—
sync/	Чтение и запись Excel (.xlsx), конвертация между Excel и JSON	excel_sync.py — импорт/экспорт	cashflow_model
engine/	Расчёт прогноза, сценарный анализ, what-if	forecast.py (прогноз), scenarios.py (сценарии)	cashflow_model
ai/	Промпты для AI-ассистента, форматирование контекста	prompts.py (шаблоны), assistant.py (интерфейс)	cashflow_model, engine
cli/	CLI-интерфейс (Typer)	main.py — точки входа	Все модули

4. Модели данных

Account

Поле	Тип	Ограничения	Описание
id	UUID	pk	Уникальный идентификатор
name	str	required	Название счёта
currency	str	default="USD"	Валюта
balance	float	required	Текущий баланс

Transaction

Поле	Тип	Ограничения	Описание
id	UUID	pk	Уникальный идентификатор
date	str (ISO date)	required	Дата операции
account	UUID	fk → Account	Счёт
category	str	required	Категория
amount	float	required	Сумма
description	str	optional	Описание

RecurringCashflow

Поле	Тип	Ограничения	Описание
id	UUID	pk	Уникальный идентификатор
start_date	str (ISO date)	required	Дата начала
end_date	str (ISO date)	optional	Дата окончания
frequency	str	enum: monthly/weekly/yearly	Периодичность
amount	float	required	Сумма
category	str	required	Категория

Asset

Поле	Тип	Ограничения	Описание
id	UUID	pk	Уникальный идентификатор
name	str	required	Название
value	float	required	Текущая стоимость
growth_rate	float	default=0.0	Годовой темп роста (%)

Liability

Поле	Тип	Ограничения	Описание
id	UUID	pk	Уникальный идентификатор
name	str	required	Название
balance	float	required	Текущий остаток
interest	float	required	Годовая ставка (%)
payment	float	required	Ежемесячный платёж

Связи:

• Transaction → Account (многие к одному)
• RecurringCashflow → Account (многие к одному, опционально)
• FinancialModel включает все сущности + параметры

5. API / Интерфейсы

CLI (Typer)

Команда	Описание	Пример
import <file.xlsx>	Импорт данных из Excel в JSON	cf import data.xlsx
export <file.xlsx>	Экспорт из JSON в Excel	cf export report.xlsx
forecast [--months 12]	Запуск прогноза	cf forecast --months 12
scenario <name>	Применить сценарий	cf scenario optimistic
analyze	AI-анализ модели	cf analyze
init	Инициализация пустой модели	cf init

6. Обработка ошибок

• Стратегия: Исключения Python с кастомными типами (ModelError, SyncError, ForecastError)
• Формат ошибок: { "error": "<message>", "code": "<CODE>", "details": {} }
• Логирование: logging с уровнями INFO/ERROR; CLI-вывод через Typer + rich

7. Тестирование

• Unit-тесты: pytest для каждого модуля (cashflow_model, engine, sync)
• Integration-тесты: чтение/запись Excel, полный цикл import → forecast → export
• Mock-стратегия: временные файлы для Excel/JSON тестов
• Команда запуска: pytest

8. Предварительная группировка задач

Задача	Описание	Тип
T1	Инициализация проекта + scaffold	config
T2	Модель данных (dataclass + JSON serialization)	feature
T3	Forecast Engine (базовый прогноз)	feature
T4	Excel Sync (import/export)	feature
T5	CLI (Typer) — все команды	feature
T6	AI Assistant (промпты + интерфейс)	feature
T7	Тесты на все модули	test
T8	Финальная проверка и документация	docs

9. Примечания

Для MVP берётся минимальный функционал: модель + forecast + excel sync + cli. AI — только интерфейс (заглушка с промптами). Сценарии — базовая реализация.