docs: make project documentation self-contained

This commit is contained in:
2026-09-12 13:09:37 +03:00
parent aa9afc15e4
commit 3a99af1a6e
36 changed files with 1006 additions and 703 deletions
+22 -25
View File
@@ -1,34 +1,31 @@
# Рабочий процесс backend
# Backend: ответственность и проверка
## Предварительные условия
Backend требует Node 22. Создайте `backend/.env` на основе
`backend/.env.example` и замените placeholder-значения `JWT_SECRET` и
`TOKEN_ENCRYPTION_KEY`; token T-Bank в этот файл не записывается.
Backend обслуживает публичный HTTP API, локальные сессии, хранение данных
и интеграции с внешними источниками. Локальная поставка использует Node 22
и SQLite. Окружению нужны адрес frontend, адрес базы, секрет подписи сессий
и отдельный ключ шифрования подключения. T-Bank token вводится пользователем
через настройки и не является общим секретом окружения.
```bash
cd backend
cp .env.example .env
npm ci
```
Назначение параметров, согласование адресов и сохранение данных описаны в
[локальном окружении](local-workspace.md).
## Локальная проверка
Canonical gate не изменяет versioned-файлы:
Проверка backend объединяет статический анализ, проверку типов приложения
и тестов, автоматические сценарии и сборку. Она не изменяет исходные материалы;
автоматическое исправление форматирования не считается доказательством проверки.
Диагностика покрытия доступна отдельно, общего числового порога для backend нет.
```bash
npm run verify
```
[Сравнение OpenAPI](runtime-openapi-verification.md) проверяет соответствие
публичного контракта ожиданиям frontend. Валидация запросов, cookie, доступ
и ошибки требуют полного HTTP-потока; целостность и конкурентные изменения
данных — проверки с изолированной реальной базой.
Он последовательно запускает lint, application/test TypeScript, Jest и build. `npm run lint:fix` — явная
записывающая команда, а `npm run test:cov` — отдельная диагностика без общего
числового threshold. Runtime OpenAPI сверяется с frontend snapshot из workspace:
```bash
cd backend
npm run test:openapi-contract
```
`npm run test:e2e` временно не является passing gate: Prisma schema engine
останавливает migration до Jest. Точная диагностика и trigger пересмотра
зафиксированы в [audit remediation registry](audit-remediation.md).
**Известное ограничение:** движок Prisma 7.9.1 при применении миграций к новой
SQLite-базе возвращает `Schema engine error` до запуска сквозных тестов.
Это воспроизведено и при проверке локального окружения 12 сентября 2026 года.
Успех остальных проверок не подтверждает прохождение этой границы. Условие
пересмотра — стабильная версия с тремя последовательными успешными применениями
миграций на новых базах под Node 22.