Версия: 3.3.51 Обновлено: 2026-01-23

Unified Config System Architecture¶

Обзор¶

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

Архитектурные принципы¶

Единый источник истины¶

✅ ЕДИНЫЙ ИСТОЧНИК: Все настройки через UnifiedConfig систему
✅ АВТОМАТИЧЕСКАЯ ЗАГРУЗКА .env: Система использует cleanenv библиотеку
✅ ИЕРАРХИЯ ЗАГРУЗКИ: Environment variables > .env file > config.yaml > code defaults
❌ КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНО: os.Getenv() вызовы, хардкод параметров

Модульная структура¶

Система использует 7 специализированных модулей вместо монолитного config.yaml:

config/
├── network.yaml      # Сервер, CORS, домены, сетевые настройки
├── database.yaml     # PostgreSQL, пулы соединений, настройки БД
├── auth.yaml         # JWT, Supabase Auth, администраторы, сессии
├── blockchain.yaml   # Сети, контракты, стейкинг протоколы
├── testing.yaml      # Тестовые настройки, производительность
├── monitoring.yaml   # Логирование, мониторинг, метрики, таймауты
└── limits.yaml       # Лимиты, стратегии инвестирования

Master Configuration Generation¶

Система автоматически генерирует unified конфигурации из модулей:

Сгенерированные файлы (read-only)¶

config.yaml - единая конфигурация сервера (chmod 444)
frontend/shared/config/generated-config.ts - TypeScript конфигурация
.env.generated - публичные переменные окружения
frontend/e2e/config/generated-master-test-config.json - E2E тесты

Команды генерации¶

# Генерация всех конфигураций из модулей
make generate-config

# Валидация модульных конфигураций
make validate-config

# Анализ хардкода в коде
make analyze-hardcode-violations

Environment Variables¶

.env файлы¶

.env (ручной) - ТОЛЬКО секретные данные (private keys, passwords, JWT secrets)
.env.generated (автогенерация) - ТОЛЬКО публичные константы из config/ модулей
Защита от перезаписи: Генератор НИКОГДА не трогает .env файл с секретами

Обязательные переменные¶

# Database
DB_PASSWORD=aisee

# JWT Authentication
JWT_SECRET=test-jwt-secret-for-smoke-tests-minimum-32-chars-required

# Blockchain
BLOCKCHAIN_RPC_URL=http://188.42.218.164:8545

💻 Использование в коде¶

Backend (Go)¶

// ВСЕГДА используй UnifiedConfig для настроек
cfg := config.LoadUnifiedConfig()

// Получение конфигурации
port := cfg.GetServerPort()
secret := cfg.GetJWTSecret()
rpcURL := cfg.GetBlockchainRPCURL()

Frontend¶

Frontend переменные встраиваются в build через next.config.js:

// next.config.js читает config.yaml во время сборки
const config = yaml.load(fs.readFileSync('../../config.yaml', 'utf8'))

const nextConfig = {
  env: {
    NEXT_PUBLIC_API_URL: `http://${config.server.host}:${config.server.port}`,
    NEXT_PUBLIC_USDC_CONTRACT_ADDRESS: config.frontend.usdc_contract.localhost
  }
}

ЗАПРЕЩЕНО: Runtime .env файлы, next-runtime-env, PublicEnvScript компоненты

Workflow разработчика¶

1. Редактирование конфигурации¶

✅ Редактируй ТОЛЬКО файлы в config/ директории
✅ Используй ${ENV_VAR} для секретных данных
❌ НЕ трогай сгенерированные файлы (chmod 444 защита)

2. Применение изменений¶

# После изменения модулей:
make generate-config    # Генерирует все конфигурации
make restart           # Применяет изменения

3. Валидация¶

make analyze-hardcode-violations  # Проверяет отсутствие констант в коде

Hardcode Analyzer¶

Система автоматически обнаруживает нарушения single source of truth принципа:

Загружает все константы из config/ модулей
Сканирует всю кодовую базу на поиск этих констант
Выявляет нарушения и предлагает исправления через UnifiedConfig методы

Пример нарушения:

// ❌ ХАРДКОД (будет найден анализатором)
const serverPort = 8080

// ✅ ПРАВИЛЬНО (использование UnifiedConfig)
serverPort := cfg.GetServerPort()

Mapping таблица для агентов¶

Тип настроек	Config модуль	Примеры констант
Сетевые настройки	`config/network.yaml`	порты, CORS домены, хосты, SSL
База данных	`config/database.yaml`	PostgreSQL подключения, пулы, timeouts
Аутентификация	`config/auth.yaml`	JWT секреты, Supabase Auth, администраторы
Blockchain	`config/blockchain.yaml`	адреса контрактов, RPC endpoints, network IDs
Тестирование	`config/testing.yaml`	E2E настройки, производительность, test users
Мониторинг	`config/monitoring.yaml`	логирование, метрики, таймауты, health checks
Лимиты	`config/limits.yaml`	инвестиционные стратегии, APY, withdrawal лимиты

Критические требования¶

❌ ЗАПРЕЩЕНО: Создание дубликатов конфигурационных файлов (test-config.yaml, dev-config.yaml)
❌ ЗАПРЕЩЕНО: Хардкод любых константы из config/ модулей в коде
❌ ЗАПРЕЩЕНО: Ручное редактирование сгенерированных файлов
✅ ОБЯЗАТЕЛЬНО: Использование UnifiedConfig для всех настроек
✅ ОБЯЗАТЕЛЬНО: Environment variables для секретных данных в модулях