Initial commit MKD fixes
This commit is contained in:
Arsen
209
docs/DOMA_AI_INTEGRATION.md
Executable file
209
docs/DOMA_AI_INTEGRATION.md
Executable file
@@ -0,0 +1,209 @@
|
||||
# Интеграция с 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`
|
||||
- Для продакшена используйте переменные окружения сервера
|
||||
Reference in New Issue
Block a user