104 lines
7.0 KiB
Markdown
104 lines
7.0 KiB
Markdown
## Context
|
||
|
||
Корень workspace — coordination directory, а не package-manager workspace и не
|
||
Git-репозиторий. `frontend`, `backend`, `specs` и `docs` — независимые Git
|
||
roots. `specs/scripts/verify-openspec-authority.sh` уже показывает правильное
|
||
место для versioned cross-repository tooling: script определяет workspace
|
||
относительно себя, а не доверяет текущей директории.
|
||
|
||
Frontend закрепляет Node 22 и имеет offline `npm run verify`. Для backend нет
|
||
эквивалентных runtime policy и отдельных quality gates: `lint` запускает ESLint
|
||
с `--fix`, base tsconfig включает тесты, а build tsconfig исключает их.
|
||
Существующие e2e tests создают in-memory Nest application, но их script сначала
|
||
запускает Prisma на фиксированной `/tmp` DB и сейчас падает до Jest. Swagger
|
||
доступен по `/api/docs-json` при `NODE_ENV=development`;
|
||
`frontend/scripts/openapi:sync.mjs` — единственный намеренный writer committed
|
||
snapshot и generated types.
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Цели:**
|
||
|
||
- Восстановить исполнимые backend gates для lint и TypeScript приложения и
|
||
тестов с понятной диагностикой failures.
|
||
- Доказать отдельной read-only командой, что полный runtime OpenAPI document
|
||
совпадает с committed frontend snapshot.
|
||
- Сделать Node/npm bootstrap и конкретные verification commands discoverable
|
||
для агентов.
|
||
- Сохранить pre-existing working-tree state пользователя; не создавать
|
||
versioned writes во время проверок.
|
||
|
||
**Не входит в scope:**
|
||
|
||
- CI/CD, remote verification, Docker, новый task runner, package-manager
|
||
workspace или общий workspace verifier.
|
||
- Изоляция backend e2e DB, обновление Prisma packages и восстановление
|
||
migration gate: WL-P2-05 и зависимый WL-P2-13 отложены из-за нестабильности
|
||
Prisma 7.9.1 на Node 22.
|
||
- JSON report format, cached results, plug-in architecture, arbitrary diff
|
||
bases, сохранённые hashes либо fixture/unit-test harness для process scripts.
|
||
- Изменение OpenAPI sync writer, generated frontend types, пользовательских API
|
||
statuses, T-Bank integration, application features, перенос business glossary
|
||
`CONTEXT.md` или удаление существующего OpenSpec authority fixture test.
|
||
|
||
## Decisions
|
||
|
||
### Backend check и fix — разные операции
|
||
|
||
Backend предоставляет `lint:check` без `--fix`, `lint:fix` с явным write intent
|
||
и сохраняет `lint` как совместимый alias для `lint:check`. Он предоставляет
|
||
отдельные команды `typecheck:app` и `typecheck:test` на основе выделенных
|
||
tsconfig files. Эти команды не создают repository artifacts; build и e2e не
|
||
объявляются частью нового общего verdict.
|
||
|
||
### Runtime OpenAPI сверяется отдельной read-only командой
|
||
|
||
`specs/scripts/verify-runtime-openapi.sh` определяет workspace из собственного
|
||
пути, поднимает backend с детерминированным development environment, ждёт local
|
||
readiness, получает `/api/docs-json` и всегда завершает child process. Команда
|
||
рекурсивно упорядочивает JSON object keys, сохраняя array order, записывает
|
||
canonical runtime и snapshot documents во временную директорию, сравнивает их
|
||
SHA-256 и выводит unified diff при различии.
|
||
|
||
Она никогда не вызывает `openapi:sync`, не записывает frontend snapshot и не
|
||
обновляет generated types. Это узкий контрактный gate, а не orchestration
|
||
interface для всех репозиториев.
|
||
|
||
### Bootstrap и документация задают один contract
|
||
|
||
Оба приложения требуют Node 22 и `npm ci`. Scoped `AGENTS.md` перечисляют
|
||
только реально существующие non-mutating verification commands и явно отделяют
|
||
писатели `lint:fix` и `openapi:sync`. Durable development documentation
|
||
показывает prerequisites и границы отдельной runtime-contract команды.
|
||
|
||
### Prisma findings явно отложены, а не маскируются обходом
|
||
|
||
`prisma migrate deploy` 7.9.1 воспроизводимо возвращает пустой schema-engine
|
||
error как на фиксированной, так и на уникальной временной SQLite DB; включение
|
||
engine diagnostics меняет результат. На 2026-08-23 опубликованная latest
|
||
stable version также 7.9.1. Не вводится второй migration mechanism и не
|
||
обновляются зависимости без подтверждённого stable candidate. Реестр фиксирует
|
||
дату, причину и trigger review: следующая stable Prisma должна трижды применить
|
||
existing migrations к чистой DB на Node 22.
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- [Runtime backend не стартует или child process остаётся после ошибки] →
|
||
command создаёт cleanup trap до запуска backend и сохраняет фактический exit
|
||
status.
|
||
- [Canonicalization скрывает различие контрактов] → нормализуется только
|
||
порядок object keys; arrays и каждое JSON field остаются частью SHA-256 input.
|
||
- [Prisma schema engine остаётся недоступным на supported runtime] → WL-P2-05
|
||
и WL-P2-13 остаются `deferred` до опубликованной stable версии, прошедшей
|
||
оговорённый reproduction gate.
|
||
- [Ignored artifacts путаются с versioned writes] → отдельные команды не
|
||
считают `build` или e2e своим успехом и документируют свои временные ресурсы.
|
||
|
||
## Migration Plan
|
||
|
||
Не нужны migration production data или deployment sequence. Разработчики
|
||
запускают `npm ci` под Node 22 в каждом application repository, используют
|
||
`npm run lint:fix` только осознанно и запускают runtime OpenAPI check отдельно
|
||
из workspace. Rollback — обычный revert independently versioned changes; он не
|
||
меняет committed API artifacts или persistent user data.
|