# 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 должен быть совместим с результатом, но крупные визуальные доработки не входят в критический путь этой спецификации.