chat/docs/MOBILE_API.md

# Инструкция по интеграции мобильного 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  | Внутренняя ошибка сервера             |

## Контактная информация

При возникновении вопросов или проблем с интеграцией, пожалуйста, свяжитесь с командой разработки.