From 2d1777823b411846161f3c2c211e46b2e97ea1a2 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Wed, 12 Aug 2026 23:04:36 +0300 Subject: [PATCH] docs: add baseline OpenSpec change --- AGENTS.md | 18 +++++ openspec/changes/baseline/.openspec.yaml | 2 + openspec/changes/baseline/design.md | 68 +++++++++++++++++++ openspec/changes/baseline/proposal.md | 29 ++++++++ .../specs/api-contract-generation/spec.md | 26 +++++++ .../specs/project-documentation/spec.md | 26 +++++++ .../baseline/specs/project-foundation/spec.md | 33 +++++++++ openspec/changes/baseline/tasks.md | 38 +++++++++++ 8 files changed, 240 insertions(+) create mode 100644 AGENTS.md create mode 100644 openspec/changes/baseline/.openspec.yaml create mode 100644 openspec/changes/baseline/design.md create mode 100644 openspec/changes/baseline/proposal.md create mode 100644 openspec/changes/baseline/specs/api-contract-generation/spec.md create mode 100644 openspec/changes/baseline/specs/project-documentation/spec.md create mode 100644 openspec/changes/baseline/specs/project-foundation/spec.md create mode 100644 openspec/changes/baseline/tasks.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0cc2371 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,18 @@ +# Specs + +## Назначение + +Репозиторий SDD-артефактов и OpenSpec store: `openspec/`. Все функциональные изменения планируются в `openspec/changes//` до реализации в frontend или backend. + +## Проверка + +```bash +openspec validate --type change --store wealth-ledger-specs +openspec instructions apply --change --json --store wealth-ledger-specs +``` + +## Границы + +- Change содержит proposal, design, delta-specs и tasks; требования и задачи живут здесь, не в `MVP.md` или коде. +- Реализация отмечается в tasks только после выполненной работы. Перед архивированием change проходит `opsx-verify` и получает связанную документацию в `../docs`. +- Не хранить код приложений и долгоживущие ADR в этом репозитории. diff --git a/openspec/changes/baseline/.openspec.yaml b/openspec/changes/baseline/.openspec.yaml new file mode 100644 index 0000000..5081c98 --- /dev/null +++ b/openspec/changes/baseline/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-08-12 diff --git a/openspec/changes/baseline/design.md b/openspec/changes/baseline/design.md new file mode 100644 index 0000000..9708082 --- /dev/null +++ b/openspec/changes/baseline/design.md @@ -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 не затрагиваются. diff --git a/openspec/changes/baseline/proposal.md b/openspec/changes/baseline/proposal.md new file mode 100644 index 0000000..912cb5f --- /dev/null +++ b/openspec/changes/baseline/proposal.md @@ -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`. diff --git a/openspec/changes/baseline/specs/api-contract-generation/spec.md b/openspec/changes/baseline/specs/api-contract-generation/spec.md new file mode 100644 index 0000000..bad37d8 --- /dev/null +++ b/openspec/changes/baseline/specs/api-contract-generation/spec.md @@ -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 diff --git a/openspec/changes/baseline/specs/project-documentation/spec.md b/openspec/changes/baseline/specs/project-documentation/spec.md new file mode 100644 index 0000000..8c026b7 --- /dev/null +++ b/openspec/changes/baseline/specs/project-documentation/spec.md @@ -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** изменение не считается готовым к архивированию diff --git a/openspec/changes/baseline/specs/project-foundation/spec.md b/openspec/changes/baseline/specs/project-foundation/spec.md new file mode 100644 index 0000000..8c44083 --- /dev/null +++ b/openspec/changes/baseline/specs/project-foundation/spec.md @@ -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 diff --git a/openspec/changes/baseline/tasks.md b/openspec/changes/baseline/tasks.md new file mode 100644 index 0000000..2e66ed9 --- /dev/null +++ b/openspec/changes/baseline/tasks.md @@ -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 Обновить отметки задач после подтвержденной верификации и закоммитить изменения по отдельным репозиториям.