From c74c57373329e4accc46dbc13fdbe57ebf7ea3fd Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Sun, 13 Sep 2026 14:52:20 +0300 Subject: [PATCH] docs: close SQLite migration and e2e blocker --- README.md | 3 +- development/audit-remediation.md | 41 ++++++++++++++++++++- development/local-workspace.md | 17 +++++---- development/runtime-openapi-verification.md | 10 +++-- development/verification.md | 39 ++++++++++---------- 5 files changed, 75 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 5f14a17..ba36dd8 100644 --- a/README.md +++ b/README.md @@ -51,8 +51,7 @@ WealthLedger помогает частному инвестору понимат | Изменить или проверить систему | [Сопровождение](development/README.md), затем инструкции нужного репозитория | Практический tutorial первого инвестиционного сценария пока не подготовлен: -он требует подключения брокера, а запуск на новой базе имеет известное -ограничение. Маршрут первого знакомства выше — чтение, не учебный запуск. +он требует подключения брокера. Маршрут первого знакомства выше — чтение, не учебный запуск. UI-каталог содержит безопасные вымышленные примеры и поясняет границы их использования. ## Границы знаний diff --git a/development/audit-remediation.md b/development/audit-remediation.md index 30ef043..db48976 100644 --- a/development/audit-remediation.md +++ b/development/audit-remediation.md @@ -226,7 +226,7 @@ authority. | WL-P2-02 | Вернуть предсказуемый 409 при конкурентной регистрации. | backend, specs, docs | done | [`2026-08-23-harden-auth-and-cache-concurrency`](../../specs/openspec/changes/archive/2026-08-23-harden-auth-and-cache-concurrency/) | — | 2026-08-23; backend `c77b3cf`, specs `6e20cdf`, docs `8568e7b`; P2002 mapping and barrier regression test passed. | | WL-P2-03 | Сделать refresh rotation атомарной. | backend, specs, docs | done | [`2026-08-23-harden-auth-and-cache-concurrency`](../../specs/openspec/changes/archive/2026-08-23-harden-auth-and-cache-concurrency/) | — | 2026-08-23; backend `c77b3cf`, specs `6e20cdf`, docs `8568e7b`; CAS one-winner regression test passed. | | WL-P2-04 | Синхронизировать runtime, OpenAPI и auth success statuses. | backend, frontend | done | [`2026-08-24-align-api-contract-and-client-resilience`](../../specs/openspec/changes/archive/2026-08-24-align-api-contract-and-client-resilience/) | — | 2026-08-24; backend `9bd3400`, frontend `6d892da`, specs `800450d`, docs `b91280c`; metadata regression, frontend OpenAPI check и runtime/snapshot SHA совпали. | -| WL-P2-05 | Восстановить runnable backend e2e gate. | backend | deferred | — | Пересмотреть после следующей stable Prisma: три чистых `migrate deploy` на Node 22 должны пройти подряд. | 2026-08-23; Prisma 7.9.1 на Node 22 воспроизводимо возвращает пустой schema-engine error даже для fresh SQLite DB; published latest также 7.9.1. | +| WL-P2-05 | Восстановить runnable backend e2e gate. | backend | done | — | — | 2026-09-13; унаследованный RUST_LOG изолирован в Prisma config, 3 последовательных и 2 параллельных полных e2e passed. [Результаты](#2026-09-13--wl-p2-05-воспроизводимый-sqlite-e2e). | | WL-P2-06 | Добавить проходящий app/test TypeScript gate backend. | backend | done | [`2026-08-23-make-local-verification-agent-safe`](../../specs/openspec/changes/archive/2026-08-23-make-local-verification-agent-safe/) | — | 2026-08-23; backend `71d57d6`, specs `72444db`, docs `293df9c`; `npm run typecheck:app` и `npm run typecheck:test` — passed. [2026-09-13: включён strict по P1-10](#2026-09-13--wl-p2-06-strict-typescript). | | WL-P2-07 | Сохранять cached data во время background refetch. | frontend | done | [`2026-08-24-align-api-contract-and-client-resilience`](../../specs/openspec/changes/archive/2026-08-24-align-api-contract-and-client-resilience/) | — | 2026-08-24; frontend `6d892da`, specs `800450d`, docs `b91280c`; observable Accounts/Portfolio refetch tests и `npm run verify` — passed (17 files, 55 tests). | | WL-P2-08 | Нормализовать cold-start refresh failure. | frontend | done | [`2026-08-24-align-api-contract-and-client-resilience`](../../specs/openspec/changes/archive/2026-08-24-align-api-contract-and-client-resilience/) | — | 2026-08-24; frontend `6d892da`, specs `800450d`, docs `b91280c`; cold-start и protected-401 transport-failure tests passed. | @@ -253,6 +253,45 @@ authority. Terminal evidence добавляется сюда только после завершения соответствующего change. +### 2026-09-13 — WL-P2-05: воспроизводимый SQLite e2e + +Закрыты TODO 03 и 03.docs, повторно проверен SQLite scope 11. Backend +`8637ad2` с текущим diff, Node 22.21.0 / Prisma 7.9.1. Schema, migrations, +зависимости и HTTP-контракт не менялись. + +- До исправления fresh migration: `RUST_LOG=warn` и `error` — exit 1 с пустым + `Schema engine error`; переменная отсутствует или равна `info` — exit 0. + В исходном окружении было `RUST_LOG=warn`. Это воспроизведённая зависимость + запуска от окружения, а не доказательство внутреннего дефекта Rust engine. +- Prisma config исключает унаследованный `RUST_LOG` после dotenv. Общий runner + даёт каждому suite свою DB и один URL для migration/Jest, отклоняет прямой + Jest без изоляции и очищает каталог после ошибки или сигнала. +- `npm run verify` — PASS: zero-warning lint, app/test types, 35 suites / + 257 unit tests, Prisma generation и build. +- Docs `npm run verify` — PASS: Markdown, ссылки/якоря и `git diff --check`. +- `npm run test:e2e` — PASS: 8 suites / 98 tests, включая runtime OpenAPI. +- `node test/sqlite-regression.cjs` — PASS: три последовательных и два + параллельных полных e2e (каждый 98 tests, всего 40 разных DB); внешний + вымышленный файл неизменён. Недоступный schema engine возвращает exit 1; + SIGINT/SIGTERM — 130/143. Все 43 созданных DB-каталога удалены. +- `npm run test:durability -- /tmp/p111-baseline` — PASS: отдельная baseline + сборка `8ec172f48eefa2237dc0c16919fbb2e726b39a65`, additive migration, + сохранение User/Session/TbankConnection, банковской истории и защиты повторов, + restart, откат приложения и backup/restore. `RUST_LOG=info` удалён из runner; + для старого baseline унаследованная переменная также исключается. +- HTTP/durability проверены вне sandbox после воспроизведения запрета локальных + портов `EPERM`. Это ограничение среды, не failing migration. Пользовательская + DB и `.env` не использовались как цель записи. + +Логи этой проверки: `/tmp/wl-sqlite-verify.log`, `/tmp/wl-sqlite-e2e-1.log`, +`/tmp/wl-sqlite-regression.log`, `/tmp/wl-sqlite-durability.log`. +Подробные regression logs сохранены в системном temp-каталоге +`wealthledger-sqlite-regression-pSyuoe`, durability — +`wealthledger-bank-durability-V0u1NA`. Эти локальные временные логи могут быть +удалены системой; воспроизводимые команды и +[матрица рисков](../../backend/README.md#реальная-sqlite-и-сохранность-данных) +остаются в backend. Исторические evidence ниже сохранены без переписывания. + ### 2026-09-13 — P1-12: backend responsibilities Статус: `done`. Backend commit `8ba0053`. diff --git a/development/local-workspace.md b/development/local-workspace.md index 5189e57..1da32d8 100644 --- a/development/local-workspace.md +++ b/development/local-workspace.md @@ -25,13 +25,14 @@ T-Bank token вводится пользователем через интерф на отдельной копии. Потеря или замена ключа не является безвредным сбросом: прежнее подключение нельзя расшифровать новым ключом. -**Известное ограничение:** ранее была зафиксирована ошибка `Schema engine error` -на новой временной SQLite-базе до создания схемы. Условия проверки и пересмотра — -в [ограничении сквозной проверки](verification.md#известное-ограничение-сквозной-проверки). -На Node 22.21.0 / Prisma 7.9.1 подтверждено три последовательных применения -миграций к новым временным базам с `RUST_LOG=info` вне sandbox. Без этой -переменной ошибка воспроизводится. Пользовательская база для воспроизведения -не нужна; успешная миграция сама по себе не подтверждает полный первый запуск. +После подготовки зависимостей и конфигурации примените штатные migrations: +из backend после `nvm use --silent` выполните `npx prisma migrate deploy`. +Для существующей базы сначала сохраните согласованный backup. +На Node 22.21.0 / Prisma 7.9.1 обнаружена зависимость fresh migration от +унаследованного `RUST_LOG=warn/error`. Backend Prisma config исключает эту +переменную из процесса CLI; назначать `RUST_LOG=info` больше не требуется. +Условия и доказательство — в +[сквозной проверке](verification.md#известное-ограничение-сквозной-проверки). В development доступна [локальная Swagger UI](http://localhost:3000/api/docs) при стандартном порте API. Она показывает контракт, но не доказывает доступность @@ -96,7 +97,7 @@ backend при сохранении расширенной схемы. Стар | --- | --- | | Порт занят | Адрес действующего процесса или выбранный свободный порт должен совпадать с настройками клиента и разрешённым origin | | Ошибка CORS или сессия теряется после reload | Согласованность адресов, hostname и режима cookie проверяется на стороне browser и backend | -| Ошибка подготовки базы | Установленный blocker не устраняется удалением пользовательской базы или обходом миграций; сохраняются версия среды и текст ошибки | +| Ошибка подготовки базы | Сохранить версию среды и текст ошибки; использовать backend Prisma config, не удалять пользовательскую базу и не обходить migrations | | `TBANK_NOT_CONNECTED` | Подключение создаётся в настройках текущего пользователя | | `INVALID_TBANK_TOKEN` | После проверки token и прав у брокера подключение заменяется через настройки | | `TBANK_UNAVAILABLE`, TLS или rate limit | Проверяются сеть, лимиты и доверенный CA; проверка TLS сохраняется | diff --git a/development/runtime-openapi-verification.md b/development/runtime-openapi-verification.md index 8193ecd..b8d32ad 100644 --- a/development/runtime-openapi-verification.md +++ b/development/runtime-openapi-verification.md @@ -34,8 +34,10 @@ API не требует нового описания контракта. HTTP-потока. Согласованность описаний и функциональная корректность — разные доказательства. -## Ограничение e2e +## Граница e2e -Сравнение OpenAPI не запускает сквозные проверки с миграциями базы. -Известная ошибка движка миграций и условие пересмотра описаны в -[сквозной проверке](verification.md#известное-ограничение-сквозной-проверки). +`npm run test:openapi-contract` подготавливает отдельную временную SQLite-базу +через общий runner и выполняет только сравнение OpenAPI. Соседний frontend +checkout нужен для snapshot. Полные HTTP-сценарии запускает `test:e2e`; +миграция перед сравнением не подменяет проверку поведения приложения. +Подробности — в [сквозной проверке](verification.md#известное-ограничение-сквозной-проверки). diff --git a/development/verification.md b/development/verification.md index c6b13e8..dbc3c32 100644 --- a/development/verification.md +++ b/development/verification.md @@ -33,28 +33,27 @@ ### Известное ограничение сквозной проверки -В сохранённой проверке Prisma 7.9.1 под Node 22 применение миграций к новой -SQLite-базе завершалось `Schema engine error` до запуска сквозных тестов. -Это ограничение зафиксировано в [WL-P2-05](audit-remediation.md#p2). -Предыдущее описание локальной проверки от 12 сентября 2026 года также отмечало -ошибку на временной базе без обращения к пользовательской базе. +Прежний blocker WL-P2-05 снят в конфигурации Prisma: на Node 22.21.0 / +Prisma 7.9.1 унаследованный `RUST_LOG=warn` или `error` воспроизводит пустой +`Schema engine error`, а отсутствие переменной позволяет fresh migration. +Backend Prisma config удаляет переменную в процессе CLI после загрузки `.env`; +это не меняет application logging. Версии зависимостей и SQL history сохранены. -Успех unit-проверок и OpenAPI не закрывает эту границу. Условие проверки — -стабильная версия Prisma с тремя последовательными успешными применениями -миграций на новых базах под Node 22. +`npm run test:e2e` применяет migrations и запускает каждую HTTP suite на отдельной +временной DB. Один URL передаётся Prisma и Jest; прямой запуск Jest без runner +отклоняется до DB-запросов. При ошибке и SIGINT/SIGTERM выполняется cleanup. +`npm run test:sqlite` выбирает auth/cards; `test:durability` отдельно проверяет +migration, restart, возврат предыдущего приложения и backup/restore. +Команды и runnable regression — в +[backend README](../../backend/README.md#реальная-sqlite-и-сохранность-данных), +фактические результаты — в +[registry](audit-remediation.md#2026-09-13--wl-p2-05-воспроизводимый-sqlite-e2e). -При реализации ручных карт Prisma 7.9.1 на Node 22.21.0 трижды подряд применил -существующие migrations к новым временным базам командой -`RUST_LOG=info DATABASE_URL=file:<новая-временная-база> npx prisma migrate deploy` -вне sandbox. Без `RUST_LOG=info` пустой `Schema engine error` воспроизводился -и вне sandbox. Поэтому подтверждён именно этот способ запуска; исправление -обычного запуска или причина зависимости от журналирования не установлены. -Он использует штатную историю migrations без `db push`, reset или ручного SQL-обхода. -Результат исходной проверки сохранён в -[Tasks ручных карт](../../specs/openspec/changes/add-manual-bank-cards/tasks.md). -Применение новой миграции, DB-инварианты и HTTP-сценарии требуют своих проверок. -Условия безопасного локального запуска и сохранения данных — -в [локальном окружении](local-workspace.md). +Backend `verify` остаётся статическим/unit/build gate; полный HTTP/DB scope +проверяется отдельным `test:e2e`. Успех этих команд не подтверждает доступность +внешнего T-Bank. HTTP tests требуют локальных портов, которые sandbox может +запрещать. Безопасное сохранение реальных данных — в +[локальном окружении](local-workspace.md). ## Где выполнять проверки