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

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

## Стек технологий
- **Фронтенд**: Next.js 14+ (App Router), React 18, TypeScript, Tailwind CSS
- **Бэкенд**: Go 1.22+, Chi router, PostgreSQL (pgx), Redis
- **Аутентификация**: JWT (access + refresh токены), bcrypt
- **Карты**: Leaflet + OSM (основной), MapLibre GL (запасной)
- **Платежи**: 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)