210 lines
8.7 KiB
Markdown
Executable File
210 lines
8.7 KiB
Markdown
Executable File
# Интеграция с 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`
|
||
- Для продакшена используйте переменные окружения сервера
|