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