This commit is contained in:
600
docs/EMERGENCY_SERVICE_API.md
Normal file
600
docs/EMERGENCY_SERVICE_API.md
Normal file
@@ -0,0 +1,600 @@
|
||||
# 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 токены имеют ограниченный срок действия
|
||||
Reference in New Issue
Block a user