69 lines
8.6 KiB
Markdown
69 lines
8.6 KiB
Markdown
## 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
|
||
|
||
1. Инициализировать Git в docs и создать локальные guidance и MVP-файлы.
|
||
2. Создать структуру docs и ADR, фиксирующие принятые решения.
|
||
3. Адаптировать frontend и backend foundations без доменной функциональности.
|
||
4. Сгенерировать и проверить базовый OpenAPI-клиент frontend из запущенного backend.
|
||
5. Выполнить проверки каждого репозитория и верификацию OpenSpec baseline.
|
||
6. При откате удалить только baseline-коммиты в затронутом независимом репозитории; общая рабочая область и read-only references не затрагиваются.
|