bootstrap

2026-07-12 19:46:07 +03:00
parent 2ddf2251d6
commit 940d25435e
36 changed files with 1914 additions and 0 deletions
@@ -0,0 +1,151 @@
+# 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 — только интерфейс (заглушка с промптами). Сценарии — базовая реализация.