Markuiz Docs

Единая документация Маркуйза: архитектура, API, OAuth, MarkuizUI, realtime-чаты и базовые правила интеграции. Здесь собраны практические примеры для разработчиков и авторов приложений.

Что такое Markuiz

Markuiz — социальная платформа с профилями, публикациями, комментариями, подписками, уведомлениями, личными чатами, OAuth-приложениями, КуйзВидео и игровым разделом.

Frontend

Основная оболочка работает как SPA: маршруты профилей и разделов обслуживаются одной HTML-оболочкой.

Backend

HTTP API построен на Flask. Авторизация поддерживает JWT в cookie/header, CSRF-защиту и отдельные OAuth endpoints.

API

API использует JSON там, где не передаются файлы. Для защищённых запросов нужна действующая сессия пользователя.

Авторизация

GET  /api/auth/me
POST /api/auth/login
POST /api/auth/logout
POST /api/auth/verify-2fa

Пользователи

GET    /api/users/<username>
GET    /api/users/<username>/followers
GET    /api/users/<username>/following
POST   /api/users/<username>/follow
GET    /api/users/<username>/posts
PUT    /api/users/me
DELETE /api/users/me

Публикации и социальные действия

POST /api/reports
GET  /api/reports
POST /api/posts/<post_id>/bookmark
GET  /api/users/me/bookmarks
GET  /api/users/me/drafts

Личные чаты

GET  /api/chats
GET  /api/chats/unread-count
GET  /api/chats/<username>/messages
POST /api/chats/<username>/messages
POST /api/chats/<username>/read
POST /api/chats/<username>/typing
GET  /api/chats/<username>/status
POST /api/chats/<username>/block
DELETE /api/chats/<username>/block

Realtime

GET /api/realtime

Используется для событий чатов и обновлений интерфейса. Клиент должен иметь fallback-поллинг для случаев, когда SSE недоступен.

OAuth

OAuth-приложение не получает пароль пользователя Маркуйза. Пользователь проходит авторизацию на стороне Markuiz, после чего приложение получает authorization code и обменивает его на token.

Поток

1. GET  /sdk/oauth/login?appid=CLIENT_ID&state=STATE
2. POST /sdk/oauth/authorize
3. callback приложения: /auth/markuiz/callback?code=CODE&state=STATE
4. POST /sdk/oauth/token
5. GET  /api/oauth/user

MarkuizUI

MarkuizUI — визуальная система проекта. Компоненты должны выглядеть одинаково на мобильном и ПК.

Liquid Glass

Полупрозрачные поверхности, мягкий blur, тонкая граница и аккуратная глубина.

Touch first

Интерактивные элементы на телефоне имеют удобную область нажатия, safe-area и поддержку экранной клавиатуры.

Темы

Системная, светлая и тёмная тема интерфейса. Для чатов может использоваться отдельный фон.

Диалоговые окна

Для подтверждений, ошибок и ввода используются собственные модальные окна вместо браузерных alert/confirm/prompt.

Базовый CSS

button, a, [role="button"] {
  touch-action: manipulation;
  -webkit-tap-highlight-color: transparent;
}

img, video, iframe, canvas {
  max-width: 100%;
}

Безопасность

Механизм	Назначение
JWT	Сессионная авторизация пользователя.
CSRF	Защита изменяющих запросов при cookie-auth.
2FA	Дополнительная защита входа и админки.
OAuth state	Защита callback от подмены OAuth-сессии.
Rate limiting	Ограничение частоты чувствительных запросов.

Чаты

Чат поддерживает realtime-события, вложения, реакции, блокировку пользователей и управление историей.

События

После действий, влияющих на список или сообщения, интерфейс должен обновляться без F5. SSE является основным каналом, лёгкий fallback-поллинг — запасным.