photoplaces/CONTRIBUTING.md

Contributing

Стек

Компонент	Технология
Фронтенд	Next.js 14, React 18, TypeScript, Tailwind CSS
Бэкенд	Go 1.22, Chi router, pgx v5
База данных	PostgreSQL 16 + PostGIS
Кеш	Redis 7
Файлы	MinIO (S3-совместимое)
Аутентификация	JWT (access + refresh токены)
Инфраструктура	Docker, docker-compose

Начало разработки

git clone http://192.168.88.96:10880/foxtime/photoplaces.git
cd photoplaces

# 1. Поднять инфраструктуру (БД, Redis, MinIO)
docker compose up -d postgres redis minio

# 2. Переменные окружения
cp backend/.env.example backend/.env
cp frontend/.env.local.example frontend/.env.local

# 3. Бэкенд (в терминале 1)
cd backend && go run ./cmd/api

# 4. Фронтенд (в терминале 2)
cd frontend && npm install && npm run dev

Правила работы с git

• Ветки: feature/краткое-описание, fix/краткое-описание
• Коммиты на русском, в настоящем времени
• Перед коммитом: go vet ./..., npm run lint (бэкенд/фронтенд)
• Не коммитить deploy/env.prod (в .gitignore)
• Не коммитить backend/.env, frontend/.env.local

Сборка Docker

# Локальная сборка (проверка Dockerfile)
docker compose build backend
docker compose build frontend

# Полный продакшен
bash deploy/deploy.sh

Тестирование

make test-backend    # go test ./... -v -race
make test-frontend   # npm run test (когда появится)

Тестов пока нет — см. obsidian_data/Photoplaces_data/decision-test-strategy.md.

Миграции БД

make migrate        # накатить
make migrate-down   # откатить последнюю

Новая миграция: migrate create -ext sql -dir backend/migrations -seq название.

Структура бэкенда

backend/
  cmd/api/main.go          # точка входа
  internal/
    config/                # загрузка из env / _FILE (Docker secrets)
    log/                   # структурированное логирование (slog)
    models/                # структуры данных (User, Place, Booking...)
    repository/            # слой доступа к БД (pgx)
    services/              # бизнес-логика
    handlers/              # HTTP-обработчики (Chi router)
    middleware/             # JWT, rate limiter, CORS
    validator/             # кастомные валидаторы (go-playground)
  migrations/              # SQL-миграции
  docs/                    # API контракт, схема БД, ТЗ

Структура фронтенда

frontend/
  src/
    app/                   # Next.js App Router
      admin/               # панель модератора
      auth/                # логин/регистрация
      places/add/          # добавление места
      services/add/        # добавление услуги
      studios/add/         # добавление студии
    components/            # Header, MapView, PlaceForm
    hooks/                 # useAuth (AuthProvider)
    lib/                   # api.ts (клиент), map.ts (Leaflet)
    types/                 # TypeScript-интерфейсы

Документирование

• Go: package-level doc comment (// Package xxx) — обязательно для каждого пакета
• TypeScript: JSDoc (/** ... */) перед каждым экспортом
• Комментарии на русском языке
• Решения архитектуры — в Obsidian (obsidian_data/Photoplaces_data/)

Code Review

• Проверять обработку ошибок (все err должны быть обработаны)
• Проверять _FILE суффикс для Docker secrets в конфигах
• Проверять валидацию входных данных (go-playground/validator)
• Проверять rate limiting на публичных эндпоинтах
• Проверять авторизацию (владелец ресурса или admin/moderator)