commit 57a6b4943a70e40e6653a00f90c924cc6f7f309f Author: BitCode Date: Thu Apr 23 13:47:27 2026 +0300 Очистка истории Wiki diff --git a/API.md b/API.md new file mode 100644 index 0000000..43879ba --- /dev/null +++ b/API.md @@ -0,0 +1,128 @@ +# 📚 Документация API проекта: Excavators AI + +> **Базовый URL:** `https://ex.neimarker.ru/api/` (или ваш рабочий домен) +> **Формат дат:** ISO 8601 (например, `2026-04-20T15:30:00Z`) +> **Аутентификация (Для интеграций):** Заголовок `Authorization: Api-Key <токен>` +> **Аутентификация (Web):** Заголовок `Authorization: Bearer ` + +## 📑 Оглавление +1. [Аутентификация и интеграция](#auth) +2. [Экскаваторы (Базовый CRUD)](#devices_crud) +3. [Настройки графика и работы экскаватора](#device_settings) +4. [Аналитика и Цифровой двойник](#analytics) +5. [Видеоархив, Карты и Очистка данных](#video_archive) +--- + + +## 1. Аутентификация и интеграция +В системе предусмотрено два типа доступа: для живых пользователей (через веб-интерфейс с логином/паролем) и для сторонних систем (интеграция по статичному API-ключу). + +### 🔑 Доступ для сторонних систем (Интеграция) +Для работы внешних скриптов, 1С, Telegram-ботов и других систем (M2M) капча и временные токены не используются. + +> ⚠️ **Важно:** Для получения ключа интеграции (`Api-Key`) вашей организации необходимо обратиться в службу технической поддержки или к менеджеру. + +### 💻 Пример на Python: Интеграция по Api-Key +```python +import requests + +BASE_URL = "https://ex.neimarker.ru/api/" +# Токен, выданный для вашей организации +API_KEY = "ВАШ_УНИКАЛЬНЫЙ_ТОКЕН_ИНТЕГРАЦИИ" + +headers = { + "Authorization": f"Api-Key {API_KEY}" +} + +# Пример 1: Запрашиваем список всех доступных экскаваторов вашей организации +devices_res = requests.get(f"{BASE_URL}/devices/", headers=headers) +print("Доступная техника:", devices_res.json()) + +# Пример 2: Запрашиваем аналитику по одному экскаватору +analytics_res = requests.get( + f"{BASE_URL}/analytics/?device_id=1&start_date=2026-04-20T00:00:00Z&end_date=2026-04-20T23:59:59Z", + headers=headers +) +print("Аналитика:", analytics_res.json()) +``` +--- + +## 2. Экскаваторы (Базовый CRUD) +Автоматически ограничивает выдачу только устройствами, принадлежащими организации, чей токен совершает запрос. + +| Метод | Эндпоинт | Описание | +|---|---|---| +| `GET` | `/devices/` | Список всех устройств организации. | +| `POST` | `/devices/` | Создание устройства. Ожидает: `name`, `bucket_volume`. MAC и API-токен генерируются автоматически. | +| `GET` | `/devices//` | Данные одного устройства. | +| `PATCH`| `/devices//` | Изменение параметров (объем ковша, смены, часовой пояс `timezone_offset` и т.д.). | +| `DELETE`| `/devices//`| Удаление. (Можно удалять только устройства с MAC "OFFLINE-..."). | + +--- + + +## 3. Настройки графика и работы экскаватора +Вложенные справочники для конкретного `device_id`. Поддерживают создание, чтение списка и удаление по `pk` (ID записи). + +| Метод | Эндпоинт | Описание | +|---|---|---| +| `GET`, `POST` | `/devices//materials/` | Типы грунта (плотность, коэффициенты) на заданный период. | +| `DELETE` | `/devices//materials//`| Удалить настройку материала. | +| `GET`, `POST` | `/devices//schedule-exceptions/` | Исключения графика: ТО, ремонты, выходные, спец-смены. | +| `DELETE` | `/devices//schedule-exceptions//` | Удалить исключение. | +| `GET`, `POST` | `/devices//breaks/` | Ежедневные перерывы (например, Обед 12:00 - 13:00). | +| `DELETE` | `/devices//breaks//` | Удалить перерыв. | +| `GET`, `POST` | `/devices//shifts/` | Настройка смен (при `has_multiple_shifts=True` у устройства). | +| `DELETE` | `/devices//shifts//` | Удалить смену. | + +### 💻 Пример на Python: Настройка расписания +```python +device_id = 1 +headers = {"Authorization": f"Api-Key {API_KEY}"} + +# 1. Добавляем обед +requests.post(f"{BASE_URL}/devices/{device_id}/breaks/", headers=headers, json={ + "start_time": "12:00:00", + "end_time": "13:00:00", + "description": "Обеденный перерыв" +}) + +# 2. Добавляем исключение (выходной / праздник) +requests.post(f"{BASE_URL}/devices/{device_id}/schedule-exceptions/", headers=headers, json={ + "date": "2026-05-01", + "end_date": "2026-05-01", + "is_working": False, + "is_maintenance": False, + "description": "День Труда" +}) +``` + +--- + + +## 4. Аналитика и Цифровой двойник +Тяжелые вычислительные эндпоинты для получения отчетов и метрик. + +| Метод | Эндпоинт | Описание | +|---|---|---| +| `GET` | `/analytics/` | Сводная аналитика. Требует параметры `?device_id=...&start_date=...&end_date=...`. Возвращает объемы, массу, таймлайн, циклы, телеметрию (JSON). | +| `POST` | `/analytics/recalculate/` | Полный пересчет аналитики (сборка циклов и простоев). Ожидает JSON: `device_id`, `start_date`. Запускается в фоне. | + +--- + + +## 5. Видеоархив, Карты и Очистка данных +Все, что связано с видео, треками и управлением сырыми данными устройства. + +| Метод | Эндпоинт | Описание | +|---|---|---| +| `GET` | `/devices//available-dates/` | Массив дат (YYYY-MM-DD), за которые есть загруженные данные. | +| `GET` | `/devices//folders/` | Список папок архива (кусков видео по 1 часу). | +| `GET` | `/devices//folders//detections/` | Координаты рамок (Bounding Boxes) для рисования поверх видеоплеера. | +| `GET` | `/devices//video-frame/?timestamp=...` | Поиск видеофайла и секунды для перемотки по точному времени. | +| `GET` | `/devices//trajectory/?start_date=...&end_date=...`| Координаты GPS для отрисовки линии маршрута на карте. | +| `POST`| `/devices//upload-archive/` | Ручная загрузка оффлайн `.zip` архива. Возвращает Streaming HTTP с логами распаковки. | +| `GET` | `/devices//alerts/` | Список последних экстренных событий (Алертов) от устройства. | +| `POST`| `/devices//clear-data/` | **Опасная операция.** Очистка данных устройства. JSON: `{"mode": "all"}` или `{"mode": "date", "date": "..."}`. | + +--- \ No newline at end of file diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..0408d9f --- /dev/null +++ b/Home.md @@ -0,0 +1 @@ +1 странийца \ No newline at end of file