This commit is contained in:
254
docs/MOBILE_API.md
Normal file
254
docs/MOBILE_API.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# Инструкция по интеграции мобильного API календарного сервиса
|
||||
|
||||
## Обзор
|
||||
|
||||
Этот документ содержит информацию о том, как интегрировать мобильное приложение с API календарного сервиса. Календарный сервис предоставляет эндпоинты для создания, получения и удаления записей в календаре женского здоровья.
|
||||
|
||||
## Базовый URL
|
||||
|
||||
```
|
||||
http://[domain]/api/v1/calendar/
|
||||
```
|
||||
|
||||
## Аутентификация
|
||||
|
||||
Все запросы к API должны включать токен аутентификации в заголовке `Authorization`:
|
||||
|
||||
```
|
||||
Authorization: Bearer [token]
|
||||
```
|
||||
|
||||
Для получения токена аутентификации используйте сервис аутентификации:
|
||||
|
||||
```
|
||||
POST /api/v1/auth/token
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
username=user@example.com&password=userpassword
|
||||
```
|
||||
|
||||
## Эндпоинты для мобильного приложения
|
||||
|
||||
### 1. Создание записи в календаре
|
||||
|
||||
```
|
||||
POST /api/v1/calendar/entries/mobile
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer [token]
|
||||
```
|
||||
|
||||
#### Формат запроса
|
||||
|
||||
```json
|
||||
{
|
||||
"date": "2025-09-26",
|
||||
"type": "MENSTRUATION",
|
||||
"flow_intensity": 3,
|
||||
"symptoms": ["CRAMPS", "HEADACHE"],
|
||||
"mood": "NORMAL",
|
||||
"notes": "Пример записи"
|
||||
}
|
||||
```
|
||||
|
||||
#### Параметры
|
||||
|
||||
| Параметр | Тип | Обязательный | Описание |
|
||||
|----------------|--------------|--------------|--------------------------------------------------------------------------------------|
|
||||
| date | string | Да | Дата записи в формате YYYY-MM-DD |
|
||||
| type | string | Да | Тип записи: MENSTRUATION, OVULATION, SPOTTING, DISCHARGE, PAIN, MOOD |
|
||||
| flow_intensity | integer | Нет | Интенсивность выделений по шкале 1-5 (только для MENSTRUATION и SPOTTING) |
|
||||
| symptoms | array[string]| Нет | Массив симптомов: CRAMPS, HEADACHE, BLOATING, FATIGUE, и т.д. |
|
||||
| mood | string | Нет | Настроение: HAPPY, SAD, NORMAL, STRESSED, ANXIOUS, IRRITATED |
|
||||
| notes | string | Нет | Текстовая заметка |
|
||||
|
||||
#### Пример успешного ответа
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 123,
|
||||
"uuid": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"entry_date": "2025-09-26",
|
||||
"entry_type": "period",
|
||||
"flow_intensity": "medium",
|
||||
"period_symptoms": "",
|
||||
"mood": "happy",
|
||||
"energy_level": 1,
|
||||
"sleep_hours": 0,
|
||||
"symptoms": "CRAMPS, HEADACHE",
|
||||
"medications": "",
|
||||
"notes": "Пример записи",
|
||||
"is_predicted": false,
|
||||
"confidence_score": null,
|
||||
"created_at": "2023-09-26T14:30:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Получение записей календаря
|
||||
|
||||
```
|
||||
GET /api/v1/calendar/entries
|
||||
Authorization: Bearer [token]
|
||||
```
|
||||
|
||||
#### Параметры запроса (в URL)
|
||||
|
||||
| Параметр | Тип | Обязательный | Описание |
|
||||
|-------------|--------|--------------|------------------------------------------|
|
||||
| start_date | string | Нет | Начальная дата в формате YYYY-MM-DD |
|
||||
| end_date | string | Нет | Конечная дата в формате YYYY-MM-DD |
|
||||
| entry_type | string | Нет | Тип записи (period, ovulation, symptoms) |
|
||||
| limit | integer| Нет | Ограничение количества возвращаемых записей (по умолчанию 100) |
|
||||
|
||||
#### Пример успешного ответа
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 123,
|
||||
"uuid": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"entry_date": "2025-09-26",
|
||||
"entry_type": "period",
|
||||
"flow_intensity": "medium",
|
||||
"period_symptoms": "",
|
||||
"mood": "happy",
|
||||
"energy_level": 1,
|
||||
"sleep_hours": 0,
|
||||
"symptoms": "CRAMPS, HEADACHE",
|
||||
"medications": "",
|
||||
"notes": "Пример записи",
|
||||
"is_predicted": false,
|
||||
"confidence_score": null,
|
||||
"created_at": "2023-09-26T14:30:00.000Z"
|
||||
},
|
||||
{
|
||||
"id": 124,
|
||||
"uuid": "550e8400-e29b-41d4-a716-446655440001",
|
||||
"entry_date": "2025-09-30",
|
||||
"entry_type": "ovulation",
|
||||
"flow_intensity": null,
|
||||
"period_symptoms": "",
|
||||
"mood": "happy",
|
||||
"energy_level": 1,
|
||||
"sleep_hours": 0,
|
||||
"symptoms": "BREAST_TENDERNESS",
|
||||
"medications": "",
|
||||
"notes": "Пример записи об овуляции",
|
||||
"is_predicted": false,
|
||||
"confidence_score": null,
|
||||
"created_at": "2023-09-26T14:30:00.000Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 3. Удаление записи календаря
|
||||
|
||||
```
|
||||
DELETE /api/v1/entries/{entry_id}
|
||||
Authorization: Bearer [token]
|
||||
```
|
||||
|
||||
#### Параметры
|
||||
|
||||
| Параметр | Тип | Обязательный | Описание |
|
||||
|-----------|---------|--------------|------------------------|
|
||||
| entry_id | integer | Да | ID записи для удаления |
|
||||
|
||||
#### Пример успешного ответа
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Entry deleted successfully"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Получение обзора цикла
|
||||
|
||||
```
|
||||
GET /api/v1/cycle-overview
|
||||
Authorization: Bearer [token]
|
||||
```
|
||||
|
||||
#### Пример успешного ответа
|
||||
|
||||
```json
|
||||
{
|
||||
"current_cycle_day": 14,
|
||||
"current_phase": "ovulation",
|
||||
"next_period_date": "2023-10-15",
|
||||
"days_until_period": 12,
|
||||
"cycle_regularity": "regular",
|
||||
"avg_cycle_length": 28
|
||||
}
|
||||
```
|
||||
|
||||
## Маппинг типов данных
|
||||
|
||||
### Типы записей
|
||||
|
||||
| Мобильное приложение | Сервер |
|
||||
|----------------------|--------------|
|
||||
| MENSTRUATION | period |
|
||||
| OVULATION | ovulation |
|
||||
| SPOTTING | symptoms |
|
||||
| DISCHARGE | symptoms |
|
||||
| PAIN | symptoms |
|
||||
| MOOD | mood |
|
||||
|
||||
### Интенсивность выделений
|
||||
|
||||
| Мобильное приложение | Сервер |
|
||||
|----------------------|--------------|
|
||||
| 1 | light |
|
||||
| 2 | light |
|
||||
| 3 | medium |
|
||||
| 4 | heavy |
|
||||
| 5 | heavy |
|
||||
|
||||
### Настроение
|
||||
|
||||
| Мобильное приложение | Сервер |
|
||||
|----------------------|--------------|
|
||||
| HAPPY | happy |
|
||||
| SAD | sad |
|
||||
| NORMAL | happy |
|
||||
| STRESSED | anxious |
|
||||
| ANXIOUS | anxious |
|
||||
| IRRITATED | irritated |
|
||||
|
||||
## Тестирование API
|
||||
|
||||
Для тестирования API можно использовать скрипты:
|
||||
|
||||
1. `setup_mobile_test.py` - создание токена для тестирования
|
||||
2. `mobile_format_test.py` - тестирование преобразования форматов данных
|
||||
3. `test_mobile_api.py` - полное тестирование мобильного API
|
||||
|
||||
### Пример запроса с curl
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8004/api/v1/calendar/entries/mobile \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer $(cat auth_token.txt)" \
|
||||
-d '{
|
||||
"date": "2025-09-26",
|
||||
"type": "MENSTRUATION",
|
||||
"flow_intensity": 3,
|
||||
"symptoms": ["CRAMPS", "HEADACHE"],
|
||||
"mood": "NORMAL",
|
||||
"notes": "Тестовая запись"
|
||||
}'
|
||||
```
|
||||
|
||||
## Коды ошибок
|
||||
|
||||
| Код | Описание |
|
||||
|------|---------------------------------------|
|
||||
| 400 | Неверный запрос или данные |
|
||||
| 401 | Ошибка аутентификации |
|
||||
| 404 | Запись не найдена |
|
||||
| 422 | Ошибка валидации данных |
|
||||
| 500 | Внутренняя ошибка сервера |
|
||||
|
||||
## Контактная информация
|
||||
|
||||
При возникновении вопросов или проблем с интеграцией, пожалуйста, свяжитесь с командой разработки.
|
||||
Reference in New Issue
Block a user