This commit is contained in:
495
docs/MOBILE_API_SPECS.md
Normal file
495
docs/MOBILE_API_SPECS.md
Normal file
@@ -0,0 +1,495 @@
|
||||
# API Спецификации для мобильного приложения Women's Safety App
|
||||
|
||||
## Обзор системы
|
||||
Микросервисная архитектура с 6 сервисами:
|
||||
- **API Gateway** (порт 8000) - точка входа
|
||||
- **User Service** (порт 8001) - управление пользователями
|
||||
- **Emergency Service** (порт 8002) - экстренные ситуации
|
||||
- **Location Service** (порт 8003) - геолокация
|
||||
- **Calendar Service** (порт 8004) - календарь здоровья
|
||||
- **Notification Service** (порт 8005) - уведомления
|
||||
|
||||
**Базовый URL:** `http://192.168.0.103:8000` (API Gateway)
|
||||
**Прямые сервисы:** `http://192.168.0.103:800X` (где X - номер сервиса)
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Система авторизации
|
||||
|
||||
### Регистрация пользователя
|
||||
**POST** `/api/v1/auth/register`
|
||||
```json
|
||||
{
|
||||
"username": "testuser",
|
||||
"email": "test@example.com",
|
||||
"password": "password123",
|
||||
"full_name": "Test User",
|
||||
"phone": "+1234567890"
|
||||
}
|
||||
```
|
||||
|
||||
### Вход в систему
|
||||
**POST** `/api/v1/auth/login`
|
||||
```json
|
||||
{
|
||||
"username": "testuser", // или "email": "test@example.com"
|
||||
"password": "password123"
|
||||
}
|
||||
```
|
||||
**Ответ:**
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"token_type": "bearer"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 👤 User Service API
|
||||
|
||||
### Профиль пользователя
|
||||
**GET** `/api/v1/user/profile`
|
||||
**Ответ:** Полная информация о пользователе
|
||||
|
||||
**PUT** `/api/v1/user/profile` - Обновление профиля
|
||||
|
||||
### Дашборд пользователя
|
||||
**GET** `/api/v1/user/dashboard`
|
||||
**Ответ:**
|
||||
```json
|
||||
{
|
||||
"user_info": {...},
|
||||
"recent_alerts": [...],
|
||||
"emergency_contacts": [...],
|
||||
"safety_stats": {...}
|
||||
}
|
||||
```
|
||||
|
||||
### Экстренные контакты
|
||||
**GET** `/api/v1/user/emergency-contacts` - Список контактов
|
||||
**POST** `/api/v1/user/emergency-contacts` - Добавить контакт
|
||||
**PUT** `/api/v1/user/emergency-contacts/{id}` - Обновить контакт
|
||||
**DELETE** `/api/v1/user/emergency-contacts/{id}` - Удалить контакт
|
||||
|
||||
**Схема контакта:**
|
||||
```json
|
||||
{
|
||||
"name": "Мама",
|
||||
"phone_number": "+1234567890",
|
||||
"relationship": "mother",
|
||||
"notes": "Основной контакт",
|
||||
"is_active": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Emergency Service API (Полная спецификация)
|
||||
|
||||
### Типы данных
|
||||
```typescript
|
||||
enum AlertType {
|
||||
GENERAL = "general",
|
||||
MEDICAL = "medical",
|
||||
VIOLENCE = "violence",
|
||||
HARASSMENT = "harassment",
|
||||
UNSAFE_AREA = "unsafe_area",
|
||||
ACCIDENT = "accident",
|
||||
FIRE = "fire",
|
||||
NATURAL_DISASTER = "natural_disaster"
|
||||
}
|
||||
|
||||
enum AlertStatus {
|
||||
ACTIVE = "active",
|
||||
RESOLVED = "resolved",
|
||||
CANCELLED = "cancelled",
|
||||
INVESTIGATING = "investigating"
|
||||
}
|
||||
|
||||
enum ResponseType {
|
||||
HELP_ON_WAY = "help_on_way",
|
||||
CONTACTED_AUTHORITIES = "contacted_authorities",
|
||||
SAFE_NOW = "safe_now",
|
||||
FALSE_ALARM = "false_alarm"
|
||||
}
|
||||
```
|
||||
|
||||
### Основные endpoints
|
||||
|
||||
#### 1. Создание экстренного оповещения
|
||||
**POST** `/api/v1/alert` (через Emergency Service напрямую: порт 8002)
|
||||
```json
|
||||
{
|
||||
"latitude": 55.7558,
|
||||
"longitude": 37.6176,
|
||||
"alert_type": "general",
|
||||
"message": "Нужна помощь",
|
||||
"address": "Красная площадь, Москва",
|
||||
"contact_emergency_services": true,
|
||||
"notify_emergency_contacts": true
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Получение оповещений
|
||||
- **GET** `/api/v1/alerts/my` - Мои оповещения
|
||||
- **GET** `/api/v1/alerts/active` - Активные оповещения
|
||||
- **GET** `/api/v1/alerts/nearby?latitude=55.7558&longitude=37.6176&radius_km=10` - Ближайшие
|
||||
|
||||
#### 3. Отклик на оповещение
|
||||
**POST** `/api/v1/alert/{alert_id}/respond`
|
||||
```json
|
||||
{
|
||||
"response_type": "help_on_way",
|
||||
"message": "Еду к вам!",
|
||||
"eta_minutes": 15,
|
||||
"location_sharing": true
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. Управление оповещением
|
||||
- **PUT** `/api/v1/alert/{alert_id}` - Обновить оповещение
|
||||
- **PUT** `/api/v1/alert/{alert_id}/resolve` - Пометить как решенное
|
||||
- **GET** `/api/v1/alert/{alert_id}/responses` - Получить отклики
|
||||
|
||||
#### 5. Отчеты о происшествиях
|
||||
**POST** `/api/v1/report`
|
||||
```json
|
||||
{
|
||||
"latitude": 55.7558,
|
||||
"longitude": 37.6176,
|
||||
"report_type": "harassment",
|
||||
"description": "Описание происшествия",
|
||||
"severity": 4,
|
||||
"is_anonymous": false
|
||||
}
|
||||
```
|
||||
|
||||
#### 6. Отметки безопасности
|
||||
**POST** `/api/v1/safety-check`
|
||||
```json
|
||||
{
|
||||
"message": "Я в безопасности",
|
||||
"location_latitude": 55.7558,
|
||||
"location_longitude": 37.6176
|
||||
}
|
||||
```
|
||||
|
||||
#### 7. Статистика
|
||||
**GET** `/api/v1/stats`
|
||||
```json
|
||||
{
|
||||
"total_alerts": 150,
|
||||
"active_alerts": 12,
|
||||
"resolved_alerts": 138,
|
||||
"total_responders": 89,
|
||||
"avg_response_time_minutes": 8.5
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📍 Location Service API
|
||||
|
||||
### Обновление местоположения
|
||||
**POST** `/api/v1/location/update`
|
||||
```json
|
||||
{
|
||||
"latitude": 55.7558,
|
||||
"longitude": 37.6176,
|
||||
"accuracy": 10.0,
|
||||
"altitude": 150.0
|
||||
}
|
||||
```
|
||||
|
||||
### Поиск пользователей рядом
|
||||
**GET** `/api/v1/nearby-users?latitude=55.7558&longitude=37.6176&radius_km=1.0`
|
||||
|
||||
### Геокодирование
|
||||
**GET** `/api/v1/geocode/reverse?latitude=55.7558&longitude=37.6176`
|
||||
**GET** `/api/v1/geocode/forward?address=Красная площадь, Москва`
|
||||
|
||||
---
|
||||
|
||||
## 📅 Calendar Service API
|
||||
|
||||
### Календарь здоровья
|
||||
**GET** `/api/v1/calendar/entries` - Записи календаря
|
||||
**POST** `/api/v1/calendar/entries` - Добавить запись
|
||||
|
||||
**Схема записи:**
|
||||
```json
|
||||
{
|
||||
"date": "2024-01-15",
|
||||
"entry_type": "period_start", // period_start, period_end, mood, symptoms
|
||||
"notes": "Заметки",
|
||||
"mood_score": 4, // 1-5
|
||||
"symptoms": ["headache", "fatigue"]
|
||||
}
|
||||
```
|
||||
|
||||
### Аналитика
|
||||
**GET** `/api/v1/calendar/analytics` - Аналитика цикла
|
||||
|
||||
---
|
||||
|
||||
## 🔔 Notification Service API
|
||||
|
||||
### Отправка уведомления
|
||||
**POST** `/api/v1/send-notification`
|
||||
```json
|
||||
{
|
||||
"user_id": 123,
|
||||
"title": "Экстренное оповещение",
|
||||
"message": "Новое оповещение рядом с вами",
|
||||
"type": "emergency_alert",
|
||||
"data": {"alert_id": 456}
|
||||
}
|
||||
```
|
||||
|
||||
### Push токены
|
||||
**POST** `/api/v1/push-token`
|
||||
```json
|
||||
{
|
||||
"token": "fcm_or_apns_token",
|
||||
"platform": "ios" // или "android"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Интеграция для мобильного приложения
|
||||
|
||||
### Базовый HTTP клиент
|
||||
```javascript
|
||||
class WomenSafetyAPI {
|
||||
constructor(baseUrl = 'http://192.168.0.103:8000') {
|
||||
this.baseUrl = baseUrl;
|
||||
this.token = null;
|
||||
}
|
||||
|
||||
setToken(token) {
|
||||
this.token = token;
|
||||
}
|
||||
|
||||
async request(method, endpoint, data = null) {
|
||||
const config = {
|
||||
method,
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
}
|
||||
};
|
||||
|
||||
if (this.token) {
|
||||
config.headers.Authorization = `Bearer ${this.token}`;
|
||||
}
|
||||
|
||||
if (data && (method === 'POST' || method === 'PUT')) {
|
||||
config.body = JSON.stringify(data);
|
||||
}
|
||||
|
||||
const url = `${this.baseUrl}${endpoint}`;
|
||||
const response = await fetch(url, config);
|
||||
|
||||
if (!response.ok) {
|
||||
const error = await response.json();
|
||||
throw new Error(error.detail || 'API Error');
|
||||
}
|
||||
|
||||
return await response.json();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Основные методы API
|
||||
```javascript
|
||||
class EmergencyAPI extends WomenSafetyAPI {
|
||||
// Авторизация
|
||||
async login(username, password) {
|
||||
const response = await this.request('POST', '/api/v1/auth/login', {
|
||||
username,
|
||||
password
|
||||
});
|
||||
this.setToken(response.access_token);
|
||||
return response;
|
||||
}
|
||||
|
||||
async register(userData) {
|
||||
return await this.request('POST', '/api/v1/auth/register', userData);
|
||||
}
|
||||
|
||||
// Экстренные ситуации (через порт 8002)
|
||||
async createAlert(alertData) {
|
||||
const emergencyUrl = this.baseUrl.replace('8000', '8002');
|
||||
return await fetch(`${emergencyUrl}/api/v1/alert`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${this.token}`
|
||||
},
|
||||
body: JSON.stringify(alertData)
|
||||
}).then(r => r.json());
|
||||
}
|
||||
|
||||
async getNearbyAlerts(latitude, longitude, radiusKm = 10) {
|
||||
const emergencyUrl = this.baseUrl.replace('8000', '8002');
|
||||
const params = new URLSearchParams({
|
||||
latitude: latitude.toString(),
|
||||
longitude: longitude.toString(),
|
||||
radius_km: radiusKm.toString()
|
||||
});
|
||||
|
||||
return await fetch(`${emergencyUrl}/api/v1/alerts/nearby?${params}`, {
|
||||
headers: { 'Authorization': `Bearer ${this.token}` }
|
||||
}).then(r => r.json());
|
||||
}
|
||||
|
||||
async respondToAlert(alertId, responseData) {
|
||||
const emergencyUrl = this.baseUrl.replace('8000', '8002');
|
||||
return await fetch(`${emergencyUrl}/api/v1/alert/${alertId}/respond`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${this.token}`
|
||||
},
|
||||
body: JSON.stringify(responseData)
|
||||
}).then(r => r.json());
|
||||
}
|
||||
|
||||
// Профиль пользователя
|
||||
async getProfile() {
|
||||
return await this.request('GET', '/api/v1/user/profile');
|
||||
}
|
||||
|
||||
async getDashboard() {
|
||||
return await this.request('GET', '/api/v1/user/dashboard');
|
||||
}
|
||||
|
||||
// Экстренные контакты
|
||||
async getEmergencyContacts() {
|
||||
return await this.request('GET', '/api/v1/user/emergency-contacts');
|
||||
}
|
||||
|
||||
async addEmergencyContact(contactData) {
|
||||
return await this.request('POST', '/api/v1/user/emergency-contacts', contactData);
|
||||
}
|
||||
|
||||
// Местоположение
|
||||
async updateLocation(locationData) {
|
||||
return await this.request('POST', '/api/v1/location/update', locationData);
|
||||
}
|
||||
|
||||
// Отметка безопасности
|
||||
async createSafetyCheck(safetyData) {
|
||||
const emergencyUrl = this.baseUrl.replace('8000', '8002');
|
||||
return await fetch(`${emergencyUrl}/api/v1/safety-check`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${this.token}`
|
||||
},
|
||||
body: JSON.stringify(safetyData)
|
||||
}).then(r => r.json());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Примеры использования
|
||||
```javascript
|
||||
// Инициализация
|
||||
const api = new EmergencyAPI('http://192.168.0.103:8000');
|
||||
|
||||
// Авторизация
|
||||
await api.login('testuser', 'password123');
|
||||
|
||||
// Создание экстренного оповещения
|
||||
const alert = await api.createAlert({
|
||||
latitude: 55.7558,
|
||||
longitude: 37.6176,
|
||||
alert_type: 'general',
|
||||
message: 'Нужна помощь!',
|
||||
address: 'Красная площадь, Москва'
|
||||
});
|
||||
|
||||
// Поиск ближайших оповещений
|
||||
const nearbyAlerts = await api.getNearbyAlerts(55.7558, 37.6176, 5);
|
||||
|
||||
// Отклик на оповещение
|
||||
const response = await api.respondToAlert(alert.id, {
|
||||
response_type: 'help_on_way',
|
||||
message: 'Еду к вам!',
|
||||
eta_minutes: 10
|
||||
});
|
||||
|
||||
// Получение профиля
|
||||
const profile = await api.getProfile();
|
||||
|
||||
// Отметка безопасности
|
||||
const safetyCheck = await api.createSafetyCheck({
|
||||
message: 'Добрался домой безопасно',
|
||||
location_latitude: 55.7600,
|
||||
location_longitude: 37.6100
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Безопасность и аутентификация
|
||||
|
||||
### JWT токены
|
||||
- Время жизни: настраивается в конфигурации
|
||||
- Формат: `Bearer {token}`
|
||||
- Включают: user_id, email, exp (время истечения)
|
||||
|
||||
### Заголовки запросов
|
||||
```
|
||||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
### Коды ошибок
|
||||
- `401 Unauthorized` - Неверные учетные данные
|
||||
- `403 Forbidden` - Недостаточно прав
|
||||
- `422 Unprocessable Entity` - Ошибки валидации
|
||||
- `500 Internal Server Error` - Внутренняя ошибка
|
||||
|
||||
---
|
||||
|
||||
## 📱 Рекомендации для мобильной разработки
|
||||
|
||||
### Push уведомления
|
||||
1. Зарегистрируйте push токен через `/api/v1/push-token`
|
||||
2. Обрабатывайте входящие уведомления для экстренных ситуаций
|
||||
3. Показывайте локальные уведомления при получении emergency_alert
|
||||
|
||||
### Геолокация
|
||||
1. Запрашивайте разрешения на точное местоположение
|
||||
2. Обновляйте координаты через `/api/v1/location/update`
|
||||
3. Кэшируйте последнее известное местоположение
|
||||
|
||||
### Оффлайн режим
|
||||
1. Кэшируйте экстренные контакты локально
|
||||
2. Сохраняйте черновики оповещений для отправки при восстановлении связи
|
||||
3. Показывайте статус подключения к сервису
|
||||
|
||||
### UI/UX
|
||||
1. Красная кнопка SOS должна быть всегда доступна
|
||||
2. Быстрый доступ к созданию оповещения (виджет, ярлык)
|
||||
3. Показывайте статус отправленных оповещений
|
||||
4. Уведомления о новых откликах на оповещения
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Тестирование
|
||||
|
||||
Используйте прилагаемый скрипт `test_emergency_api.sh` для полного тестирования API:
|
||||
```bash
|
||||
./test_emergency_api.sh
|
||||
```
|
||||
|
||||
Скрипт проверит:
|
||||
- Регистрацию и авторизацию
|
||||
- Создание и управление оповещениями
|
||||
- Отклики на оповещения
|
||||
- Отчеты и отметки безопасности
|
||||
- Статистику и аналитику
|
||||
Reference in New Issue
Block a user