trevor/chat

Fork 0

Files

Andrew K. Choi 7c22664daf

continuous-integration/drone/push Build is passing

Details

sdf

2025-09-26 12:22:14 +09:00

21 KiB

Raw Blame History

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

Обзор

Emergency Service предоставляет API для работы с экстренными ситуациями, включая создание оповещений, получение статистики и управление чрезвычайными ситуациями.

Базовый URL: http://192.168.0.103:8002 Аутентификация: Bearer Token (JWT)

Схемы данных (Schemas)

1. AlertType (Enum)

Типы экстренных ситуаций:

GENERAL = "general"           # Общая помощь
MEDICAL = "medical"          # Медицинская помощь
VIOLENCE = "violence"        # Насилие
HARASSMENT = "harassment"    # Преследование
UNSAFE_AREA = "unsafe_area"  # Небезопасная зона
ACCIDENT = "accident"        # ДТП/авария
FIRE = "fire"               # Пожар
NATURAL_DISASTER = "natural_disaster"  # Стихийное бедствие

2. AlertStatus (Enum)

Статусы оповещений:

ACTIVE = "active"           # Активно
RESOLVED = "resolved"       # Решено
CANCELLED = "cancelled"     # Отменено
INVESTIGATING = "investigating"  # Расследуется

3. ResponseType (Enum)

Типы ответов на оповещения:

HELP_ON_WAY = "help_on_way"                 # Помощь в пути
CONTACTED_AUTHORITIES = "contacted_authorities"  # Связались с властями
SAFE_NOW = "safe_now"                       # Сейчас в безопасности
FALSE_ALARM = "false_alarm"                 # Ложная тревога
INVESTIGATING = "investigating"             # Расследуется
RESOLVED = "resolved"                       # Решено

4. EmergencyAlertCreate

Создание экстренного оповещения:

{
  "latitude": 55.7558,              // float, координата широты (-90 до 90)
  "longitude": 37.6176,             // float, координата долготы (-180 до 180)
  "alert_type": "general",          // AlertType, тип оповещения
  "message": "Описание ситуации",   // string?, описание (макс 500 символов)
  "address": "Адрес места",         // string?, адрес (макс 500 символов)
  "contact_emergency_services": true, // bool, связываться ли со службами экстренного реагирования
  "notify_emergency_contacts": true   // bool, уведомлять ли экстренные контакты
}

5. EmergencyAlertResponse

Ответ с данными оповещения:

{
  "id": 123,                        // int, ID оповещения
  "uuid": "8ed4fb51-8a90-4b22...", // string, UUID оповещения
  "user_id": 26,                    // int, ID пользователя
  "latitude": 55.7558,              // float, широта
  "longitude": 37.6176,             // float, долгота
  "address": "Красная площадь, Москва", // string?, адрес
  "alert_type": "general",          // AlertType, тип оповещения
  "status": "active",               // AlertStatus, статус
  "message": "Нужна помощь",        // string?, описание
  "is_resolved": false,             // bool, решено ли
  "resolved_at": null,              // datetime?, время решения
  "resolved_notes": null,           // string?, заметки о решении
  "notified_users_count": 5,        // int, количество уведомленных пользователей
  "responded_users_count": 2,       // int, количество ответивших пользователей
  "created_at": "2024-01-15T10:30:00Z", // datetime, время создания
  "updated_at": "2024-01-15T10:35:00Z", // datetime?, время обновления
  "user_name": "Test User",         // string?, имя пользователя
  "user_phone": "+1234567890"       // string?, телефон пользователя
}

6. EmergencyResponseCreate

Создание ответа на оповещение:

{
  "response_type": "help_on_way",   // ResponseType, тип ответа
  "message": "Еду к вам!",          // string?, сообщение (макс 500 символов)
  "eta_minutes": 15,                // int?, предполагаемое время прибытия в минутах (0-240)
  "location_sharing": true          // bool, делиться ли местоположением
}

7. EmergencyResponseResponse

Ответ с данными отклика:

{
  "id": 456,                        // int, ID отклика
  "uuid": "8ed4fb51-8a90-4b22...", // string, UUID отклика
  "alert_id": 123,                  // int, ID оповещения
  "user_id": 27,                    // int, ID откликнувшегося пользователя
  "response_type": "help_on_way",   // ResponseType, тип отклика
  "message": "Еду к вам!",          // string?, сообщение
  "eta_minutes": 15,                // int?, время прибытия
  "location_sharing": true,         // bool, делиться местоположением
  "created_at": "2024-01-15T10:32:00Z", // datetime, время создания
  "responder_name": "Helper User",  // string?, имя откликнувшегося
  "responder_phone": "+9876543210"  // string?, телефон откликнувшегося
}

8. EmergencyReportCreate

Создание отчета о происшествии:

{
  "latitude": 55.7558,              // float, широта (-90 до 90)
  "longitude": 37.6176,             // float, долгота (-180 до 180)
  "report_type": "violence",        // string, тип происшествия
  "description": "Детальное описание происшествия...", // string, описание (10-1000 символов)
  "address": "Адрес происшествия",  // string?, адрес (макс 500 символов)
  "is_anonymous": false,            // bool, анонимный отчет
  "severity": 4                     // int, серьезность от 1 до 5
}

9. EmergencyReportResponse

Ответ с данными отчета:

{
  "id": 789,                        // int, ID отчета
  "uuid": "8ed4fb51-8a90-4b22...", // string, UUID отчета
  "user_id": 26,                    // int?, ID пользователя (null для анонимных)
  "latitude": 55.7558,              // float, широта
  "longitude": 37.6176,             // float, долгота
  "address": "Красная площадь",     // string?, адрес
  "report_type": "violence",        // string, тип происшествия
  "description": "Описание...",     // string, описание
  "is_anonymous": false,            // bool, анонимный ли
  "severity": 4,                    // int, серьезность (1-5)
  "status": "pending",              // string, статус (pending/investigating/resolved)
  "created_at": "2024-01-15T10:45:00Z" // datetime, время создания
}

10. SafetyCheckCreate

Создание отметки безопасности:

{
  "message": "Я в порядке",         // string?, сообщение (макс 200 символов)
  "location_latitude": 55.7558,     // float?, широта (-90 до 90)
  "location_longitude": 37.6176     // float?, долгота (-180 до 180)
}

11. SafetyCheckResponse

Ответ с данными отметки безопасности:

{
  "id": 101,                        // int, ID отметки
  "uuid": "8ed4fb51-8a90-4b22...", // string, UUID отметки
  "user_id": 26,                    // int, ID пользователя
  "message": "Я в порядке",         // string?, сообщение
  "location_latitude": 55.7558,     // float?, широта
  "location_longitude": 37.6176,    // float?, долгота
  "created_at": "2024-01-15T11:00:00Z" // datetime, время создания
}

12. EmergencyStatistics

Статистика экстренных ситуаций:

{
  "total_alerts": 150,              // int, общее количество оповещений
  "active_alerts": 12,              // int, активные оповещения
  "resolved_alerts": 138,           // int, решенные оповещения
  "total_responders": 89,           // int, общее количество откликнувшихся
  "avg_response_time_minutes": 8.5  // float, среднее время отклика в минутах
}

13. NearbyAlertResponse

Ближайшие оповещения:

{
  "id": 123,                        // int, ID оповещения
  "alert_type": "medical",          // string, тип оповещения
  "latitude": 55.7558,              // float, широта
  "longitude": 37.6176,             // float, долгота
  "address": "Больница №1",         // string?, адрес
  "distance_km": 2.5,               // float, расстояние в километрах
  "created_at": "2024-01-15T09:15:00Z", // datetime, время создания
  "responded_users_count": 3        // int, количество откликов
}

API Endpoints

1. Проверка здоровья сервиса

GET /health

Описание: Проверка статуса работы сервиса Авторизация: Не требуется

Ответ:

{
  "status": "healthy",
  "service": "emergency_service"
}

2. Создание экстренного оповещения

POST /api/v1/alert

Описание: Создание нового экстренного оповещения Авторизация: Bearer Token

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

Пример запроса:

curl -X POST http://192.168.0.103:8002/api/v1/alert \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "latitude": 55.7558,
    "longitude": 37.6176,
    "alert_type": "general",
    "message": "Нужна помощь, подозрительная активность",
    "address": "Красная площадь, Москва"
  }'

Успешный ответ: 200 OK Тело ответа: EmergencyAlertResponse

3. Ответить на оповещение

POST /api/v1/alert/{alert_id}/respond

Описание: Отправка отклика на экстренное оповещение Авторизация: Bearer Token

Параметры URL:

alert_id (int) - ID оповещения

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

Пример запроса:

curl -X POST http://192.168.0.103:8002/api/v1/alert/123/respond \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "response_type": "help_on_way",
    "message": "Еду к вам, буду через 10 минут!",
    "eta_minutes": 10
  }'

Успешный ответ: 200 OK Тело ответа: EmergencyResponseResponse

Ошибки:

404 - Оповещение не найдено
400 - Пользователь уже откликнулся на это оповещение

4. Решить оповещение

PUT /api/v1/alert/{alert_id}/resolve

Описание: Помечает оповещение как решенное Авторизация: Bearer Token

Параметры URL:

alert_id (int) - ID оповещения

Пример запроса:

curl -X PUT http://192.168.0.103:8002/api/v1/alert/123/resolve \
  -H "Authorization: Bearer YOUR_TOKEN"

Успешный ответ: 200 OK

{
  "message": "Alert resolved successfully"
}

Ошибки:

404 - Оповещение не найдено
403 - Только создатель может решить оповещение

5. Обновить оповещение

PUT /api/v1/alert/{alert_id}

Описание: Обновление существующего оповещения Авторизация: Bearer Token

Параметры URL:

alert_id (int) - ID оповещения

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

{
  "status": "resolved",                    // AlertStatus?, новый статус
  "message": "Обновленное описание",       // string?, новое описание
  "resolved_notes": "Помощь получена"     // string?, заметки о решении
}

Успешный ответ: 200 OK Тело ответа: EmergencyAlertResponse

6. Получить мои оповещения

GET /api/v1/alerts/my

Описание: Получение оповещений текущего пользователя Авторизация: Bearer Token

Пример запроса:

curl -X GET http://192.168.0.103:8002/api/v1/alerts/my \
  -H "Authorization: Bearer YOUR_TOKEN"

Успешный ответ: 200 OK Тело ответа: List[EmergencyAlertResponse]

7. Получить активные оповещения

GET /api/v1/alerts/active

Описание: Получение всех активных оповещений Авторизация: Bearer Token

Успешный ответ: 200 OK Тело ответа: List[EmergencyAlertResponse]

8. Получить ближайшие оповещения

GET /api/v1/alerts/nearby

Описание: Поиск оповещений в указанном радиусе Авторизация: Bearer Token

Query параметры:

latitude (float, обязательный) - Широта (-90 до 90)
longitude (float, обязательный) - Долгота (-180 до 180)
radius_km (float, опциональный) - Радиус поиска в км (по умолчанию 10.0, макс 100.0)

Пример запроса:

curl -X GET "http://192.168.0.103:8002/api/v1/alerts/nearby?latitude=55.7558&longitude=37.6176&radius_km=5.0" \
  -H "Authorization: Bearer YOUR_TOKEN"

Успешный ответ: 200 OK Тело ответа: List[NearbyAlertResponse] (отсортированы по расстоянию)

9. Получить отклики на оповещение

GET /api/v1/alert/{alert_id}/responses

Описание: Получение всех откликов на конкретное оповещение Авторизация: Bearer Token

Параметры URL:

alert_id (int) - ID оповещения

Успешный ответ: 200 OK Тело ответа: List[EmergencyResponseResponse]

10. Создать отчет о происшествии

POST /api/v1/report

Описание: Создание отчета о происшествии Авторизация: Bearer Token

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

Пример запроса:

curl -X POST http://192.168.0.103:8002/api/v1/report \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "latitude": 55.7558,
    "longitude": 37.6176,
    "report_type": "harassment",
    "description": "Преследование в районе метро...",
    "severity": 4,
    "is_anonymous": false
  }'

Успешный ответ: 200 OK Тело ответа: EmergencyReportResponse

11. Получить отчеты

GET /api/v1/reports

Описание: Получение списка отчетов о происшествиях Авторизация: Bearer Token

Успешный ответ: 200 OK Тело ответа: List[EmergencyReportResponse]

12. Создать отметку безопасности

POST /api/v1/safety-check

Описание: Отметка о том, что пользователь в безопасности Авторизация: Bearer Token

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

Пример запроса:

curl -X POST http://192.168.0.103:8002/api/v1/safety-check \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "message": "Добрался домой, все хорошо",
    "location_latitude": 55.7558,
    "location_longitude": 37.6176
  }'

Успешный ответ: 200 OK Тело ответа: SafetyCheckResponse

13. Получить отметки безопасности

GET /api/v1/safety-checks

Описание: Получение отметок безопасности пользователя Авторизация: Bearer Token

Успешный ответ: 200 OK Тело ответа: List[SafetyCheckResponse]

14. Получить статистику

GET /api/v1/stats

Описание: Получение статистики по экстренным ситуациям Авторизация: Bearer Token

Пример запроса:

curl -X GET http://192.168.0.103:8002/api/v1/stats \
  -H "Authorization: Bearer YOUR_TOKEN"

Успешный ответ: 200 OK Тело ответа: EmergencyStatistics

Коды ошибок

Общие ошибки

400 Bad Request - Неверные данные в запросе
401 Unauthorized - Требуется авторизация
403 Forbidden - Недостаточно прав
404 Not Found - Ресурс не найден
422 Unprocessable Entity - Ошибка валидации данных
500 Internal Server Error - Внутренняя ошибка сервера

Специфические ошибки

400 - "You have already responded to this alert" (при повторном отклике)
403 - "Only alert creator can resolve/update the alert" (при попытке изменения чужого оповещения)
404 - "Alert not found" (оповещение не найдено)

Примеры интеграции с мобильным приложением

1. Создание экстренного оповещения

const createEmergencyAlert = async (alertData) => {
  const response = await fetch('http://192.168.0.103:8002/api/v1/alert', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${userToken}`
    },
    body: JSON.stringify({
      latitude: alertData.latitude,
      longitude: alertData.longitude,
      alert_type: alertData.type || 'general',
      message: alertData.message,
      address: alertData.address
    })
  });
  
  return await response.json();
};

2. Получение ближайших оповещений

const getNearbyAlerts = async (latitude, longitude, radiusKm = 10) => {
  const params = new URLSearchParams({
    latitude: latitude.toString(),
    longitude: longitude.toString(),
    radius_km: radiusKm.toString()
  });
  
  const response = await fetch(
    `http://192.168.0.103:8002/api/v1/alerts/nearby?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${userToken}`
      }
    }
  );
  
  return await response.json();
};

3. Отклик на оповещение

const respondToAlert = async (alertId, responseData) => {
  const response = await fetch(
    `http://192.168.0.103:8002/api/v1/alert/${alertId}/respond`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${userToken}`
      },
      body: JSON.stringify({
        response_type: responseData.type,
        message: responseData.message,
        eta_minutes: responseData.etaMinutes
      })
    }
  );
  
  return await response.json();
};

Дополнительные возможности

WebSocket подключения (планируется)

Для получения уведомлений в реальном времени о новых оповещениях и откликах.

Push уведомления

API интегрируется с Notification Service для отправки push уведомлений на мобильные устройства.

Геолокация

Все координаты используют WGS84 (стандарт GPS). Расстояния вычисляются по формуле гаверсинусов.

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

Все данные о местоположении шифруются
Анонимные отчеты не содержат идентификационных данных
JWT токены имеют ограниченный срок действия

21 KiB Raw Blame History Unescape Escape

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

Обзор

Схемы данных (Schemas)

1. AlertType (Enum)

2. AlertStatus (Enum)

3. ResponseType (Enum)

4. EmergencyAlertCreate

5. EmergencyAlertResponse

6. EmergencyResponseCreate

7. EmergencyResponseResponse

8. EmergencyReportCreate

9. EmergencyReportResponse

10. SafetyCheckCreate

11. SafetyCheckResponse

12. EmergencyStatistics

13. NearbyAlertResponse

API Endpoints

1. Проверка здоровья сервиса

2. Создание экстренного оповещения

3. Ответить на оповещение

4. Решить оповещение

5. Обновить оповещение

6. Получить мои оповещения

7. Получить активные оповещения

8. Получить ближайшие оповещения

9. Получить отклики на оповещение

10. Создать отчет о происшествии

11. Получить отчеты

12. Создать отметку безопасности

13. Получить отметки безопасности

14. Получить статистику

Коды ошибок

Общие ошибки

Специфические ошибки

Примеры интеграции с мобильным приложением

1. Создание экстренного оповещения

2. Получение ближайших оповещений

3. Отклик на оповещение

Дополнительные возможности

WebSocket подключения (планируется)

Push уведомления

Геолокация

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

21 KiB

Raw Blame History