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
2. Зарегистрируйтесь, указав email и пароль
3. Создайте новую организацию в системе

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

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

# 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

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

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

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

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

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

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

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

• Общая документация
• API Playground
• Примеры использования

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

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

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

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

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:

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
• Для продакшена используйте переменные окружения сервера