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