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).
2026-09-19 21:50:06 +03:00
parent 86dff94a02
commit 1b1a679827
63 changed files with 8477 additions and 187 deletions
@@ -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 });
+}
@@ -0,0 +1,206 @@
+import { create } from 'zustand';
+
+import type { GatewayGuild, GatewaySnapshot, GatewayUser } from '@/api/gateway';
+import type { Channel, GuildSummary, User } from '@/api/types';
+
+/**
+ * Снапшот реального времени (READY/RESUMED) живёт здесь, а не в TanStack
+ * Query: Query отвечает за REST-данные (профиль, настройки, сессии), Zustand —
+ * за состояние, которое приходит событиями шлюза.
+ */
+
+/** Сервер снапшота: сводка для рейки + каналы/роли для сайдбара. */
+export interface SessionGuild extends GuildSummary {
+  channels: Channel[];
+  my_nickname?: string;
+}
+
+interface SessionState {
+  user: GatewayUser | null;
+  guilds: SessionGuild[];
+  dmChannels: Channel[];
+  sessionId: string | null;
+  selectedGuildId: string | null;
+  selectedChannelId: string | null;
+
+  applyReady: (snapshot: GatewaySnapshot) => void;
+  /** RESUMED приходит без снапшота — обновляем только то, что пришло. */
+  applyResumed: (user: GatewayUser | null) => void;
+  setUser: (user: GatewayUser | null) => void;
+  /** Синхронизация с REST-профилем (PATCH /users/@me возвращает полного user). */
+  patchUser: (user: User) => void;
+  upsertGuild: (guild: GuildSummary) => void;
+  removeGuild: (guildId: string) => void;
+  setGuildChannels: (guildId: string, channels: Channel[]) => void;
+  upsertChannel: (guildId: string, channel: Channel) => void;
+  selectGuild: (guildId: string | null) => void;
+  selectChannel: (guildId: string | null, channelId: string | null) => void;
+  reset: () => void;
+}
+
+interface SessionDefaults {
+  user: null;
+  guilds: SessionGuild[];
+  dmChannels: Channel[];
+  sessionId: null;
+  selectedGuildId: null;
+  selectedChannelId: null;
+}
+
+const defaults: SessionDefaults = {
+  user: null,
+  guilds: [],
+  dmChannels: [],
+  sessionId: null,
+  selectedGuildId: null,
+  selectedChannelId: null,
+};
+
+function toSessionGuild(guild: GatewayGuild): SessionGuild {
+  const summary: SessionGuild = {
+    id: guild.id,
+    name: guild.name,
+    owner_id: guild.owner_id,
+    is_main: guild.is_main,
+    member_count: guild.member_ids.length,
+    my_role_ids: guild.my_role_ids,
+    my_permissions: guild.my_permissions ?? [],
+    channels: guild.channels,
+  };
+  if (guild.icon_file_id !== undefined) {
+    summary.icon_file_id = guild.icon_file_id;
+  }
+  if (guild.my_nickname !== undefined) {
+    summary.my_nickname = guild.my_nickname;
+  }
+  return summary;
+}
+
+export const useSessionStore = create<SessionState>((set, get) => ({
+  ...defaults,
+
+  applyReady: (snapshot) => {
+    const guilds = snapshot.guilds.map(toSessionGuild);
+    const previous = get();
+    // Сохраняем выбор пользователя, если он ещё существует в снапшоте.
+    const selectedGuildId =
+      previous.selectedGuildId !== null && guilds.some((g) => g.id === previous.selectedGuildId)
+        ? previous.selectedGuildId
+        : null;
+    const channels =
+      selectedGuildId === null
+        ? []
+        : (guilds.find((g) => g.id === selectedGuildId)?.channels ?? []);
+    const selectedChannelId =
+      previous.selectedChannelId !== null &&
+      channels.some((c) => c.id === previous.selectedChannelId)
+        ? previous.selectedChannelId
+        : null;
+    set({
+      user: snapshot.user,
+      guilds,
+      dmChannels: snapshot.dm_channels,
+      sessionId: snapshot.session_id,
+      selectedGuildId,
+      selectedChannelId,
+    });
+  },
+
+  applyResumed: (user) => {
+    if (user !== null) {
+      set({ user });
+    }
+  },
+
+  setUser: (user) => {
+    set({ user });
+  },
+
+  patchUser: (user) => {
+    // PATCH /users/@me возвращает полный профиль — переносим его в снапшот,
+    // сохраняя открытые шлюзом поля присутствия, если сервер их не вернул.
+    const current = get().user;
+    const next: GatewayUser = {
+      id: user.id,
+      username: user.username,
+      display_name: user.display_name,
+      is_instance_admin: user.is_instance_admin,
+      badges: user.badges,
+      status: user.status,
+      custom_status: user.custom_status,
+      custom_status_emoji: user.custom_status_emoji,
+    };
+    const avatar = user.avatar_file_id ?? current?.avatar_file_id;
+    if (avatar !== undefined) {
+      next.avatar_file_id = avatar;
+    }
+    set({ user: next });
+  },
+
+  upsertGuild: (guild) => {
+    const guilds = get().guilds;
+    const index = guilds.findIndex((item) => item.id === guild.id);
+    if (index === -1) {
+      set({ guilds: [...guilds, { ...guild, channels: [] }] });
+      return;
+    }
+    const existing = guilds[index];
+    if (existing === undefined) {
+      return;
+    }
+    const merged: SessionGuild = { ...existing, ...guild, channels: existing.channels };
+    const next = [...guilds];
+    next[index] = merged;
+    set({ guilds: next });
+  },
+
+  removeGuild: (guildId) => {
+    const state = get();
+    set({
+      guilds: state.guilds.filter((guild) => guild.id !== guildId),
+      selectedGuildId: state.selectedGuildId === guildId ? null : state.selectedGuildId,
+      selectedChannelId: state.selectedGuildId === guildId ? null : state.selectedChannelId,
+    });
+  },
+
+  setGuildChannels: (guildId, channels) => {
+    set({
+      guilds: get().guilds.map((guild) => (guild.id === guildId ? { ...guild, channels } : guild)),
+    });
+  },
+
+  upsertChannel: (guildId, channel) => {
+    set({
+      guilds: get().guilds.map((guild) => {
+        if (guild.id !== guildId) {
+          return guild;
+        }
+        const index = guild.channels.findIndex((item) => item.id === channel.id);
+        if (index === -1) {
+          return { ...guild, channels: [...guild.channels, channel] };
+        }
+        const channels = [...guild.channels];
+        channels[index] = channel;
+        return { ...guild, channels };
+      }),
+    });
+  },
+
+  selectGuild: (guildId) => {
+    set({ selectedGuildId: guildId, selectedChannelId: null });
+  },
+
+  selectChannel: (guildId, channelId) => {
+    set({ selectedGuildId: guildId, selectedChannelId: channelId });
+  },
+
+  reset: () => {
+    set({ ...defaults });
+  },
+}));
+
+/** Селектор сервера по id (без подписки на весь список). */
+export function selectGuildById(guildId: string | null) {
+  return (state: SessionState): SessionGuild | null =>
+    guildId === null ? null : (state.guilds.find((guild) => guild.id === guildId) ?? null);
+}