ADR-0002: Unified Config System

Статус

Accepted

Контекст

В процессе роста проекта конфигурация была разбросана по множеству файлов, environment переменных и хардкода. Это создавало проблемы: - Невозможность понять полную конфигурацию системы - Дублирование параметров в разных местах - Хардкод значений в коде (magic numbers, URLs, порты) - Сложность изменения конфигурации для разных сред - Отсутствие валидации конфигурации при запуске

Необходима централизованная система управления конфигурацией с единым источником истины.

Решение

Реализована система UnifiedConfig как единственный способ работы с конфигурацией.

Архитектура:

backend/config/
├── unified_config.go           # Основная структура (100+ параметров)
├── unified_config_interface.go # ConfigInterface с методами доступа  
├── unified_config_loader.go    # Система загрузки и валидации
├── legacy_adapter.go          # Совместимость со старым кодом
└── unified_config_test.go     # Comprehensive тесты

Принципы:

1. Единый источник истины - все параметры только в UnifiedConfig
2. Иерархия загрузки: Environment → config.yaml → Code defaults
3. Обязательная валидация - система не запускается с некорректной конфигурацией
4. Интерфейсный доступ - весь код использует ConfigInterface методы
5. Ошибка вместо fallback - отсутствие параметра = ошибка, не default

Использование:

cfg, err := config.LoadUnifiedConfig()
apiBaseURL := cfg.GetAPIBaseURL()
jwtSecret := cfg.GetJWTSecret()

Альтернативы

Множественные конфиг файлы

Отклонена - сложность отслеживания всех параметров, дублирование, отсутствие единой валидации.

Environment-only конфигурация

Отклонена - неудобство для разработки, отсутствие структурированности, сложность валидации сложных типов.

Конфигурация через флаги командной строки

Отклонена - не масштабируется для большого количества параметров, сложность automation.

Distributed configuration (Consul, etcd)

Отклонена - избыточная сложность для текущих потребностей, дополнительная инфраструктура.

Последствия

Положительные

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

Отрицательные

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

Нейтральные

• Изменение привычного способа работы с конфигурацией
• Необходимость поддержки legacy adapter временно

Связанные решения

• Связано с: ADR-0006 (Centralized Test Config) - для тестовых конфигураций
• Связано с: ADR-0004 (HD Wallet Architecture) - для blockchain параметров

Примечания

Структура конфигурации:

type UnifiedConfig struct {
    Server     ServerConfig     // Порты, адреса, таймауты
    Database   DatabaseConfig   // PostgreSQL подключение
    Auth       AuthConfig       // JWT секреты, сессии
    Blockchain BlockchainConfig // HD Wallet, network URLs
    Email      EmailConfig      // SMTP настройки (опционально)
}

Валидация включает:

• JWT секреты (минимум 32 символа)
• HD Wallet XPUB и master адрес
• Порты (1-65535)
• Email адреса (если включены)
• Обязательные vs опциональные параметры

Добавление новых параметров:

1. Добавить поле в соответствующую секцию
2. Добавить default в setDefaults()
3. Добавить getter в ConfigInterface
4. Добавить тест
5. Обновить .env.example

Категорически запрещено:

• os.Getenv() вызовы в коде
• Хардкод параметров
• Создание альтернативных конфигурационных систем
• Игнорирование ошибок валидации