klg-asutk-app/docs/API.md

API Документация

Базовый URL

http://localhost:3000/api

Аутентификация

Примечание: Аутентификация будет реализована в будущих версиях. Сейчас все endpoints доступны без авторизации.

Endpoints

GET /api/aircraft

Получение списка воздушных судов.

Ответ:

[
  {
    "id": "1",
    "registrationNumber": "RA-12345",
    "serialNumber": "SN-001",
    "aircraftType": "Boeing 737-800",
    "operator": "Аэрофлот",
    "status": "Активен",
    "flightHours": 12500
  }
]

POST /api/ai-data

Получение данных для ИИ агента.

Тело запроса:

{
  "dataType": "aircraft",
  "filters": {
    "registrationNumber": "RA-12345",
    "operator": "Аэрофлот"
  }
}

Параметры:

• dataType (string, required): Тип данных (aircraft, risks, audits, organizations, checklists, applications, users, documents, regulations, all)
• filters (object, optional): Фильтры для данных

Ответ:

{
  "dataType": "aircraft",
  "count": 3,
  "data": [...]
}

POST /api/ai-chat

Отправка сообщения ИИ агенту.

Тело запроса:

{
  "message": "Сколько ВС у Аэрофлота?",
  "history": [
    {
      "role": "user",
      "content": "Привет"
    },
    {
      "role": "assistant",
      "content": "Привет! Чем могу помочь?"
    }
  ],
  "files": []
}

Ответ:

{
  "response": "У Аэрофлота 150 воздушных судов.",
  "timestamp": "2025-01-21T10:00:00.000Z"
}

Rate Limit: 50 запросов в минуту

GET /api/regulations

Получение нормативных документов.

Query параметры:

• source (string, optional): Фильтр по источнику (ICAO, EASA, FAA, MAK, ARMAC, RUSSIAN_RULES, AIR_CODE)
• type (string, optional): Фильтр по типу (convention, annex, regulation, rule, code)
• search (string, optional): Поисковый запрос

Ответ:

{
  "documents": [
    {
      "id": "chicago-convention",
      "title": "Конвенция о международной гражданской авиации",
      "source": "ICAO",
      "type": "convention",
      "category": "Основополагающий документ",
      "version": "2024",
      "lastUpdated": "2025-01-21T00:00:00.000Z",
      "content": "...",
      "url": "https://www.icao.int/..."
    }
  ],
  "total": 19
}

POST /api/regulations/update

Обновление нормативных документов (требует авторизации).

Тело запроса:

{
  "source": "ICAO"
}

Ответ:

{
  "success": true,
  "message": "Нормативные документы успешно обновлены",
  "results": {
    "timestamp": "2025-01-21T10:00:00.000Z",
    "sources": [...]
  }
}

Коды ошибок

• 400 - Неверный запрос (ошибка валидации)
• 401 - Не авторизован
• 403 - Доступ запрещен
• 404 - Ресурс не найден
• 429 - Превышен лимит запросов
• 500 - Внутренняя ошибка сервера

Формат ошибки

{
  "error": "Описание ошибки",
  "code": "ERROR_CODE",
  "details": {}
}

Rate Limiting

• /api/ai-chat: 50 запросов в минуту
• /api/ai-data: 100 запросов в минуту
• Остальные endpoints: 200 запросов в минуту

При превышении лимита возвращается статус 429 с заголовками:

• X-RateLimit-Limit: Максимальное количество запросов
• X-RateLimit-Remaining: Оставшееся количество
• X-RateLimit-Reset: Время сброса лимита (timestamp)

Валидация данных

Все входные данные валидируются с использованием Zod схем. При ошибке валидации возвращается статус 400 с деталями ошибок.

Версионирование

Текущая версия API: v1

В будущем версионирование будет реализовано через префикс пути: /api/v1/...