Последнее обновление: 2026-02-21
Назначение: Основной API для мобильного приложения — автомобили, заказы, файлы, курсы валют, вебхуки Bitrix24.
Стек: FastAPI 2.0, SQLAlchemy (async), Alembic, MinIO, Redis, Prometheus
Порт: 8000
БД: stageplus (Patroni 192.168.100.130:5000)
Префикс: /api/v1
| Метод | Путь | Описание | Доступ |
|---|---|---|---|
| GET | /cars |
Список авто с фильтрами, пагинацией, showcase-режим | auth |
| GET | /cars/brands |
Уникальные марки с количеством | auth |
| GET | /cars/brands/{brand}/models |
Модели марки | auth |
| GET | /cars/favorites |
Избранные авто пользователя | auth |
| GET | /cars/{id} |
Детали авто + cost estimate | auth |
| POST | /cars/{id}/favorite |
Добавить в избранное | auth |
| DELETE | /cars/{id}/favorite |
Убрать из избранного | auth |
| GET | /orders |
Список заказов (клиент — свои, менеджер — все) | auth |
| GET | /orders/{id} |
Детали заказа + timeline статусов | auth |
| POST | /files/upload |
Загрузка файла в MinIO (+ thumbnail) | auth |
| GET | /files/{id} |
Метаданные файла | auth |
| GET | /files/{id}/download |
Скачивание файла | auth |
| GET | /rates |
Курсы валют (CBR USD/EUR + ATB JPY/CNY) | auth |
| POST | /webhooks/bitrix |
Входящий webhook Bitrix24 | token |
| GET | /health |
Healthcheck | public |
| GET | /metrics |
Prometheus метрики | public |
Car — cars table:
id (UUID PK), ajes_lot_id (unique), make, model, year, country (enum: japan/korea/china)engine_volume, fuel_type, transmission, drive, body_type, horsepower, color, mileageauction_name, auction_date, auction_grade, equipmentstart_price, sold_price (JPY/KRW/CNY)status (enum: available/sold/reserved/in_transit/delivered)photos (JSONB: {urls: [...], keys: [...]})raw_data (JSONB), source_urlCarFavorite — car_favorites: user_id (no FK, IAM DB) + car_id
Order — orders table:
id, user_id, contact_phone, bitrix_deal_id (unique)car_id (FK → cars), car_descriptionstatus (enum: request → search → won → payment → documents → shipping → in_transit → customs → delivery → completed/cancelled)bitrix_data (JSONB: title, stage, car details, products, contract)OrderStatusHistory — order_status_history: order_id, status, comment, created_at
File — files table:
id, uploaded_by, original_name, mime_type, size_bytesbucket (default: stageplus), object_key ({type}/{year}/{month}/{uuid}.{ext})width, height, thumbnail_keyCore API содержит car_calculator.py — расчёт таможенной пошлины, утильсбора, сборов для отображения estimate на карточке авто.
Назначение: Identity & Access Management — регистрация, аутентификация (OTP + JWT), управление пользователями, push-уведомления, версии приложения.
Стек: FastAPI, SQLAlchemy (async), jose (JWT), bcrypt, Firebase Admin SDK
Порт: 8010
БД: stageplus_iam
| Метод | Путь | Описание | Доступ |
|---|---|---|---|
| POST | /auth/send-otp |
Отправить OTP код | public |
| POST | /auth/verify-otp |
Проверить OTP, получить JWT | public |
| POST | /auth/refresh |
Обновить access token | auth |
| GET | /users/me |
Профиль текущего пользователя | auth |
| PATCH | /users/me |
Обновить профиль | auth |
| POST | /notifications/register-token |
Регистрация FCM токена | auth |
| DELETE | /notifications/unregister-token |
Удаление FCM токена | auth |
| GET | /app-versions |
Список версий приложения | auth |
| GET | /internal/users/{id} |
Внутренний API для других сервисов | internal |
| GET | /internal/users/by-phone/{phone} |
Поиск по телефону | internal |
| GET | /internal/device-tokens/{user_id} |
FCM токены пользователя | internal |
User — users:
id (UUID), phone (unique), password_hash, role (enum: client/manager/admin)first_name, last_name, avatar_file_idis_active, is_online, last_seenbitrix_contact_id, app_version, app_platformDeviceToken — device_tokens:
user_id (FK → users), token (unique), platform (ios/android)AppVersion — app_versions:
version, commit_hash, platform, build_number, notes/send-code для отправки кодаНазначение: Реал-тайм чат между клиентами и менеджерами. WebSocket + Redis pub/sub для масштабирования.
Стек: FastAPI, WebSocket, Redis pub/sub, SQLAlchemy, Firebase
Порт: 8020
БД: stageplus_chat
| Метод | Путь | Описание | Доступ |
|---|---|---|---|
| GET | /chats |
Список чатов пользователя | auth |
| POST | /chats |
Создать чат | auth |
| GET | /chats/{id} |
Детали чата | auth |
| GET | /messages |
Сообщения чата (пагинация) | auth |
| POST | /files/upload |
Загрузка файла для чата | auth |
| WS | /ws?token=JWT |
WebSocket соединение | JWT |
Входящие сообщения (client → server):
ping → pongtyping — индикатор набора текстаsend_message — отправка сообщения (text, image, document, voice, car_link)edit_message — редактированиеdelete_message — удаление (soft delete)read — отметить прочитаннымИсходящие сообщения (server → client):
new_message — новое сообщение в чатеmessage_edited, message_deletedtyping — кто-то печатаетread — кто-то прочиталonline — статус online/offlinenew_message_unassigned — для менеджеров (непривязанный чат)Chat — chats:
id, type (private/group), name, is_activelast_message_id, last_message_atChatMember — chat_members:
chat_id, user_id, role (member/admin)is_muted, unread_count, last_read_message_idMessage — messages:
id, chat_id, sender_id, type (text/image/document/video/voice/car_link/system)text, reply_to_id, car_idis_edited, is_deletedMessageFile — message_files:
message_id, file_id, sort_orderoriginal_name, mime_type, object_key, thumbnail_keyget_user_info, get_users_batch, find_user_by_phone, get_user_device_tokensget_car для обогащения car_link сообщенийchat:ws:* для broadcast между инстансамиНазначение: Расчёт полной стоимости авто из Японии «под ключ» — таможенная пошлина, утилизационный сбор, логистика.
Стек: FastAPI (stateless)
Порт: 8095
| Метод | Путь | Описание |
|---|---|---|
| POST | /calculate |
Полный расчёт стоимости |
| GET | /rates |
Текущие курсы JPY/RUB, EUR/RUB |
| GET | /health |
Healthcheck |
Входные параметры: price_jpy, engine_volume, year, make, model, horsepower (опционально)
Расчёт включает:
Курсы: CBR (EUR/RUB) + ATB банк (JPY/RUB), кэш 1 час.
Назначение: Справочник технических характеристик автомобилей (марка, модель, объём, мощность). Данные парсятся с drom.ru.
Стек: FastAPI, SQLAlchemy, Playwright (парсер)
Порт: 8094
БД: car_specs (отдельный сервер db3.zubat.ru)
| Метод | Путь | Описание |
|---|---|---|
| GET | /specs |
Поиск спецификаций (make, model, engine_volume) |
| GET | /specs/{id} |
Спецификация по ID |
| POST | /specs |
Создать запись |
| POST | /specs/bulk |
Массовый импорт |
| GET | /brands |
Список марок |
| GET | /brands/{make}/models |
Модели марки |
| POST | /parse/refresh |
Запуск парсинга drom.ru (background) |
| GET | /parse/status |
Статус парсинга |
CarSpec — car_specs:
id, make, model, generationyear_from, year_to, engine_volume, fuel_typehorsepower, engine_code(make, model, engine_volume, fuel_type, generation)Назначение: Парсер аукционных лотов с AJES (auc.stage-plus.ru). Использует Playwright для управления браузером, т.к. AJES — SPA с AJAX загрузкой данных.
Стек: Playwright (Chromium), asyncpg, Pydantic
Запуск: cron-скрипты (run_full_sync.py, run_incremental.py, run_daily_stats.py)
БД: stageplus (пишет в таблицу cars)
/aj_neo (основной интерфейс аукциона)ajx.dataReady(...)) через Playwright response interceptorAjesLot dataclasscars по ajes_lot_id (ON CONFLICT DO UPDATE)| Метод | Путь | Описание |
|---|---|---|
| POST | /sync |
Запуск синхронизации (background) |
| GET | /status |
Статус текущей синхронизации |
~50 марок (Toyota, Nissan, Honda, BMW, Mercedes, Tesla и др.)
Назначение: Telegram бот для доставки OTP-кодов аутентификации (dev/staging среда).
Стек: FastAPI, Telegram Bot API (httpx)
Порт: 8095
| Метод | Путь | Описание |
|---|---|---|
| POST | /send-code |
Отправить код {phone, code} в Telegram группу |
| GET | /health |
Healthcheck |
BOT_TOKEN — токен Telegram ботаCHAT_ID — ID группы для отправки кодовНазначение: Мобильное приложение Stage+ для iOS и Android.
Стек: Flutter 3.x, Riverpod, Dio, WebSocket, Firebase Messaging, GoRouter
dio — HTTP клиентweb_socket_channel — WebSocket для чатаflutter_riverpod — state managementgo_router — навигацияfirebase_messaging — push-уведомленияflutter_secure_storage — хранение JWTcached_network_image — кэшированные изображенияimage_picker, file_picker — выбор файловНазначение: Админ-панель для менеджеров Stage+.
Стек: React 19, Vite, TypeScript, TanStack Query, Zustand, Firebase
Все Python-сервисы используют:
pydantic-settings с env_prefix="SP_" и .env файлами/metrics)/health)logging_config.py с JSON structured loggingSP_SECRET_KEY)| Переменная | Описание |
|---|---|
SP_DATABASE_URL |
PostgreSQL connection string |
SP_REDIS_URL |
Redis URL |
SP_SECRET_KEY |
JWT signing key (shared) |
SP_MINIO_ENDPOINT |
MinIO host:port |
SP_MINIO_ACCESS_KEY |
MinIO access key |
SP_MINIO_SECRET_KEY |
MinIO secret key |
SP_MINIO_PUBLIC_URL |
Public URL для файлов |
FIREBASE_CREDENTIALS |
Путь к firebase-service-account.json |
Назначение: Отслеживание позиций судов Phenix Asia (перевозка авто Япония → Владивосток). AIS-данные для отображения на карте в мобильном приложении.
Стек: FastAPI, httpx, BeautifulSoup4
Порт: 8000
Репо: stageplus/vessel-tracking-service
БД: нет (stateless, in-memory cache)
Ingress: /api/v1/vessels, /api/v1/schedule
| Судно | IMO | MMSI | MarineTraffic |
|---|---|---|---|
| AMUR | 9036600 | 667002124 | ссылка |
| ANGARA | 9124043 | 667001861 | ссылка |
| BAIKAL | 9167617 | 667001819 | ссылка |
| IRTYSH | 9031789 | 667002343 | ссылка |
| OLKHON | 9031791 | 667001269 | ссылка |
| SELENGA | 9007477 | 352004292 | ссылка |
| URAL | 9238246 | 667001322 | ссылка |
| YENISEY | 8911267 | 667001923 | ссылка |
| Источник | URL | Данные | Метод |
|---|---|---|---|
| myshiptracking.com | vessels/{name}-mmsi-{mmsi}-imo-{imo} |
AIS позиции (lat, lon, speed, course) | HTML scraping |
| phenix.asia | /schedule |
Расписание рейсов | HTML scraping (BeautifulSoup) |
Обновление позиций: каждые 60 минут (фоновый asyncio task).
| Метод | Путь | Описание | Доступ |
|---|---|---|---|
| GET | /vessels |
Список всех судов с текущими позициями | public |
| GET | /vessels/{mmsi} |
Позиция конкретного судна по MMSI | public |
| GET | /schedule |
Расписание Phenix Asia (парсинг таблицы) | public |
| POST | /refresh |
Принудительное обновление позиций | internal |
| GET | /health |
Healthcheck (статус, last_update, vessel_count) | public |
/vessels{
"vessels": [
{
"mmsi": "667002124",
"name": "AMUR",
"imo": "9036600",
"lat": 35.32565,
"lon": 139.71192,
"speed": 10.9,
"course": 225.0,
"destination": "VLADIVOSTOK",
"updated_at": "2026-02-22T07:00:00+00:00"
}
],
"last_update": "2026-02-22T07:00:00+00:00"
}
phenix.asia/schedule ──► BeautifulSoup ──► /schedule endpoint
myshiptracking.com ──► HTML regex ──► In-Memory Cache ──► /vessels endpoint
↑
asyncio task (1h)
stageplusstageplus (компонент vessel-tracking)