docs: archive baseline change

2026-08-12 23:09:16 +03:00
parent 2d1777823b
commit 68be4760ce
10 changed files with 91 additions and 0 deletions
@@ -0,0 +1,28 @@
+# api-contract-generation Specification
+
+## Purpose
+
+Определяет единый, проверяемый контракт HTTP API между backend и frontend, исключающий ручное расхождение типов и маршрутов.
+
+## 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,28 @@
+# project-documentation Specification
+
+## Purpose
+
+Определяет обязательную документацию архитектурных решений и пользовательских возможностей, сопровождающую SDD-изменения WealthLedger.
+
+## 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,35 @@
+# project-foundation Specification
+
+## Purpose
+
+Определяет минимальный, согласованный фундамент рабочих приложений и правила их совместного развития через отдельные репозитории и SDD-изменения.
+
+## 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