8.6 KiB
Context
См. мотивацию в proposal.md. Рабочая область уже содержит независимые Git-репозитории frontend, backend и specs; docs и корневые рабочие файлы еще не подготовлены. Frontend и backend являются начальными шаблонами без общего контракта, доменной структуры или локальных инструкций. Frontend-template и fin-tracker доступны только как read-only референсы.
Goals / Non-Goals
Goals:
- Подготовить воспроизводимый фундамент четырех независимых репозиториев.
- Установить OpenAPI как единственный контракт между NestJS API и React-клиентом.
- Перенести только нужную инфраструктуру frontend-template и тему
fin-tracker, не перенося шаблонный домен. - Сделать локальную конфигурацию и ошибки безопасными по умолчанию.
- Оставить ясные места расширения для последующих OpenSpec changes без реализации их поведения.
Non-Goals:
- Реализовывать регистрацию, сессии, T-Bank gRPC-клиент, хранение токенов, счета или портфель.
- Добавлять Docker, CI/CD, deployment, Redis, серверные snapshots, dark mode или доменные mock-сценарии.
- Создавать отдельный UI-пакет или копировать все компоненты
fin-tracker.
Decisions
Четыре изолированных Git-репозитория и локальная рабочая карта
В корне остаются неверсируемые AGENTS.md и MVP.md. Каждый из frontend, backend, specs и docs содержит собственный AGENTS.md, а docs инициализируется отдельным Git-репозиторием. MVP.md хранит компактный порядок поставок и уже принятые решения; нормативные требования и design/tasks артефакты живут только в OpenSpec.
Альтернатива - сделать корень монорепозиторием или хранить все правила только в одном AGENTS.md. Она отклонена, потому что пользователь явно выбрал независимую историю модулей, а локальный агент не всегда получает контекст рабочей области.
OpenAPI как однонаправленный контракт
Backend генерирует Swagger/OpenAPI из контроллеров и DTO, использует /api/v1 для будущих HTTP-маршрутов и публикует документ только для локальной разработки. Frontend запускает локальную команду генерации и коммитит типы и HTTP-модуль в свой репозиторий. Работающий frontend не получает типы динамически и не зависит от Swagger endpoint.
Альтернатива - вручную поддерживать типы или хранить OpenAPI YAML в docs/specs. Она отклонена: ручные дубликаты расходятся с backend, а документация не является исполняемым источником контракта.
Минимальная адаптация frontend-template
Frontend получает FSD-каркас, React Router, React Query, Mantine, русский i18n, инструменты генерации API, тестовую и quality-инфраструктуру из референса. Todo entities, features, pages, mocks, e2e-сценарии и тексты не переносятся. Цвета и spacing tokens адаптируются из fin-tracker в светлую тему Mantine и небольшой CSS token layer. На baseline создаются только маршруты, app shell и нейтральные loading/error/empty pages.
Альтернатива - копировать весь шаблон или строить frontend на чистом Vite. Полный перенос оставит неиспользуемый Todo-код, а чистый Vite потребует повторно собирать уже проверенную инфраструктуру.
NestJS foundation с Prisma и SQLite
Backend добавляет конфигурацию окружения с fail-fast валидацией, Prisma с SQLite, versioned global prefix, Swagger, CORS с origin из окружения и единый безопасный формат HTTP-ошибок. Базовая схема Prisma может быть пустой до add-authentication; baseline не создает пользовательские или сессионные таблицы.
Альтернатива - добавить БД вместе с auth. Она отклонена, поскольку Prisma-механика и проверка конфигурации являются общим фундаментом будущих изменений и должны быть проверены отдельно.
Документация разделена по назначению
Docs содержит adr/ для долгоживущих технических решений, architecture/ для cross-feature устройства, development/ для процесса и features/ для завершенных пользовательских возможностей. ADR создаются уже в baseline для Prisma/SQLite, OpenAPI, будущего gRPC boundary, шифрования T-Bank токенов, upstream resilience, auth session model и React Query caching. Mermaid остается встроенным в Markdown.
Альтернатива - фиксировать решения только в OpenSpec. Она отклонена: после архивирования change его план не удобен как постоянная архитектурная документация.
Risks / Trade-offs
- [Перенос слишком большого объема из frontend-template] → Переносить только инфраструктурные файлы и удалять все Todo-специфичные зависимости, код и конфигурацию.
- [Несовпадение OpenAPI generation с будущими Nest DTO] → Добавить локальную команду генерации и проверять обновление generated client при изменении контракта.
- [SQLite и local-only окружение маскируют deployment-проблемы] → Хранить connection string и CORS origin в env, не добавляя deployment-инфраструктуру до реальной потребности.
- [Ранние ADR описывают еще не реализованные технические решения] → ADR четко отмечают статус baseline decision и привязывают применение к соответствующему будущему OpenSpec change.
- [Пустой Prisma schema не создает полезную миграцию] → Подключить Prisma и конфигурацию в baseline, первую доменную миграцию создать вместе с authentication.
Migration Plan
- Инициализировать Git в docs и создать локальные guidance и MVP-файлы.
- Создать структуру docs и ADR, фиксирующие принятые решения.
- Адаптировать frontend и backend foundations без доменной функциональности.
- Сгенерировать и проверить базовый OpenAPI-клиент frontend из запущенного backend.
- Выполнить проверки каждого репозитория и верификацию OpenSpec baseline.
- При откате удалить только baseline-коммиты в затронутом независимом репозитории; общая рабочая область и read-only references не затрагиваются.