new api

Author: nawinds

docs/api/admin.mdx

@@ -1,56 +1,150 @@
 ---
-sidebar_position: 2
+sidebar_position: 1
 title: API
 ---
 
-import HighlightParam from '@site/src/components/HighlightParam';
+# Smart Parking API (v2)
 
-# General API (v1.0)
+**Базовый URL:** `https://api.parktrack.live`
 
-**Base address:**
-<HighlightParam>`https://api.parktrack.live`</HighlightParam>
+API предоставляет доступ к системе интеллектуального поиска парковок, которая агрегирует данные из различных источников (камеры, внешние API и будущие интеграции) для определения текущей и прогнозируемой занятости парковок.
 
-:::warning Обновление API
-17 ноября документация `Cameras`, `Parking Zones` была обновлена, все изменения выделены жёлтым цветом.
-:::
+---
+
+## Основные принципы
+
+### 1. Модульная архитектура
+API разделён на независимые модули:
+
+- Основные сущности (`cameras`, `parking_zones`)
+- Данные во времени (`occupancy`, `forecasts`)
+- Навигация (`routing`)
+- Доступ и авторизация (`auth`, `users`, `subscriptions`, `partners`)
+- Интеграции (`data_sources`)
+
+Это позволяет масштабировать систему без ломки существующего функционала.
+
+---
+
+### 2. Обратная совместимость (MVP-first)
+Существующие эндпоинты (`cameras`, `parking_zones`) сохраняются, чтобы не ломать текущие интеграции.
+
+Новая функциональность добавляется в отдельных разделах.
 
-## Swagger версия
+---
 
-Документация API также доступна в Swagger. Там можно будет поиграться с API и вручную поотправлять запросы, когда API сервер будет готов.
+### 3. Разделение данных по времени
+В системе явно разделены:
 
-[Открыть документацию в Swagger](https://swagger.parktrack.live)
+- **Статические данные** → камеры, зоны
+- **Динамические данные** → занятость (история и текущее состояние)
+- **Предсказания** → прогнозы
 
-:::info Предупреждение
-Swagger может содержать неточности или ошибки, приоритетной считать документацию на этом сайте.
-:::
+---
 
-## Общие ошибки
+### 4. Поддержка нескольких источников данных
+Система проектируется с учётом разных источников:
 
-| Код     | Тип                      | Описание                                                                          |
-|---------|--------------------------|-----------------------------------------------------------------------------------|
-| **400** | `Bad Request`            | Невалидный JSON или неверные типы полей.                                          |
-| **401** | `Unauthorized`           | Отсутствует или просрочен токен. Укажи `Authorization: Bearer <token>`.           |
-| **403** | `Forbidden`              | У пользователя нет прав создавать камеры. Проверь роли/права API-токена.          |
-| **415** | `Unsupported Media Type` | Неверный `Content-Type`. Используй `application/json`.                            |
-| **500** | `Internal Server Error`  | Необработанная ошибка сервера. Повтори позже; при повторе — обратись в поддержку. |
-| **503** | `Service Unavailable`    | Сервис временно недоступен/перезапускается. Повтори запрос позднее.               |
+- Камеры (MVP)
+- Парктроники (в будущем)
+- Навигационные данные (в будущем)
+- Данные об оплатах (в будущем)
 
-Более подробное описание ошибки возвращается в JSON в ключе `error_description`, например:
+Каждый источник может иметь разный уровень достоверности.
+
+---
+
+## Формат времени
+
+Все временные значения передаются в формате **UTC ISO 8601**:
+
+```
+2025-10-08T09:12:00Z
+```
+
+---
+
+## 🔐 Авторизация
+
+Большинство эндпоинтов требуют заголовок:
+
+```
+Authorization: Bearer <token>
+```
+
+Типы токенов:
+- Системный токен
+- Пользовательский токен
+- Партнёрский токен
+
+---
+
+## ❗ Общие ошибки
+
+| Код | Тип | Описание |
+|-----|-----|----------|
+| 400 | Bad Request | Невалидный JSON или типы данных |
+| 401 | Unauthorized | Отсутствует или неверный токен |
+| 403 | Forbidden | Недостаточно прав |
+| 404 | Not Found | Ресурс не найден |
+| 415 | Unsupported Media Type | Используй `application/json` |
+| 422 | Unprocessable Entity | Ошибка валидации |
+| 500 | Internal Server Error | Ошибка сервера |
+| 503 | Service Unavailable | Сервис временно недоступен |
+
+Пример ответа с ошибкой:
 
 ```json
-{ "error_description": "Unsupported Media Type: expected application/json" }
+{
+  "error_description": "Unsupported Media Type: expected application/json"
+}
 ```
 
-## Формат данных
+---
+
+## 📦 Разделы API
+
+### Основные сущности
+- Cameras
+- Parking Zones
 
-### Время
+### Данные о занятости
+- Occupancy (история и текущее состояние)
+- Forecasts (прогнозы)
 
-Время передается в UTC в строковом представлении в формате ISO 8601, с постфиксом Z.
+### Навигация
+- Routing (поиск парковки и построение маршрутов)
 
-Например, `2025-10-08T09:12:00Z`.
+### Доступ
+- Auth
+- Users
+- Subscriptions
+- Partners
 
-### Опорные точки
+### Интеграции
+- Data Sources
 
-Для упрощения рендеринга парковочных зон, порядок выбора 4 опорных точек записывается Labeler
-при разметке. Пользователю должно показываться сообщение, что отмечать точки нужно по часовой стрелке.
-Сохраненный порядок точек должен сохраняться при передаче данных, а также при хранении на сервере.
+### Дополнительно
+- Feedback
+- Admin
+- Analytics
+- System
+
+---
+
+## 🚀 Версионирование
+
+Текущая версия API: `v1 (MVP+)`
+
+В будущем изменения будут вводиться без ломки существующих эндпоинтов.
+
+---
+
+## 🔮 Планируемые расширения
+
+- ML-прогнозирование занятости парковок
+- Выбор оптимальной парковки с учётом ETA
+- Реалтайм-мониторинг камер и распознавания
+- Интеграция с внешними источниками данных (навигация, каршеринг, оплаты)
+
+---