benadis-rac/requirements.md

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 практиками.

Приоритизация улучшений должна основываться на конкретных потребностях пользователей и доступных ресурсах для разработки.