# 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 практиками. Приоритизация улучшений должна основываться на конкретных потребностях пользователей и доступных ресурсах для разработки.