Qadam Platform — архитектурные решения

Паспорт документа

• Статус документа: working spec
• Актуально на: 28 марта 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении платформенной архитектуры, roadmap или статуса реализации
• Область применения: канонические платформенные spec-документы для текущего ядра Qadam
• Связанные документы:
  • Текущее состояние
  • Roadmap
  • Индекс документации

ADR-001: Хранение JWT в httpOnly cookies

Контекст

Токены в localStorage создают лишний XSS-риск и усложняют безопасную серверную работу в Next.js.

Решение

Access token и refresh token хранятся в httpOnly cookies.

Последствия

• Frontend не читает токены напрямую.
• Проверка авторизации идёт через GET /auth/me.
• Нужна корректная настройка cookies, CORS и SSR.

ADR-002: Refresh token rotation с jti

Контекст

Простой долгоживущий refresh token плохо защищает от повторного использования и кражи.

Решение

Refresh token содержит jti. Активные jti хранятся в Redis. При refresh токен одноразово потребляется, а семейство токенов может быть отозвано при подозрении на reuse.

Последствия

• Нужна инфраструктура хранения в Redis.
• Старые refresh token без jti должны считаться устаревшими после соответствующего деплоя.
• Unit-тесты auth-слоя должны учитывать новую модель.

ADR-003: Next.js App Router и SSR как базовая модель для публичных страниц

Контекст

Каталог, карточки айтемов и публичные страницы продавцов должны быть пригодны для SEO и быстро отдаваться из сервера.

Решение

Использовать Next.js App Router, Server Components и SSR как основную модель для публичной части.

Последствия

• Данные для публичных страниц грузятся на сервере.
• Client Components используются только там, где действительно нужна интерактивность.
• Нужно следить за корректной hydration-моделью и сериализацией.

ADR-004: Общие схемы в packages/shared

Контекст

Валидация не должна расходиться между frontend и backend.

Решение

Общие DTO и Zod-схемы живут в packages/shared.

Последствия

• Один источник истины для валидации.
• Backend и frontend используют одинаковые контракты.
• Изменение поля начинается с общей схемы, а не с локальных DTO.

ADR-005: Канонический production deploy на текущем сервере — host runtime, а не Docker runtime

Контекст

В репозитории есть Docker-контур, но фактический production на текущем сервере запущен через systemd, nginx, PostgreSQL и Redis на хосте.

Решение

До отдельного пересмотра канонической считается именно host-level модель деплоя.

Последствия

• Источником истины по эксплуатации становится docs/operations/deployment-runbook.md.
• Docker-скрипты считаются legacy и требуют ревизии перед любым использованием в production.
• Любые изменения инфраструктуры должны сначала отражаться в хостовом runbook.

ADR-006: Отдельный защищённый портал документации на поддомене

Контекст

Команде нужен быстрый доступ к roadmap, требованиям, текущему состоянию и markdown-документам прямо с сервера.

Решение

Поднять qadam-roadmap.2fab.app, закрыть его basic auth, вынести runtime в отдельный standalone docs-service и читать канонические markdown-документы из qadam-core/docs с поддержкой переходов в связанные specs и docs/Agents.

Последствия

• Команда работает с живыми файлами, а не с экспортами или копиями.
• Портал можно использовать как внутреннюю рабочую поверхность для документации.
• Требуется отдельное сопровождение basic auth, upload/delete/comment механики, отдельного runtime/unit и TLS.