REQUIREMENTS_SPECIFICATION.md

Техническое задание: Рефакторинг bot-generator.ts

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

Проект: Telegram Bot Builder
Модуль: bot-generator.ts
Версия ТЗ: 1.0
Дата: 25.01.2026
Приоритет: Высокий
Тип задачи: Рефакторинг архитектуры

🎯 Цель проекта

Провести рефакторинг монолитного файла client/lib/bot-generator.ts в модульную архитектуру для улучшения читаемости, поддерживаемости и масштабируемости кода.

📊 Текущее состояние системы

Проблемы:

• Монолитная архитектура: Один файл содержит 9,276 строк кода
• Гигантская функция: generatePythonCode содержит 7,635 строк (82% файла)
• Дублирование кода: 10 функций дублируются в основном файле и модулях
• Сложность поддержки: Трудно найти и изменить конкретную функциональность
• Невозможность параллельной разработки: Конфликты при работе нескольких разработчиков

Текущие метрики:

Общий размер файла: 9,276 строк
Количество функций: 34
Критическая функция: generatePythonCode (7,635 строк)
Дублированных функций: 10 (~200 строк)
Покрытие функциями: 97% файла

🎯 Требования к результату

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

FR-1: Сохранение функциональности

• Приоритет: Критический
• Описание: Все существующие функции должны работать идентично до и после рефакторинга
• Критерии приемки:
  • Генерация Python кода ботов работает без изменений
  • Все типы узлов (start, message, command, media) поддерживаются
  • Условная логика и переходы между узлами функционируют
  • Клавиатуры (inline/reply) генерируются корректно
  • Обработка медиа-файлов работает

FR-2: Модульная архитектура

• Приоритет: Высокий
• Описание: Код должен быть разбит на логические модули
• Критерии приемки:
  • Основной файл сокращен до <2,000 строк
  • Создано минимум 15 модулей
  • Каждый модуль отвечает за конкретную функциональность
  • Четкое разделение ответственности между модулями

FR-3: Устранение дублирования

• Приоритет: Средний
• Описание: Дублированный код должен быть устранен
• Критерии приемки:
  • Удалены все 10 дублированных функций из основного файла
  • Добавлены корректные импорты из новых модулей
  • Функции используются из единого источника

FR-4: Разбиение главной функции

• Приоритет: Критический
• Описание: Функция generatePythonCode должна быть разбита на модули
• Критерии приемки:
  • Создано 4 основных модуля генерации
  • Главная функция стала координатором (orchestrator)
  • Каждый модуль отвечает за свою часть генерации
  • Размер каждого модуля <2,000 строк

Нефункциональные требования:

NFR-1: Производительность

• Описание: Производительность не должна ухудшиться
• Критерии:
  • Время генерации кода ±5% от текущего
  • Время запуска приложения не увеличивается
  • Потребление памяти остается на том же уровне

NFR-2: Совместимость

• Описание: Обратная совместимость с существующим API
• Критерии:
  • Все экспортируемые функции остаются доступными
  • Сигнатуры функций не изменяются
  • Существующие импорты продолжают работать

NFR-3: Качество кода

• Описание: Улучшение качества и читаемости кода
• Критерии:
  • Все модули имеют четкую документацию
  • TypeScript компиляция без ошибок
  • Соблюдение принципов SOLID
  • Покрытие тестами (если есть) сохраняется

NFR-4: Безопасность рефакторинга

• Описание: Минимизация рисков при изменениях
• Критерии:
  • Возможность отката на любом этапе
  • Резервные копии всех изменений
  • Пошаговая валидация изменений
  • Автоматизированные проверки

🏗️ Архитектурные требования

Целевая структура модулей:

client/lib/bot-generator/
├── index.ts                    # Главный экспорт (обратная совместимость)
├── core/                       # Ядро системы генерации
│   ├── generator.ts           # Главная функция generatePythonCode
│   ├── imports-generator.ts   # Генерация импортов Python
│   ├── data-analyzer.ts       # Анализ данных бота
│   ├── handlers-generator.ts  # Генерация обработчиков узлов
│   ├── main-loop-generator.ts # Генерация основного цикла
│   ├── parser.ts              # parsePythonCodeToJson
│   └── keyboard-generator.ts  # Генерация клавиатур
├── utils/                      # Утилиты
│   ├── string-utils.ts        # Работа со строками
│   ├── node-utils.ts          # Работа с узлами
│   └── validation.ts          # Валидация данных
├── analyzers/                  # Анализаторы возможностей
│   ├── feature-analyzer.ts    # Анализ функций бота
│   └── media-analyzer.ts      # Анализ медиа-контента
├── keyboards/                  # Генерация клавиатур
│   ├── keyboard-utils.ts      # Общие утилиты
│   ├── reply-keyboard.ts      # Reply клавиатуры
│   ├── inline-keyboard.ts     # Inline клавиатуры
│   └── conditional-keyboard.ts # Условные клавиатуры
├── handlers/                   # Обработчики узлов
│   ├── message-handlers.ts    # Обработчики сообщений
│   ├── media-handlers.ts      # Обработчики медиа
│   ├── user-management.ts     # Управление пользователями
│   ├── content-management.ts  # Управление контентом
│   └── admin-handlers.ts      # Административные функции
├── logic/                      # Бизнес-логика
│   ├── conditional.ts         # Условная логика
│   ├── variables.ts           # Работа с переменными
│   └── transitions.ts         # Переходы между узлами
└── generators/                 # Дополнительные генераторы
    └── documentation.ts       # Генерация документации

Принципы архитектуры:

Single Responsibility Principle (SRP)

• Каждый модуль отвечает за одну функциональность
• Четкое разделение обязанностей
• Минимальная связанность между модулями

Open/Closed Principle (OCP)

• Модули открыты для расширения
• Закрыты для модификации
• Легкое добавление новых типов узлов

Dependency Inversion Principle (DIP)

• Зависимости через интерфейсы
• Инверсия управления
• Легкое тестирование модулей

🚀 План выполнения

Этап 1: Подготовка и анализ (1 день)

Задачи:

• Анализ текущего состояния кода
• Создание резервных копий
• Настройка инструментов автоматизации
• Создание плана детального рефакторинга

Критерии готовности:

• Полный анализ функций выполнен
• Резервные копии созданы
• Скрипты автоматизации готовы

Этап 2: Устранение дублирования (0.5 дня)

Задачи:

• Удаление 10 дублированных функций
• Добавление корректных импортов
• Валидация изменений

Критерии готовности:

• Дублированные функции удалены
• TypeScript компиляция успешна
• Приложение запускается

Этап 3: Создание модульной структуры (1 день)

Задачи:

• Создание папочной структуры
• Извлечение утилит и анализаторов
• Создание базовых модулей

Критерии готовности:

• Структура папок создана
• Базовые модули извлечены
• Импорты настроены

Этап 4: Разбиение главной функции (2-3 дня)

Задачи:

• Анализ функции generatePythonCode
• Создание 4 основных модулей
• Реализация координирующей функции

Критерии готовности:

• Главная функция разбита
• Все модули реализованы
• Генерация кода работает

Этап 5: Извлечение обработчиков (1-2 дня)

Задачи:

• Извлечение обработчиков узлов
• Создание модулей handlers/
• Настройка импортов

Критерии готовности:

• Все обработчики извлечены
• Модули handlers/ созданы
• Функциональность сохранена

Этап 6: Финализация и тестирование (1 день)

Задачи:

• Полное тестирование системы
• Оптимизация импортов
• Документирование изменений

Критерии готовности:

• Все тесты проходят
• Документация обновлена
• Производительность в норме

🧪 Критерии приемки

Обязательные критерии:

AC-1: Функциональность сохранена

• Генерация простых ботов работает
• Генерация сложных ботов работает
• Все типы узлов поддерживаются
• Условная логика функционирует
• Клавиатуры генерируются корректно

AC-2: Архитектура улучшена

• Основной файл <2,000 строк
• Создано >15 модулей
• Дублирование устранено
• Главная функция разбита

AC-3: Качество кода

• TypeScript компиляция без ошибок
• Все модули документированы
• Импорты настроены корректно
• Обратная совместимость сохранена

AC-4: Производительность

• Время генерации ±5%
• Время запуска не увеличилось
• Потребление памяти в норме

Дополнительные критерии:

AC-5: Удобство разработки

• Легко найти нужную функциональность
• Простое добавление новых типов узлов
• Возможность параллельной разработки
• Четкое разделение ответственности

AC-6: Безопасность изменений

• Возможность отката на любом этапе
• Резервные копии созданы
• Автоматизированные проверки работают
• Пошаговая валидация настроена

🛠️ Инструменты и технологии

Основные инструменты:

• TypeScript - основной язык
• Node.js - среда выполнения скриптов
• Git - контроль версий и откаты

Скрипты автоматизации:

• analyze-functions.js - анализ кода
• remove-duplicates.cjs - удаление дублей
• split-main-function.cjs - разбиение главной функции
• refactor-manager.cjs - управление процессом
• validate-fixes.cjs - валидация результатов

Проверки качества:

• TypeScript компилятор
• ESLint (если настроен)
• Автоматические тесты (если есть)

⚠️ Риски и ограничения

Высокие риски:

R-1: Поломка генерации кода

• Вероятность: Средняя
• Влияние: Критическое
• Митигация: Пошаговое тестирование, резервные копии

R-2: Нарушение обратной совместимости

• Вероятность: Низкая
• Влияние: Высокое
• Митигация: Сохранение всех экспортов, тестирование API

R-3: Ухудшение производительности

• Вероятность: Низкая
• Влияние: Среднее
• Митигация: Мониторинг производительности, оптимизация

Средние риски:

R-4: Сложность отладки

• Вероятность: Средняя
• Влияние: Среднее
• Митигация: Детальное логирование, документация

R-5: Увеличение времени разработки

• Вероятность: Высокая
• Влияние: Низкое
• Митигация: Автоматизация, четкий план

Ограничения:

L-1: Сохранение API

• Нельзя изменять сигнатуры экспортируемых функций
• Все существующие импорты должны работать

L-2: Обратная совместимость

• Существующий код должен работать без изменений
• Нельзя удалять публичные функции

L-3: Производительность

• Время генерации не должно увеличиться >5%
• Потребление памяти должно остаться на том же уровне

📊 Метрики успеха

Количественные метрики:

Размер кода:

• До: 9,276 строк в одном файле
• После: <2,000 строк в основном файле + модули
• Цель: Сокращение основного файла на 80%

Количество модулей:

• До: 1 монолитный файл
• После: >15 специализированных модулей
• Цель: Создание модульной архитектуры

Дублирование:

• До: 10 дублированных функций
• После: 0 дублированных функций
• Цель: Полное устранение дублирования

Качественные метрики:

Читаемость:

• Легко найти нужную функциональность
• Понятная структура модулей
• Четкое разделение ответственности

Поддерживаемость:

• Простое добавление новых функций
• Изолированные изменения в модулях
• Возможность параллельной разработки

Надежность:

• Все тесты проходят
• TypeScript компиляция без ошибок
• Стабильная работа приложения

🔍 Процедуры тестирования

Автоматическое тестирование:

Компиляция TypeScript:

npx tsc --noEmit --skipLibCheck client/lib/bot-generator.ts

Запуск приложения:

npm run dev

Валидация структуры:

node scripts/validate-fixes.cjs

Ручное тестирование:

Тест 1: Генерация простого бота

• Создать бота с узлом start
• Добавить узел message
• Сгенерировать Python код
• Проверить корректность кода

Тест 2: Генерация бота с кнопками

• Создать бота с inline кнопками
• Добавить reply кнопки
• Проверить генерацию клавиатур

Тест 3: Генерация бота с условиями

• Создать условные переходы
• Добавить переменные
• Проверить условную логику

Тест 4: Генерация бота с медиа

• Добавить медиа-узлы
• Проверить обработку файлов
• Тестировать различные типы медиа

Критерии прохождения тестов:

• Все автоматические тесты проходят
• Ручные тесты выполняются успешно
• Сгенерированный код работает корректно
• Производительность в допустимых пределах

📋 Чек-лист выполнения

Подготовка:

• Анализ текущего состояния выполнен
• Резервные копии созданы
• Скрипты автоматизации готовы
• План детализирован

Рефакторинг:

• Дублированные функции удалены
• Модульная структура создана
• Главная функция разбита
• Обработчики извлечены
• Импорты настроены

Валидация:

• TypeScript компиляция успешна
• Приложение запускается
• Генерация ботов работает
• Все тесты проходят
• Производительность в норме

Финализация:

• Документация обновлена
• Код-ревью проведено
• Изменения задокументированы
• Команда обучена новой структуре

📞 Контакты и ответственность

Роли и ответственность:

Разработчик-исполнитель:

• Выполнение рефакторинга
• Создание и тестирование модулей
• Документирование изменений

Ревьюер кода:

• Проверка качества кода
• Валидация архитектурных решений
• Контроль соблюдения требований

Тестировщик:

• Функциональное тестирование
• Проверка производительности
• Валидация пользовательских сценариев

Критерии завершения проекта:

• Все критерии приемки выполнены
• Код-ревью пройдено успешно
• Документация обновлена
• Команда обучена новой архитектуре

---

Дата создания: 25.01.2026
Версия: 1.0
Статус: Утверждено к выполнению