gskaro-v1/.skaro/architecture/invariants.md

rchitectural Invariants

1. Язык и рантайм

• Go 1.22 — основной язык разработки.
• Использование стандартной библиотеки предпочтительно внешним зависимостям.
• Код должен оставаться совместимым с Go 1.22 на всём жизненном цикле проекта.

2. Фреймворк и сетевой стек

• HTTP‑стек: net/http.
• Роутер: chi.
• Middleware — преимущественно стандартные или собственные, минимизация сторонних библиотек.

3. Архитектурный стиль

• Чистая архитектура (Domain → Usecase → Transport/Infrastructure).
• REST API как основной протокол взаимодействия.
• Фронтенд и бэкенд — полностью разделённые компоненты.

4. Хранилище данных

• Основная СУБД: PostgreSQL 15 (совместимость 14–16).
• Только параметризованные SQL‑запросы.
• Миграции — единый инструмент (фиксируется отдельно в ADR).
• Фронтенд хранит временную историю в localStorage.

5. Инфраструктура

• Контейнеризация: Docker.
• Запуск: systemd или Kubernetes (опционально).
• Конфигурация — только через переменные окружения.
• Никаких хардкодов конфигурации в коде.
• Логирование: структурированное JSON.
• Метрики: Prometheus‑совместимые.

6. Стандарты кодирования

• Linter: golangci‑lint с конфигурацией .golangci.yml.
• Formatter: gofmt.
• Именование: idiomatic Go (MixedCaps, без snake_case).
• Понятные имена без необоснованных сокращений.
• Максимальная длина функции: 40 строк.
• Максимальная вложенность: 3 уровня.
• Минимум внешних зависимостей.
• Запрет на дублирование кода — использовать абстракции и переиспользование.

7. Тестирование

• Минимальное покрытие: ≥ 70%.
• Unit‑тесты обязательны для:
• domain‑слоя
• usecase‑слоя
• Интеграционные тесты:
• API (контрактные)
• репозитории (если возможно)
• Инструменты:
• стандартный testing
• testify/assert, testify/require

8. Безопасность

• Аутентификация: JWT.
• Авторизация: RBAC (administrator/operator).
• Проверка прав — middleware.
• Валидация данных:
• DTO‑структуры
• валидация на HTTP‑слое
• Секреты:
• только env
• или секреты оркестратора (K8s/Proxmox)
• никаких секретов в репозитории
• SQL:
• только параметризованные запросы
• запрет на SQL‑конкатенацию

9. Коммуникация

• Протокол: REST.
• Формат: JSON.
• Защита: JWT.
• Версионирование API: /api/v1.

10. Правила работы с LLM

• Не оставлять пустые TODO — при неопределённости писать комментарий.
• Избегать скрытых предположений — документировать сомнения.
• Генерировать AI_NOTES.md:
• что сделано
• что не сделано
• вопросы и неопределённости
• Следовать Go‑идиомам.
• Не дублировать код.

11. Архитектурные решения (ADR)

• Язык: Go.
• Роутер: chi.
• База данных: PostgreSQL.
• API: REST.