67/docs/compose/specs/2026-06-22-backend-stabilization-design.md

Backend Stabilization Design

[S1] Контекст

Репозиторий уже содержит три основных слоя: apps/web, apps/gateway и Go-сервисы в services/. Сейчас проект не доведен до почти production-состояния по трем причинам: установка и сборка из корня не подтверждены, frontend частично опирается на mock-данные, а backend хранит состояние в demo/in-memory store.

Цель этой спецификации: определить первый под-проект, который переведет приложение из состояния scaffold/demo в состояние почти production-демо с реальным backend-контуром.

[S2] Цель первого под-проекта

Первый под-проект называется backend stabilization.

Его результат:

• проект воспроизводимо устанавливается и собирается из корня репозитория;
• gateway и Go-сервисы работают на PostgreSQL, а не на in-memory store;
• frontend перестает зависеть от mock-only ядра в основных сценариях;
• аутентификация, авторизация и сохранение данных становятся реальными и повторяемыми;
• локальный запуск и Docker-окружение дают одинаково рабочий backend-контур.

[S3] Объем и границы

В объем первой фазы входят:

• реальные данные для auth, users/me, content, categories, tags, speakers, subscriptions, notifications, comments, search, admin, analytics summary, media metadata/upload;
• password hashing, access token, проверка текущего пользователя, logout, защита маршрутов;
• миграции и seed-данные для стартовых ролей, аккаунтов и базовых сущностей;
• smoke/integration verification для критического пути.

В первую фазу не входят:

• внешняя production-инфраструктура вне репозитория;
• CDN или объектное хранилище;
• полный UI-polish всех экранов;
• расширенная аналитика сверх уже существующих экранов и summary-метрик.

[S4] Архитектурный подход

Архитектура сохраняется существующая:

• apps/web остается клиентом;
• apps/gateway остается единой внешней точкой входа;
• services/cmd/* остаются отдельными Go-процессами;
• database/ и миграции становятся источником истины для схемы данных.

Ключевой принцип этой фазы: не переписывать систему заново и не вводить тяжелую новую абстракцию без необходимости. Минимальный путь — заменить текущее общее demoStore на PostgreSQL-backed хранилище, сохранив текущие HTTP-контракты везде, где это возможно.

Новые или уточненные backend-компоненты:

• конфигурация для DSN, токен-секретов, TTL и внутренних URL;
• GORM-backed persistence слой поверх PostgreSQL;
• auth-логика для хэша паролей и проверки токенов;
• seed/bootstrap слой для стартовых данных;
• реальные health checks для gateway и сервисов.

[S5] Потоки данных

Целевой поток запроса:

1. frontend отправляет запрос только в gateway;
2. gateway валидирует запрос, извлекает токен, определяет пользователя и применяет базовые RBAC-проверки;
3. gateway проксирует запрос в нужный Go-сервис;
4. Go-сервис читает и записывает состояние в PostgreSQL;
5. ответ возвращается через gateway в единообразном JSON-формате.

Скрытый local fallback и demo-token перестают быть основным режимом работы. Для разработки допускаются только явные seed-данные, а не подмена настоящих ответов моками при ошибках backend-контура.

[S6] Ошибки, безопасность и наблюдаемость

Требования этой фазы:

• единый error response через gateway: код, сообщение, request ID;
• корректные 401 и 403 для защищенных endpoint'ов;
• health endpoints должны отражать реальное состояние зависимостей, включая БД;
• request ID должен проходить через gateway и сервисы для трассировки;
• пароли хранятся только в хэшированном виде;
• защищенные маршруты не должны обходиться demo-механикой.

[S7] Проверка готовности

Работа считается завершенной, когда подтверждены все пункты:

• чистая установка зависимостей и сборка проекта из корня;
• успешный npm run check;
• успешный локальный запуск backend и frontend;
• критические API-сценарии проходят в smoke/integration verification;
• данные сохраняются в PostgreSQL и переживают перезапуск сервисов.

Минимальный критический путь для проверки:

• login;
• GET /api/auth/me;
• список и изменение контента;
• создание комментария;
• создание подписки;
• admin users;
• audit log;
• analytics summary.

[S8] Решения по объему

Путь выполнения для этой спецификации: backend-first.

Это означает, что в первой фазе приоритет отдается реальности backend-контура, API, БД, auth и repeatable verification. Frontend должен быть совместим с результатом, но крупные визуальные доработки не входят в критический путь этой спецификации.