Directual + NextJS

AI-Ready Documentation: Универсальный шаблон для создания полноценного Next.js приложения с интеграцией Directual (авторизация, WebSocket, API endpoints)

📋 Обзор

Этот шаблон описывает архитектуру современного веб-приложения на Next.js 16+ с App Router, интегрированного с бэкендом Directual. Включает безопасную авторизацию через HTTP-only cookies, WebSocket для real-time обновлений, глобальное управление состоянием и адаптивную тему.

Стек технологий:

• Next.js 16+ (App Router)

• TypeScript

• Tailwind CSS

• shadcn/ui (компоненты)

• Directual (бэкенд: auth, API, WebSocket)

• socket.io-client (WebSocket)

---

🏗️ Архитектурные принципы

1. Безопасность сессии

• HTTP-only cookie для хранения sessionID (защита от XSS атак)

• SessionID НЕ хранится в localStorage или клиентском state

• API Routes в Next.js служат прокси для авторизации

• Периодическая проверка сессии через /api/auth/check

2. Разделение клиентов Directual

• Клиентский: через Next.js rewrites (apiHost: '/') для обхода CORS

• Серверный: прямое подключение к api.directual.com для API Routes

3. Глобальное управление состоянием

Иерархия провайдеров (от внешнего к внутреннему):

ThemeProvider → AuthProvider → DataProvider → App

4. WebSocket интеграция

• Singleton pattern для socket.io-client

• Подключение после получения sessionID из HTTP-only cookie

• Глобальный слушатель событий для real-time обновлений

• Важно: только прием событий, отправка не поддерживается Directual

---

📁 Структура проекта

project-root/
├── app/
│   ├── api/
│   │   └── auth/
│   │       ├── login/route.ts       # POST: авторизация + установка cookie
│   │       ├── register/route.ts    # POST: регистрация + установка cookie
│   │       ├── logout/route.ts      # POST: удаление cookie
│   │       ├── check/route.ts       # GET: проверка сессии
│   │       └── session/route.ts     # GET: получение sessionID для WebSocket
│   ├── layout.tsx                   # Root layout с провайдерами
│   ├── globals.css                  # CSS переменные для темы
│   └── page.tsx                     # Home page
│
├── components/
│   ├── ui/                          # shadcn/ui компоненты
│   ├── global-alerts.tsx            # Глобальные уведомления (из WebSocket)
│   └── socket-listener.tsx          # Глобальный слушатель WebSocket
│
├── context/
│   ├── auth-provider.tsx            # Контекст авторизации
│   ├── data-provider.tsx            # Контекст данных (глобальный кеш)
│   └── theme-provider.tsx           # Контекст темы (light/dark/system)
│
├── hooks/
│   ├── use-auth.ts                  # Хук для авторизации (реэкспорт)
│   ├── use-data.ts                  # Хук для данных (реэкспорт)
│   └── use-socket.ts                # Хуки для WebSocket
│
├── lib/
│   └── directual/
│       ├── client.ts                # Клиентский Directual API
│       ├── server-client.ts         # Серверный Directual API
│       ├── auth.ts                  # Функции авторизации
│       ├── fetcher.ts               # Универсальный fetcher
│       └── socket.ts                # WebSocket singleton
│
├── types/
│   ├── directual.d.ts               # Типы для directual-api
│   └── index.ts                     # Общие типы приложения
│
├── .env.local                       # Переменные окружения
├── next.config.mjs                  # Конфигурация Next.js (rewrites, headers)
├── tailwind.config.js               # Конфигурация Tailwind
└── package.json

---

🔐 Безопасная авторизация

Концепция

SessionID хранится в HTTP-only cookie, недоступной для JavaScript на клиенте. Все операции с сессией проходят через API Routes.

API Routes

1. /api/auth/login (POST)

• Принимает: { email, password }

• Вызывает: serverApi.auth.login()

• Возвращает: { success, user }

• Устанавливает cookie: 1cable_session (httpOnly, secure, sameSite: strict, maxAge: 7 дней)

2. /api/auth/register (POST)

• Принимает: { email, password, username }

• Вызывает: serverApi.auth.register()

• Возвращает: { success, user }

• Устанавливает cookie: аналогично login

3. /api/auth/logout (POST)

• Читает cookie 1cable_session

• Вызывает: serverApi.auth.logout(sessionID)

• Удаляет cookie (maxAge: 0)

• Возвращает: { success }

4. /api/auth/check (GET)

• Читает cookie 1cable_session

• Вызывает: serverApi.auth.check(sessionID)

• Возвращает: { success, user } или 401

• При ошибке удаляет cookie

5. /api/auth/session (GET)

• Читает cookie 1cable_session

• Возвращает: { success, sessionID }

• Используется WebSocket для авторизации

AuthProvider (context/auth-provider.tsx)

State:

• user: User | null - текущий пользователь

• loading: boolean - загрузка

• error: string | null - ошибка

Методы:

• login(email, password) - вход через /api/auth/login

• register(email, password, username) - регистрация через /api/auth/register

• logout() - выход через /api/auth/logout

• isAuthorized() - проверка авторизации

• hasRole(role) - проверка роли (RBAC)

Lifecycle:

• При монтировании вызывает /api/auth/check для проверки сессии

---

🔌 Directual клиенты

lib/directual/client.ts (клиентский)

import Directual from 'directual-api';

export const APP_ID = process.env.NEXT_PUBLIC_DIRECTUAL_APP_ID;

const api = new Directual({ 
  apiHost: '/',  // Используем rewrites
  appID: APP_ID
});

export default api;

lib/directual/server-client.ts (серверный)

import Directual from 'directual-api';

export const APP_ID = process.env.NEXT_PUBLIC_DIRECTUAL_APP_ID;

const serverApi = new Directual({ 
  apiHost: 'https://api.directual.com',  // Прямое подключение
  appID: APP_ID
});

export default serverApi;

next.config.mjs (rewrites)

async rewrites() {
  return [
    {
      source: '/good/:path*',
      destination: 'https://api.directual.com/good/:path*',
    },
  ];
}

Почему два клиента?

• Клиентский использует rewrites для обхода CORS

• Серверный используется в API Routes, где CORS не проблема

---

📡 Универсальный Fetcher

lib/directual/fetcher.ts

Класс Fetcher - обертка над directual-api с дополнительными фичами:

Ключевые возможности:

1. Кеширование sessionID - избегает множественных вызовов /api/auth/session

2. Обработка ошибок - унифицированная обработка ошибок API

3. Загрузка файлов - с отслеживанием прогресса

4. Универсальные методы - get(), post(), специфичные методы для структур

Методы:

class Fetcher {
  // Получить sessionID из cookie (с кешированием)
  async getSessionID(): Promise<string | null>
  
  // Очистить кеш sessionID
  clearSessionCache(): void
  
  // Универсальный GET
  async get<T>(structure: string, endpoint: string, params?): Promise<GetResponse<T>>
  
  // Универсальный POST
  async post<T>(structure: string, endpoint: string, payload?, params?): Promise<PostResponse<T>>
  
  // Загрузка файлов с прогрессом
  async uploadFile(file: File, onProgress?: (percent) => void): Promise<PostResponse<{urlLink: string}>>
  
  // Специфичные методы для вашего приложения (примеры):
  async checkSession(params?): Promise<GetResponse>
  async readProfile(params?): Promise<GetResponse<UserProfile>>
  async updateProfile(payload, params?): Promise<PostResponse>
  
  // Добавьте методы для ваших структур данных:
  // async getYourEntities(params?): Promise<GetResponse<YourEntity>>
  // async createYourEntity(payload, params?): Promise<PostResponse>
}

export const fetcher = new Fetcher();

Обработка ошибок:

// При ошибке API возвращаем структурированный объект
catch (error: unknown) {
  const err = error as { response?: { data?: { msg?: string } }; message?: string };
  return {
    success: false,
    error: err.response?.data?.msg || err.message || 'Ошибка запроса',
  };
}

Важно: 403 ошибки могут означать не только истечение сессии, но и ограничения по ролям (RBAC). Не рекомендуется автоматически разлогинивать пользователя при 403 - лучше показывать сообщение о недостаточных правах.

---

🌐 WebSocket интеграция

lib/directual/socket.ts

Singleton pattern для socket.io-client:

class DirectualSocket {
  private socket: Socket;
  private isConnectedFlag: boolean;

  constructor() {
    this.socket = io('https://api.directual.com', { autoConnect: false });
  }

  // Получить sessionID из cookie через API
  async getSessionID(): Promise<string | null>

  // Подключиться (async - ждет sessionID)
  async connect(): Promise<boolean>

  // Отключиться
  disconnect(): void

  // Подписаться на событие
  on(eventName: string, callback: (...args) => void): void

  // Отписаться от события
  off(eventName: string, callback?: (...args) => void): void

  // Подписаться на ВСЕ события (дебаг)
  onAny(callback: (eventName, args) => void): void

  // Статус подключения
  getStatus(): { isConnected: boolean; socketId: string | null }
  get isConnected(): boolean
}

export const getSocket = (): DirectualSocket => {
  if (!socketInstance) {
    socketInstance = new DirectualSocket();
  }
  return socketInstance;
};

Авторизация WebSocket:

this.socket.auth = {
  app_id: APP_ID,
  session_id: sessionID,  // Получен из /api/auth/session
};
this.socket.connect();

Важно: Directual WebSocket работает только на прием событий. Вы можете подписываться на события и получать их, но отправка событий в Directual НЕ поддерживается. Все изменения данных делайте через HTTP API (Fetcher).

hooks/use-socket.ts

Хуки для работы с WebSocket в React:

// Получить socket инстанс
export function useSocket(): { socket, isConnected }

// Подписаться на конкретное событие (основной хук)
export function useSocketEvent(eventName: string, callback: (...args) => void)

Примечание: Хук useSocketEmit НЕ нужен, так как Directual WebSocket не принимает события от клиента. Все изменения данных делайте через HTTP API.

components/socket-listener.tsx

Глобальный слушатель для всего приложения:

• Подключается к WebSocket при монтировании

• Логирует все события в консоль

• Обрабатывает специальные события (например, alert)

• Рендерит null (невидимый компонент)

Пример обработки события alert:

if (eventName === 'alert') {
  let alertData = args[0];
  if (Array.isArray(alertData)) alertData = alertData[0];
  if (typeof alertData === 'string') alertData = JSON.parse(alertData);
  
  if (window.__showGlobalAlert) {
    window.__showGlobalAlert(alertData);
  }
}

---

📦 Глобальное управление данными

context/data-provider.tsx

DataProvider - глобальный кеш данных приложения с автоматическим обновлением.

Концепция: Храним в контексте те данные, которые нужны во многих местах приложения (профиль пользователя, настройки, списки сущностей и т.д.). Это избавляет от повторных запросов и обеспечивает консистентность данных.

Структура State:

• userProfile: UserProfile | null - профиль текущего пользователя

• settings: Record<string, unknown> | null - настройки приложения

• [yourEntityList]: YourEntity[] - списки ваших сущностей (адаптируйте под проект)

• loading: boolean - первоначальная загрузка

• refreshing: boolean - фоновое обновление данных

• error: string | null - ошибка загрузки

Методы:

• refreshProfile(silent?) - обновить профиль пользователя

• refreshSettings(silent?) - обновить настройки

• refreshYourEntity(silent?) - обновить вашу сущность (адаптируйте)

• refreshAll(silent?) - обновить все данные

• updateProfile(profileData) - обновить профиль

Автоматическое обновление:

1. При монтировании (если isAuthorized())

2. При WebSocket событиях: refresh, entity_created, entity_updated, entity_deleted

3. При возврате на вкладку браузера (visibilitychange)

Silent refresh:

• silent=true - обновление без loading индикатора

• Используется для фоновых обновлений (WebSocket, visibilitychange)

Пример использования:

const { userProfile, settings, loading, refreshAll } = useData();

Адаптация под проект: Замените примеры методов на ваши сущности. Принцип остается тот же - централизованное хранилище данных с автоматической синхронизацией через WebSocket.

---

📤 Загрузка файлов

Настройка структуры в Directual

Обязательный шаг: Создайте структуру данных file_links в Directual:

1. Создайте структуру с именем file_links

2. Добавьте поле link с типом FileUpload

3. Настройте права доступа:

   • Write: разрешите запись для авторизованных пользователей

   • Read: настройте по необходимости

4. Создайте эндпоинт uploadFiles (POST) для загрузки файлов

Структура поля:

Название структуры: file_links
Поле: link
Тип: FileUpload
Доступ на запись: ✅ Enabled

Метод uploadFile в Fetcher

Fetcher включает специальный метод для загрузки файлов на Directual с отслеживанием прогресса.

Сигнатура:

async uploadFile(
  file: File, 
  onProgress?: (percent: number) => void
): Promise<PostResponse<{ urlLink: string }>>

Механизм работы:

1. FormData - файл оборачивается в FormData для multipart/form-data

2. Прокси через rewrites - используется /good/api/v5/data/file_links/uploadFiles

3. SessionID из cookie - автоматически добавляется в query параметры

4. XMLHttpRequest - для отслеживания прогресса (если передан onProgress)

5. Fallback на fetch - если onProgress не нужен

Структура запроса:

POST /good/api/v5/data/file_links/uploadFiles?appID={APP_ID}&sessionID={sessionID}
Content-Type: multipart/form-data
Body: FormData с файлом

Пример использования:

const handleFileUpload = async (file: File) => {
  const [progress, setProgress] = useState(0);
  
  const result = await fetcher.uploadFile(file, (percent) => {
    setProgress(percent); // Обновляем прогресс-бар
  });
  
  if (result.success && result.data) {
    const fileUrl = result.data.urlLink; // URL загруженного файла
    console.log('Файл загружен:', fileUrl);
  } else {
    console.error('Ошибка загрузки:', result.error);
  }
};

Компонент с прогресс-баром:

import { useState } from 'react';
import { Progress } from '@/components/ui/progress';
import { Button } from '@/components/ui/button';
import { fetcher } from '@/lib/directual/fetcher';

function FileUploader() {
  const [uploading, setUploading] = useState(false);
  const [progress, setProgress] = useState(0);

  const handleChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    setUploading(true);
    setProgress(0);

    const result = await fetcher.uploadFile(file, (percent) => {
      setProgress(Math.round(percent));
    });

    if (result.success && result.data) {
      console.log('URL файла:', result.data.urlLink);
      // Сохраните URL в вашу структуру данных
    }

    setUploading(false);
  };

  return (
    <div>
      <input 
        type="file" 
        onChange={handleChange} 
        disabled={uploading}
      />
      {uploading && (
        <div>
          <Progress value={progress} />
          <p>{progress}%</p>
        </div>
      )}
    </div>
  );
}

Важные детали:

1. credentials: 'include' - обязательно для отправки cookie с sessionID

2. XMLHttpRequest.upload.progress - используется для отслеживания прогресса

3. Обработка 403 - если сессия невалидна, вернется ошибка

4. Возвращаемый объект - { urlLink: string } - прямая ссылка на файл в Directual

Структура ответа от Directual:

{
  "result": {
    "urlLink": "https://api.directual.com/fileUploaded/...",
    "fileName": "example.jpg",
    "fileSize": 102400,
    "fileType": "image/jpeg"
  }
}

Рекомендации:

• ⚠️ Обязательно создайте структуру file_links с полем link (FileUpload) в Directual

• Проверяйте размер файла на клиенте перед загрузкой

• Показывайте прогресс для файлов > 1MB

• Добавьте валидацию типов файлов (MIME types)

• Обрабатывайте ошибки сети (abort, timeout)

• Настройте права доступа на запись для структуры file_links

---

🎯 Паттерн работы с Directual

Рекомендуемый подход: Single Action Endpoint

Концепция: Все действия пользователя с фронтенда отправляются в один универсальный эндпоинт (например, user_actions). Directual сценарий анализирует тип действия и возвращает результат либо синхронно, либо через WebSocket.

Преимущества:

• ✅ Единая точка входа для всех действий

• ✅ Легко логировать и анализировать действия пользователей

• ✅ Гибкость в обработке (синхронный или асинхронный ответ)

• ✅ Простота добавления новых действий без изменения API

Структура запроса

interface UserAction {
  action: string;              // Тип действия: 'create_entity', 'update_settings', etc.
  payload?: Record<string, unknown>;  // Данные действия
  [key: string]: unknown;      // Дополнительные параметры
}

Пример использования

// В Fetcher добавляем метод
async postAction(payload: UserAction, params = {}): Promise<PostResponse> {
  return this.post('user_actions', 'postUserAction', payload, params);
}

// Использование в компоненте
const createEntity = async (entityData) => {
  const result = await fetcher.postAction({
    action: 'create_entity',
    payload: entityData
  });
  
  if (result.success) {
    // Либо результат пришел синхронно в result.data
    // Либо придет через WebSocket событие 'entity_created'
  }
};

Обработка в Directual

Сценарий в эндпоинте postUserAction:

1. Читаем action из запроса

2. Switch/case по типу действия

3. Выполняем бизнес-логику

4. Возвращаем результат:

   • Синхронно: return result (быстрые операции)

   • Асинхронно: отправляем WebSocket событие (долгие операции)

Пример структуры:

postUserAction:
  ├─ IF action = 'create_entity'
  │   ├─ Создать запись
  │   ├─ Отправить WebSocket: 'entity_created'
  │   └─ Return { success: true }
  │
  ├─ IF action = 'update_settings'
  │   ├─ Обновить настройки
  │   └─ Return { success: true, data: newSettings }
  │
  └─ ELSE
      └─ Return { success: false, error: 'Unknown action' }

WebSocket события для ответов

Для асинхронных операций отправляйте WebSocket события:

• entity_created → DataProvider обновляет список

• entity_updated → DataProvider обновляет список

• entity_deleted → DataProvider обновляет список

• alert → GlobalAlerts показывает уведомление

• progress → Индикатор прогресса (для долгих операций)

Когда использовать синхронный vs асинхронный ответ

Синхронный (return result):

• Быстрые операции (< 1 сек)

• Когда нужен немедленный ответ для UI

• Операции чтения (GET)

• Обновление профиля, настроек

Асинхронный (WebSocket):

• Долгие операции (> 1 сек)

• Когда результат нужен не сразу

• Операции, влияющие на других пользователей

• Создание/удаление сущностей

• Фоновые задачи

---

🎨 Система темизации

context/theme-provider.tsx

ThemeProvider - управление темой приложения.

State:

• theme: 'light' | 'dark' | 'system' - выбранная тема

• actualTheme: 'light' | 'dark' - реальная применяемая тема

• mounted: boolean - флаг монтирования

Методы:

• setTheme(theme) - установить тему

• toggleTheme() - переключить light ↔ dark

• isDark, isLight, isSystem - утилиты проверки

Механизм работы:

1. Тема хранится в localStorage.theme

2. Применяется через класс light или dark на <html>

3. При system слушает prefers-color-scheme media query

4. При изменении системной темы автоматически переключается

CSS переменные (app/globals.css):

:root {
  --background: #ffffff;
  --foreground: #000000;
  --primary: #...;
  /* ... */
}

.dark {
  --background: #000000;
  --foreground: #ffffff;
  --primary: #...;
  /* ... */
}

tailwind.config.js

module.exports = {
  darkMode: ["class"],  // Используем class-based режим
  theme: {
    extend: {
      colors: {
        background: "var(--background)",
        foreground: "var(--foreground)",
        primary: {
          DEFAULT: "var(--primary)",
          foreground: "var(--primary-foreground)",
        },
        // ...
      },
    },
  },
};

---

🔒 Security Headers

next.config.mjs

Обязательные security headers:

async headers() {
  return [
    {
      source: '/:path*',
      headers: [
        {
          key: 'X-Frame-Options',
          value: 'DENY',  // Защита от clickjacking
        },
        {
          key: 'X-Content-Type-Options',
          value: 'nosniff',  // MIME sniffing защита
        },
        {
          key: 'X-XSS-Protection',
          value: '1; mode=block',  // XSS фильтр браузера
        },
        {
          key: 'Referrer-Policy',
          value: 'strict-origin-when-cross-origin',
        },
        {
          key: 'Permissions-Policy',
          value: 'camera=(), microphone=(), geolocation=()',
        },
        {
          key: 'Content-Security-Policy',
          value: [
            "default-src 'self'",
            "script-src 'self' 'unsafe-inline' 'unsafe-eval'",
            "style-src 'self' 'unsafe-inline'",
            "img-src 'self' data: https:",
            "connect-src 'self' https://api.directual.com wss://api.directual.com",
            "frame-ancestors 'none'",
          ].join('; '),
        },
      ],
    },
  ];
}

Важно:

• unsafe-eval может потребоваться для CodeMirror или других редакторов

• connect-src должен включать Directual API и WebSocket

• frame-ancestors 'none' запрещает iframe embedding

---

📝 Типизация TypeScript

types/index.ts

Базовые типы:

// API Response
export interface ApiResponse<T = unknown> {
  success: boolean;
  data?: T;
  error?: string;
  pageInfo?: PageInfo | null;
  status?: string | null;
}

export interface PageInfo {
  page: number;
  pageSize: number;
  totalPages: number;
}

// User
export interface User {
  id: string;
  email: string;
  username: string;
  role: string;
  avatar: string | null;
}

export interface UserProfile {
  id: string;
  firstName: string;
  lastName: string;
  userpic: string;
  email?: string;
  username?: string;
}

// Auth Context
export interface AuthContextValue {
  user: User | null;
  sessionID: string | null;  // Всегда null на клиенте
  loading: boolean;
  error: string | null;
  login: (email: string, password: string) => Promise<ApiResponse<User>>;
  register: (email: string, password: string, username: string) => Promise<ApiResponse<User>>;
  logout: () => Promise<void>;
  isAuthorized: () => boolean;
  hasRole: (role: string) => boolean;
}

// Data Context (адаптируйте под свои сущности)
export interface DataContextValue {
  userProfile: UserProfile | null;
  settings: Record<string, unknown> | null;
  // Добавьте ваши сущности:
  // entities: YourEntity[];
  loading: boolean;
  refreshing: boolean;
  error: string | null;
  refreshProfile: (silent?: boolean) => Promise<void>;
  refreshSettings: (silent?: boolean) => Promise<void>;
  // Добавьте методы для ваших сущностей:
  // refreshEntities: (silent?: boolean) => Promise<void>;
  refreshAll: (silent?: boolean) => Promise<void>;
  updateProfile: (profileData: Partial<UserProfile>) => Promise<ApiResponse<void>>;
}

// Theme
export type Theme = 'light' | 'dark' | 'system';

// WebSocket
export type SocketEventCallback = (...args: unknown[]) => void;

export interface UseSocketResult {
  connected: boolean;
  error: string | null;
  emit: (event: string, data?: unknown) => void;
}

types/directual.d.ts

Расширение типов для directual-api:

declare module 'directual-api' {
  export default class Directual {
    constructor(config: { apiHost: string; appID: string });
    
    auth: {
      login(email: string, password: string): Promise<Token>;
      register(email: string, password: string, data: any): Promise<Token>;
      logout(sessionID: string): Promise<void>;
      check(sessionID: string): Promise<Token>;
    };
    
    structure(name: string): {
      getData(endpoint: string, params?: any): Promise<{ payload: any[]; pageInfo?: any }>;
      setData(endpoint: string, payload: any, params?: any): Promise<any>;
    };
  }
  
  export interface Token {
    sessionID: string;
    username: string;
    role: string;
    nid?: string;
  }
}

---

🚀 Root Layout

app/layout.tsx

Структура провайдеров:

export default function RootLayout({ children }) {
  return (
    <html lang="ru" suppressHydrationWarning>
      <body>
        <ThemeProvider>
          <AuthProvider>
            <DataProvider>
              {/* Глобальный WebSocket слушатель */}
              <SocketListener />
              
              {/* Глобальные алерты из WebSocket */}
              <GlobalAlerts />
              
              {children}
            </DataProvider>
          </AuthProvider>
        </ThemeProvider>
      </body>
    </html>
  );
}

Важно:

• suppressHydrationWarning - для темы (класс меняется до hydration)

• Порядок провайдеров: Theme → Auth → Data

• SocketListener и GlobalAlerts монтируются глобально

---

🎯 Глобальные алерты

components/global-alerts.tsx

Механизм:

1. WebSocket отправляет событие alert с данными

2. SocketListener перехватывает и вызывает window.__showGlobalAlert()

3. GlobalAlerts отображает toast-уведомление

Структура алерта:

interface AlertData {
  type?: 'success' | 'error' | 'default';
  variant?: 'success' | 'destructive' | 'default';
  title?: string;
  description?: string;  // Может содержать HTML
  icon?: string;  // Имя иконки из lucide-react
}

Фичи:

• Автоматическое скрытие через 5 секунд

• Дедупликация (один и тот же алерт не показывается дважды)

• Ручное закрытие (кнопка X)

• Поддержка HTML в description

• Динамические иконки из lucide-react

---

⚙️ Environment Variables

.env.local

# Directual App ID (обязательная переменная)
NEXT_PUBLIC_DIRECTUAL_APP_ID=your_app_id_here

# NODE_ENV автоматически устанавливается Next.js
# development | production | test

Важно:

• Префикс NEXT_PUBLIC_ делает переменную доступной на клиенте

• Без этой переменной приложение не запустится (проверка в lib/directual/client.ts)

---

📦 Dependencies

package.json (основные зависимости)

{
  "dependencies": {
    "next": "^16.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    
    "directual-api": "^1.4.0",
    "socket.io-client": "^4.8.0",
    
    "tailwindcss": "^3.4.0",
    "tailwindcss-animate": "^1.0.7",
    "clsx": "^2.1.0",
    "tailwind-merge": "^3.4.0",
    "class-variance-authority": "^0.7.0",
    
    "@radix-ui/react-dialog": "^1.1.0",
    "@radix-ui/react-popover": "^1.1.0",
    "@radix-ui/react-tabs": "^1.1.0",
    "@radix-ui/react-tooltip": "^1.2.0",
    "@radix-ui/react-avatar": "^1.1.0",
    "@radix-ui/react-alert-dialog": "^1.1.0",
    
    "lucide-react": "^0.550.0"
  },
  "devDependencies": {
    "@types/node": "^24.0.0",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0",
    "typescript": "^5.9.0",
    "autoprefixer": "^10.4.0",
    "postcss": "^8.5.0",
    "eslint": "^9.0.0",
    "eslint-config-next": "^16.0.0"
  }
}

scripts

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  }
}

---

🔄 Жизненный цикл приложения

1. Инициализация (app load)

1. Root Layout монтируется

2. ThemeProvider загружает тему из localStorage и применяет

3. AuthProvider проверяет сессию через /api/auth/check

4. DataProvider загружает данные (если авторизован)

5. SocketListener подключается к WebSocket (если авторизован)

2. Авторизация (login flow)

1. Пользователь вводит credentials

2. authContext.login() отправляет POST /api/auth/login

3. API route вызывает serverApi.auth.login()

4. При успехе устанавливается HTTP-only cookie

5. AuthProvider обновляет user state

6. DataProvider автоматически загружает данные

7. SocketListener подключается к WebSocket

3. Работа с данными

1. Компонент вызывает refreshYourEntity() или refreshAll()

2. Fetcher получает sessionID из /api/auth/session (с кешем)

3. Выполняется запрос к Directual через api.structure().getData()

4. DataProvider обновляет state

5. React перерендеривает компоненты

4. WebSocket обновления

1. Сервер отправляет событие (например, entity_created)

2. SocketListener перехватывает событие

3. DataProvider подписан на это событие через useSocketEvent()

4. Вызывается refreshYourEntity(true) (silent)

5. UI обновляется автоматически

5. Обработка ошибок доступа

1. Fetcher получает 403 ошибку

2. Возвращается { success: false, error: 'Недостаточно прав' }

3. Компонент показывает сообщение об ошибке

4. Пользователь остается авторизованным (403 ≠ протухшая сессия)

Примечание: 403 может означать RBAC ограничения, а не истечение сессии. Для проверки сессии используйте периодический вызов /api/auth/check.

6. Выход (logout flow)

1. Пользователь нажимает "Выйти"

2. authContext.logout() отправляет POST /api/auth/logout

3. API route удаляет cookie

4. AuthProvider очищает user state

5. Fetcher очищает кеш sessionID

6. SocketListener отключается от WebSocket

7. Редирект на страницу входа

---

🎓 Best Practices

1. Безопасность

• ✅ Всегда используй HTTP-only cookie для sessionID

• ✅ Никогда не храни sessionID в localStorage

• ✅ Используй серверный клиент в API Routes

• ✅ Добавь security headers в next.config.mjs

• ✅ Проверяй сессию при каждом критичном запросе

2. Performance

• ✅ Используй silent=true для фоновых обновлений

• ✅ Кешируй sessionID в Fetcher

• ✅ WebSocket singleton предотвращает множественные подключения

• ✅ React Context оптимизирован (useCallback с [])

3. UX

• ✅ Показывай loading только при первоначальной загрузке

• ✅ Используй refreshing для индикатора обновления

• ✅ Автоматически обновляй данные при возврате на вкладку

• ✅ Показывай понятные ошибки пользователю

4. Архитектура

• ✅ Разделяй клиентский и серверный код

• ✅ Используй TypeScript для type safety

• ✅ Следуй иерархии провайдеров

• ✅ Держи бизнес-логику в контекстах, не в компонентах

5. Directual

• ✅ Всегда передавай sessionID в запросах

• ✅ Обрабатывай 403 ошибки глобально

• ✅ Используй структуры данных правильно

• ✅ WebSocket требует app_id + session_id в socket.auth

---

🐛 Troubleshooting

Проблема: WebSocket не подключается

Причины:

• sessionID не найден (не авторизован)

• Неверный APP_ID

• Неверный формат socket.auth

Решение:

• Проверь что cookie установлена (document.cookie)

• Проверь что /api/auth/session возвращает sessionID

• Убедись что NEXT_PUBLIC_DIRECTUAL_APP_ID установлен

Проблема: 403 ошибка на запросе

Причины:

• Недостаточно прав (RBAC ограничения)

• Неверная роль пользователя для этого эндпоинта

• sessionID не передается в запросах

• Cookie не отправляется (credentials: 'include')

Решение:

• Проверь права пользователя в Directual (структура WebUser, поле role)

• Проверь что fetcher.getSessionID() возвращает sessionID

• Убедись что credentials: 'include' в fetch

• Проверь настройки эндпоинта в Directual (Access control)

Проблема: Данные не обновляются

Причины:

• DataProvider не подписан на WebSocket события

• WebSocket не подключен

• Неверное имя события

Решение:

• Проверь что SocketListener монтирован в layout

• Проверь консоль на наличие логов [WebSocket] eventName

• Убедись что структура данных в событии правильная

Проблема: Тема не применяется

Причины:

• CSS переменные не определены

• Класс dark не добавляется на <html>

• Tailwind не настроен на darkMode: ["class"]

Решение:

• Проверь app/globals.css на наличие :root и .dark

• Проверь что ThemeProvider монтирован

• Проверь tailwind.config.js

---

📚 Дополнительные ресурсы

Directual

• Directual API Documentation

• directual-api NPM Package

Next.js

• Next.js Documentation

• App Router Guide

• API Routes

Security

• OWASP Security Headers

• Content Security Policy

React Patterns

• Context API

• Custom Hooks

---

🚪 Страница входа (Login Page)

Что нужно реализовать

Шаблон НЕ включает готовую страницу входа "из коробки". Вам нужно создать:

1. Страницу /app/auth/login/page.tsx:

'use client';
import { useState } from 'react';
import { useRouter } from 'next/navigation';
import { useAuth } from '@/hooks/use-auth';
import { Input } from '@/components/ui/input';
import { Button } from '@/components/ui/button';

export default function LoginPage() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const { login, loading, error } = useAuth();
  const router = useRouter();

  const handleSubmit = async (e) => {
    e.preventDefault();
    const result = await login(email, password);
    if (result.success) {
      router.push('/dashboard'); // Редирект после входа
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
      <Input type="password" value={password} onChange={(e) => setPassword(e.target.value)} />
      <Button type="submit" disabled={loading}>Войти</Button>
      {error && <p>{error}</p>}
    </form>
  );
}

2. Страницу /app/auth/register/page.tsx (аналогично)

3. Middleware для защиты роутов (опционально):

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const sessionCookie = request.cookies.get('1cable_session');
  
  // Если нет сессии и пытается зайти на защищенную страницу
  if (!sessionCookie && !request.nextUrl.pathname.startsWith('/auth')) {
    return NextResponse.redirect(new URL('/auth/login', request.url));
  }
  
  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/profile/:path*'],
};

---

🧩 shadcn/ui Компоненты

Что входит "из коробки"

Шаблон предполагает использование shadcn/ui, но НЕ устанавливает компоненты автоматически.

Вам нужно установить вручную:

# Инициализация shadcn/ui
npx shadcn@latest init

# Базовые компоненты для авторизации
npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add card
npx shadcn@latest add form

# Для алертов и уведомлений
npx shadcn@latest add alert
npx shadcn@latest add alert-dialog
npx shadcn@latest add toast
npx shadcn@latest add sonner  # Альтернатива тостам

# Для UI приложения
npx shadcn@latest add dialog
npx shadcn@latest add popover
npx shadcn@latest add dropdown-menu
npx shadcn@latest add tabs
npx shadcn@latest add tooltip
npx shadcn@latest add avatar
npx shadcn@latest add skeleton  # Для loading states

GlobalAlerts vs Toast

В шаблоне есть GlobalAlerts (компонент для WebSocket алертов), который работает аналогично тостам, но:

• Показывает алерты из WebSocket

• Позиционируется fixed top-4 right-4

• Автоматически скрывается через 5 секунд

Если вам нужны обычные тосты для клиентских уведомлений:

Вариант 1: shadcn/ui Toast

npx shadcn@latest add toast

Вариант 2: Sonner (рекомендуется)

npx shadcn@latest add sonner

Используйте в приложении:

import { toast } from 'sonner';

toast.success('Операция выполнена');
toast.error('Произошла ошибка');

Рекомендуемый набор компонентов

Минимальный (для авторизации):

• button, input, card, alert

Стандартный (для приложения):

• dialog, popover, dropdown-menu, tabs, tooltip, avatar, skeleton, toast/sonner

Расширенный (для сложных UI):

• command, combobox, select, radio-group, checkbox, switch, slider, calendar, date-picker, table, pagination

---

✅ Чеклист для нового проекта

При создании нового приложения по этому шаблону:

Шаг 1: Инициализация

• npx create-next-app@latest с TypeScript и App Router

• Установить зависимости: directual-api, socket.io-client, tailwindcss, lucide-react

• npx shadcn@latest init для инициализации shadcn/ui

• Установить базовые shadcn компоненты (button, input, card, alert, toast)

• Создать .env.local с NEXT_PUBLIC_DIRECTUAL_APP_ID

Шаг 2: Конфигурация

• Настроить rewrites в next.config.mjs

• Добавить security headers в next.config.mjs

• Настроить CSS переменные для темы в globals.css

• Настроить Tailwind (darkMode: ["class"])

Шаг 3: Структура проекта

• Создать структуру папок: app/api/auth/, lib/directual/, context/, hooks/, types/, components/ui/

• Создать типы в types/index.ts и types/directual.d.ts

Шаг 4: Directual интеграция

• Реализовать Directual клиенты (client.ts, server-client.ts)

• Реализовать API Routes для авторизации (login, register, logout, check, session)

• Создать Fetcher класс с обработкой сессии

• Создать WebSocket singleton

• Добавить методы в Fetcher для ваших структур данных

Шаг 5: Провайдеры и контексты

• Создать ThemeProvider

• Создать AuthProvider

• Создать DataProvider (адаптировать под ваши сущности)

• Создать хуки (use-auth, use-data, use-socket)

• Настроить Root Layout с провайдерами

Шаг 6: UI компоненты

• Добавить SocketListener и GlobalAlerts в layout

• Создать страницы /app/auth/login/page.tsx и /app/auth/register/page.tsx

• Создать middleware для защиты роутов (опционально)

• Создать компоненты для вашего приложения

Шаг 7: Directual Backend

• Настроить структуру user_actions в Directual

• Создать эндпоинт postUserAction с обработкой разных действий

• Настроить WebSocket события для асинхронных ответов

• Протестировать синхронные и асинхронные операции

Шаг 8: Тестирование

• Протестировать авторизацию (login/logout/register)

• Протестировать WebSocket подключение

• Протестировать переключение темы

• Протестировать работу с данными (CRUD операции)

• Протестировать обработку истечения сессии (403)

• Проверить security headers (browser DevTools → Network → Headers)