docs(specs): archive auth and cache remediation

2026-08-23 22:42:40 +03:00
parent 72444dbbb1
commit 6e20cdffaf
8 changed files with 257 additions and 1 deletions
@@ -0,0 +1,16 @@
+## ADDED Requirements
+
+### Requirement: Кэш страниц журнала ограничивает локальные ресурсы
+Система SHALL кэшировать не более 100 недавно использованных страниц Account Ledger в каждом backend process не более чем на 30 секунд. Cache key MUST включать User, Brokerage Account, нормализованные период и categories, opaque cursor и limit; порядок или дублирование categories MUST NOT создавать отдельную cache identity, а отсутствующий конец периода MUST использовать текущий 30-секундный bucket. Просроченная страница MUST NOT возвращаться, а при переполнении cache MUST удалять наименее недавно использованную страницу.
+
+#### Scenario: Равнозначные фильтры используют одну cache identity
+- **WHEN** User в одном 30-секундном bucket повторяет запрос страницы журнала с теми же периодом, cursor и limit, но с categories в другом порядке или с дубликатами
+- **THEN** система использует ту же cache identity и не запрашивает upstream повторно для свежей страницы
+
+#### Scenario: Большое число уникальных запросов не увеличивает cache без границы
+- **WHEN** backend обслуживает больше 100 уникальных запросов страниц журнала
+- **THEN** cache содержит не более 100 страниц и освобождает наименее недавно использованные страницы
+
+#### Scenario: Просроченная страница не возвращается
+- **WHEN** cached страница журнала старше 30 секунд
+- **THEN** система не возвращает её как свежий результат и получает актуальную страницу из upstream
@@ -0,0 +1,43 @@
+## MODIFIED Requirements
+
+### Requirement: Регистрация пользователя
+Система SHALL позволять зарегистрировать User по уникальному нормализованному email и паролю. Email MUST нормализоваться удалением внешних пробелов и приведением к нижнему регистру; он MUST содержать не более 254 символов, ровно один `@`, непустые local и domain части и не содержать пробельных или управляющих символов. Пароль MUST передаваться без изменения, содержать от 12 до 72 UTF-8 байтов и не иметь требований к составу символов. Успешная регистрация MUST создать первую Session и вернуть профиль `{ id, email }` и access token.
+
+#### Scenario: Успешная регистрация
+- **WHEN** пользователь отправляет новый email и валидный пароль
+- **THEN** система создаёт User и Session, устанавливает refresh-cookie и возвращает access token с нормализованным профилем
+
+#### Scenario: Нормализация email при регистрации
+- **WHEN** пользователь регистрирует ` Anna@Example.com `
+- **THEN** система сохраняет и возвращает email `anna@example.com`
+
+#### Scenario: Повторная регистрация
+- **WHEN** пользователь регистрирует email, уже принадлежащий User после нормализации
+- **THEN** система отвечает `409` Problem Details с code `EMAIL_ALREADY_REGISTERED`
+
+#### Scenario: Конкурентная регистрация
+- **WHEN** два запроса одновременно регистрируют один нормализованный email
+- **THEN** ровно один запрос создаёт User и Session, а второй отвечает `409` Problem Details с code `EMAIL_ALREADY_REGISTERED`
+
+#### Scenario: Невалидные регистрационные данные
+- **WHEN** пользователь отправляет email или пароль, не соответствующие правилам регистрации
+- **THEN** система отвечает `400` Problem Details с code `VALIDATION_ERROR` и указателями на невалидные поля
+
+### Requirement: Access и refresh сессии
+Система SHALL выдавать access token сроком 15 минут и refresh token сроком 7 дней. Access token MUST передаваться клиенту только в ответе API и использоваться как Bearer token. Refresh token MUST передаваться только в `httpOnly`, `SameSite=Lax`, host-only cookie `refresh_token` с path `/api/v1/auth`; в HTTPS-среде cookie MUST иметь атрибут `Secure`. Каждый новый refresh token MUST иметь уникальный JWT ID и ротироваться при успешном обновлении Session; Session MUST оставаться активной 7 дней после последнего успешного обновления. Одновременные Session одного User MUST быть независимы и не иметь числового лимита.
+
+#### Scenario: Успешное восстановление сессии
+- **WHEN** клиент отправляет действительный refresh-cookie
+- **THEN** система заменяет refresh-cookie и возвращает новый access token и профиль Session
+
+#### Scenario: Конкурентное восстановление сессии
+- **WHEN** два запроса одновременно отправляют один действительный refresh-cookie одной Session
+- **THEN** ровно один запрос заменяет refresh-cookie и возвращает новый access token и профиль, второй отвечает `401` Problem Details с code `UNAUTHORIZED`, а Session победителя остаётся активной
+
+#### Scenario: Истёкшая сессия
+- **WHEN** клиент отправляет refresh-cookie Session, не обновлявшейся более 7 дней
+- **THEN** система удаляет refresh-cookie и отвечает `401` Problem Details с code `UNAUTHORIZED`
+
+#### Scenario: Повторное использование refresh token
+- **WHEN** клиент отправляет refresh token, заменённый предыдущим успешным refresh
+- **THEN** система удаляет refresh-cookie и отвечает `401` Problem Details с code `UNAUTHORIZED`, не отзывая связанную Session только из-за этого запроса