feat(api): ручки Фаз(ы) 1 — профиль, серверы, роли, админ инстанса

REST-слой Фазы 1 на huma (OpenAPI 3.1 генерируется из кода):

- профиль: GET/PATCH /users/@me, смена пароля со step-up, публичный профиль,
  завершение онбординга (новая миграция 00003 с onboarding_completed_at);
- серверы: создание/изменение/удаление, join/leave, список серверов
  пользователя, журнал действий;
- комнаты: список с учётом прав, создание/изменение/удаление;
- участники: список с профилями и ролями, никнейм, тайм-аут, исключение;
- роли: CRUD, выдача/снятие с проверкой иерархии и запретом выдачи прав выше
  собственных;
- админ инстанса: публичная информация, настройки, серверы, пользователи,
  аудит, выдача прав администратора со step-up; обход лимитов фиксируется в
  аудите отдельной записью limits.bypass;
- движок прав: участие в сервере стало обязательным условием (IsMember),
  не участник не получает прав роли @user; калькулятор прав общий для API и
  Gateway, инвалидация кэша после изменений;
- Gateway: браузерный клиент аутентифицируется cookie на рукопожатии, IDENTIFY
  без токена использует её; события GUILD/CHANNEL/MEMBER/ROLE рассылаются из
  ручек, USER_UPDATE — адресно;
- ошибки huma отдаются в едином конверте {"error":{"code","message"}}.

Тесты: 8 сценариев API (профиль, жизненный цикл сервера и права, лимиты и
обход админом, иерархия ролей, тайм-аут, скрытие комнаты оверрайдом,
членство в движке прав, cookie-идентификация Gateway).

web/src/stores/gateway.ts

@@ -0,0 +1,147 @@
+import { create } from 'zustand';
+
+import {
+  connectGateway,
+  disconnectGateway,
+  parseGatewaySnapshot,
+  type GatewayDispatch,
+  type GatewayStatus,
+  type GatewayUser,
+} from '@/api/gateway';
+import { useSessionStore } from '@/stores/session';
+
+/**
+ * Состояние соединения со шлюзом. Данные приходят в session-store,
+ * здесь — только транспорт: статус, heartbeat, resume и переподключение.
+ */
+interface GatewayState {
+  status: GatewayStatus;
+  heartbeatIntervalMs: number | null;
+  sessionId: string | null;
+  attempts: number;
+  /** Признак того, что после INVALID_SESSION нужно уйти на /login. */
+  invalidated: boolean;
+  connect: (userId: string) => void;
+  disconnect: () => void;
+  reset: () => void;
+}
+
+const defaults = {
+  status: 'idle' as GatewayStatus,
+  heartbeatIntervalMs: null,
+  sessionId: null,
+  attempts: 0,
+  invalidated: false,
+};
+
+export const useGatewayStore = create<GatewayState>((set, get) => ({
+  ...defaults,
+
+  connect: (userId) => {
+    if (get().status !== 'idle') {
+      return;
+    }
+    // userId пока не уходит на сервер (аутентификация — cookie на рукопожатии),
+    // но фиксирует, что снапшот принадлежит именно этому пользователю.
+    void userId;
+    connectGateway({
+      handlers: {
+        onStatus: (status) => {
+          set({
+            status,
+            attempts: status === 'reconnecting' ? get().attempts + 1 : get().attempts,
+          });
+        },
+        onInvalidSession: () => {
+          set({ invalidated: true, status: 'disconnected' });
+          useSessionStore.getState().reset();
+          void invalidateCurrentUser();
+        },
+        onResumeIncomplete: () => {
+          // Сервер не прислал снапшот — перечитываем профиль по REST.
+          void refetchCurrentUser();
+        },
+        onDispatch: (event) => {
+          dispatchGatewayEvent(event);
+        },
+      },
+    });
+  },
+
+  disconnect: () => {
+    disconnectGateway();
+    set({ ...defaults });
+  },
+
+  reset: () => {
+    disconnectGateway();
+    set({ ...defaults });
+  },
+}));
+
+/** Разбор события DISPATCH: в Фазе 1 обрабатываем READY/RESUMED, остальные — в диспетчер. */
+export function dispatchGatewayEvent(event: GatewayDispatch): void {
+  const session = useSessionStore.getState();
+  switch (event.t) {
+    case 'READY': {
+      const snapshot = parseGatewaySnapshot(event.d);
+      if (snapshot === null) {
+        return;
+      }
+      session.applyReady(snapshot);
+      useGatewayStore.setState({
+        status: 'connected',
+        heartbeatIntervalMs: snapshot.heartbeat_interval_ms,
+        sessionId: snapshot.session_id,
+        attempts: 0,
+      });
+      return;
+    }
+    case 'RESUMED': {
+      const user = parseResumedUser(event.d);
+      session.applyResumed(user);
+      useGatewayStore.setState({ status: 'connected', attempts: 0 });
+      return;
+    }
+    // Заготовка диспетчера Фазы 2: события приходят, но пока не меняют UI.
+    case 'GUILD_CREATE':
+    case 'GUILD_UPDATE':
+    case 'GUILD_DELETE':
+    case 'CHANNEL_CREATE':
+    case 'CHANNEL_UPDATE':
+    case 'CHANNEL_DELETE':
+    case 'MEMBER_UPDATE':
+    case 'PRESENCE_UPDATE':
+      return;
+    default:
+      // Неизвестные события игнорируем: контракт может расширяться.
+      return;
+  }
+}
+
+function parseResumedUser(payload: unknown): GatewayUser | null {
+  if (typeof payload !== 'object' || payload === null) {
+    return null;
+  }
+  const user = (payload as { user?: unknown }).user;
+  const snapshot = parseGatewaySnapshot({ user, guilds: [] });
+  return snapshot === null ? null : snapshot.user;
+}
+
+/** Ленивые импорты разрывают цикл «стор → query-client → стор». */
+async function invalidateCurrentUser(): Promise<void> {
+  const [{ getQueryClient }, { currentUserQueryKey }] = await Promise.all([
+    import('@/lib/queryClient'),
+    import('@/api/users'),
+  ]);
+  // removeQueries вместо invalidate: сессия мертва, повторный запрос не нужен.
+  getQueryClient().removeQueries({ queryKey: currentUserQueryKey });
+}
+
+async function refetchCurrentUser(): Promise<void> {
+  const [{ getQueryClient }, { currentUserQueryKey }] = await Promise.all([
+    import('@/lib/queryClient'),
+    import('@/api/users'),
+  ]);
+  await getQueryClient().invalidateQueries({ queryKey: currentUserQueryKey });
+}