docs: add baseline OpenSpec change
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-08-12
|
||||
@@ -0,0 +1,68 @@
|
||||
## 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 не затрагиваются.
|
||||
@@ -0,0 +1,29 @@
|
||||
## Why
|
||||
|
||||
В WealthLedger есть пустые стартовые проекты NestJS и React/Vite, но отсутствуют общий технический фундамент, документированная архитектура и повторяемый SDD-процесс. Установление этих границ до реализации пользовательских возможностей не позволит последующим фичам авторизации и T-Bank переопределить общие контракты проекта.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Создать правила для рабочей области с четырьмя репозиториями и локальный план поставки MVP.
|
||||
- Создать структуру документации и зафиксировать устойчивые архитектурные решения о хранении данных, API-контрактах, внешней интеграции, секретах, сессиях и кэшировании.
|
||||
- Адаптировать инфраструктуру frontend-шаблона без Todo-домена: FSD, русская локализация, тема Mantine, маршрутизация, генерация API-клиента и проверки качества.
|
||||
- Подготовить backend-инфраструктуру для версионированного REST API, генерируемого OpenAPI, локального SQLite через Prisma, валидации конфигурации, CORS и безопасной обработки ошибок.
|
||||
- Определить правила реализации и верификации baseline; авторизация, подключение T-Bank, получение брокерских счетов и отображение портфеля в него не входят.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `project-foundation`: Документированный и версионируемый фундамент frontend и backend, необходимый для будущих SDD-изменений.
|
||||
- `api-contract-generation`: Генерируемый OpenAPI как контракт между NestJS backend и React frontend.
|
||||
- `project-documentation`: Устойчивые архитектурные решения и правила документирования фич.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
Нет.
|
||||
|
||||
## Impact
|
||||
|
||||
- Затрагивает репозитории `frontend`, `backend`, `specs` и `docs`, а также локальные корневые `MVP.md` и `AGENTS.md`.
|
||||
- Добавляет инфраструктурные зависимости frontend и зависимости backend для Swagger/OpenAPI, конфигурации, валидации, Prisma и SQLite.
|
||||
- Устанавливает `/api/v1` как префикс API backend, а сгенерированный OpenAPI-документ как источник frontend-клиента.
|
||||
- Создает границу реализации для последующих изменений `add-authentication`, `add-tbank-connection`, `add-brokerage-accounts` и `add-portfolio-view`.
|
||||
@@ -0,0 +1,26 @@
|
||||
## Purpose
|
||||
|
||||
Определяет единый, проверяемый контракт HTTP API между backend и frontend, исключающий ручное расхождение типов и маршрутов.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Backend публикует машиночитаемый API-контракт
|
||||
Backend SHALL публиковать версионированный OpenAPI-документ, описывающий доступные HTTP-маршруты, параметры, тела запросов, ответы и ошибки API `/api/v1`.
|
||||
|
||||
#### Scenario: Разработчик получает контракт API
|
||||
- **WHEN** backend запущен в локальной среде разработки
|
||||
- **THEN** разработчик может получить OpenAPI-документ для генерации frontend-клиента
|
||||
|
||||
### Requirement: Frontend использует сгенерированный API-клиент
|
||||
Frontend SHALL генерировать типы и модуль HTTP-запросов из опубликованного OpenAPI-документа. Сгенерированный результат MUST храниться в frontend-репозитории и обновляться локальной воспроизводимой командой.
|
||||
|
||||
#### Scenario: API-контракт изменяется
|
||||
- **WHEN** backend меняет опубликованный API-контракт
|
||||
- **THEN** frontend может повторно сгенерировать типы и запросный модуль до интеграции изменения
|
||||
|
||||
### Requirement: Frontend не зависит от OpenAPI во время работы
|
||||
Работающий frontend MUST использовать ранее сгенерированный клиент и MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска или выполнения пользовательского сценария.
|
||||
|
||||
#### Scenario: OpenAPI endpoint недоступен после сборки frontend
|
||||
- **WHEN** frontend уже собран, а endpoint OpenAPI временно недоступен
|
||||
- **THEN** frontend продолжает использовать сгенерированный код для запросов к API
|
||||
@@ -0,0 +1,26 @@
|
||||
## Purpose
|
||||
|
||||
Определяет обязательную документацию архитектурных решений и пользовательских возможностей, сопровождающую SDD-изменения WealthLedger.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Важные архитектурные решения фиксируются в ADR
|
||||
Репозиторий docs SHALL содержать ADR для выбора локального хранилища, API-контракта, gRPC-интеграции T-Bank, хранения T-Bank токенов, устойчивости upstream-вызовов, auth-сессий и frontend-кэша. Каждый ADR MUST описывать контекст, решение и последствия.
|
||||
|
||||
#### Scenario: Разработчик оценивает архитектурное ограничение
|
||||
- **WHEN** разработчик хочет изменить один из зафиксированных механизмов
|
||||
- **THEN** он может определить исходное решение и его последствия из соответствующего ADR
|
||||
|
||||
### Requirement: Реализованная фича получает документацию
|
||||
Каждая завершенная пользовательская фича SHALL иметь Markdown-документ в `docs/features`, описывающий пользовательский поток, API-сценарий, ограничения и необходимые Mermaid-диаграммы.
|
||||
|
||||
#### Scenario: Функциональное изменение готово к закрытию
|
||||
- **WHEN** реализация пользовательской фичи завершена
|
||||
- **THEN** ее feature-документ существует и отражает фактическое поведение
|
||||
|
||||
### Requirement: OpenSpec change закрывается только после полной верификации
|
||||
Функциональный OpenSpec change MUST содержать все требуемые артефакты, реализацию, критические тесты, успешную проверку `opsx-verify` и связанную документацию до архивирования.
|
||||
|
||||
#### Scenario: Команда пытается архивировать незавершенное изменение
|
||||
- **WHEN** для изменения отсутствует реализация, верификация или feature-документ
|
||||
- **THEN** изменение не считается готовым к архивированию
|
||||
@@ -0,0 +1,33 @@
|
||||
## Purpose
|
||||
|
||||
Определяет минимальный, согласованный фундамент рабочих приложений и правила их совместного развития через отдельные репозитории и SDD-изменения.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Репозитории содержат локальные инструкции для AI-агентов
|
||||
Система SHALL содержать обзорный `AGENTS.md` в корне рабочей области и отдельный `AGENTS.md` в репозиториях frontend, backend, specs и docs. Инструкции MUST описывать назначение области, локальные команды проверки, границы ответственности и связь с SDD-артефактами.
|
||||
|
||||
#### Scenario: Агент начинает работу в отдельном репозитории
|
||||
- **WHEN** агент открывает любой из репозиториев frontend, backend, specs или docs
|
||||
- **THEN** он может определить локальные правила работы и источник связанных спецификаций из `AGENTS.md` этого репозитория
|
||||
|
||||
### Requirement: Локальный план MVP не является источником спецификации
|
||||
Система SHALL содержать корневой локальный `MVP.md` с границами MVP, принятыми решениями, порядком поставок и критериями готовности. Требования к функциональности MUST храниться в OpenSpec, а устойчивая документация MUST храниться в репозитории docs.
|
||||
|
||||
#### Scenario: Решение уточняется во время SDD-изменения
|
||||
- **WHEN** изменение уточняет наблюдаемое поведение системы
|
||||
- **THEN** оно фиксируется в OpenSpec и соответствующей документации, а `MVP.md` остается компактной картой поставки
|
||||
|
||||
### Requirement: Frontend предоставляет минимальный каркас приложения
|
||||
Frontend SHALL предоставлять русскоязычный адаптивный каркас приложения с маршрутами `/login`, `/register`, `/accounts`, `/accounts/:accountId` и `/settings`, светлой финансовой темой и навигацией для счетов и настроек. Каркас MUST содержать состояния загрузки, ошибки и пустых данных без реализации доменных сценариев.
|
||||
|
||||
#### Scenario: Пользователь открывает маршрут MVP
|
||||
- **WHEN** пользователь переходит на любой маршрут MVP
|
||||
- **THEN** frontend отображает соответствующий каркас страницы и не показывает шаблонный Todo-интерфейс
|
||||
|
||||
### Requirement: Backend предоставляет безопасный API-фундамент
|
||||
Backend SHALL публиковать HTTP API с префиксом `/api/v1`, принимать разрешенные frontend origins только из конфигурации и возвращать клиенту безопасные ошибки без секретов или внутренних деталей.
|
||||
|
||||
#### Scenario: Запрос приходит с неразрешенного origin
|
||||
- **WHEN** браузер отправляет cross-origin запрос не с настроенного frontend origin
|
||||
- **THEN** backend не разрешает браузеру доступ к ответу через CORS
|
||||
@@ -0,0 +1,38 @@
|
||||
## 1. Рабочая область и SDD
|
||||
|
||||
- [x] 1.1 Создать корневые `AGENTS.md` и `MVP.md` с картой рабочей области, границами MVP, принятыми решениями, порядком поставок и критериями закрытия OpenSpec change.
|
||||
- [x] 1.2 Добавить локальные `AGENTS.md` в frontend, backend, specs и docs с назначением репозитория, командами проверки, границами ответственности и ссылками на OpenSpec.
|
||||
- [x] 1.3 Проверить, что docs является независимым Git-репозиторием, а frontend, backend и specs не получили изменений в их Git-границах.
|
||||
|
||||
## 2. Постоянная документация
|
||||
|
||||
- [x] 2.1 Создать в docs разделы `adr`, `architecture`, `development` и `features` с минимальными индексами или правилами размещения документов.
|
||||
- [x] 2.2 Описать в ADR выбор Prisma с SQLite и его границы для локального MVP.
|
||||
- [x] 2.3 Описать в ADR Nest-generated OpenAPI как backend-to-frontend контракт.
|
||||
- [x] 2.4 Описать в ADR будущий gRPC boundary T-Bank и запрет прямых вызовов из frontend.
|
||||
- [x] 2.5 Описать в ADR модель шифрования T-Bank токена и безопасное обращение с секретами.
|
||||
- [x] 2.6 Описать в ADR глобальный rate limit, повторы и in-memory TTL-кэш T-Bank данных.
|
||||
- [x] 2.7 Описать в ADR access/refresh auth-сессии и React Query caching policy.
|
||||
|
||||
## 3. Backend foundation
|
||||
|
||||
- [x] 3.1 Добавить зависимости backend для конфигурации, валидации, Swagger/OpenAPI, Prisma и SQLite.
|
||||
- [x] 3.2 Добавить типизированную проверку переменных окружения, `.env.example` и безопасную конфигурацию CORS с разрешенным frontend origin.
|
||||
- [x] 3.3 Настроить Prisma с SQLite и доступный lifecycle-managed database service без доменных таблиц и миграций.
|
||||
- [x] 3.4 Настроить `/api/v1`, Swagger/OpenAPI document и единый безопасный HTTP error response.
|
||||
- [x] 3.5 Добавить минимальные backend-проверки конфигурации и безопасного error response, выполнить их и backend build.
|
||||
|
||||
## 4. Frontend foundation
|
||||
|
||||
- [x] 4.1 Удалить Vite demo UI и перенести минимальный FSD app shell, providers и маршрутизацию из frontend-template без Todo-кода.
|
||||
- [x] 4.2 Добавить React Router, React Query, Mantine, русскую i18n-инфраструктуру и светлую тему на основе токенов `fin-tracker`.
|
||||
- [x] 4.3 Реализовать адаптивную навигацию счетов и настроек, а также нейтральные loading, error и empty состояния для маршрутов MVP без доменных запросов.
|
||||
- [x] 4.4 Добавить frontend environment configuration, локальную команду OpenAPI generation и размещение сгенерированного API-клиента в репозитории.
|
||||
- [x] 4.5 Добавить только необходимые quality/test tooling из frontend-template и минимальные проверки отсутствия Todo-кода и загрузки маршрутов.
|
||||
|
||||
## 5. Контракт и верификация baseline
|
||||
|
||||
- [x] 5.1 Запустить backend, сгенерировать frontend API-клиент из его OpenAPI-документа и убедиться, что frontend runtime не зависит от OpenAPI endpoint.
|
||||
- [x] 5.2 Выполнить typecheck, lint, тесты и build frontend; выполнить lint, тесты и build backend.
|
||||
- [x] 5.3 Выполнить проверку OpenSpec baseline совместимой командой CLI и устранить все ошибки в артефактах.
|
||||
- [x] 5.4 Обновить отметки задач после подтвержденной верификации и закоммитить изменения по отдельным репозиториям.
|
||||
Reference in New Issue
Block a user