code-ai-installer 1.2.0 → 1.3.0

package/.agents/state_rtk_beast_practices/SKILL.md

@@ -1,15 +1,735 @@
----
-name: state_rtk_beast_practices
-description: Redux Toolkit: предсказуемый state для сложных приложений, slices, async thunks, нормализация, селекторы, тестируемость.
----
-
-# Skill: RTK Beast Practices
-
-## Когда выбирать RTK
-- Сложные домены, много событий, сложная синхронизация UI/данных
-
-## Правила
-- slices по доменам
-- нормализация сущностей
-- селекторы и мемоизация
-- side effects — через thunks/мидлвары, не в компонентах
+---
+name: state_rtk_beast_practices
+description: Redux Toolkit — предсказуемый state для сложных приложений. createSlice, createAsyncThunk, createEntityAdapter, createSelector, RTK Query, middleware, TypeScript типизация, тестирование. Активируй при создании нового slice, рефакторинге Redux, или при вопросах «как правильно организовать RTK».
+---
+
+# Skill: RTK Beast Practices
+
+Конкретные DO/DON'T паттерны для Redux Toolkit — от архитектуры slices до тестирования.
+
+**Разделы:**
+1. [Когда RTK vs Zustand](#1-когда-rtk-vs-zustand)
+2. [createSlice: архитектура](#2-createslice-архитектура)
+3. [createAsyncThunk: async operations](#3-createasyncthunk)
+4. [createEntityAdapter: нормализация](#4-createentityadapter)
+5. [Селекторы и createSelector](#5-селекторы)
+6. [RTK Query: server state](#6-rtk-query)
+7. [TypeScript типизация](#7-typescript)
+8. [Тестирование](#8-тестирование)
+9. [Anti-patterns](#9-anti-patterns)
+
+---
+
+## 1. Когда RTK vs Zustand
+
+| Критерий | RTK ✅ | Zustand ✅ |
+|---------|--------|-----------|
+| Сложные домены с множеством событий | ✅ | ⚠️ Возможно, но сложнее |
+| Нормализация сущностей (entities) | ✅ `createEntityAdapter` | ❌ Вручную |
+| Middleware (logging, analytics, undo) | ✅ Встроенный | ⚠️ Базовый |
+| DevTools | ✅ Redux DevTools (полный) | ✅ Redux DevTools (базовый) |
+| Server state кэширование | ✅ RTK Query | ❌ Вручную или TanStack Query |
+| Небольшой проект, мало state | ❌ Оверкилл | ✅ Минимальный boilerplate |
+| Размер бандла | ⚠️ ~11KB | ✅ ~1KB |
+| Learning curve | ⚠️ Средняя | ✅ Низкая |
+
+> [!TIP]
+> **Простое правило:** Zustand для простого client state, RTK для сложных доменов с нормализацией и middleware. RTK Query заменяет TanStack Query в RTK-экосистеме.
+
+---
+
+## 2. createSlice: архитектура
+
+### ✅ DO: один slice на домен (bounded context)
+
+```js
+// features/coupons/couponsSlice.js
+import { createSlice } from '@reduxjs/toolkit';
+
+const INITIAL_STATE = {
+  items: [],
+  selectedId: null,
+  status: 'idle',  // 'idle' | 'loading' | 'succeeded' | 'failed'
+  error: null,
+};
+
+const couponsSlice = createSlice({
+  name: 'coupons',
+  initialState: INITIAL_STATE,
+  reducers: {
+    /**
+     * Выбирает купон по ID.
+     * @param {Object} state - текущее состояние.
+     * @param {{ payload: string }} action - ID купона.
+     */
+    couponSelected(state, action) {
+      state.selectedId = action.payload;
+    },
+
+    /**
+     * Деактивирует купон по ID.
+     * @param {Object} state - текущее состояние.
+     * @param {{ payload: string }} action - ID купона.
+     */
+    couponDeactivated(state, action) {
+      const coupon = state.items.find((c) => c.id === action.payload);
+      if (coupon) coupon.active = false;  // ✅ Мутация OK внутри createSlice (Immer)
+    },
+
+    /** Сбрасывает slice к начальному состоянию. */
+    couponsReset() {
+      return INITIAL_STATE;
+    },
+  },
+});
+
+export const { couponSelected, couponDeactivated, couponsReset } = couponsSlice.actions;
+export default couponsSlice.reducer;
+```
+
+### ✅ DO: Naming convention для actions
+
+```js
+// Формат: [noun][PastTenseVerb]
+// Описывает ЧТО ПРОИЗОШЛО, а не что делать
+
+// ✅ Events (что произошло)
+couponSelected      // купон выбран
+couponDeactivated   // купон деактивирован
+templateLoaded      // шаблон загружен
+formSubmitted       // форма отправлена
+
+// ❌ Commands (что делать) — менее предсказуемо
+selectCoupon        // императивный стиль
+deactivateCoupon
+loadTemplate
+```
+
+### ✅ DO: prepare callback для формирования payload
+
+```js
+const couponsSlice = createSlice({
+  name: 'coupons',
+  initialState,
+  reducers: {
+    /**
+     * Добавляет новый купон с автоматическим ID и timestamp.
+     * @param {Object} state - текущее состояние.
+     * @param {{ payload: { id: string, createdAt: string, code: string, discount: number } }} action
+     */
+    couponAdded: {
+      reducer(state, action) {
+        state.items.push(action.payload);
+      },
+      // ✅ prepare отделяет логику создания payload от reducer
+      prepare(code, discount) {
+        return {
+          payload: {
+            id: crypto.randomUUID(),
+            createdAt: new Date().toISOString(),
+            code,
+            discount,
+          },
+        };
+      },
+    },
+  },
+});
+
+// Использование:
+dispatch(couponAdded('SAVE20', 20));
+// payload: { id: 'abc...', createdAt: '2026-...', code: 'SAVE20', discount: 20 }
+```
+
+### Структура директорий
+
+```
+src/
+├── app/
+│   ├── store.js           # configureStore
+│   └── hooks.js           # useAppDispatch, useAppSelector
+├── features/
+│   ├── coupons/
+│   │   ├── couponsSlice.js
+│   │   ├── couponsSlice.test.js
+│   │   ├── couponsSelectors.js
+│   │   └── CouponList.jsx
+│   └── templates/
+│       ├── templatesSlice.js
+│       ├── templatesSlice.test.js
+│       └── TemplateEditor.jsx
+```
+
+---
+
+## 3. createAsyncThunk
+
+### ✅ DO: async operations через createAsyncThunk
+
+```js
+import { createSlice, createAsyncThunk } from '@reduxjs/toolkit';
+
+/**
+ * Загружает список купонов с сервера.
+ * @returns {Promise<Coupon[]>} массив купонов.
+ */
+export const fetchCoupons = createAsyncThunk(
+  'coupons/fetchCoupons',
+  async (_, { rejectWithValue }) => {
+    try {
+      const res = await fetch('/api/coupons');
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return await res.json();
+    } catch (err) {
+      return rejectWithValue(err.message);
+    }
+  }
+);
+
+/**
+ * Удаляет купон по ID.
+ * @param {string} couponId - ID купона для удаления.
+ * @returns {Promise<string>} ID удалённого купона.
+ */
+export const deleteCoupon = createAsyncThunk(
+  'coupons/deleteCoupon',
+  async (couponId, { rejectWithValue }) => {
+    try {
+      const res = await fetch(`/api/coupons/${couponId}`, { method: 'DELETE' });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return couponId; // ✅ Возвращаем ID для удаления из state
+    } catch (err) {
+      return rejectWithValue(err.message);
+    }
+  }
+);
+
+const couponsSlice = createSlice({
+  name: 'coupons',
+  initialState: { items: [], status: 'idle', error: null },
+  reducers: {},
+  extraReducers: (builder) => {
+    builder
+      // fetchCoupons
+      .addCase(fetchCoupons.pending, (state) => {
+        state.status = 'loading';
+        state.error = null;
+      })
+      .addCase(fetchCoupons.fulfilled, (state, action) => {
+        state.status = 'succeeded';
+        state.items = action.payload;
+      })
+      .addCase(fetchCoupons.rejected, (state, action) => {
+        state.status = 'failed';
+        state.error = action.payload ?? action.error.message;
+      })
+      // deleteCoupon
+      .addCase(deleteCoupon.fulfilled, (state, action) => {
+        state.items = state.items.filter((c) => c.id !== action.payload);
+      });
+  },
+});
+```
+
+### ✅ DO: условные thunks с condition
+
+```js
+export const fetchCouponsIfNeeded = createAsyncThunk(
+  'coupons/fetchCoupons',
+  async () => {
+    const res = await fetch('/api/coupons');
+    return res.json();
+  },
+  {
+    // ✅ Не запускаем повторно если уже загружено
+    condition: (_, { getState }) => {
+      const { status } = getState().coupons;
+      return status === 'idle'; // Запускаем только из idle
+    },
+  }
+);
+```
+
+### ✅ DO: thunk с доступом к другим slices
+
+```js
+export const applyCouponToOrder = createAsyncThunk(
+  'coupons/applyCouponToOrder',
+  async ({ couponId, orderId }, { getState, rejectWithValue }) => {
+    const coupon = getState().coupons.items.find((c) => c.id === couponId);
+    if (!coupon?.active) {
+      return rejectWithValue('Coupon is inactive');
+    }
+
+    const res = await fetch(`/api/orders/${orderId}/apply-coupon`, {
+      method: 'POST',
+      body: JSON.stringify({ couponId }),
+      headers: { 'Content-Type': 'application/json' },
+    });
+    return res.json();
+  }
+);
+```
+
+---
+
+## 4. createEntityAdapter
+
+### ✅ DO: нормализация для коллекций сущностей
+
+```js
+import { createSlice, createEntityAdapter } from '@reduxjs/toolkit';
+
+// ✅ EntityAdapter: автоматические ids[] и entities{} + CRUD операции
+const couponsAdapter = createEntityAdapter({
+  sortComparer: (a, b) => a.code.localeCompare(b.code), // сортировка по коду
+});
+
+const couponsSlice = createSlice({
+  name: 'coupons',
+  initialState: couponsAdapter.getInitialState({
+    status: 'idle',
+    error: null,
+  }),
+  // initialState = { ids: [], entities: {}, status: 'idle', error: null }
+
+  reducers: {
+    couponAdded: couponsAdapter.addOne,
+    couponUpdated: couponsAdapter.updateOne,
+    couponRemoved: couponsAdapter.removeOne,
+    couponsReceived: couponsAdapter.setAll,
+  },
+  extraReducers: (builder) => {
+    builder
+      .addCase(fetchCoupons.fulfilled, (state, action) => {
+        couponsAdapter.setAll(state, action.payload);
+        state.status = 'succeeded';
+      });
+  },
+});
+
+// ✅ Автоматические селекторы
+export const {
+  selectAll: selectAllCoupons,        // все купоны как массив
+  selectById: selectCouponById,       // купон по ID
+  selectIds: selectCouponIds,         // массив ID
+  selectTotal: selectTotalCoupons,    // количество
+  selectEntities: selectCouponEntities, // словарь
+} = couponsAdapter.getSelectors((state) => state.coupons);
+```
+
+### Dispatch примеры
+
+```js
+// Добавить
+dispatch(couponAdded({ id: '1', code: 'SAVE10', discount: 10, active: true }));
+
+// Обновить (partial update)
+dispatch(couponUpdated({ id: '1', changes: { active: false } }));
+
+// Удалить
+dispatch(couponRemoved('1'));
+
+// Загрузить все
+dispatch(couponsReceived(couponsFromApi));
+```
+
+---
+
+## 5. Селекторы
+
+### ✅ DO: createSelector для мемоизированных derived данных
+
+```js
+import { createSelector } from '@reduxjs/toolkit';
+
+// Базовый селектор
+const selectCouponsState = (state) => state.coupons;
+
+// ✅ Мемоизированный: пересчитывается только при изменении `items`
+export const selectActiveCoupons = createSelector(
+  [selectAllCoupons],
+  (coupons) => coupons.filter((c) => c.active)
+);
+
+export const selectCouponStats = createSelector(
+  [selectAllCoupons],
+  (coupons) => ({
+    total: coupons.length,
+    active: coupons.filter((c) => c.active).length,
+    inactive: coupons.filter((c) => !c.active).length,
+    totalDiscount: coupons.reduce((sum, c) => sum + c.discount, 0),
+  })
+);
+
+// ✅ Параметризованный селектор
+export const selectCouponsByType = createSelector(
+  [selectAllCoupons, (_, type) => type],
+  (coupons, type) => coupons.filter((c) => c.type === type)
+);
+
+// Использование: selectCouponsByType(state, 'percent')
+```
+
+### ❌ DON'T: вычисления в компоненте без мемоизации
+
+```js
+// ❌ Фильтрация вызывается при КАЖДОМ рендере — новый массив → ререндер дочерних
+function ActiveCoupons() {
+  const coupons = useSelector((state) => state.coupons.items);
+  const active = coupons.filter((c) => c.active); // ❌ каждый раз новый массив
+  return <List items={active} />;
+}
+
+// ✅ С мемоизированным селектором — один и тот же массив если данные не менялись
+function ActiveCoupons() {
+  const active = useSelector(selectActiveCoupons);
+  return <List items={active} />;
+}
+```
+
+---
+
+## 6. RTK Query
+
+### ✅ DO: RTK Query для server state
+
+```js
+// features/api/apiSlice.js
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';
+
+export const apiSlice = createApi({
+  reducerPath: 'api',
+  baseQuery: fetchBaseQuery({ baseUrl: '/api' }),
+  tagTypes: ['Coupon', 'Template'],
+  endpoints: (builder) => ({
+
+    /**
+     * Получить все купоны.
+     */
+    getCoupons: builder.query({
+      query: () => '/coupons',
+      providesTags: (result) =>
+        result
+          ? [
+              ...result.map(({ id }) => ({ type: 'Coupon', id })),
+              { type: 'Coupon', id: 'LIST' },
+            ]
+          : [{ type: 'Coupon', id: 'LIST' }],
+    }),
+
+    /**
+     * Создать новый купон.
+     */
+    addCoupon: builder.mutation({
+      query: (coupon) => ({
+        url: '/coupons',
+        method: 'POST',
+        body: coupon,
+      }),
+      invalidatesTags: [{ type: 'Coupon', id: 'LIST' }],
+    }),
+
+    /**
+     * Удалить купон.
+     */
+    deleteCoupon: builder.mutation({
+      query: (id) => ({
+        url: `/coupons/${id}`,
+        method: 'DELETE',
+      }),
+      invalidatesTags: (_, __, id) => [
+        { type: 'Coupon', id },
+        { type: 'Coupon', id: 'LIST' },
+      ],
+    }),
+  }),
+});
+
+export const {
+  useGetCouponsQuery,
+  useAddCouponMutation,
+  useDeleteCouponMutation,
+} = apiSlice;
+```
+
+### Использование в компоненте
+
+```jsx
+function CouponList() {
+  const { data: coupons, isLoading, error } = useGetCouponsQuery();
+  const [deleteCoupon] = useDeleteCouponMutation();
+
+  if (isLoading) return <Spinner />;
+  if (error) return <Error message={error.message} />;
+
+  return (
+    <ul>
+      {coupons.map((c) => (
+        <li key={c.id}>
+          {c.code} — {c.discount}%
+          <button onClick={() => deleteCoupon(c.id)}>Delete</button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+## 7. TypeScript
+
+### ✅ DO: типизированные hooks
+
+```ts
+// app/hooks.ts
+import { useDispatch, useSelector } from 'react-redux';
+import type { AppDispatch, RootState } from './store';
+
+export const useAppDispatch = useDispatch.withTypes<AppDispatch>();
+export const useAppSelector = useSelector.withTypes<RootState>();
+```
+
+### ✅ DO: типизированный store
+
+```ts
+// app/store.ts
+import { configureStore } from '@reduxjs/toolkit';
+import couponsReducer from '../features/coupons/couponsSlice';
+import { apiSlice } from '../features/api/apiSlice';
+
+export const store = configureStore({
+  reducer: {
+    coupons: couponsReducer,
+    [apiSlice.reducerPath]: apiSlice.reducer,
+  },
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware().concat(apiSlice.middleware),
+});
+
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;
+```
+
+### ✅ DO: типизированный slice
+
+```ts
+interface CouponState {
+  items: Coupon[];
+  selectedId: string | null;
+  status: 'idle' | 'loading' | 'succeeded' | 'failed';
+  error: string | null;
+}
+
+const initialState: CouponState = {
+  items: [],
+  selectedId: null,
+  status: 'idle',
+  error: null,
+};
+
+const couponsSlice = createSlice({
+  name: 'coupons',
+  initialState,
+  reducers: {
+    couponSelected(state, action: PayloadAction<string>) {
+      state.selectedId = action.payload;
+    },
+  },
+});
+```
+
+---
+
+## 8. Тестирование
+
+### ✅ DO: тестировать reducer напрямую
+
+```js
+import { describe, it, expect } from 'vitest';
+import reducer, { couponSelected, couponDeactivated, couponsReset } from './couponsSlice';
+
+describe('couponsSlice reducer', () => {
+  const initialState = { items: [], selectedId: null, status: 'idle', error: null };
+
+  it('should return initial state', () => {
+    expect(reducer(undefined, { type: 'unknown' })).toEqual(initialState);
+  });
+
+  it('should select coupon', () => {
+    const state = reducer(initialState, couponSelected('c-1'));
+    expect(state.selectedId).toBe('c-1');
+  });
+
+  it('should deactivate coupon by id', () => {
+    const state = {
+      ...initialState,
+      items: [{ id: 'c-1', code: 'X', active: true }],
+    };
+
+    const next = reducer(state, couponDeactivated('c-1'));
+    expect(next.items[0].active).toBe(false);
+  });
+
+  it('should reset to initial state', () => {
+    const dirty = { items: [{ id: '1' }], selectedId: '1', status: 'failed', error: 'err' };
+    expect(reducer(dirty, couponsReset())).toEqual(initialState);
+  });
+});
+```
+
+### ✅ DO: тестировать async thunks
+
+```js
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { configureStore } from '@reduxjs/toolkit';
+import reducer, { fetchCoupons } from './couponsSlice';
+
+describe('fetchCoupons thunk', () => {
+  let store;
+
+  beforeEach(() => {
+    store = configureStore({ reducer: { coupons: reducer } });
+    global.fetch = vi.fn();
+  });
+
+  it('should fetch and store coupons on success', async () => {
+    const mockCoupons = [{ id: '1', code: 'A', active: true }];
+    fetch.mockResolvedValue({ ok: true, json: () => Promise.resolve(mockCoupons) });
+
+    await store.dispatch(fetchCoupons());
+
+    const state = store.getState().coupons;
+    expect(state.status).toBe('succeeded');
+    expect(state.items).toEqual(mockCoupons);
+    expect(state.error).toBeNull();
+  });
+
+  it('should set error on failure', async () => {
+    fetch.mockResolvedValue({ ok: false, status: 500 });
+
+    await store.dispatch(fetchCoupons());
+
+    const state = store.getState().coupons;
+    expect(state.status).toBe('failed');
+    expect(state.error).toMatch(/500/);
+  });
+});
+```
+
+### ✅ DO: тестировать селекторы
+
+```js
+import { selectActiveCoupons, selectCouponStats } from './couponsSelectors';
+
+describe('coupon selectors', () => {
+  const state = {
+    coupons: {
+      ids: ['1', '2', '3'],
+      entities: {
+        '1': { id: '1', code: 'A', active: true, discount: 10 },
+        '2': { id: '2', code: 'B', active: false, discount: 20 },
+        '3': { id: '3', code: 'C', active: true, discount: 15 },
+      },
+    },
+  };
+
+  it('should select only active coupons', () => {
+    const active = selectActiveCoupons(state);
+    expect(active).toHaveLength(2);
+    expect(active.every((c) => c.active)).toBe(true);
+  });
+
+  it('should compute stats', () => {
+    const stats = selectCouponStats(state);
+    expect(stats).toEqual({ total: 3, active: 2, inactive: 1, totalDiscount: 45 });
+  });
+});
+```
+
+---
+
+## 9. Anti-patterns
+
+### ❌ DON'T: мутировать state вне createSlice
+
+```js
+// ❌ Мутация вне Immer — баг
+const newState = state;
+newState.items.push(item); // мутация оригинала!
+
+// ✅ Мутация только внутри createSlice reducers (Immer обёрнут)
+reducers: {
+  itemAdded(state, action) {
+    state.items.push(action.payload); // ✅ OK — Immer proxy
+  },
+},
+```
+
+### ❌ DON'T: dispatch в render
+
+```jsx
+// ❌ Dispatch при каждом рендере — бесконечный цикл
+function CouponList() {
+  const dispatch = useDispatch();
+  dispatch(fetchCoupons()); // ❌ каждый рендер
+
+  // ✅ Правильно:
+  useEffect(() => {
+    dispatch(fetchCoupons());
+  }, [dispatch]);
+}
+```
+
+### ❌ DON'T: хранить не-сериализуемые данные в state
+
+```js
+// ❌ Date, Map, Set, Class instances, Functions — не сериализуемы
+const initialState = {
+  createdAt: new Date(),      // ❌ Date объект
+  cache: new Map(),           // ❌ Map
+  onClick: () => {},          // ❌ Function
+};
+
+// ✅ Только plain objects, arrays, primitives
+const initialState = {
+  createdAt: new Date().toISOString(),  // ✅ string
+  cache: {},                             // ✅ plain object
+};
+```
+
+### ❌ DON'T: вкладывать state глубже 3 уровней
+
+```js
+// ❌ Глубокая вложенность — даже с Immer тяжело читать
+state.orders[0].items[2].variants[0].price = 100;
+
+// ✅ Нормализовать через createEntityAdapter
+// orders: { ids, entities }
+// items:  { ids, entities }
+// variants: { ids, entities }
+```
+
+---
+
+## Краткая шпаргалка
+
+| Задача | Решение |
+|--------|---------|
+| Создать slice | `createSlice({ name, initialState, reducers, extraReducers })` |
+| Async операция | `createAsyncThunk('name', async (arg, { rejectWithValue }) => ...)` |
+| Нормализация | `createEntityAdapter()` → `getSelectors()` |
+| Мемоизация | `createSelector([inputs], output)` |
+| Server state | RTK Query: `createApi({ endpoints })` |
+| Типизация hooks | `useDispatch.withTypes<AppDispatch>()` |
+| Reset state | `return initialState` в reducer |
+| Тестирование | `reducer(state, action)`, `store.dispatch(thunk())`, `selector(state)` |
+
+---
+
+## См. также
+- `$state_zustand_beast_practices` — Zustand для простого client state
+- `$react_beast_practices` — React-специфичные паттерны
+- `$testing_strategy_js` — стратегия тестирования
+- `$es2025_beast_practices` — современный JavaScript