152 lines
7.6 KiB
Markdown
152 lines
7.6 KiB
Markdown
# 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 — только интерфейс (заглушка с промптами). Сценарии — базовая реализация.
|