solver-sdk/docs/indexing/INDEXING.md

SDK для интеграции с Code Solver Backend API

# Индексация проектов

Это руководство описывает, как использовать SDK для индексации проектов и отдельных файлов.

## Инициализация SDK

Прежде чем использовать функции индексации, необходимо инициализировать SDK с указанием API ключа:

```typescript
import { CodeSolverSDK } from 'solver-sdk';

const sdk = new CodeSolverSDK({
  baseURL: 'https://api.example.com',
  apiKey: 'ваш_api_ключ', // API ключ обязателен для авторизации WebSocket соединений
});
```

## Индексация проекта

### Запуск индексации

Для запуска индексации проекта используйте метод `indexProject` или его псевдоним `startIndexing`:

```typescript
// Полная индексация проекта
await sdk.projects.indexProject('идентификатор_проекта', {
  indexingMode: 'full'
});

// Инкрементальная индексация (только изменившиеся файлы)
await sdk.projects.indexProject('идентификатор_проекта', {
  indexingMode: 'incremental'
});

// Автоматический выбор режима индексации (рекомендуется)
await sdk.projects.indexProject('идентификатор_проекта', {
  indexingMode: 'auto'
});

// Псевдоним startIndexing (работает аналогично indexProject)
await sdk.projects.startIndexing('идентификатор_проекта', {
  indexingMode: 'auto'
});
```

### Режимы индексации

SDK поддерживает следующие режимы индексации:

- **full** - полная переиндексация всех файлов проекта
- **incremental** - индексация только изменившихся файлов (более быстрая)
- **auto** - автоматический выбор режима на основе метаданных проекта

Вы также можете использовать флаг `forceFull` для принудительной полной индексации:

```typescript
await sdk.projects.indexProject('идентификатор_проекта', {
  forceFull: true
});
```

### Фильтрация файлов

Можно указать шаблоны включения и исключения файлов:

```typescript
await sdk.projects.indexProject('идентификатор_проекта', {
  indexingMode: 'auto',
  includePatterns: ['**/*.js', '**/*.ts', '**/*.jsx', '**/*.tsx'],
  excludePatterns: ['**/node_modules/**', '**/dist/**', '**/build/**']
});
```

## Обновление индекса отдельных файлов

Для индексации одного файла используйте метод `updateFileIndex`:

```typescript
// Индексация файла с чтением его содержимого с диска
await sdk.projects.updateFileIndex(
  'идентификатор_проекта',
  'путь/к/файлу.js'
);

// Индексация с передачей содержимого файла
await sdk.projects.updateFileIndex(
  'идентификатор_проекта',
  'путь/к/файлу.js',
  {
    content: 'содержимое файла',
    force: true // Принудительная индексация, даже если файл не изменился
  }
);

// С дополнительными опциями
await sdk.projects.updateFileIndex(
  'идентификатор_проекта',
  'путь/к/файлу.ts',
  {
    content: 'содержимое файла',
    language: 'typescript', // Явное указание языка
    updateDependencies: true // Обновление зависимостей после индексации
  }
);
```

## Работа с новыми проектами

### Создание и индексация проекта

```typescript
// Создание проекта и немедленная индексация
const result = await sdk.projects.createAndIndexProject('/путь/к/проекту', {
  name: 'Название проекта',
  indexingMode: 'full',
  excludePatterns: ['**/node_modules/**', '**/dist/**']
});

console.log(`Проект создан с ID: ${result.projectId}`);
console.log(`Статус индексации: ${result.indexingStatus}`);
```

### Поиск или создание проекта

```typescript
// Найти существующий проект или создать новый
const project = await sdk.projects.getOrCreateProject('/путь/к/проекту', 'Название проекта');
console.log(`ID проекта: ${project.id}`);

// После получения проекта можно запустить индексацию
await sdk.projects.indexProject(project.id, {
  indexingMode: 'auto'
});
```

## Управление индексацией

### Проверка статуса индексации

```typescript
// Получение текущего статуса индексации
const status = await sdk.projects.getIndexingStatus('идентификатор_проекта');
console.log(`Статус: ${status.status}`);
console.log(`Количество файлов: ${status.fileCount}`);
console.log(`Статистика по языкам:`, status.languageStats);
```

### Отмена индексации

```typescript
// Отмена текущей индексации
await sdk.projects.cancelIndexing('идентификатор_проекта');
```

### Очистка ошибок индексации

```typescript
// Очистка ошибки, если индексация завершилась с ошибкой
await sdk.projects.clearIndexingError('идентификатор_проекта');
```

## Отслеживание индексации через WebSocket

SDK поддерживает отслеживание процесса индексации в реальном времени через WebSocket:

```typescript
// Подключение к WebSocket
await sdk.projects.connectWebSocket();

// Подписка на события индексации отдельных файлов
sdk.projects.on('file_indexed', (data) => {
  console.log(`Файл индексирован: ${data.file.path}`);
  console.log(`Язык: ${data.file.language}`);
  console.log(`Тип изменения: ${data.file.changeType}`);
});

// Подписка на событие завершения индексации
sdk.projects.on('indexing_complete', (data) => {
  console.log(`Индексация завершена для проекта ${data.projectId}`);
  console.log(`Всего файлов: ${data.stats.totalFiles}`);
  console.log(`Проиндексировано: ${data.stats.indexed}`);
  console.log(`Ошибок: ${data.stats.failed}`);
  console.log(`Время индексации: ${data.stats.time}мс`);
});

// Отключение от WebSocket после завершения работы
await sdk.projects.disconnectWebSocket();
```

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

```typescript
try {
  await sdk.projects.indexProject('идентификатор_проекта', {
    indexingMode: 'full'
  });
} catch (error) {
  if (error.message.includes('не найден')) {
    console.error('Проект не найден');
  } else if (error.message.includes('forbidden')) {
    console.error('Ошибка авторизации. Проверьте API ключ');
  } else {
    console.error(`Ошибка индексации: ${error.message}`);
  }
}
```

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

Начиная с версии 1.7.7, SDK автоматически добавляет API ключ в качестве параметра `authToken` при подключении WebSocket, что обеспечивает корректную авторизацию для всех операций через WebSocket (индексация, рассуждения и т.д.).

Для корректной работы WebSocket соединений:
1. **Обязательно указывайте `apiKey` при инициализации SDK**
2. Подключайтесь к WebSocket перед использованием событий
3. Отключайтесь от WebSocket после завершения работы

```typescript
// Корректная инициализация с apiKey
const sdk = new CodeSolverSDK({
  baseURL: 'https://api.example.com',
  apiKey: 'ваш_api_ключ' // Обязательно для WebSocket авторизации
});

// Подключение
await sdk.projects.connectWebSocket();

// Использование WebSocket...

// Отключение
await sdk.projects.disconnectWebSocket();
```