Init

requirements.md

@@ -0,0 +1,319 @@
+# Requirements для проекта GitOps RAC
+
+## Обзор проекта
+
+GitOps RAC - это Go-библиотека и CLI-утилита для управления сервисным режимом информационных баз 1С:Предприятие через утилиту RAC (Remote Administration Client). Проект реализует автоматизацию операций включения/выключения сервисного режима с поддержкой принудительного отключения пользователей и верификации операций.
+
+## Функциональные требования
+
+### 1. Основная функциональность
+
+#### 1.1 Управление сервисным режимом
+- **Включение сервисного режима** с автоматическим отключением всех активных пользователей
+- **Выключение сервисного режима** с восстановлением доступа
+- **Проверка статуса** текущего состояния сервисного режима
+- **Верификация операций** - проверка корректности выполнения команд
+
+#### 1.2 Работа с пользовательскими сессиями
+- Получение списка активных сессий пользователей
+- Принудительное завершение всех пользовательских сессий
+- Обработка ошибок при завершении отдельных сессий (продолжение работы)
+
+#### 1.3 Интеграция с RAC
+- Выполнение команд через утилиту rac.exe
+- Автоматическое получение UUID кластера и информационной базы
+- Поддержка аутентификации на уровне кластера и базы данных
+
+### 2. Интерфейсы использования
+
+#### 2.1 CLI интерфейс
+- Команды: `enable`, `disable`, `status`
+- Флаги: `-config`, `-secret`, `-command`, `-version`, `-help`
+- Переопределение параметров конфигурации через командную строку
+
+#### 2.2 Библиотечный API
+- Публичный интерфейс `ServiceModeManager`
+- Методы: `EnableServiceMode()`, `DisableServiceMode()`, `GetServiceModeStatus()`
+- Поддержка контекста для отмены операций
+
+## Нефункциональные требования
+
+### 3. Производительность и надежность
+
+#### 3.1 Retry-логика
+- Настраиваемое количество попыток (по умолчанию: 3)
+- Настраиваемая задержка между попытками (по умолчанию: 5 секунд)
+- Обработка временных сбоев сети и сервера
+
+#### 3.2 Таймауты
+- Таймаут подключения (по умолчанию: 30 секунд)
+- Таймаут выполнения команды (по умолчанию: 60 секунд)
+- Общий таймаут операции (по умолчанию: 5 минут)
+
+#### 3.3 Контекст и отмена операций
+- Поддержка `context.Context` для всех операций
+- Возможность отмены длительных операций
+- Корректная обработка отмены контекста
+
+### 4. Безопасность
+
+#### 4.1 Управление секретами
+- Разделение конфигурации и секретов (config.yaml / secret.yaml)
+- Маскирование паролей в логах (замена на `***`)
+- Отсутствие секретов в основной конфигурации
+
+#### 4.2 Валидация
+- Валидация обязательных параметров конфигурации
+- Проверка корректности путей к файлам
+- Валидация входных параметров
+
+### 5. Логирование и мониторинг
+
+#### 5.1 Структурированное логирование
+- Использование `log/slog` для JSON-логирования
+- Уровни логирования: Debug, Info, Warn, Error
+- Добавление метаданных (версия приложения, источник)
+
+#### 5.2 Детализация логов
+- Логирование всех RAC команд (с маскированием паролей)
+- Отслеживание попыток retry
+- Логирование результатов верификации
+- Информация о завершении сессий пользователей
+
+### 6. Конфигурация
+
+#### 6.1 Файлы конфигурации
+**config.yaml** должен содержать:
+- Параметры подключения (server_host, server_port, rac_port)
+- Путь к rac.exe (rac_path)
+- Настройки таймаутов и retry
+- Параметры логирования
+- Имена сервера и базы данных
+
+**secret.yaml** должен содержать:
+- Учетные данные кластера (cluster_admin, cluster_admin_password)
+- Учетные данные базы данных (db_admin, db_admin_password)
+
+#### 6.2 Настраиваемые параметры
+- Сообщение для пользователей при включении сервисного режима
+- Код разрешения для сервисного режима
+- Все таймауты и параметры retry
+- Уровень логирования
+
+## Архитектурные требования
+
+### 7. Структура проекта
+
+#### 7.1 Модульная архитектура
+```
+benadis-rac/
+├── cmd/                    # CLI приложение
+├── internal/               # Внутренние пакеты
+│   ├── config/            # Управление конфигурацией
+│   ├── constants/         # Константы приложения
+│   ├── logger/            # Логирование
+│   ├── rac/              # Взаимодействие с RAC
+│   └── service/          # Бизнес-логика
+├── gitops_rac.go          # Публичный API
+└── integration_test.go    # Интеграционные тесты
+```
+
+#### 7.2 Принципы проектирования
+- **SOLID принципы** - каждый компонент имеет единственную ответственность
+- **Dependency Injection** - внедрение зависимостей через конструкторы
+- **Интерфейсы** - использование интерфейсов для абстракции (Logger, ServiceModeManager)
+- **Модульность** - четкое разделение ответственности между пакетами
+
+### 8. Управление константами
+
+#### 8.1 Централизованные константы
+- Все строковые литералы вынесены в пакет constants
+- Сообщения об ошибках
+- Сообщения для логирования
+- Параметры по умолчанию
+- RAC команды и параметры
+
+#### 8.2 Типизированные константы
+- Версия приложения
+- Таймауты (time.Duration)
+- Числовые значения (порты, счетчики)
+- Флаги паролей для маскирования
+
+## Требования к тестированию
+
+### 9. Unit тесты
+- Покрытие всех публичных функций
+- Тестирование обработки ошибок
+- Мок-тесты для внешних зависимостей
+- Тестирование валидации конфигурации
+
+### 10. Интеграционные тесты
+- Тесты с реальным 1С сервером
+- Проверка полного цикла операций
+- Тестирование retry-логики
+- Верификация маскирования паролей
+
+## Предложения по улучшению
+
+### 11. Расширение функциональности
+
+#### 11.1 Мониторинг и метрики
+- **Экспорт метрик** в формате Prometheus
+  - Количество успешных/неуспешных операций
+  - Время выполнения операций
+  - Количество активных сессий
+- **Health check endpoint** для проверки доступности
+- **Статистика использования** команд и операций
+
+#### 11.2 Уведомления
+- **Webhook уведомления** о смене статуса сервисного режима
+- **Email уведомления** администраторам
+- **Slack/Teams интеграция** для команд разработки
+- **Настраиваемые шаблоны** уведомлений
+
+#### 11.3 Планировщик задач
+- **Cron-подобный планировщик** для автоматического включения/выключения
+- **Календарные окна обслуживания**
+- **Интеграция с внешними планировщиками** (Kubernetes CronJob, systemd timer)
+
+### 12. Операционные улучшения
+
+#### 12.1 Конфигурация
+- **Поддержка переменных окружения** для всех параметров
+- **Конфигурация через Kubernetes ConfigMap/Secret**
+- **Горячая перезагрузка конфигурации** без перезапуска
+- **Валидация конфигурации** с детальными сообщениями об ошибках
+
+#### 12.2 Безопасность
+- **Интеграция с внешними системами управления секретами**:
+  - HashiCorp Vault
+  - Kubernetes Secrets
+  - Azure Key Vault
+  - AWS Secrets Manager
+- **Ротация паролей** с автоматическим обновлением
+- **Аудит операций** с записью в отдельный лог
+- **RBAC** для разграничения доступа к операциям
+
+#### 12.3 Мониторинг и диагностика
+- **Structured logging** с дополнительными полями:
+  - Correlation ID для трассировки операций
+  - User ID инициатора операции
+  - Временные метки с микросекундами
+- **Distributed tracing** (OpenTelemetry/Jaeger)
+- **Профилирование производительности** (pprof)
+
+### 13. Масштабируемость
+
+#### 13.1 Поддержка множественных баз
+- **Конфигурация нескольких информационных баз**
+- **Групповые операции** над множеством баз
+- **Параллельное выполнение** операций
+- **Приоритизация** операций по базам
+
+#### 13.2 Кластеризация
+- **Поддержка нескольких кластеров 1С**
+- **Load balancing** между кластерами
+- **Failover** при недоступности основного кластера
+- **Синхронизация состояния** между экземплярами
+
+#### 13.3 Производительность
+- **Пулы соединений** к RAC
+- **Кэширование** UUID кластеров и баз
+- **Асинхронные операции** для неблокирующего выполнения
+- **Batch операции** для массовых изменений
+
+### 14. Интеграции
+
+#### 14.1 CI/CD интеграция
+- **GitHub Actions** для автоматизации развертывания
+- **GitLab CI** пайплайны
+- **Jenkins** плагины
+- **Helm charts** для Kubernetes развертывания
+
+#### 14.2 Мониторинг систем
+- **Grafana dashboards** для визуализации метрик
+- **Alertmanager** правила для уведомлений
+- **Nagios/Zabbix** плагины для мониторинга
+- **DataDog/New Relic** интеграция
+
+#### 14.3 API расширения
+- **REST API** для внешних систем
+- **GraphQL** для гибких запросов
+- **gRPC** для высокопроизводительных интеграций
+- **WebSocket** для real-time уведомлений
+
+### 15. Пользовательский интерфейс
+
+#### 15.1 Web интерфейс
+- **Веб-панель управления** для администраторов
+- **Dashboard** с текущим статусом всех баз
+- **История операций** с возможностью фильтрации
+- **Планировщик задач** с графическим интерфейсом
+
+#### 15.2 Мобильное приложение
+- **Мобильное приложение** для экстренного управления
+- **Push уведомления** о критических событиях
+- **Биометрическая аутентификация**
+
+### 16. Документация и обучение
+
+#### 16.1 Документация
+- **OpenAPI/Swagger** спецификация для API
+- **Интерактивная документация** с примерами
+- **Руководство по миграции** между версиями
+- **Best practices** для production использования
+
+#### 16.2 Инструменты разработки
+- **Docker образы** для разработки и тестирования
+- **Makefile** для автоматизации сборки
+- **Pre-commit hooks** для проверки качества кода
+- **Benchmark тесты** для оценки производительности
+
+## Технические ограничения
+
+### 17. Совместимость
+- **Go версия**: 1.24+
+- **1С:Предприятие**: 8.3.x
+- **Операционные системы**: Windows, Linux, macOS
+- **Архитектуры**: amd64, arm64
+
+### 18. Зависимости
+- Минимальное количество внешних зависимостей
+- Использование только стабильных и поддерживаемых библиотек
+- Регулярное обновление зависимостей для безопасности
+
+### 19. Производительность
+- **Время отклика**: < 5 секунд для стандартных операций
+- **Потребление памяти**: < 100MB в runtime
+- **CPU использование**: < 10% при нормальной нагрузке
+- **Concurrent операции**: до 10 одновременных операций
+
+## Критерии приемки
+
+### 20. Функциональные критерии
+- ✅ Успешное включение/выключение сервисного режима
+- ✅ Корректная верификация операций
+- ✅ Принудительное отключение пользователей
+- ✅ Маскирование паролей в логах
+- ✅ Retry-логика при сбоях
+
+### 21. Качественные критерии
+- ✅ Покрытие unit тестами > 80%
+- ✅ Успешное прохождение интеграционных тестов
+- ✅ Отсутствие критических уязвимостей безопасности
+- ✅ Соответствие Go coding standards
+- ✅ Полная документация API
+
+### 22. Операционные критерии
+- ✅ Стабильная работа в production окружении
+- ✅ Корректная обработка всех типов ошибок
+- ✅ Информативное логирование для диагностики
+- ✅ Возможность мониторинга состояния приложения
+
+## Заключение
+
+Проект GitOps RAC представляет собой зрелое решение для автоматизации управления сервисным режимом 1С:Предприятие. Текущая реализация покрывает основные потребности и следует лучшим практикам разработки на Go.
+
+Предложенные улучшения позволят расширить функциональность для enterprise использования, улучшить операционные характеристики и интегрироваться с современными DevOps практиками.
+
+Приоритизация улучшений должна основываться на конкретных потребностях пользователей и доступных ресурсах для разработки.