chat/docs/EMERGENCY_SERVICE_API.md

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

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

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

---

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

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

### 2. AlertStatus (Enum)
Статусы оповещений:
```python
ACTIVE = "active"           # Активно
RESOLVED = "resolved"       # Решено
CANCELLED = "cancelled"     # Отменено
INVESTIGATING = "investigating"  # Расследуется
```

### 3. ResponseType (Enum)
Типы ответов на оповещения:
```python
HELP_ON_WAY = "help_on_way"                 # Помощь в пути
CONTACTED_AUTHORITIES = "contacted_authorities"  # Связались с властями
SAFE_NOW = "safe_now"                       # Сейчас в безопасности
FALSE_ALARM = "false_alarm"                 # Ложная тревога
INVESTIGATING = "investigating"             # Расследуется
RESOLVED = "resolved"                       # Решено
```

### 4. EmergencyAlertCreate
Создание экстренного оповещения:
```json
{
  "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
Ответ с данными оповещения:
```json
{
  "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
Создание ответа на оповещение:
```json
{
  "response_type": "help_on_way",   // ResponseType, тип ответа
  "message": "Еду к вам!",          // string?, сообщение (макс 500 символов)
  "eta_minutes": 15,                // int?, предполагаемое время прибытия в минутах (0-240)
  "location_sharing": true          // bool, делиться ли местоположением
}
```

### 7. EmergencyResponseResponse
Ответ с данными отклика:
```json
{
  "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
Создание отчета о происшествии:
```json
{
  "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
Ответ с данными отчета:
```json
{
  "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
Создание отметки безопасности:
```json
{
  "message": "Я в порядке",         // string?, сообщение (макс 200 символов)
  "location_latitude": 55.7558,     // float?, широта (-90 до 90)
  "location_longitude": 37.6176     // float?, долгота (-180 до 180)
}
```

### 11. SafetyCheckResponse
Ответ с данными отметки безопасности:
```json
{
  "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
Статистика экстренных ситуаций:
```json
{
  "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
Ближайшие оповещения:
```json
{
  "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`

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

**Ответ:**
```json
{
  "status": "healthy",
  "service": "emergency_service"
}
```

---

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

**POST** `/api/v1/alert`

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

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

**Пример запроса:**
```bash
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`

**Пример запроса:**
```bash
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 оповещения

**Пример запроса:**
```bash
curl -X PUT http://192.168.0.103:8002/api/v1/alert/123/resolve \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Успешный ответ:** `200 OK`
```json
{
  "message": "Alert resolved successfully"
}
```

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

---

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

**PUT** `/api/v1/alert/{alert_id}`

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

**Параметры URL:**
- `alert_id` (int) - ID оповещения

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

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

---

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

**GET** `/api/v1/alerts/my`

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

**Пример запроса:**
```bash
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)

**Пример запроса:**
```bash
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`

**Пример запроса:**
```bash
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`

**Пример запроса:**
```bash
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

**Пример запроса:**
```bash
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. Создание экстренного оповещения
```javascript
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. Получение ближайших оповещений
```javascript
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. Отклик на оповещение
```javascript
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 токены имеют ограниченный срок действия