photoplaces/backend/docs/SPEC.md

PhotoPlaces — Техническое задание

Обзор проекта

Сервис онлайн-карты с отметками мест для фотосъёмки, аренды фотостудий и найма фотографов. Цель: запуск в России, затем международная экспансия.

Стек технологий

• Фронтенд: Next.js 14+ (App Router), React 18, TypeScript, Tailwind CSS
• Бэкенд: Go 1.22+, Chi router, PostgreSQL (pgx), Redis
• Аутентификация: JWT (access + refresh токены), bcrypt
• Карты: Яндекс Карты API (основной для РФ), MapLibre GL + OSM (запасной/международный)
• Платежи: CloudPayments (РФ), Stripe (международные)
• Файлы: S3-совместимое хранилище (MinIO локально, Selectel/Cloudflare R2 в проде)
• Деплой: Docker, docker-compose, GitHub Actions CI/CD

Архитектура

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Next.js   │────▶│   Go API    │────▶│ PostgreSQL  │
│  (Фронтенд) │     │  (Бэкенд)   │     │  (Основная) │
└─────────────┘     └─────────────┘     └─────────────┘
                           │                    │
                           ▼                    ▼
                    ┌─────────────┐     ┌─────────────┐
                    │    Redis    │     │   MinIO/S3  │
                    │  (Кеш,      │     │  (Картинки) │
                    │   Сессии)   │     │             │
                    └─────────────┘     └─────────────┘

Роли пользователей

Роль	Ключ	Разрешения
Суперадминистратор	superadmin	Полный доступ, управление всеми пользователями и системой
Модератор	moderator	Управление местами, пользователями (кроме админов и модераторов), модерация
Арендодатель	landlord	Добавление/редактирование своих студий (требует подтверждения)
Исполнитель	executor	Добавление/редактирование своих услуг (фото/видеосъёмка)
Заказчик	customer	Добавление/редактирование своих мест (требует подтверждения)
Гость	guest	Только просмотр карты, карточки мест недоступны

Типы мест

1. Место (place) — публичные локации для самостоятельной съёмки
2. Студия (studio) — арендуемые фотостудии с бронированием

Карточка места (PlaceCard)

• Основная информация: название, описание, адрес, координаты
• Информация о доступе: как добраться, парковка, общественный транспорт
• Медиа: фотогалерея, обложка
• Атрибуты: теги (стили съёмки), характеристики (освещение, пространство, оборудование)
• Рейтинг и отзывы
• Только для студий: цены, кнопка бронирования, ссылка на услуги исполнителей

Карточка услуги (ServiceCard) — для Исполнителей

• Информация об услуге: название, описание, цена, длительность
• Профиль исполнителя: биография, портфолио, рейтинг, отзывы
• Теги: стили фотосъёмки
• Контакты / интеграция бронирования

Пользовательские сценарии

Гость (неавторизован)

1. Видит полноэкранную схематическую карту
2. Видит своё местоположение (геолокация)
3. Видит других посетителей как зелёные выпуклые точки (некликабельные)
4. Не может нажимать на маркеры мест
5. Кнопка: «Зарегистрируйтесь, чтобы исследовать места»

Авторизованный пользователь (любая роль, кроме Гостя)

1. Видит все опубликованные маркеры на карте
2. Может фильтровать: тип, теги, рейтинг, характеристики, ценовой диапазон
3. Клик по маркеру → открывается PlaceCard / StudioCard
4. StudioCard: кнопка «Забронировать» → переход к бронированию
5. Может добавлять места (Заказчик) или студии (Арендодатель) → отправка на модерацию

Арендодатель

1. Форма «Добавить студию» → создаётся черновик
2. Модератор/Админ проверяет → публикует или отклоняет
3. Редактирование требует повторного подтверждения

Заказчик

1. Форма «Добавить место» → создаётся черновик
2. Модератор/Админ проверяет → публикует или отклоняет

Исполнитель

1. Создаёт карточку услуги (ServiceCard)
2. Публикуется сразу или после лёгкой модерации
3. Привязывается к карточкам студий

Провайдеры карт

• Карта: Leaflet + OpenStreetMap (через Nominatim для геокодинга)
• Тайлы: OpenStreetMap (бесплатно, без ключа)
• Геокодинг: Nominatim OpenStreetMap API (GeocodeReverse handler)

Платежи (CloudPayments)

• Студии: ежемесячная плата за размещение или комиссия с бронирований
• Исполнители: плата за продвижение
• Пользователи: донаты / премиум-функции (расширенные фильтры, сохранённые места)
• Виджет для разовых и регулярных платежей, вебхуки для статусов

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

• Ограничение запросов (in-memory rate limiter с очисткой старых записей)
• CORS, Helmet/CSP заголовки
• Валидация ввода (go-playground/validator)
• Параметризованные SQL-запросы (pgx)
• Валидация загружаемых файлов (тип, размер)
• Мягкое удаление (deleted_at)
• Проверка владельца ресурса: изменение/удаление места, услуги или брони доступно только владельцу, модератору или суперадминистратору
• JWT-аутентификация: access token (15 мин) + refresh token (30 дней, X-Refresh-Token заголовок)

Окружения

• Локальное: docker-compose (PostgreSQL, Redis, MinIO, Бэкенд, Фронтенд)
• Стенд: один сервер, Docker Compose, Let's Encrypt
• Продакшн: Kubernetes или Docker Swarm, CDN, WAF

Планы на будущее

• Мобильные приложения (React Native / Expo)
• ML-рекомендации мест
• Партнёрская программа для фотографов
• Redis-кеширование для карты и списков
• Геопоиск по радиусу с использованием PostGIS
• Модерация услуг исполнителей
• Система уведомлений (email/push)