Skip to content

📋 Разработка плагина Finam Trade Pro для Teleton #166

Closed
#167
Closed
📋 Разработка плагина Finam Trade Pro для Teleton#166
#167
@xlabtg

Description

@xlabtg
xlabtg
opened on Apr 19, 2026

🚀 [FEATURE] Профессиональный плагин finam-trade для Teleton Agent

🎯 Цель задачи

Разработать полнофункциональный плагин finam-trade для экосистемы Teleton, обеспечивающий агенту доступ ко всем возможностям Finam Trade API для алготрейдинга, анализа рынка и управления портфелем.

Репозитории:

📐 Технические требования

🔐 Аутентификация и безопасность

  • Реализовать класс FinamAuth с поддержкой:
    • Получение токена через POST /v1/sessions с использованием secret
    • Авто-рефреш токена при истечении срока действия (парсинг JWT exp)
    • Хранение секрета через sdk.secrets.require('FINAM_SECRET')
  • Запретить логирование токенов, секретов и чувствительных данных
  • Реализовать rate limiting: не более 200 запросов/минуту (требование Finam)
  • Добавить обработку ошибок 401/403 с автоматической пере-аутентификацией

🏗️ Архитектура плагина

plugins/finam-trade/
├── index.js              # Точка входа: export { manifest, tools, migrate, start, stop }
├── manifest.json         # Метаданные для реестра плагинов Teleton
├── package.json          # Зависимости: @grpc/grpc-js, axios, jwt-decode
├── src/
│   ├── auth.js           # Аутентификация и управление токенами
│   ├── client.js         # REST/gRPC клиент с retry-логикой
│   ├── tools/            # Группы инструментов (по одному файлу на группу)
│   │   ├── accounts.js   # Счета, позиции, баланс
│   │   ├── orders.js     # Выставление/отмена/статус ордеров
│   │   ├── market.js     # Рыночные данные: свечи, котировки, стакан
│   │   ├── instruments.js# Справочники: инструменты, биржи, расписание
│   │   └── reports.js    # Отчёты, история сделок, транзакции
│   └── utils.js          # Вспомогательные функции: маппинг, валидация, форматирование
├── README.md             # Документация для пользователя плагина
├── .env.example          # Шаблон конфигурации
└── __tests__/            # Unit-тесты для критических функций

📦 manifest.json (требования)

{
  "id": "finam-trade",
  "name": "Finam Trade Pro",
  "version": "1.0.0",
  "description": "Полнофункциональная интеграция с брокером Финам: торговля, аналитика, отчёты",
  "author": { "name": "Teleton Community", "url": "https://github.com/xlabtg" },
  "license": "MIT",
  "entry": "index.js",
  "teleton": ">=1.0.0",
  "sdkVersion": ">=1.0.0",
  "permissions": ["network", "secrets", "database"],
  "secrets": ["FINAM_SECRET"],
  "defaultConfig": {
    "api_base": "https://api.finam.ru",
    "grpc_base": "api.finam.ru:443",
    "rate_limit_rps": 3,
    "timeout_ms": 30000
  },
  "tags": ["trading", "finam", "stocks", "futures", "forex", "moex"],
  "tools": [/* массив всех инструментов с описаниями */]
}

🛠️ Список инструментов (полный охват API)

📋 Группа 1: Управление счетами

Инструмент Описание Параметры Возврат
finam_get_accounts Список доступных торговых счетов {} [{account_id, name, type, status}]
finam_get_account_info Детали счёта: equity, PnL, маржа {account_id} {equity, pnl, margin, buying_power}
finam_get_positions Открытые позиции с текущей ценой {account_id, symbol?} [{symbol, qty, avg_price, current_price, pnl}]
finam_get_cash Денежные остатки по валютам {account_id} [{currency, amount, available}]
finam_get_trades История исполненных сделок {account_id, limit?, start_time?, end_time?, symbol?} [{trade_id, symbol, qty, price, side, timestamp}]
finam_get_transactions История транзакций (вводы/выводы) {account_id, limit?, start_time?, end_time?} [{tx_id, type, amount, currency, timestamp}]

📈 Группа 2: Ордера и торговля

Инструмент Описание Параметры Возврат
finam_place_order Выставить заявку (рыночная/лимитная/стоп) {account_id, symbol, quantity, side, type, limit_price?, stop_price?, time_in_force, comment?} {success, order_id?, error?}
finam_cancel_order Отменить активную заявку {account_id, order_id} {success, error?}
finam_get_orders Список активных заявок {account_id, symbol?} [{order_id, symbol, side, qty, price, status}]
finam_get_order_status Детальный статус заявки {account_id, order_id} {status, filled_qty, avg_price, reject_reason?}
finam_place_sltp Выставить SL/TP к существующей позиции {account_id, order_id, sl_price?, tp_price?, quantity_sl?, quantity_tp?} {success, sl_order_id?, tp_order_id?, error?}

📊 Группа 3: Рыночные данные

Инструмент Описание Параметры Возврат
finam_get_instrument Информация об инструменте {symbol} {symbol, name, mic, currency, lot_size, min_step, trading_hours}
finam_get_bars Исторические свечи {symbol, interval, start_time, end_time} [{timestamp, open, high, low, close, volume}]
finam_get_latest_trades Последние сделки по инструменту {symbol, limit?} [{price, qty, timestamp, side}]
finam_get_orderbook Стакан заявок (если доступно) {symbol, depth?} {bids: [[price, qty]], asks: [[price, qty]]}
finam_get_instruments_list Справочник инструментов с пагинацией {cursor?, only_active?, mic?} {instruments: [...], next_cursor?}
finam_get_exchanges Список доступных бирж/площадок {} [{mic, name, timezone, schedule}]
finam_get_schedule Торговое расписание инструмента {symbol} {sessions: [{start, end, type}], holidays: [...]}

🔍 Группа 4: Аналитика и отчёты

Инструмент Описание Параметры Возврат
finam_generate_report Запрос генерации отчёта {account_id, date_begin, date_end, report_form} {report_id, status: "processing"}
finam_get_report_status Проверка статуса отчёта {report_id} {status, download_url?, error?}
finam_get_usage Текущие квоты и лимиты API {} {requests_today, limit_daily, reset_time}

✅ Acceptance Criteria (критерии приёмки)

🎯 Функциональные требования

  • Все 20+ инструментов реализованы и экспортированы через tools(sdk)
  • Каждый инструмент имеет:
    • Чёткое description для LLM-понимания
    • Валидацию параметров через JSON Schema
    • Обработку ошибок с возвратом {success: false, error: "..."}
    • Логирование через sdk.log.info/warn/error
  • Аутентификация работает с автоматическим рефрешем токена
  • Rate limiting реализован на уровне клиента (очередь запросов)
  • Поддержка как REST, так и gRPC эндпоинтов (где применимо)

🔒 Требования безопасности

  • Секреты запрашиваются только через sdk.secrets.require()
  • В логах отсутствуют токены, пароли, персональные данные
  • Все внешние запросы используют HTTPS с валидацией сертификатов
  • Реализована защита от SSRF (валидация URL перед запросом)

🧪 Тестирование

  • Unit-тесты для auth.js и utils.js (покрытие >80%)
  • Интеграционные тесты с mock-сервером Finam API
  • Тесты на rate limiting и retry-логику
  • Ручное тестирование в sandbox-режиме (если доступен)

📚 Документация

  • README.md содержит:
    • Инструкцию по установке и настройке
    • Примеры использования каждого инструмента
    • Описание форматов символов (TICKER@MIC)
    • Список возможных ошибок и их обработка
  • .env.example с комментариями по каждой переменной
  • JSDoc-комментарии для всех публичных функций

⚡ Производительность

  • Время ответа инструмента < 5 сек (при нормальных условиях сети)
  • Кэширование справочников (instruments, exchanges) в sdk.db с TTL 1 час
  • Поддержка пагинации для списков с большим объёмом данных

🚦 Приоритеты разработки (поэтапная реализация)

🥇 Этап 1: MVP (неделя 1)

✅ finam_get_accounts
✅ finam_get_account_info  
✅ finam_get_positions
✅ finam_place_order (только limit/market)
✅ finam_get_orders
✅ finam_get_bars
✅ finam_get_instrument

🥈 Этап 2: Полная торговля (неделя 2)

✅ finam_cancel_order
✅ finam_get_order_status
✅ finam_place_sltp
✅ finam_get_trades
✅ finam_get_cash
✅ Все типы ордеров: stop_market, stop_limit

🥉 Этап 3: Аналитика и отчёты (неделя 3)

✅ finam_get_instruments_list
✅ finam_get_exchanges
✅ finam_get_schedule
✅ finam_get_latest_trades
✅ finam_get_orderbook
✅ finam_generate_report + finam_get_report_status
✅ finam_get_usage

🔧 Конфигурация и запуск

Переменные окружения (.env.example)

# Обязательные
FINAM_SECRET=your_secret_key_here

# Опциональные (переопределяют defaultConfig)
FINAM_API_BASE=https://api.finam.ru
FINAM_GRPC_BASE=api.finam.ru:443
FINAM_RATE_LIMIT_RPS=3
FINAM_TIMEOUT_MS=30000
FINAM_CACHE_TTL=3600

Установка плагина

# 1. Клонировать репозиторий плагинов
git clone https://github.com/xlabtg/teleton-plugins
cd teleton-plugins

# 2. Создать папку плагина
mkdir -p plugins/finam-trade
# 3. Разместить файлы плагина (из структуры выше)

# 4. Установить зависимости
cd plugins/finam-trade
npm install @grpc/grpc-js axios jwt-decode

# 5. Добавить секрет в конфиг агента (~/.teleton/config.yaml)
secrets:
  FINAM_SECRET: "your_actual_secret"

# 6. Перезапустить агента — плагин загрузится автоматически

Проверка работоспособности

// Пример вызова через агент
const result = await sdk.tools.execute('finam_get_accounts', {}, context);
console.log(result); 
// Ожидаемый вывод: { success: true, data: [{account_id: "...", name: "..."}] }

⚠️ Известные ограничения и риски

Риск Митигация
Изменения в Finam API Реализовать абстракцию клиента, централизовать маппинг ответов
Превышение rate limit Очередь запросов с приоритетами, экспоненциальный backoff
Потеря соединения Retry-логика с максимальным числом попыток (3-5)
Неверный формат символа Валидация TICKER@MIC перед запросом, понятные ошибки
Утечка токенов Строгий запрет на логирование секретов, аудит кода

📎 Приложения и ссылки

🏷️ Метки и метаданные

labels: ["feature", "plugin", "finam", "trading", "high-priority"]
assignees: []
project: "Teleton Ecosystem"
milestone: "Q2 2026 Integrations"
estimated_hours: 40-60

💬 Комментарии для Hive Mind

При генерации кода:

  1. Следуй принципу "один инструмент — одна функция" для лёгкого тестирования
  2. Используй sdk.log для всех логов, никогда console.*
  3. Все асинхронные операции оборачивай в try/catch с возвратом {success: false, error}
  4. Для маппинга параметров создай отдельный файл utils.js с чистыми функциями
  5. Добавляй JSDoc к каждой экспортируемой функции
  6. Тестируй каждый инструмент изолированно перед интеграцией
  7. При сомнениях в формате параметра — сверяйся с официальной документацией Finam

При создании PR:

  • Все чекбоксы Acceptance Criteria отмечены ✅
  • Добавлены/обновлены тесты
  • Документация актуализирована
  • Нет console.log, нет утечек секретов
  • Проходит линтинг и форматирование
  • Описаны breaking changes (если есть)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions