mkd/docs/DOMA_AI_INTEGRATION.md

# Интеграция с Doma AI API

Этот документ описывает интеграцию приложения с Doma AI для автоматической синхронизации заявок.

## Обзор

Модуль заявок (`ApplicationsModule`) интегрирован с Doma AI через GraphQL API. Все заявки автоматически загружаются из Doma AI и отображаются в разделе "Заявки".

## Настройка

### 1. Получение доступа к Doma AI

**Для продакшена:**
1. Получите доступ к вашему продакшн инстансу Doma AI
2. Убедитесь, что у вас есть учетные данные для API
3. Получите URL API вашего инстанса (обычно: `https://your-domain.doma.ai/admin/api`)

**Для тестирования (опционально):**
1. Перейдите на [тестовый стенд Doma AI](https://condo.d.doma.ai/)
2. Зарегистрируйтесь, указав email и пароль
3. Создайте новую организацию в системе

### 2. Настройка переменных окружения

Создайте файл `.env.local` в корне проекта и добавьте:

```env
# URL API Doma AI (PRODUCTION)
# ВАЖНО: Укажите URL вашего продакшн инстанса Doma AI
# Пример: https://your-domain.doma.ai/admin/api
VITE_DOMA_AI_API_URL=https://your-domain.doma.ai/admin/api

# Учетные данные (используйте email ИЛИ телефон)
# Для продакшена используйте учетные данные вашей организации
VITE_DOMA_AI_EMAIL=your-email@example.com
VITE_DOMA_AI_PASSWORD=your-password

# ИЛИ используйте телефон:
# VITE_DOMA_AI_PHONE=+79991234567
# VITE_DOMA_AI_PASSWORD=your-password
```

**Для продакшена:**
- Укажите URL вашего инстанса Doma AI (не тестовый стенд)
- Используйте учетные данные вашей организации в Doma AI
- Убедитесь, что URL доступен из вашего окружения

### 3. Авторизация

При первом открытии раздела "Заявки" приложение автоматически:
- Проверяет наличие сохраненного токена
- Если токена нет, выполняет авторизацию с использованием учетных данных из переменных окружения
- Сохраняет токен в localStorage для последующих запросов

## Архитектура

### Компоненты

1. **`domaGraphQLClient.ts`** - GraphQL клиент для работы с Doma AI API
   - Управление авторизацией (токены)
   - Выполнение GraphQL запросов и мутаций
   - Обработка ошибок

2. **`domaService.ts`** - Сервис для работы с заявками
   - Инициализация подключения
   - Получение заявок из Doma AI
   - Преобразование данных из формата Doma AI в формат приложения
   - Fallback на бэкенд или мок-данные при ошибках

3. **`ApplicationsModule.tsx`** - UI компонент модуля заявок
   - Отображение заявок
   - Инициализация подключения при загрузке

## Работа с API

### Получение заявок

```typescript
import { domaService } from './services/domaService';

// Инициализация (выполняется автоматически при первом использовании)
await domaService.initialize();

// Получение всех заявок
const applications = await domaService.getApplications();

// Получение заявок с фильтрами
const applications = await domaService.getApplications({
  status: 'new',
  limit: 50
});
```

### Авторизация вручную

```typescript
import { domaGraphQLClient } from './services/domaGraphQLClient';

// Через email
await domaGraphQLClient.authenticate('email@example.com', 'password');

// Через телефон
await domaGraphQLClient.authenticateWithPhone('+79991234567', 'password');
```

## Маппинг данных

Данные из Doma AI автоматически преобразуются в формат приложения:

| Doma AI | Приложение |
|---------|------------|
| `ticket.id` | `application.id` |
| `ticket.number` | `application.number` |
| `ticket.status.type` | `application.status` (new/in_progress/done/canceled) |
| `ticket.description` | `application.description` |
| `ticket.property.address` | `application.address` |
| `ticket.property.unitName` | `application.apartment` |
| `ticket.client.name` | `application.clientName` |
| `ticket.assignee.name` | `application.performer.name` |
| `ticket.createdAt` | `application.createdAt` |
| `ticket.deadline` | `application.deadlineAt` |

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

Сервис имеет многоуровневую систему fallback:

1. **Doma AI API** - основной источник данных
2. **Backend API** - если Doma AI недоступен
3. **Мок-данные** - если оба источника недоступны

Это обеспечивает работу приложения даже при проблемах с подключением.

## Отладка

Для отладки интеграции откройте консоль браузера. Сервис выводит подробные логи:

- `[domaService]` - логи сервиса заявок
- `[DomaGraphQLClient]` - логи GraphQL клиента

### Типичные проблемы

1. **Ошибка авторизации**
   - Проверьте правильность email/телефона и пароля
   - Убедитесь, что учетная запись создана в Doma AI

2. **Заявки не загружаются**
   - Проверьте URL API в переменных окружения
   - Убедитесь, что токен сохранен (проверьте localStorage)
   - Проверьте консоль на наличие ошибок GraphQL

3. **Неправильные данные**
   - Возможно, схема GraphQL в Doma AI отличается от ожидаемой
   - Проверьте структуру ответа в Network вкладке DevTools
   - Может потребоваться обновление запросов в `domaGraphQLClient.ts`

## Документация Doma AI

- [Общая документация](https://developers.doma.ai/ru/docs/index)
- [API Playground](https://condo.d.doma.ai/admin/api)
- [Примеры использования](https://developers.doma.ai/ru/docs/api/examples)

## Расширение функциональности

### Добавление новых запросов

Для добавления новых запросов к Doma AI:

1. Добавьте метод в `domaGraphQLClient.ts`:

```typescript
async getCustomData(): Promise<CustomData> {
  const query = `
    query GetCustomData {
      customData {
        id
        name
      }
    }
  `;
  
  const response = await this.request<{ customData: CustomData }>(query);
  return response.data?.customData;
}
```

2. Используйте его в `domaService.ts`:

```typescript
async getCustomData(): Promise<CustomData> {
  await this.initialize();
  return await domaGraphQLClient.getCustomData();
}
```

### Обновление статуса заявки

Для реализации обновления статуса заявки в Doma AI:

1. Изучите схему GraphQL в API Playground
2. Создайте мутацию в `domaGraphQLClient.ts`
3. Реализуйте метод в `domaService.ts`

## Безопасность

⚠️ **Важно**: Не коммитьте файлы `.env.local` с реальными учетными данными в репозиторий!

- Используйте `.env.example` для примера конфигурации
- Добавьте `.env.local` в `.gitignore`
- Для продакшена используйте переменные окружения сервера