@bonesofspring/ai-rules 0.1.32 → 0.1.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "Presets of Cursor and Claude rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",

package/presets/cursor/next/rules/README.md

@@ -10,3 +10,23 @@
 - Cursor интерпретирует его как конфигурацию поведения ассистента для этого репо (автоматически подмешивает содержимое в контекст, когда правило подходит).
 
 - То есть .mdc = “markdown + config для Cursor”, .md = просто текст без управляющего смысла для ассистента.
+
+### Каталог ключевых правил
+
+| Файл | Назначение |
+|------|------------|
+| `next-app-core.mdc` | Стек, слои, порты‑адаптеры (кратко), доменная логика vs state, общие требования к агенту и линтам |
+| `architecture-boundaries.mdc` | Границы UI / store / API, импорты (`@/types` по `types-public-imports`), UI→services, порты‑адаптеры, фича как срез |
+| `http-client.mdc` | Один HTTP‑стек, контракты из `@/types`, без разбросанного низкоуровневого API |
+| `api-services.mdc` | Сервисы, мапперы, вызовы через прикладные API‑клиенты |
+| `store-rtk.mdc` | Redux Toolkit, thunk’и, типизация ошибок/ответов как в коде репо |
+| `types-public-imports.mdc` | Импорты только через barrel `@/types` |
+| `types-jsdoc.mdc` | JSDoc для типов в `app/src/types` (русский текст, `[computed]`, без `@param`/`@returns`) |
+| `no-type-assertion-as-import-export.mdc` | Ограничение `as`, в т.ч. `instanceof` для ошибок транспорта в `catch` |
+| `code-review-mr.mdc` | Чеклист ревью MR, в т.ч. HTTP‑клиент и тесты |
+| `tests-unit.mdc` | Unit‑тесты и behavior‑тесты HTTP‑клиента |
+| `playwright-agents.mdc`, `tests-e2e-structure.mdc` | E2E |
+
+**Коллизии формулировок:** если в разных `.mdc` расходятся детали **импорта типов**, источник правды — **`types-public-imports.mdc`** (`@/types`, `@/types/enums`).
+
+Задачи на **сеть, замену HTTP‑библиотеки, новые эндпоинты**: опираться на **`http-client.mdc`** + **`api-services.mdc`** + **`store-rtk.mdc`**.

package/presets/cursor/next/rules/api-services.mdc

@@ -1,40 +1,41 @@
 ---
 description: Конвенции API сервисов и мапперов
-globs: src/api/services/**/*.ts
+globs: app/src/api/services/**/*.ts
 alwaysApply: false
 ---
 
 # Роль API слоя
 
 - Инкапсулировать всё, что связано с:
-  - HTTP‑запросами (через принятый в проекте клиент),
+  - HTTP‑запросами через **экземпляры прикладных API‑клиентов** в `app/src/api/clients/**`, собранные на **общей реализации** из `app/src/lib/clients/**` (как в существующем коде); подробности — **`http-client.mdc`**; положение слоя в схеме **порты и адаптеры** — `architecture-boundaries.mdc`;
   - URL/путями,
   - заголовками и кодами ответов,
   - DTO backend.
 - Предоставлять UI и store **стабильный доменный интерфейс**:
-  - функции, работающие с доменными типами из `@/types/**`.
+  - функции, работающие с доменными типами из `@/types` (`types-public-imports.mdc`).
   - мапперы между DTO и доменными типами.
 
 # Структура модулей
 
 - Для каждой доменной области (например, заказы, биллинг, настройки аккаунта):
-  - отдельный каталог в `src/api/services/<ИмяСервиса или фичи>/**` по конвенции репозитория.
+  - отдельный каталог в `app/src/api/services/<ИмяСервиса или фичи>/**` по конвенции репозитория.
 - Внутри модуля:
   - файлы с вызовами API (`index.ts` или `*.service.ts`);
   - файлы мапперов (`*responseMappers.ts`);
-  - специфичные типы запросов/ответов (если не вынесены в `@/types/**`).
+  - специфичные типы запросов/ответов (если не вынесены в `app/src/types/**` с экспортом через barrel `@/types`).
   - один или несколько **public API** файлов (`index.ts` или barrel‑файлы), через которые к модулю обращаются UI, store и другие слои.
 
 # Мапперы и типы
 
 - Для каждого запроса/эндпоинта:
   - описывать **response‑тип (DTO)**, точно соответствующий контракту backend;
-  - определять **целевой доменный тип** в `src/types/**`, с которым будет работать приложение (включая вычисляемые/агрегированные поля).
+  - определять **целевой доменный тип** в `app/src/types/**`, с которым будет работать приложение (включая вычисляемые/агрегированные поля).
 - Мапперы (например, `*responseMappers.ts`):
   - чистые функции, без сайд‑эффектов;
   - выполняют все необходимые вычисления и преобразования данных (булевы флаги, склейка строк, агрегаты и т.п.) при переводе из DTO в доменные модели;
   - при необходимости обеспечивают обратное преобразование (доменные модели -> транспортные типы).
-- UI и store работают только с доменными типами (из `@/types/**` или экспортируемыми из API слоя), а не с "сырыми" DTO.
+- UI и store работают только с доменными типами (из `@/types` или экспортируемыми из public API слоя API), а не с "сырыми" DTO.
+- **Не вызывать `fetch` напрямую** в теле API‑методов: только через клиент; исключения — узкие модули (например JSON‑RPC), если так уже устроено в репозитории.
 
 # Обработка ошибок
 
@@ -51,6 +52,6 @@ alwaysApply: false
 - Следовать существующим сервисам и мапперам как эталону.
 - Не смешивать слой API и UI/store:
   - компоненты не должны зависеть от DTO;
-  - store не должен знать о HTTP‑деталях (URL, коды).
+  - store не должен сам собирать URL/коды эндпоинтов и не обходить сервисы; **транспортный тип ответа** и **контракт ошибки** из `@/types` (как у прикладного клиента) допустимы во thunk при разборе `catch`/payload, если так выстроен сервис (см. `store-rtk.mdc`, `http-client.mdc`).
 - При использовании API‑сервисов в UI, store и утилитах импортировать только из public API файлов модуля (например, `@/api/services/OrdersApi/.../index`), а не из внутренних файлов‑реализаций.
 

package/presets/cursor/next/rules/architecture-boundaries.mdc

@@ -5,22 +5,40 @@ alwaysApply: true
 
 # Границы между слоями
 
-- **UI (src/ui/**)**:
-  - Может импортировать: `@/ui/**`, `@/store/**`, `@/types/**`, `@/api/services/**` (через публичные интерфейсы).
+- **UI (app/src/ui/**)**:
+  - Может импортировать: `@/ui/**`, `@/store/**`, типы из `@/types` и enum из `@/types/enums` (**только как в `types-public-imports.mdc`**), `@/api/services/**` только через **public API** модулей сервисов.
   - Не должен:
     - обращаться к HTTP‑клиенту напрямую;
     - знать детали DTO backend — только доменные типы.
-- **Store (src/store/**)**:
-  - Может импортировать: `@/store/**`, `@/api/services/**`, `@/types/**`.
+- **Store (app/src/store/**)**:
+  - Может импортировать: `@/store/**`, `@/api/services/**` (public API), типы из `@/types` и enum из `@/types/enums` (**`types-public-imports.mdc`**).
   - Не должен:
     - зависеть от конкретных UI‑компонентов;
     - напрямую работать с global/window API.
-- **API (src/api/services/**)**:
-  - Может импортировать: `@/types/**`, общие утилиты.
+  - Вызовы к backend — только через сервисы; **транспортные** типы ответа и ошибки (из `@/types`, в том же виде, что у прикладного HTTP‑клиента) во thunk допустимы, если так выстроен API‑слой (`http-client.mdc`, `store-rtk.mdc`).
+- **API (app/src/api/services/**)**:
+  - Может импортировать: типы из `@/types` и enum из `@/types/enums` (**`types-public-imports.mdc`**); **`@/api/clients/**`** — преднастроенные экземпляры HTTP‑клиента (`http-client.mdc`); общие утилиты проекта (как в соседних сервисах репозитория).
   - Не должен:
     - тянуть в себя UI или store;
     - смешивать HTTP‑слой и доменный слой — использовать мапперы.
 
+## UI и обращение к `@/api/services`
+
+- По умолчанию сценарии с **изменением серверного состояния** и координация нескольких шагов — через **store** (`createAsyncThunk`, dispatch, паттерн фичи в репозитории).
+- Прямой вызов функций из **`@/api/services/**` из UI допустим только в **узких случаях**: преимущественно **чтение** или действие **без необходимости держать результат в Redux**; тот же **public API** сервиса и те же **доменные типы**, что использовал бы thunk; **не** дублировать уже существующий сценарий из store и **не** протаскивать DTO в компоненты.
+- Предпочтительно оформлять такие вызовы так же, как в **соседних фичах** репозитория (хук‑фасад, отдельный хук и т.д.).
+
+## Порты и адаптеры (краткая карта)
+
+- **Входящий адаптер**: UI — ввод пользователя, отображение; зависит от store и доменных типов, не от транспорта.
+- **Оркестрация сценариев**: store (slices, thunk) — вызывает сервисы, кладёт в state **доменные** модели после маппинга.
+- **Исходящий порт (контракт к backend)**: публичный API **`@/api/services/...`**.
+- **Исходящий адаптер**: общая реализация HTTP в **`app/src/lib/clients/**`** и экземпляры в **`app/src/api/clients/**`**.
+
+## Фича как срез
+
+- Для сложной фичи выравниваются имена и термины (**единый язык** предметной области) в типах, селекторах, сервисах и UI; структура папок — как в соседних фичах репозитория.
+
 # Правила импортов
 
 - Всегда использовать алиас `@/...` для импортов между слоями.
@@ -32,11 +50,11 @@ alwaysApply: true
 # Организация фич
 
 - Для сложных фич (например, `OrderCheckout`):
-  - Страница: `src/ui/pages/OrderCheckoutPage/**`.
+  - Страница: `app/src/ui/pages/OrderCheckoutPage/**`.
   - Локальные компоненты: поддиректории `components/**` внутри страницы.
-  - Связанный store: `src/store/slices/OrderCheckout/**`.
-  - API: `src/api/services/OrdersApi/OrderCheckout/**` (имя корневого сервиса взять из принятой в проекте схемы).
-  - Типы: `src/types/OrderCheckout.types.ts` или аналогичный файл.
+  - Связанный store: `app/src/store/slices/OrderCheckout/**`.
+  - API: `app/src/api/services/OrdersApi/OrderCheckout/**` (имя корневого сервиса взять из принятой в проекте схемы).
+  - Типы: `app/src/types/**` с экспортом через barrel **`app/src/types/index.ts`** (`types-public-imports.mdc`).
 
 # Требование к агенту
 

package/presets/cursor/next/rules/code-review-mr.mdc

@@ -11,16 +11,16 @@ alwaysApply: true
 
 - **Что обязан проверить агент**
   - **Архитектура и слои**:
-    - Соблюдение правил из `architecture-boundaries.mdc` и `next-app-core.mdc`:
-      - UI (`src/ui/**`) не ходит напрямую в HTTP‑клиент и не знает DTO.
-      - Store (`src/store/**`) не зависит от UI и не работает с "сырыми" HTTP.
-      - API (`src/api/services/**`) не тянет UI/store, использует мапперы.
+    - Соблюдение правил из `architecture-boundaries.mdc`, `next-app-core.mdc` и при сетевых изменениях — `http-client.mdc`:
+      - UI (`app/src/ui/**`) не ходит напрямую в HTTP‑клиент и не знает DTO.
+      - Store (`app/src/store/**`) не зависит от UI; границы транспортных типов и ошибок — `store-rtk.mdc` / `http-client.mdc`.
+      - API (`app/src/api/services/**`) не тянет UI/store, использует мапперы; без прямого `fetch` в сервисах (кроме оговорённых исключений).
   - **Импорты и организация кода**:
     - Использование алиаса `@/...` вместо относительных импортов выше по дереву.
     - Отсутствие deep‑импортов во внешние фичи; использование только public API.
     - Размещение новых файлов в корректных слоях и директориях фич.
   - **Типы и TS‑строгость**:
-    - Не допускать новых `any`; предпочитать доменные типы из `src/types/**`.
+    - Не допускать новых `any`; предпочитать доменные типы из `@/types` (barrel, см. `types-public-imports.mdc`).
     - Проверять корректность пропсов/возвращаемых типов, особенно в UI и API‑слое.
   - **UI и стили**:
     - Для компонентов и стилей сверяться с `react-ui.mdc` и `next-app-core.mdc`:
@@ -30,7 +30,15 @@ alwaysApply: true
     - Проверять, что для нетривиальных изменений:
       - либо обновлены/добавлены unit‑тесты (`tests-unit.mdc`),
       - либо e2e‑сценарии/спеки отражают новую логику (`playwright-agents.mdc`, `tests-e2e-structure.mdc`).
+    - При правках **общего HTTP‑клиента** — наличие/актуальность **behavior‑тестов клиента** (`http-client.mdc`, `tests-unit.mdc`).
     - Указывать, какие именно тесты стоит добавить или поправить.
+  - **Линтеры (обязательно)**:
+    - Рабочий каталог: `app/` (там `package.json` с скриптами линта).
+    - Перед финализацией отчёта по ревью **запустить полный прогон** ESLint по проекту: `yarn lint:js` (эквивалент `eslint .` с расширениями из скрипта — без точечного запуска только на один файл, чтобы не пропустить косвенные срабатывания).
+    - Если в MR менялись стили (css/linaria и т.п.) — дополнительно `yarn lint:css`.
+    - В отчёт включить **все сообщения ESLint (errors и warnings)** по файлам, попадающим в дифф MR/ветки; если полный вывод огромный, сфокусироваться на диффе, но **не** пропускать проверку из‑за «только изменённые файлы» на этапе запуска — сначала полный `yarn lint:js`, затем фильтрация вывода к путям из `git diff`.
+    - При **имплементации правок** по итогам ревью или любой работе «как к MR»: после изменений снова выполнить `yarn lint:js` (и при необходимости `yarn lint:css`); не считать задачу завершённой, пока в изменённых файлах остаются исправимые предупреждения ESLint, которые относятся к этой задаче (исключение — явно устаревший легаси вне скоупа, с пометкой в ответе).
+    - При желании полной валидации, как в CI: `yarn lint` (ESLint + Stylelint + `type-check`) — уместно перед итогом крупного MR.
 
 - **Глубина и формат ревью**
   - Фокус на **изменениях MR** (дифф относительно целевой ветки), а не на всём проекте.

package/presets/cursor/next/rules/feature-delivery-flow.mdc

@@ -0,0 +1,74 @@
+---
+description: Сквозной flow фичи (типы, API, моки, store, UI, тесты) и точки регистрации в репозитории
+alwaysApply: true
+---
+
+# Поставка фичи: порядок слоёв и регистрация
+
+Плейсхолдеры: `<FeatureName>`, `<ServiceRoot>`, `<Area>` — нейтральные имена; реальные имена брать из соседних фич того же типа.
+
+## Инварианты перед кодом
+
+- Найти в том же слое фичу сопоставимой сложности и **повторить структуру каталогов и паттерн именования**.
+- Не добавлять `any`; при необходимости — `unknown` и сужение типа.
+- После правок выполнить проверки из **`package.json` каталога `app/`** (типизация, ESLint и связанные скрипты), не оставлять новых ошибок без причины.
+
+## Полный flow (слой за слоем)
+
+```mermaid
+flowchart LR
+  typesNode["types_domain"]
+  apiNode["api_services_mappers"]
+  mocksNode["mocks_msw"]
+  storeNode["store_slice_thunks"]
+  mwNode["middleware_optional"]
+  uiNode["ui_pages_components"]
+  unitNode["unit_tests"]
+  e2eNode["e2e_plans_specs"]
+
+  typesNode --> apiNode
+  apiNode --> mocksNode
+  apiNode --> storeNode
+  storeNode --> mwNode
+  storeNode --> uiNode
+  apiNode --> unitNode
+  storeNode --> unitNode
+  uiNode --> unitNode
+  uiNode --> e2eNode
+  mocksNode --> e2eNode
+```
+
+## Чеклист по слоям (куда класть и что зарегистрировать)
+
+1. **Типы** — `app/src/types/**` (или согласованное имя вроде `<FeatureName>.types.ts`). Доменная модель — источник правды для UI и store.
+
+2. **API** — `app/src/api/services/<ServiceRoot>/<Segment>/`: вызовы HTTP, DTO ответов, `*responseMappers.ts`. Новые публичные экспорты (фасады сервисов, типы, **константы путей** для моков) добавить в **`app/src/api/index.ts`** (`@/api`).
+
+3. **Моки (MSW)** — `app/src/mocks/data/<feature>/`: `data.ts`, `handlers.ts`; собрать хендлеры в **`app/src/mocks/handlers.ts`**. В хендлерах использовать **те же константы путей**, что и в API (импорт из `@/api`), **не дублировать сырые строки URL**. В репозитории могут быть **два контура** (браузерный worker и Node `setupServer` для тестов): общий список хендлеров должен оставаться согласованным — при добавлении проверять существующие входные точки в `app/src/mocks/**`, чтобы моки были доступны там, где ожидается.
+
+4. **Store** — `app/src/store/slices/<FeatureName>/`: slice, thunk’и вызывают методы из **`@/api`**, не HTTP‑клиент. Подключить редюсер в **`app/src/store/reducers.ts`**. Новый **middleware**: реализация в `app/src/store/middleware/**`, регистрация в **`app/src/store/index.ts`** в цепочке `configureStore` (порядок `prepend`/`concat` — как у соседних middleware в этом файле).
+
+5. **UI** — `app/src/ui/pages/<FeatureName>Page/**` и/или `app/src/ui/components/**`; стили — как в проекте (см. `package.json` и соседние компоненты). Данные и побочные эффекты загрузки — через store/hooks, без DTO и без прямого HTTP‑клиента.
+
+6. **Unit‑тесты** — `*.spec.ts` / `*.spec.tsx` (см. `tests-unit.mdc`); мапперы и нетривиальная логика — обязательно покрыть; e2e Jest не запускает (см. `jest.config.js`).
+
+7. **E2E** — план: `app/__tests__/e2e/<Area>/<plan>.cases.md`; реализация: `*.spec.ts` рядом; детали — `tests-e2e-structure.mdc`.
+
+## Частичные сценарии (вход с середины)
+
+| Задача | Минимум действий |
+|--------|------------------|
+| Только API + типы | Типы в `app/src/types/**`, сервис и мапперы, реэкспорт в `app/src/api/index.ts`; unit на маппер. |
+| Только моки | Константа пути уже в `@/api`; `handlers.ts` + данные; регистрация в `app/src/mocks/handlers.ts`; при необходимости убедиться, что хендлеры подхватываются и в браузерном, и в Node‑контуре MSW, если в проекте используются оба. |
+| Только store | Thunk на существующий метод `@/api`; slice + `app/src/store/reducers.ts`. |
+| Только UI | Читать готовое состояние из store; не добавлять HTTP/DTO; `data-testid` при необходимости для e2e. |
+| Только e2e | Синхронизировать `*.cases.md` и спеки; page object и `_shared`. |
+
+## Антипаттерны
+
+- DTO и структуры ответа бэкенда в UI или в нетипизированных кусках store.
+- Прямой вызов HTTP‑клиента из компонента или thunk’а в обход сервисного слоя.
+- Deep‑импорты в `app/src/api/services/**/…` из UI/store там, где принят импорт из `@/api`.
+- Проброс пропсов в компоненты через `{...props}` — см. `no-props-spread.mdc`.
+
+Подробные границы слоёв: `architecture-boundaries.mdc`, `store-rtk.mdc`, `api-services.mdc`, `react-ui.mdc`.

package/presets/cursor/next/rules/http-client.mdc

@@ -0,0 +1,42 @@
+---
+description: Единый HTTP-клиент, типы ошибок и ответов
+globs:
+  - app/src/lib/clients/HttpClient/**/*.ts
+  - app/src/api/clients/**/*.ts
+alwaysApply: false
+---
+
+# HTTP-транспорт
+
+**Имена** фабрик, классов ошибок, типов ответа и конфига — **как в текущем коде репозитория** и в barrel `app/src/types/index.ts`. Ниже — **архитектурные правила**, а не спецификация переименований.
+
+## Роль слоя
+
+- Обычные REST‑вызовы к backend идут через **одну реализацию** в `app/src/lib/clients/**` (модуль общего клиента) и **преднастроенные экземпляры** в `app/src/api/clients/**`, по тому же паттерну, что уже принят в проекте.
+- Место транспорта в общей картине **порты и адаптеры** — в `architecture-boundaries.mdc` (раздел **«Порты и адаптеры»**).
+- **Не** вызывать `fetch` напрямую из `api/services`, store и UI (см. `architecture-boundaries.mdc`, `api-services.mdc`).
+- **Исключения** (узкие протоколы, отдельный транспорт) — только там, где в репозитории уже есть образец; повторять его, не плодить произвольные обходы общего клиента.
+
+## Типы
+
+- Всё, что относится к **контракту запроса/ответа/ошибки** приложения и реэкспортируется для HTTP‑слоя, импортировать **только** из barrel `@/types`, без deep‑импортов из внутренних файлов `app/src/types/**` (см. `types-public-imports.mdc`).
+- Не поднимать в новом коде **типы и зависимости от внешнего HTTP‑клиента**, от которого проект ушёл; ориентир — **`package.json`** и существующие вызовы.
+
+## Контракт ошибок
+
+- Ошибки сети и HTTP должны приходить в **едином виде**, который задаёт общий клиент (обычно класс/обёртка с полем вроде `response` для тела и статуса).
+- В **`catch`** ориентироваться на **фактическую форму** ошибки в этом репозитории (как в соседних слайсах/сервисах): доступ к телу ошибки, статусу, диагностическому коду — **по полям текущей реализации**, без выдумывания второго формата.
+
+## Поведение, которое остаётся в клиенте
+
+- Общие заголовки, `credentials`, загрузка файлов (**FormData** / снятие лишних заголовков), бинарные ответы (**blob** и аналоги), единообразный разбор JSON и прочих тел.
+- Перехват **401 / refresh**, обработка **404** и т.п. — **централизованно**, если так уже сделано в клиенте; не дублировать ту же логику в каждом сервисе.
+
+## Связь со store
+
+- Thunk может возвращать **тип обёртки успешного ответа**, если сервис так устроен; в **state** по возможности класть **доменные** типы после маппинга. Подробнее — `store-rtk.mdc`.
+
+## Требование к агенту
+
+- Меняя реализацию общего клиента — **обновить или добавить behavior‑тесты** рядом с модулем клиента (`tests-unit.mdc`).
+- Не вводить **второй полноценный HTTP‑стек** без явной задачи и согласования с архитектурой репозитория.

package/presets/cursor/next/rules/next-app-core.mdc

@@ -27,30 +27,39 @@ alwaysApply: true
 
 # Архитектурные слои
 
-- **UI слой** (`src/ui/**`):
-  - `src/ui/pages/**` — страницы и контейнеры.
-  - `src/ui/components/**` — переиспользуемые компоненты.
-- **Store слой** (`src/store/**`):
-  - `src/store/slices/**` — модули состояния (в этом preset — Redux Toolkit; подробности в `store-rtk.mdc`).
-  - `src/store/middleware/**` — middleware для сайд‑эффектов (например, файлы, аналитика).
-- **API слой** (`src/api/services/**`):
+- **UI слой** (`app/src/ui/**`):
+  - `app/src/ui/pages/**` — страницы и контейнеры.
+  - `app/src/ui/components/**` — переиспользуемые компоненты.
+- **Store слой** (`app/src/store/**`):
+  - `app/src/store/slices/**` — модули состояния (в этом preset — Redux Toolkit; подробности в `store-rtk.mdc`).
+  - `app/src/store/middleware/**` — middleware для сайд‑эффектов (например, файлы, аналитика).
+- **API слой** (`app/src/api/services/**`):
   - Сервисы и мапперы, инкапсулирующие HTTP‑логику.
-- **Типы** (`src/types/**`):
-  - Общие доменные типы продукта (сущности предметной области, агрегаты и т.д.).
-- **Моки и тестовые данные** (`src/mocks/**`):
+- **HTTP‑транспорт** (модуль общего клиента под `app/src/lib/clients/**`, экземпляры под `app/src/api/clients/**` — как в репозитории):
+  - Один механизм запросов, без разбросанного «сырого» `fetch`/`XMLHttpRequest` по фичам. Детали и исключения — **`http-client.mdc`**.
+- **Типы** (`app/src/types/**`):
+  - Доменные модели и при необходимости транспортные контракты; **потребители** импортируют только через **`types-public-imports.mdc`** (`@/types`, `@/types/enums`).
+- **Моки и тестовые данные** (`app/src/mocks/**`):
   - По структуре и назначению — как принято в репозитории.
 
+## Порты и адаптеры (сопоставление с каталогами)
+
+Та же идея, что в `architecture-boundaries.mdc` (раздел **«Порты и адаптеры»**): UI и store зависят от **контракта** к backend (сервисы + доменные типы), а **реализация HTTP** изолирована в **`app/src/lib/clients/**`** и **`app/src/api/clients/**`**. Детали транспорта — `http-client.mdc`.
+
 # Общие архитектурные принципы
 
 - **Чёткое разделение слоёв**:
-  - UI знает только о доменных типах и публичных интерфейсах store/API.
+  - UI знает о доменных типах (из `@/types` / `@/types/enums`) и публичных API store и при необходимости **`@/api/services`** — см. политику в `architecture-boundaries.mdc` (**«UI и обращение к `@/api/services`»**).
   - Store знает о доменных типах и API‑сервисах.
-  - API знает о транспортном слое (HTTP, выбранный клиент) и DTO.
+  - API‑сервисы знают о DTO, мапперах и вызовах через клиенты из `app/src/api/clients/**` (`http-client.mdc`).
 - **Никаких "проникновений" слоёв**:
-  - UI не обращается к API напрямую — только через store или абстракции сервисов.
-  - Store не работает напрямую с "сырыми" HTTP‑ответами — только через мапперы.
+  - UI не вызывает HTTP‑клиент и не работает с DTO; сценарии с записью в общий state — через store; узкие исключения для вызова сервисов из UI — только по правилам `architecture-boundaries.mdc`.
+  - Store не собирает запросы сам и не обходит API‑сервисы; данные для state — доменные модели после маппинга. Допустимые **транспортные** типы ответа/ошибки во thunk — как в `@/types` и согласованно с `http-client.mdc`, `store-rtk.mdc`.
+- **Доменная логика и state**:
+  - Нетривиальные правила предметной области и преобразования **DTO → домен** — в **мапперах** и чистых функциях/модулях фичи (`api-services.mdc`); **редюсеры и селекторы** держать узкими (обновление state и проекции), без дублирования тяжёлой бизнес‑логики, если её место в маппере или доменном помощнике. Подробности — `store-rtk.mdc`.
 - **Типы — источник правды**:
-  - Новые сущности описывать в `src/types/**`, переиспользовать, а не дублировать типы по слоям.
+  - При коллизии с другими правилами по **импорту типов** — ориентир **`types-public-imports.mdc`**.
+  - Новые сущности описывать в `app/src/types/**` и экспортировать через barrel; потребители не обходят `types-public-imports.mdc`.
   - Не использовать `any`; при необходимости — `unknown` + безопасное сужение типа.
 
 # Кодстайл и качества кода
@@ -61,17 +70,17 @@ alwaysApply: true
   - Модульность и переиспользование через компоненты, хуки, слайсы, сервисы.
   - Визуальную консистентность за счёт принятых в проекте UI‑примитивов и токенов, а не разовых литералов в стилях.
 - При добавлении нового кода **искать и копировать существующие паттерны**:
-  - Для страниц — аналогичные файлы в `src/ui/pages/**`.
-  - Для блоков — компоненты в `src/ui/components/**`.
-  - Для API — сервисы в `src/api/services/**`.
-  - Для состояния — слайсы в `src/store/slices/**`.
+  - Для страниц — аналогичные файлы в `app/src/ui/pages/**`.
+  - Для блоков — компоненты в `app/src/ui/components/**`.
+  - Для API — сервисы в `app/src/api/services/**`.
+  - Для состояния — слайсы в `app/src/store/slices/**`.
 
 # Работа агента
 
 При генерации кода:
 - Определить целевой слой (UI/store/API/типизация/тесты).
 - Найти в соответствующей директории похожие примеры и **копировать архитектурный паттерн** (структура файлов, типы, именование).
-- Не упрощать архитектуру в ущерб существующим слоям (не тянуть API в UI, не описывать "DTO" прямо в компонентах).
- - Избегать использования `any` при типизации кода; при необходимости использовать `unknown` с последующим безопасным сужением типов.
- - После создания или редактирования любых файлов **обязательно проверять проект на ошибки TypeScript и ESLint** (либо точечно по изменённым файлам, либо по всему проекту) и устранять найденные проблемы, если это возможно без изменения бизнес‑логики).
+- Не упрощать архитектуру в ущерб существующим слоям (не тянуть DTO и HTTP в UI; вызовы сервисов из UI — только в рамках `architecture-boundaries.mdc`).
+- Избегать использования `any` при типизации кода; при необходимости использовать `unknown` с последующим безопасным сужением типов.
+- После создания или редактирования файлов **обязательно** устранять проблемы линтера и типов: из каталога `app/` минимум **`yarn lint:js`** (полный прогон ESLint по проекту, как в `package.json`), при правках стилей — ещё **`yarn lint:css`**; для проверки типов — **`yarn type-check`**. Точечный ESLint только на один файл не заменяет полный прогон при завершении задачи/MR. Устранять найденное в зоне изменений, если это возможно без искажения бизнес‑логики.
 

package/presets/cursor/next/rules/no-type-assertion-as-import-export.mdc

@@ -0,0 +1,56 @@
+---
+description: Избегать приведения типов через as на границах модулей (импорт/экспорт)
+alwaysApply: true
+---
+
+# Не использовать `as` для приведения типов при экспорте и импорте (кроме необходимых случаев)
+
+## О чём речь
+
+Речь о **type assertion** в TypeScript: выражение вида `значение as Тип`.
+
+**Не относится к правилу** (это не assertion, а синтаксис модулей):
+
+- переименование при экспорте: `export { foo as bar }`, `export { default as Baz } from '...'`;
+- переименование при импорте: `import { foo as bar } from '...'`;
+- `import type { Foo as Bar }` — алиас типа в импорте типов.
+
+## Требование
+
+- На **публичной границе модуля** (то, что **экспортируется** из файла / barrel, и то, что сразу **присваивается импортированным символам** с принудительным приведением) **не использовать** `as Тип` для «подгонки» типов, если можно обойтись нормальной типизацией.
+
+## Предпочитать вместо `as`
+
+- явную аннотацию: `const x: T = ...` / `function f(): T`;
+- **дженерики** у функций и классов;
+- **`satisfies`** (когда нужно проверить совместимость без сужения до `any`);
+- сужение **`unknown`** после проверки (type guards, `zod` и т.п.);
+- правку **исходных типов/DTO/мапперов**, а не assertion на выходе.
+
+## Когда `as` допустим
+
+- взаимодействие с **не типизированными** или некорректно типизированными внешними модулями, где нет разумной альтернативы;
+- узкие места после **валидации** данных, если типовый гард всё ещё не выразить без шума (предпочтительно всё же guard/`satisfies`);
+- **`as const`** — когда нужны литеральные типы и широкий вывод ломает контракт (это отдельный механизм; применять по делу, не как замену типизации API).
+- блок **`catch (error)`** после вызова HTTP через общий клиент: по возможности сужать через **`instanceof`** на **класс ошибки транспорта** из `@/types` (какой именно — по существующей реализации) и работать с уже суженным типом; голый **`as` к тому же типу** — только если `instanceof` недоступен (иной источник выброса) и осознанно.
+
+## Примеры
+
+```typescript
+// ❌ Плохо: assertion на экспортируемом API
+export const config = loadRaw() as AppConfig
+
+// ✅ Лучше: аннотация + проверка или маппер
+export const config: AppConfig = mapToAppConfig(loadRaw())
+
+// ❌ Плохо: сразу после импорта «ломаем» тип
+import { getData } from './api'
+export const data = getData() as MyDto[]
+
+// ✅ Лучше: типизировать getData / обернуть типобезопасной функцией
+```
+
+## Требование к агенту
+
+При ревью и генерации кода **не добавлять** новые `as Тип` на экспортируемые сущности и на цепочку import → export без явной необходимости; по возможности исправлять контракт типов в источнике.
+- В слайсах и сервисах при обработке ошибок API сначала рассматривать **`instanceof`** на класс ошибки транспорта из `@/types` по образцу существующего кода (`http-client.mdc`, `store-rtk.mdc`).

package/presets/cursor/next/rules/react-ui.mdc

@@ -1,6 +1,6 @@
 ---
 description: Паттерны React/Next UI и стилей (preset)
-globs: src/ui/**/*.tsx
+globs: app/src/ui/**/*.tsx
 alwaysApply: false
 ---
 
@@ -42,7 +42,7 @@ alwaysApply: false
 - Описывать пропсы через `type Props = { ... }` или `interface Props { ... }`.
 - Не использовать `any`; при необходимости:
   - обобщения (`<T>`), `unknown`, тип‑предикаты и user‑defined type guards.
-- Для доменных сущностей использовать типы из `@/types/**`, а не описывать их заново.
+- Для доменных сущностей использовать типы из `@/types` (и enum из `@/types/enums`), а не описывать их заново (`types-public-imports.mdc`).
 
 # Логика и side effects
 

package/presets/cursor/next/rules/store-rtk.mdc

@@ -1,6 +1,6 @@
 ---
 description: Redux Toolkit и состояние приложения
-globs: src/store/**/*.ts
+globs: app/src/store/**/*.ts
 alwaysApply: false
 ---
 
@@ -16,7 +16,7 @@ alwaysApply: false
 
 # Структура слайсов
 
-- Каждый доменный модуль — свой слайс в `src/store/slices/**`.
+- Каждый доменный модуль — свой слайс в `app/src/store/slices/**`.
 - Слайс экспортирует:
   - `reducer` по умолчанию;
   - `actions` именованным экспортом;
@@ -33,14 +33,20 @@ alwaysApply: false
     - вызывать API через сервисы из `@/api/services/**`;
     - не вызывать HTTP‑клиент напрямую — только через сервисы `@/api/services/**`.
 - Сайд‑эффекты (логирование, аналитика, работа с файлами):
-  - выносить в middleware (`src/store/middleware/**`) или специализированные слайсы.
+  - выносить в middleware (`app/src/store/middleware/**`) или специализированные слайсы.
 
 # Типизация
 
 - Использовать `RootState`, `AppDispatch` и типизированные хуки `useAppDispatch`, `useAppSelector` (если есть).
+- **HTTP и ошибки API**:
+  - не импортировать типы **сторонних HTTP‑библиотек**, которых нет в актуальных зависимостях и существующих слайсах (ориентир — **`package.json`** и соседние файлы);
+  - когда сервис возвращает **обёртку ответа** прикладного клиента — использовать **соответствующий тип из `@/types`** (как в barrel и в аналогичных thunk’ах);
+  - при ошибках после вызова сервиса — опираться на **тот же класс/контракт ошибки транспорта**, что использует общий клиент (из `@/types`), и разбирать тело/статус **по полям текущей реализации**, а не по воображаемому API;
+  - в **`catch`** предпочитать **`instanceof`** на класс ошибки транспорта из `@/types` (если он есть в коде) вместо голого `as`, когда это выразимо без шума (см. `no-type-assertion-as-import-export.mdc`).
 - Для сущностей:
-  - доменные типы (включая вычисляемые поля) определять в `@/types/**` и импортировать в слайсы как **источник правды** для структуры данных;
+  - доменные типы (включая вычисляемые поля) определять в `app/src/types/**`, экспортировать через barrel и импортировать в слайсы из `@/types` как **источник правды** для структуры данных (`types-public-imports.mdc`);
   - избегать дублирования описаний сущностей в нескольких местах.
+- **Граница домена**: в **state** хранить доменные модели; тип **обёртки ответа клиента** допустим как тип **возвращаемого значения thunk** или промежуточно до маппинга — без дублирования DTO в полях state без нужды (согласовано с `api-services.mdc` и `http-client.mdc`).
 
 # Тестирование слайсов
 
@@ -56,4 +62,5 @@ alwaysApply: false
 - Не класть логику API внутрь редюсеров/компонентов.
 - Строго типизировать state и actions.
 - Использовать единый стиль именования actions и селекторов, как в существующих слайсах.
+- При работе с ошибками и ответами HTTP опираться на **`http-client.mdc`** и контракты из `@/types`, а не на типы внешних HTTP‑библиотек вне зависимостей проекта.
 

package/presets/cursor/next/rules/technical-retro.mdc

@@ -0,0 +1,58 @@
+---
+description: Роль агента для проведения технического ретроспективы (retro) команды / спринта
+alwaysApply: false
+---
+
+# Техническое ретро — роль агента
+
+Агент выступает как **нейтральный фасилитатор технической ретроспективы**, а не как ревьюер кода или оценщик людей. Цель — вынести уроки, согласовать действия и улучшить процесс разработки.
+
+## Когда включать
+
+- Пользователь просит: «ретро», «техническое ретро», «разбор спринта/итерации», «что пошло хорошо / плохо», «action items после релиза».
+- Есть контекст: период (спринт, квартал), тема (релиз, инцидент, миграция), или приложены заметки/линки.
+
+## Входные данные (запросить при нехватке)
+
+- **Период и фокус** (например: две недели, релиз X, постмортем).
+- **Участники/роли** (если важно для формулировок): только разработка или весь кросс‑функциональный поток.
+- **Ограничения**: время (15 / 30 / 60 мин), формат (async в чате vs синхронная повестка).
+- По желанию: список deliverables, метрики, ссылки на тикеты/MR — **без выдумывания** фактов, которых нет в сообщении или репозитории.
+
+Если контекста мало — задать **1–3 коротких уточняющих вопроса**, затем продолжить с явными допущениями в шапке вывода.
+
+## Принципы фасилитации
+
+- **Безопасность и нейтральность**: формулировки про процесс и систему, не про «виноватых»; избегать ярлыков к людям.
+- **Конкретика**: от абстрактного «надо лучше общаться» — к наблюдаемым событиям и договорённостям.
+- **Баланс**: зафиксировать и позитив (что усилить), и зоны роста.
+- **Один владелец и срок** у каждого action item; избегать списка «сделает команда» без имени/роли.
+- **Не смешивать с code review**: ретро не заменяет построчный разбор диффа; при запросе «и ретро, и ревью» — развести два блока в ответе.
+
+## Рекомендуемая структура сессии (по умолчанию)
+
+Подстроить под указанное время. Для короткого async‑формата — сжать до шагов 2–4.
+
+1. **Цель и рамки** (1–2 предложения): зачем встреча, что в фокусе / что вне скоупа.
+2. **Сбор фактов** (молча в чате — списком от пользователя; агент структурирует):
+   - что шло хорошо,
+   - что мешало / вызывало риски,
+   - сюрпризы (технический долг, узкие места, зависимости).
+3. **Группировка тем**: объединить дубли, выделить 3–7 тем для обсуждения (приоритет — влияние × изменяемость).
+4. **Корневые причины (легко)**: для 1–2 самых болезненных тем — кратко «5 почему» или «что в процессе/артефактах позволило этому случиться», без морализаторства.
+5. **Эксперименты на следующий цикл**: не больше 1–3 изменений процесса/инструментов; каждое — измеримое или с явным критерием «успех/не успех».
+6. **Action items**: таблица или список с **что / владелец / до когда / как поймём, что сработало**.
+
+## Формат ответа агента
+
+- Краткая **шапка**: период, фокус, допущения (если были).
+- **Повестка** или итог по этапам выше.
+- **Темы** — буллеты; по спорным местам — **вопросы команде**, а не окончательные выводы без данных.
+- **Решения и эксперименты** отдельным блоком.
+- **Action items** — в конце, каждый пункт с владельцем и дедлайном (или пометка «нужно назначить на встрече»).
+
+## Ограничения
+
+- Не приписывать команде цитаты или факты, которых не было во входе.
+- Не выдавать юридические/HR‑рекомендации; при явных конфликтах или токсичности — мягко предложить эскалацию человеку, ответственному за команду, без детализации «наказаний».
+- Если пользователь просит только шаблон — выдать **шаблон повестки и доски** (колонки, таймбоксы) без выдуманного контента.

package/presets/cursor/next/rules/tests-unit.mdc

@@ -1,6 +1,6 @@
 ---
 description: Unit и интеграционные тесты (Testing Library и runner проекта)
-globs: src/**/*.test.{ts,tsx}
+globs: app/src/**/*.{spec,test}.{ts,tsx}
 alwaysApply: false
 ---
 
@@ -9,9 +9,19 @@ alwaysApply: false
 - **Runner и матчеры** — как в проекте (часто Jest или Vitest); для компонентов — **@testing-library/react**.
 - Основная цель тестов:
   - проверять **поведение и бизнес‑правила**, а не реализацию или внутренние детали.
- - Именование:
-  - названия `describe` / `it` / `test` и любые человекочитаемые описания в тестах **должны быть на русском языке**, формулироваться как понятные бизнес‑фразы (что именно ожидается от системы).
-  - строки в `describe` / `it` / `test` **должны начинаться с заглавной буквы**.
+- **Именование unit‑тестов** (строки в `describe` / `it` / `test`):
+  - формулировки **только на русском языке** — понятные бизнес‑фразы (что проверяется и какой ожидается результат);
+  - **каждое предложение** в названии **начинается с заглавной буквы** (в том числе после `.`, `!`, `?` и при нескольких предложениях в одной строке); первая буква всей строки — тоже заглавная.
+
+```typescript
+// ✅ Хорошо
+it('Возвращает пустой список. Пользователь не авторизован', () => {})
+it('При ошибке сети показывается сообщение об ошибке', () => {})
+
+// ❌ Плохо (не с заглавной после точки; или не русский)
+it('Возвращает пустой список. пользователь не авторизован', () => {})
+it('Returns empty list when user is guest', () => {})
+```
 
 # Тесты компонентов
 
@@ -27,6 +37,11 @@ alwaysApply: false
   - мокать store (через test‑store) или использовать принятый в проекте способ моков HTTP/API.
 - Не мокать то, что является частью публичного контракта фичи, если это ломает смысл теста.
 
+# HTTP‑клиент
+
+- При изменении **реализации общего HTTP‑клиента** (разбор тел, заголовки, ветки ошибок, 401/refresh, `FormData`, `blob` и т.п.) — **обновить или добавить behavior‑тесты** рядом с модулем клиента в `app/src/lib/clients/**` (`*.spec.ts` / `*.test.ts` — как принято в репо).
+- Проверять смысловые ветки: успешный JSON, HTTP‑ошибка, сеть, релевантные для проекта сценарии авторизации.
+
 # Мапперы и преобразование данных
 
 - Функции маппинга данных (DTO -> доменная модель и обратно), особенно содержащие вычисляемые поля и ветвления, должны быть покрыты unit‑тестами.
@@ -35,11 +50,11 @@ alwaysApply: false
 # Требование к агенту
 
 При добавлении тестов:
-- Следовать существующей структуре и паттернам тестов в `src/**/__tests__/**` или рядом с компонентом.
+- Следовать существующей структуре и паттернам тестов в `app/src/**/__tests__/**` или рядом с компонентом.
 - Добавлять тесты для критичных веток логики и edge‑кейсов.
  - При работе с данными:
-   - использовать **типы респонса** из API (DTO‑типы), а также **целевые доменные типы** из `@/types/**`, не дублировать интерфейсы в тестах;
-   - по возможности опираться на данные и обработчики из `src/mocks/**` (или аналог в репо), а не плодить случайные тестовые данные "с нуля".
+   - использовать **типы респонса** из API (DTO‑типы), а также **целевые доменные типы** из `@/types`, не дублировать интерфейсы в тестах;
+   - по возможности опираться на данные и обработчики из `app/src/mocks/**` (или аналог в репо), а не плодить случайные тестовые данные "с нуля".
  - При написании unit‑тестов рядом с компонентом или модулем:
    - **не создавать** поддиректорию `__tests__` внутри папки компонента;
    - именовать файлы тестов с суффиксом `*.spec.ts` / `*.spec.tsx`, а не `*.test.ts` / `*.test.tsx`.

package/presets/cursor/next/rules/types-jsdoc.mdc

@@ -0,0 +1,42 @@
+---
+description: Стиль JSDoc для доменных и транспортных типов в app/src/types
+globs: app/src/types/**/*.ts
+alwaysApply: false
+---
+
+# Документация типов в `app/src/types`
+
+При добавлении или существенном изменении типов в этом слое **следовать уже принятому в репозитории стилю JSDoc** (см. примеры: `User.types.ts`, `Common.types.ts`, `ServerValidation.types.ts`, `TreatmentPlan/*.types.ts`).
+
+## Язык и форма
+
+- Текст комментариев — **на русском**, кратко и по делу: что означает тип или поле в предметной области или в контракте с API.
+- **Не опираться** на теги в духе `@param`, `@returns`, `@see`, `@deprecated` для описания типов — в этом слое они **не используются**; достаточно обычного текста в `/** … */`.
+
+## Экспортируемый `type` / `interface`
+
+- Сразу **перед объявлением** — блок `/** … */`.
+- Если нужно пояснить источник данных, ограничения или неочевидности — **второй абзац** в том же блоке (в JSDoc для абзаца — пустая строка между строками текста).
+- Для **вложенных** объектов в том же файле каждый такой тип документируется отдельным блоком над своим объявлением.
+
+## Поля
+
+- У **каждого** публичного свойства — **однострочный** `/** … */` на строке непосредственно **над** полем.
+- Если поле **не приходит с бэкенда «как есть»**, а вычисляется или дополняется на фронте (маппер, селектор, UI) — начать описание с префикса **`[computed]`** (как в `TUserProfile`, типах плана лечения).
+- Для форматов данных указывать это **в тексте**: например дата `YYYY-MM-DD`, пример отображаемой строки в кавычках.
+
+## Классы и прочие объявления
+
+- Для **классов** (например ошибки транспорта) при изменении публичного API — краткий блок над классом и **комментарии к публичным полям** по тем же правилам, что у свойств интерфейса.
+
+## `enum`
+
+- В `enums.ts` исторически часто **без JSDoc** на каждом члене; для новых enum допустимо короткое описание **над самим enum**, если назначение неочевидно из имени. Подписи для UI — как принято, через объекты `*Names` рядом с enum.
+
+## Практика для агента
+
+- Добавляя новый тип или поле, **не оставлять** новые публичные поля без пояснения, если смысл не равен имени на 100%.
+- Правя файл, где уже есть такие комментарии, **поддерживать тот же стиль**, а не смешивать с англоязычными или «теговыми» блоками.
+- Не раздувать комментарии: одна-две фразы на тип, одна строка на поле — норма; исключение — действительно сложная доменная оговорка.
+
+См. также импорты и barrel: `types-public-imports.mdc`.

package/presets/cursor/next/rules/types-public-imports.mdc

@@ -0,0 +1,29 @@
+---
+description: Импорт доменных типов только через публичный API @/types
+alwaysApply: true
+---
+
+# Импорты из `@/types`
+
+- **Публичный API типов** — barrel `app/src/types/index.ts`, импортировать типы и интерфейсы только как `@/types` (или `@/types/index` при необходимости явного пути).
+- **Запрещено** для потребителей слоя обходить barrel: любой импорт вида `@/types/<что‑угодно>`, кроме перечисленного ниже исключения для enum.
+- Отдельно **нельзя** импортировать из вложенных файлов `*.types.ts` по путям `@/types/**/…*.types.ts` (типичный deep‑импорт).
+- **Исключение — enum**: перечисления можно импортировать только из `@/types/enums` / `@/types/enums.ts` (не из других файлов под `@/types`).
+
+## Внутри слоя `app/src/types/**`
+
+- При реализации и поддержке barrel‑файла допустимы **относительные** импорты между файлами внутри `app/src/types` (например `from './User.types'`). Это не относится к потребителям слоя.
+
+## Примеры
+
+```typescript
+// ✅ Допустимо — доменные и транспортные сущности с теми именами, что экспортирует barrel
+import type { TUserProfile } from '@/types'
+import { SomeEnum } from '@/types/enums'
+
+// ❌ Запрещено (обход публичного API)
+import type { TUserProfile } from '@/types/User.types'
+import { TransportError } from '@/types/TransportError'
+```
+
+При ревью и правках кода **не добавлять** новые импорты типов из `@/types/...` кроме `@/types` и `@/types/enums`.