docs(specs): archive api contract resilience remediation

2026-08-24 00:51:06 +03:00
parent 6e20cdffaf
commit 800450d075
8 changed files with 386 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-23
@@ -0,0 +1,120 @@
+## Контекст
+
+Мотивация изложена в `proposal.md`, а поведенческий contract — в delta specs.
+Backend документирует `200` через OpenAPI decorators, но Nest использует
+стандартный `201` для трёх auth `POST` handlers, поскольку их runtime status
+не задан явно. Runtime OpenAPI verifier сравнивает два документа, поэтому не
+может обнаружить это расхождение HTTP responses.
+
+Во frontend Accounts и Account view models выбирают блокирующий loading/error
+state до проверки cached query data. У auth provider два пути refresh:
+cold start напрямую вызывает API без `catch`, а общий refresh может отклонить
+Promise при повторе защищённого запроса.
+
+## Цели и исключения
+
+**Цели:**
+
+- Согласовать фактические auth success responses, OpenAPI, snapshot и
+  generated types на `200` с детерминированным regression gate без Prisma или
+  базы данных.
+- Отображать существующие данные Accounts и Portfolio во время refetch и после
+  его ошибки с доступным локализованным warning и retry action.
+- Дать cold start и повтору защищённого запроса единый non-throwing результат
+  refresh, сохранив текущие serialization и защиту routes.
+- Фиксировать active remediation и обновлять feature/development документацию
+  только фактически поставленным поведением.
+
+**Исключения:**
+
+- Исправлять Prisma migration/e2e infrastructure или создавать workspace-wide
+  verifier, отложенный как WL-P2-05 и WL-P2-13.
+- Менять refresh-cookie attributes, token lifetime, session rotation,
+  unauthorised-error codes, auth routes, cache TTL, refetch triggers или
+  backend Portfolio fallback policy.
+- Распространять Client Cached Snapshot на постраничные operations/events,
+  чьи cursor и filters могут определять иной result set.
+
+## Решения
+
+### Явно установить `200` для трёх auth handlers успешного ответа
+
+Handlers register, login и refresh получают явный HTTP `200`, сохраняя
+существующие `ApiOkResponse` и payload/cookie code. Frontend artifacts остаются
+сгенерированными из backend document: запускается штатный sync workflow, а
+artifact коммитится только если этот workflow создаёт изменение; ручное
+редактирование generated schema запрещено.
+
+Небольшой независимый от БД backend test проверяет status metadata каждого
+handler. Он защищает decorator, управляющий реальным Nest output, пока
+Prisma-backed e2e gate остаётся deferred. Существующие e2e assertions меняются
+с `201` на `200`, но не являются terminal evidence до восстановления Prisma
+bootstrap.
+
+Отклонённые альтернативы: неявный `201` потребовал бы большего перехода
+snapshot/types и противоречил бы согласованному единообразному contract;
+опора только на runtime OpenAPI comparison повторила бы исходную blind spot.
+
+### Определять представление refetch по наличию данных, а не `isFetching` или `isError`
+
+Accounts и Account view models сначала определяют наличие Client Cached
+Snapshot. Без данных они сохраняют текущие loading, error и empty views. При
+наличии данных они возвращают loaded/empty presentation с опциональной
+информацией об обновлении и его ошибке. Page components сначала отображают
+данные, добавляют неблокирующий progress indicator во время fetch и передают
+локализованное warning/retry action в loaded presentation после ошибки.
+
+Account view сохраняет backend warning `Portfolio.isStale` отдельно от client
+warning об ошибке refresh. Оба могут отображаться, когда независимо истинны.
+Новая терминология документируется в `CONTEXT.md`; это не новое API field и
+не интерпретация server freshness.
+
+Отклонённые альтернативы: полный error/loading view после refetch скрывает уже
+полезные финансовые данные; применение правила к operations/events могло бы
+показать прошлую cursor/filter page как запрошенный результат.
+
+### Сделать общий refresh возвращающим `false` при любом неуспешном исходе
+
+Auth provider централизует успешное применение session и локальную очистку
+session. Single-flight refresh function перехватывает transport rejection API,
+а также no-data/HTTP failures, очищает token, profile и React Query cache и
+возвращает `false`; она всегда освобождает in-flight Promise. Cold start
+использует эту общую function и устанавливает `ready` в `finally`.
+`authenticatedFetch` сохраняет existing one-retry behavior: при `false` он
+возвращает исходный `401` после очистки, позволяя protected-route state
+перенаправить на login.
+
+Отклонённые альтернативы: перехват только mount effect оставляет 401 retry
+path способным отклонить Promise; добавление третьего startup error state
+меняет согласованный anonymous/login recovery flow.
+
+## Риски и компромиссы
+
+- [Metadata test не является HTTP e2e test] → WL-P2-05 остаётся deferred,
+  существующие e2e expectations обновляются, а реальное HTTP coverage станет
+  обязательным после выполнения Prisma trigger.
+- [Ошибка refresh утрачивает in-memory session] → после cold start браузер не
+  имеет действительного access token; очистка state предотвращает неоднозначный
+  protected UI и следует существующему 401 recovery behavior.
+- [Client warning и backend stale warning могут сосуществовать] → каждому
+  назначается отдельное localized message и проверяется их независимый render.
+- [Generated sync может затронуть frontend artifacts] → он запускается явно
+  только после backend contract change, а итоговый diff проверяется до принятия.
+
+## План изменений
+
+1. Сначала добавить regression tests, затем сделать backend status явным и
+   обновить существующие e2e assertions, не заявляя, что deferred e2e gate
+   прошёл.
+2. Обновить OpenAPI artifacts через штатную sync command, проверить
+   согласованность runtime document и generated client и оставить только
+   намеренный итоговый diff.
+3. Добавить observable frontend tests для состояний refetch cached data и
+   ошибок refresh, затем отрефакторить view models, pages, localized copy и
+   auth provider до их прохождения.
+4. Обновить feature docs и remediation registry, выполнить применимые
+   non-mutating gates и OpenSpec verification до archive.
+
+Rollback затрагивает только код: отмена затронутых commits восстанавливает
+предыдущий status/UX; data migration, dependency change и очистка persisted
+state не нужны.
@@ -0,0 +1,51 @@
+## Обоснование
+
+Auth endpoints фактически отвечают `201`, хотя их runtime OpenAPI-документ,
+зафиксированный frontend snapshot и сгенерированный client обещают `200`.
+Одновременно frontend скрывает успешные данные во время фонового обновления и
+допускает необработанное отклонение Promise при транспортной ошибке начального
+или повторного refresh.
+
+Это следующий рекомендуемый remediation change для WL-P2-04, WL-P2-07 и
+WL-P2-08: предыдущие P1 и связанные query-identity инварианты уже закрыты, а
+Prisma e2e остаётся честно deferred отдельным finding.
+
+## Изменения
+
+- Зафиксировать единый HTTP `200` contract успешного ответа для register,
+  login и refresh; согласовать Nest runtime, OpenAPI snapshot,
+  сгенерированные frontend types и регрессионные проверки, не меняя logout
+  `204`, error semantics или cookie/session policy.
+- Ввести UX Client Cached Snapshot для списка Brokerage Accounts и Portfolio:
+  уже полученные данные остаются видимыми при фоновом обновлении и его ошибке,
+  а ошибка отображается неблокирующе с повторной попыткой.
+- Нормализовать транспортную ошибку общего frontend refresh flow в
+  контролируемое неавторизованное состояние без необработанного отклонения
+  Promise; очистка in-memory session и query cache сохраняет существующий
+  protected-route flow.
+- Обновить устойчивую документацию и audit remediation registry по мере
+  реализации; не представлять metadata regression test как восстановленный
+  Prisma HTTP e2e gate.
+
+## Возможности
+
+### Новые возможности
+
+- `frontend-data-resilience`: поведение Client Cached Snapshot и
+  неблокирующих refresh states для Accounts и Portfolio.
+
+### Изменённые возможности
+
+- `user-authentication`: единый auth success status и контролируемое
+  frontend-поведение при транспортной ошибке refresh.
+
+## Затрагиваемые области
+
+- Backend: auth controller и независимый от БД status regression test; текущий
+  Prisma e2e gate не меняется.
+- Frontend: auth model, Accounts/Account view models и их observable UI tests;
+  сгенерированные OpenAPI artifacts обновляются только штатным sync workflow при
+  необходимости.
+- Specs/docs: delta specs, `CONTEXT.md`, feature/development documentation и
+  remediation registry. Новых runtime dependencies, T-Bank credentials,
+  persisted migrations и публичных routes не требуется.
@@ -0,0 +1,34 @@
+## Purpose
+
+Определяет, когда frontend сохраняет последний успешный ответ на экране и как
+сообщает пользователю о неудачном фоновом обновлении без искажения доменных
+состояний Portfolio.
+
+## ADDED Requirements
+
+### Requirement: Client Cached Snapshot остаётся доступным при обновлении Accounts и Portfolio
+Frontend MUST сохранять Client Cached Snapshot списка Brokerage Accounts или
+Portfolio на экране, если для этого же набора данных уже был успешно получен
+ответ. Начальная загрузка без такого ответа может показывать блокирующее
+состояние загрузки. Client Cached Snapshot MUST оставаться видимым во время
+фонового обновления и после его ошибки; он не является server-side fallback и MUST NOT
+изменять или интерпретировать поле `Portfolio.isStale`.
+
+#### Scenario: Список Brokerage Accounts обновляется в фоне
+- **WHEN** экран Accounts уже показывает Client Cached Snapshot и начинается
+  фоновое обновление того же списка
+- **THEN** frontend оставляет список видимым и показывает только
+  неблокирующий индикатор обновления
+
+#### Scenario: Обновление Portfolio завершается ошибкой после успешного ответа
+- **WHEN** экран Brokerage Account уже показывает Client Cached Snapshot
+  Portfolio, а последующее обновление этого же Portfolio завершается ошибкой
+- **THEN** frontend сохраняет Portfolio видимым, показывает локализованное
+  неблокирующее предупреждение о показе последних полученных данных и
+  предоставляет повторную попытку обновления
+
+#### Scenario: Server-side fallback и client cached snapshot различаются
+- **WHEN** backend возвращает Portfolio с `isStale` либо фоновое обновление
+  Client Cached Snapshot завершается ошибкой
+- **THEN** frontend отображает соответствующее server-side либо client-side
+  предупреждение независимо, не представляя один вид состояния другим
@@ -0,0 +1,38 @@
+## ADDED Requirements
+
+### Requirement: Единый HTTP contract успешных auth endpoints
+Успешные `POST /api/v1/auth/register`, `POST /api/v1/auth/login` и
+`POST /api/v1/auth/refresh` MUST отвечать HTTP `200`; опубликованный
+OpenAPI-документ, зафиксированный frontend snapshot и сгенерированные
+transport types MUST описывать этот же status. Каждая операция сохраняет свои
+существующие payload, refresh-cookie и session semantics. Logout MUST
+продолжать отвечать `204`.
+
+#### Scenario: Успешная регистрация возвращает контрактный status
+- **WHEN** пользователь отправляет новую валидную регистрацию
+- **THEN** система устанавливает refresh-cookie, возвращает профиль и access
+  token с HTTP `200`
+
+#### Scenario: Успешный login или refresh возвращает контрактный status
+- **WHEN** пользователь успешно входит либо восстанавливает Session
+- **THEN** система устанавливает или заменяет refresh-cookie, возвращает
+  профиль и access token с HTTP `200`
+
+### Requirement: Клиент контролируемо завершает неуспешный refresh
+Frontend MUST обрабатывать HTTP и транспортную ошибку общего refresh flow без
+необработанного отклонения Promise. При неуспешном cold-start refresh frontend
+MUST завершить инициализацию как неавторизованный, не сохраняя access token
+или профиль. При неуспешном refresh после защищённого запроса frontend MUST
+очистить in-memory session и query cache перед existing navigation to login.
+
+#### Scenario: Cold-start refresh завершается транспортной ошибкой
+- **WHEN** приложение запускается без access token и refresh запрос не может
+  получить транспортный response
+- **THEN** frontend завершается в готовом неавторизованном состоянии без
+  необработанного отклонения Promise и показывает обычный public/login flow
+
+#### Scenario: Повторный refresh после protected 401 завершается транспортной ошибкой
+- **WHEN** защищённый API отвечает `401`, а единственный serialised refresh
+  завершается транспортной ошибкой
+- **THEN** frontend очищает in-memory session и query cache и направляет User
+  в существующий login flow без необработанного отклонения Promise
@@ -0,0 +1,68 @@
+## 1. Auth success-status contract
+
+- [x] 1.1 Добавить независимый от БД backend regression test, который читает
+  Nest response-status metadata для `register`, `login` и `refresh` и
+  проверяет `200`; cookie/payload behavior не входит в его scope.
+- [x] 1.2 Добавить явный runtime status `200` в три auth POST handlers, не
+  меняя logout `204`, error responses и session/cookie logic; добиться
+  прохождения нового metadata regression test.
+- [x] 1.3 Обновить существующие auth e2e success expectations с `201` на
+  `200`, включая явный successful login assertion; задокументировать, что
+  suite остаётся deferred по WL-P2-05, а не считается passing gate.
+- [x] 1.4 Запустить штатный frontend OpenAPI sync workflow после backend
+  change; принять только artifacts, сгенерированные этим workflow, затем
+  выполнить generated-artifact и runtime-contract checks.
+
+## 2. Представление Client Cached Snapshot
+
+- [x] 2.1 Добавить observable Accounts page regression coverage для
+  существующего списка во время in-flight refetch и после его ошибки: список
+  остаётся видимым, loading indicator неблокирующий, а retry локализованного
+  warning вновь вызывает тот же query.
+- [x] 2.2 Расширить Account page coverage для эквивалентных Portfolio refetch
+  states, включая независимый render server `isStale` и client warnings об
+  ошибке refresh.
+- [x] 2.3 Отрефакторить Accounts и Account view models, чтобы blocking
+  loading/error states выбирались только при отсутствии query data; раскрыть
+  progress, failure и retry refresh рядом с данными Client Cached Snapshot без
+  изменения query TTL, retry или refetch policies.
+- [x] 2.4 Обновить Accounts и Account page presentations и localized copy для
+  отображения неблокирующего progress и доступных client refresh warnings с
+  retry, сохранив operations/events pagination вне scope.
+
+## 3. Контролируемая ошибка refresh
+
+- [x] 3.1 Добавить AuthProvider regression coverage для отклонённого
+  cold-start refresh: он устанавливает `ready`, оставляет user/access token
+  пустыми, очищает query cache и не создаёт необработанного отклонения Promise.
+- [x] 3.2 Добавить coverage для protected `401`, чей serialised refresh имеет
+  транспортную ошибку: refresh возвращает контролируемую ошибку, локальный
+  auth/cache очищен, а исходный unauthorized response сохранён для
+  существующего route handling.
+- [x] 3.3 Централизовать применение и очистку local auth state, направить
+  cold start и refresh защищённого запроса через общий non-throwing refresh
+  path и сохранить one-refresh-at-a-time behavior.
+
+## 4. Устойчивая документация и состояние remediation
+
+- [x] 4.1 Обновить feature documentation authentication, brokerage accounts и
+  portfolio с фактически поставленными `200` auth responses и различием между
+  server-side Portfolio fallback и Client Cached Snapshot refresh UX; limits и
+  deferred Prisma evidence должны остаться точными.
+- [x] 4.2 Поддерживать `docs/development/audit-remediation.md` согласованным с
+  active status change и verification evidence; только после успешного archive
+  записать terminal archive path, commits и checks, затем отметить WL-P2-04,
+  WL-P2-07 и WL-P2-08 `done` вне этого task list.
+
+## 5. Верификация перед archive
+
+- [x] 5.1 Выполнить затронутые frontend и backend non-mutating lint, typecheck
+  и unit-test gates под Node 22; выполнить frontend `verify`, когда его
+  generated artifacts окончательны, и записать точные observed results.
+- [x] 5.2 Выполнить `bash specs/scripts/verify-runtime-openapi.sh`, OpenSpec
+  authority verifier, strict change/spec validation и `git diff --check` в
+  каждом затронутом Git repository; устранить каждый blocking result.
+- [x] 5.3 Провести независимый read-only review implementation, delta specs,
+  generated-contract diff, error-state tests и документации; выполнить
+  применимую `opsx-verify` procedure и устранить все blocking findings до
+  archive.
@@ -0,0 +1,36 @@
+# frontend-data-resilience Specification
+
+## Purpose
+
+Определяет, когда frontend сохраняет последний успешный ответ на экране и как
+сообщает пользователю о неудачном фоновом обновлении без искажения доменных
+состояний Portfolio.
+
+## Requirements
+
+### Requirement: Client Cached Snapshot остаётся доступным при обновлении Accounts и Portfolio
+Frontend MUST сохранять Client Cached Snapshot списка Brokerage Accounts или
+Portfolio на экране, если для этого же набора данных уже был успешно получен
+ответ. Начальная загрузка без такого ответа может показывать блокирующее
+состояние загрузки. Client Cached Snapshot MUST оставаться видимым во время
+фонового обновления и после его ошибки; он не является server-side fallback и MUST NOT
+изменять или интерпретировать поле `Portfolio.isStale`.
+
+#### Scenario: Список Brokerage Accounts обновляется в фоне
+- **WHEN** экран Accounts уже показывает Client Cached Snapshot и начинается
+  фоновое обновление того же списка
+- **THEN** frontend оставляет список видимым и показывает только
+  неблокирующий индикатор обновления
+
+#### Scenario: Обновление Portfolio завершается ошибкой после успешного ответа
+- **WHEN** экран Brokerage Account уже показывает Client Cached Snapshot
+  Portfolio, а последующее обновление этого же Portfolio завершается ошибкой
+- **THEN** frontend сохраняет Portfolio видимым, показывает локализованное
+  неблокирующее предупреждение о показе последних полученных данных и
+  предоставляет повторную попытку обновления
+
+#### Scenario: Server-side fallback и client cached snapshot различаются
+- **WHEN** backend возвращает Portfolio с `isStale` либо фоновое обновление
+  Client Cached Snapshot завершается ошибкой
+- **THEN** frontend отображает соответствующее server-side либо client-side
+  предупреждение независимо, не представляя один вид состояния другим
@@ -123,3 +123,40 @@
 #### Scenario: Выход из настроек
 - **WHEN** пользователь нажимает logout на `/settings`
 - **THEN** клиент очищает локальную сессию и cache и направляет пользователя на `/login` независимо от результата сетевого запроса
+
+### Requirement: Единый HTTP contract успешных auth endpoints
+Успешные `POST /api/v1/auth/register`, `POST /api/v1/auth/login` и
+`POST /api/v1/auth/refresh` MUST отвечать HTTP `200`; опубликованный
+OpenAPI-документ, зафиксированный frontend snapshot и сгенерированные
+transport types MUST описывать этот же status. Каждая операция сохраняет свои
+существующие payload, refresh-cookie и session semantics. Logout MUST
+продолжать отвечать `204`.
+
+#### Scenario: Успешная регистрация возвращает контрактный status
+- **WHEN** пользователь отправляет новую валидную регистрацию
+- **THEN** система устанавливает refresh-cookie, возвращает профиль и access
+  token с HTTP `200`
+
+#### Scenario: Успешный login или refresh возвращает контрактный status
+- **WHEN** пользователь успешно входит либо восстанавливает Session
+- **THEN** система устанавливает или заменяет refresh-cookie, возвращает
+  профиль и access token с HTTP `200`
+
+### Requirement: Клиент контролируемо завершает неуспешный refresh
+Frontend MUST обрабатывать HTTP и транспортную ошибку общего refresh flow без
+необработанного отклонения Promise. При неуспешном cold-start refresh frontend
+MUST завершить инициализацию как неавторизованный, не сохраняя access token
+или профиль. При неуспешном refresh после защищённого запроса frontend MUST
+очистить in-memory session и query cache перед existing navigation to login.
+
+#### Scenario: Cold-start refresh завершается транспортной ошибкой
+- **WHEN** приложение запускается без access token и refresh запрос не может
+  получить транспортный response
+- **THEN** frontend завершается в готовом неавторизованном состоянии без
+  необработанного отклонения Promise и показывает обычный public/login flow
+
+#### Scenario: Повторный refresh после protected 401 завершается транспортной ошибкой
+- **WHEN** защищённый API отвечает `401`, а единственный serialised refresh
+  завершается транспортной ошибкой
+- **THEN** frontend очищает in-memory session и query cache и направляет User
+  в существующий login flow без необработанного отклонения Promise