92 lines
4.2 KiB
Markdown
92 lines
4.2 KiB
Markdown
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.
|
||
|
||
|
||
|