ДОбавлены авторизация, выход из профиляю ПРи авторизации приложение запоминает username, password и при входе авторизуется само, чтобы работать с актуальным токеном
This commit is contained in:
416
docs/api_specification.md
Normal file
416
docs/api_specification.md
Normal file
@@ -0,0 +1,416 @@
|
||||
# Описание API и способы взаимодействия с ним
|
||||
|
||||
## Промпт для ИИ
|
||||
|
||||
Ты — технический документатор API для микросервисной архитектуры приложения женской безопасности. Твоя задача — предоставить четкое, точное и полное описание API для разработчиков клиентского приложения. Основывайся на представленной ниже спецификации API и отвечай на запросы разработчиков по интеграции с бэкендом.
|
||||
|
||||
## Общая информация об API
|
||||
|
||||
Бэкенд приложения построен на микросервисной архитектуре с использованием FastAPI, что обеспечивает высокую производительность и масштабируемость. Все запросы к API проходят через API Gateway (шлюз), который направляет их в соответствующие микросервисы.
|
||||
|
||||
### Базовый URL
|
||||
|
||||
```
|
||||
https://api.womensafety.app/api/v1/
|
||||
```
|
||||
|
||||
В среде разработки:
|
||||
```
|
||||
http://localhost:8001/api/v1/
|
||||
```
|
||||
|
||||
### Формат данных
|
||||
|
||||
API принимает и отправляет данные в формате JSON. При отправке запроса необходимо указать заголовок:
|
||||
|
||||
```
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
### Аутентификация
|
||||
|
||||
API использует JWT (JSON Web Tokens) для аутентификации. После успешной авторизации вы получаете два токена:
|
||||
- `access_token` — для авторизации запросов (срок действия: 30 минут)
|
||||
- `refresh_token` — для обновления access_token (срок действия: 7 дней)
|
||||
|
||||
Для авторизованных запросов необходимо добавлять заголовок:
|
||||
|
||||
```
|
||||
Authorization: Bearer {access_token}
|
||||
```
|
||||
|
||||
## Сервис авторизации (User Service)
|
||||
|
||||
### Регистрация нового пользователя
|
||||
|
||||
**Эндпоинт:** `POST /auth/register`
|
||||
|
||||
**Тело запроса:**
|
||||
```json
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"username": "username",
|
||||
"password": "SecurePassword123!",
|
||||
"first_name": "Имя",
|
||||
"last_name": "Фамилия",
|
||||
"phone": "+79991234567"
|
||||
}
|
||||
```
|
||||
|
||||
**Ответ при успехе (201 Created):**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"message": "User registered successfully",
|
||||
"data": {
|
||||
"user_id": "uuid-string",
|
||||
"username": "username",
|
||||
"email": "user@example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Возможные ошибки:**
|
||||
- 400 Bad Request: Некорректные данные
|
||||
- 409 Conflict: Пользователь с таким email или username уже существует
|
||||
|
||||
### Авторизация пользователя
|
||||
|
||||
**Эндпоинт:** `POST /auth/login`
|
||||
|
||||
**Тело запроса (вариант 1):**
|
||||
```json
|
||||
{
|
||||
"username": "username",
|
||||
"password": "SecurePassword123!"
|
||||
}
|
||||
```
|
||||
|
||||
**Тело запроса (вариант 2):**
|
||||
```json
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "SecurePassword123!"
|
||||
}
|
||||
```
|
||||
|
||||
**Ответ при успехе (200 OK):**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"token_type": "bearer",
|
||||
"expires_in": 1800
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Возможные ошибки:**
|
||||
- 401 Unauthorized: Неверный логин или пароль
|
||||
- 403 Forbidden: Аккаунт заблокирован
|
||||
|
||||
### Обновление токена
|
||||
|
||||
**Эндпоинт:** `POST /auth/refresh`
|
||||
|
||||
**Тело запроса:**
|
||||
```json
|
||||
{
|
||||
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
```
|
||||
|
||||
**Ответ при успехе (200 OK):**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"token_type": "bearer",
|
||||
"expires_in": 1800
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Возможные ошибки:**
|
||||
- 401 Unauthorized: Недействительный refresh_token
|
||||
|
||||
### Выход из системы
|
||||
|
||||
**Эндпоинт:** `POST /auth/logout`
|
||||
|
||||
**Заголовки:**
|
||||
```
|
||||
Authorization: Bearer {access_token}
|
||||
```
|
||||
|
||||
**Ответ при успехе (200 OK):**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"message": "Successfully logged out"
|
||||
}
|
||||
```
|
||||
|
||||
**Возможные ошибки:**
|
||||
- 401 Unauthorized: Недействительный токен
|
||||
|
||||
### Получение профиля пользователя
|
||||
|
||||
**Эндпоинт:** `GET /users/me`
|
||||
|
||||
**Заголовки:**
|
||||
```
|
||||
Authorization: Bearer {access_token}
|
||||
```
|
||||
|
||||
**Ответ при успехе (200 OK):**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"user_id": "uuid-string",
|
||||
"username": "username",
|
||||
"email": "user@example.com",
|
||||
"first_name": "Имя",
|
||||
"last_name": "Фамилия",
|
||||
"phone": "+79991234567",
|
||||
"created_at": "2025-10-16T10:30:00Z",
|
||||
"is_verified": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Возможные ошибки:**
|
||||
- 401 Unauthorized: Недействительный токен
|
||||
|
||||
## Сервис экстренных оповещений (Emergency Service)
|
||||
|
||||
### Создание экстренного оповещения
|
||||
|
||||
**Эндпоинт:** `POST /emergency/alert`
|
||||
|
||||
**Заголовки:**
|
||||
```
|
||||
Authorization: Bearer {access_token}
|
||||
```
|
||||
|
||||
**Тело запроса:**
|
||||
```json
|
||||
{
|
||||
"location": {
|
||||
"latitude": 55.7558,
|
||||
"longitude": 37.6173
|
||||
},
|
||||
"message": "Нуждаюсь в помощи. Преследование.",
|
||||
"battery_level": 42,
|
||||
"contact_ids": ["uuid1", "uuid2"]
|
||||
}
|
||||
```
|
||||
|
||||
**Ответ при успехе (201 Created):**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"alert_id": "alert-uuid-string",
|
||||
"created_at": "2025-10-16T15:30:00Z",
|
||||
"status": "active",
|
||||
"message": "Экстренное оповещение активировано"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Возможные ошибки:**
|
||||
- 401 Unauthorized: Недействительный токен
|
||||
- 400 Bad Request: Неверные координаты или другие данные
|
||||
|
||||
### Получение статуса экстренного оповещения
|
||||
|
||||
**Эндпоинт:** `GET /emergency/alert/{alert_id}`
|
||||
|
||||
**Заголовки:**
|
||||
```
|
||||
Authorization: Bearer {access_token}
|
||||
```
|
||||
|
||||
**Ответ при успехе (200 OK):**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": {
|
||||
"alert_id": "alert-uuid-string",
|
||||
"created_at": "2025-10-16T15:30:00Z",
|
||||
"status": "active",
|
||||
"location": {
|
||||
"latitude": 55.7558,
|
||||
"longitude": 37.6173,
|
||||
"updated_at": "2025-10-16T15:35:00Z"
|
||||
},
|
||||
"notified_contacts": [
|
||||
{
|
||||
"contact_id": "uuid1",
|
||||
"status": "notified",
|
||||
"notified_at": "2025-10-16T15:31:00Z"
|
||||
},
|
||||
{
|
||||
"contact_id": "uuid2",
|
||||
"status": "pending",
|
||||
"notified_at": null
|
||||
}
|
||||
],
|
||||
"emergency_services_notified": true,
|
||||
"emergency_services_notified_at": "2025-10-16T15:32:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Возможные ошибки:**
|
||||
- 401 Unauthorized: Недействительный токен
|
||||
- 403 Forbidden: Нет доступа к данному оповещению
|
||||
- 404 Not Found: Оповещение не найдено
|
||||
|
||||
### Обновление местоположения при активном оповещении
|
||||
|
||||
**Эндпоинт:** `PUT /emergency/alert/{alert_id}/location`
|
||||
|
||||
**Заголовки:**
|
||||
```
|
||||
Authorization: Bearer {access_token}
|
||||
```
|
||||
|
||||
**Тело запроса:**
|
||||
```json
|
||||
{
|
||||
"latitude": 55.7560,
|
||||
"longitude": 37.6175,
|
||||
"accuracy": 10.5,
|
||||
"battery_level": 38
|
||||
}
|
||||
```
|
||||
|
||||
**Ответ при успехе (200 OK):**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"message": "Location updated successfully",
|
||||
"data": {
|
||||
"updated_at": "2025-10-16T15:40:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Возможные ошибки:**
|
||||
- 401 Unauthorized: Недействительный токен
|
||||
- 403 Forbidden: Нет доступа к данному оповещению
|
||||
- 404 Not Found: Оповещение не найдено или не активно
|
||||
|
||||
### Отмена экстренного оповещения
|
||||
|
||||
**Эндпоинт:** `POST /emergency/alert/{alert_id}/cancel`
|
||||
|
||||
**Заголовки:**
|
||||
```
|
||||
Authorization: Bearer {access_token}
|
||||
```
|
||||
|
||||
**Тело запроса:**
|
||||
```json
|
||||
{
|
||||
"reason": "Ложная тревога",
|
||||
"details": "Случайно нажала кнопку"
|
||||
}
|
||||
```
|
||||
|
||||
**Ответ при успехе (200 OK):**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"message": "Alert cancelled successfully",
|
||||
"data": {
|
||||
"alert_id": "alert-uuid-string",
|
||||
"cancelled_at": "2025-10-16T15:45:00Z",
|
||||
"status": "cancelled"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Возможные ошибки:**
|
||||
- 401 Unauthorized: Недействительный токен
|
||||
- 403 Forbidden: Нет доступа к данному оповещению
|
||||
- 404 Not Found: Оповещение не найдено
|
||||
- 409 Conflict: Оповещение уже отменено
|
||||
|
||||
## Рекомендации по работе с API
|
||||
|
||||
### Обработка ошибок
|
||||
|
||||
Все ошибки API возвращаются в едином формате:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"code": "ERROR_CODE",
|
||||
"message": "Описание ошибки",
|
||||
"details": {
|
||||
"field": ["Детальное описание ошибки для конкретного поля"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Управление токенами
|
||||
|
||||
1. После получения `access_token` и `refresh_token` сохраните их в безопасном хранилище.
|
||||
2. Для каждого запроса, требующего авторизацию, добавляйте `access_token` в заголовок.
|
||||
3. Если API возвращает ошибку 401, попробуйте обновить токен через эндпоинт `/auth/refresh`.
|
||||
4. Если и это не помогает, перенаправьте пользователя на страницу входа.
|
||||
|
||||
### Оптимизация работы с сетью
|
||||
|
||||
1. Используйте кэширование для уменьшения количества запросов.
|
||||
2. Реализуйте механизм повторных попыток для нестабильных соединений.
|
||||
3. При отправке экстренных оповещений учитывайте возможную нестабильность сети — сохраняйте данные локально до получения подтверждения от сервера.
|
||||
|
||||
### Работа с геолокацией
|
||||
|
||||
1. Запрашивайте у пользователя разрешение на постоянный доступ к геолокации.
|
||||
2. Оптимизируйте частоту обновления координат для экономии батареи.
|
||||
3. При активном экстренном оповещении увеличивайте частоту обновления координат.
|
||||
|
||||
## Тестирование API
|
||||
|
||||
Для облегчения интеграции с API доступна песочница:
|
||||
|
||||
```
|
||||
https://api-sandbox.womensafety.app/api/v1/
|
||||
```
|
||||
|
||||
Тестовые учетные записи:
|
||||
- Пользователь: `test_user/Test123!`
|
||||
- Администратор: `test_admin/Admin123!`
|
||||
|
||||
## Работа с реальными устройствами
|
||||
|
||||
Для корректной работы с API на реальных устройствах учитывайте:
|
||||
|
||||
1. Ограничения режима энергосбережения на некоторых устройствах.
|
||||
2. Различную точность GPS на разных моделях телефонов.
|
||||
3. Возможность потери соединения в некоторых зонах.
|
||||
|
||||
Реализуйте механизм, который будет накапливать данные локально при отсутствии сети и отправлять их, когда соединение восстановится.
|
||||
|
||||
## Безопасность
|
||||
|
||||
1. Никогда не храните пароли в открытом виде.
|
||||
2. Не сохраняйте токены в незащищенном хранилище.
|
||||
3. Всегда проверяйте SSL-сертификаты при подключении к API.
|
||||
4. Реализуйте защиту от подбора пароля, ограничивая количество попыток входа.
|
||||
|
||||
## Поддержка
|
||||
|
||||
При возникновении проблем с интеграцией можно обратиться:
|
||||
- Email: api-support@womensafety.app
|
||||
- Документация: https://docs.womensafety.app
|
||||
- Статус сервисов: https://status.womensafety.app
|
||||
159
docs/auth_emergency_system_requirements.md
Normal file
159
docs/auth_emergency_system_requirements.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# Техническое задание для ИИ агента по реализации системы авторизации, регистрации и экстренных оповещений
|
||||
|
||||
## Промпт для ИИ
|
||||
|
||||
Ты — ИИ агент-разработчик, специализирующийся на интеграции клиентской части приложения для женской безопасности с бэкендом на микросервисной архитектуре. Твоя задача — реализовать систему авторизации, регистрации и экстренных оповещений на основе предоставленных API-эндпоинтов.
|
||||
|
||||
## Общие требования
|
||||
|
||||
1. Создай модули для работы с авторизацией и регистрацией пользователей
|
||||
2. Реализуй механизм хранения и обновления токенов доступа
|
||||
3. Разработай интерфейс для экстренных оповещений
|
||||
4. Обеспечь надежную обработку ошибок и восстановление соединения
|
||||
5. Следуй современным практикам безопасности при работе с API
|
||||
|
||||
## Часть 1: Система авторизации и регистрации
|
||||
|
||||
### Эндпоинты для работы
|
||||
|
||||
#### Регистрация
|
||||
- **URL**: `/api/v1/auth/register`
|
||||
- **Метод**: `POST`
|
||||
- **Требуемые поля**:
|
||||
- email (string)
|
||||
- username (string)
|
||||
- password (string)
|
||||
- first_name (string)
|
||||
- last_name (string)
|
||||
- phone (string)
|
||||
- **Обработка ответа**: Создать локальный профиль пользователя и перенаправить на экран авторизации
|
||||
|
||||
#### Авторизация
|
||||
- **URL**: `/api/v1/auth/login`
|
||||
- **Метод**: `POST`
|
||||
- **Требуемые поля**:
|
||||
- username (string) или email (string)
|
||||
- password (string)
|
||||
- **Обработка ответа**: Сохранить полученный токен доступа и refresh token
|
||||
|
||||
#### Обновление токена
|
||||
- **URL**: `/api/v1/auth/refresh`
|
||||
- **Метод**: `POST`
|
||||
- **Требуемые поля**:
|
||||
- refresh_token (string)
|
||||
- **Обработка ответа**: Обновить сохраненный токен доступа
|
||||
|
||||
#### Выход из системы
|
||||
- **URL**: `/api/v1/auth/logout`
|
||||
- **Метод**: `POST`
|
||||
- **Заголовки**: Authorization: Bearer {token}
|
||||
- **Обработка ответа**: Удалить все локальные данные аутентификации
|
||||
|
||||
### Функциональные требования
|
||||
|
||||
1. **Валидация данных**:
|
||||
- Проверка корректности формата email
|
||||
- Проверка надежности пароля (минимум 8 символов, одна заглавная буква, одна цифра, один специальный символ)
|
||||
- Валидация номера телефона (международный формат)
|
||||
|
||||
2. **Хранение данных**:
|
||||
- Безопасное хранение токенов доступа (использовать Secure Storage)
|
||||
- Автоматическое обновление токенов при истечении срока действия
|
||||
|
||||
3. **Обработка ошибок**:
|
||||
- Четкие сообщения об ошибках для пользователя
|
||||
- Автоматические повторные попытки при проблемах с сетью
|
||||
- Логирование ошибок для отладки
|
||||
|
||||
## Часть 2: Экстренные оповещения
|
||||
|
||||
### Эндпоинты для работы
|
||||
|
||||
#### Создание экстренного оповещения
|
||||
- **URL**: `/api/v1/emergency/alert`
|
||||
- **Метод**: `POST`
|
||||
- **Заголовки**: Authorization: Bearer {token}
|
||||
- **Требуемые поля**:
|
||||
- location (object): { latitude: float, longitude: float }
|
||||
- message (string, optional): Дополнительная информация
|
||||
- **Обработка ответа**: Отобразить статус отправки и ID оповещения
|
||||
|
||||
#### Получение статуса экстренного оповещения
|
||||
- **URL**: `/api/v1/emergency/alert/{alert_id}`
|
||||
- **Метод**: `GET`
|
||||
- **Заголовки**: Authorization: Bearer {token}
|
||||
- **Обработка ответа**: Обновить интерфейс с информацией о статусе оповещения
|
||||
|
||||
#### Отмена экстренного оповещения
|
||||
- **URL**: `/api/v1/emergency/alert/{alert_id}/cancel`
|
||||
- **Метод**: `POST`
|
||||
- **Заголовки**: Authorization: Bearer {token}
|
||||
- **Требуемые поля**:
|
||||
- reason (string, optional): Причина отмены
|
||||
- **Обработка ответа**: Обновить статус оповещения в интерфейсе
|
||||
|
||||
### Функциональные требования
|
||||
|
||||
1. **Интерфейс экстренных оповещений**:
|
||||
- Кнопка SOS, заметная и легко доступная
|
||||
- Подтверждение перед отправкой для предотвращения случайных активаций
|
||||
- Индикатор статуса активного оповещения
|
||||
- Возможность отмены оповещения
|
||||
|
||||
2. **Геолокация**:
|
||||
- Автоматическое получение местоположения пользователя
|
||||
- Периодическое обновление координат при активном оповещении
|
||||
- Отправка обновлений локации на сервер
|
||||
|
||||
3. **Уведомления**:
|
||||
- Push-уведомления о статусе экстренного оповещения
|
||||
- Звуковые сигналы при изменении статуса
|
||||
- Вибрация для незаметного активирования
|
||||
|
||||
4. **Отказоустойчивость**:
|
||||
- Кэширование данных для работы офлайн
|
||||
- Повторная отправка при восстановлении соединения
|
||||
- Локальное хранение истории экстренных вызовов
|
||||
|
||||
## Технические требования
|
||||
|
||||
1. **Архитектура**:
|
||||
- Использовать паттерн MVVM или Redux для управления состоянием
|
||||
- Разделить код на модули по функциональности
|
||||
- Инкапсулировать работу с API в отдельный сервис
|
||||
|
||||
2. **Безопасность**:
|
||||
- Шифрование хранимых данных
|
||||
- Проверка SSL-сертификатов
|
||||
- Защита от CSRF и других уязвимостей
|
||||
|
||||
3. **Производительность**:
|
||||
- Минимизировать использование ресурсов
|
||||
- Оптимизировать сетевые запросы
|
||||
- Эффективное управление жизненным циклом приложения
|
||||
|
||||
4. **Тестирование**:
|
||||
- Модульные тесты для каждого компонента
|
||||
- Интеграционные тесты для проверки взаимодействия с API
|
||||
- UI-тесты для проверки пользовательского интерфейса
|
||||
|
||||
## Ожидаемые результаты
|
||||
|
||||
1. Полностью функциональная система авторизации и регистрации
|
||||
2. Интерфейс для экстренных оповещений с полной интеграцией API
|
||||
3. Документация по архитектуре и интеграции
|
||||
4. Покрытие кода тестами не менее 80%
|
||||
|
||||
## Ограничения и особые требования
|
||||
|
||||
1. Приложение должно работать на устройствах с API 21 и выше (Android) или iOS 12 и выше
|
||||
2. Учитывать различные размеры экрана и ориентации
|
||||
3. Обеспечить доступность для людей с ограниченными возможностями
|
||||
4. Минимальное потребление батареи даже при использовании геолокации
|
||||
|
||||
## Примечания
|
||||
|
||||
1. Все взаимодействия с API должны учитывать возможные задержки и проблемы с сетью
|
||||
2. Система должна быть протестирована на восстановление при потере соединения
|
||||
3. Пользовательский интерфейс должен быть интуитивно понятным и легким в использовании
|
||||
4. Все действия, связанные с безопасностью, должны логироваться для аудита
|
||||
Reference in New Issue
Block a user