ridebus-admin/QUICKSTART.md

# 🚀 Быстрый старт

## За 5 минут к рабочему API

### Шаг 1: Подготовка
```bash
# Убедитесь, что установлен Docker
docker --version
docker-compose --version

# Если нет - установите:
# Ubuntu/Debian:
sudo apt update
sudo apt install docker.io docker-compose

# Добавьте пользователя в группу docker
sudo usermod -aG docker $USER
# Перелогиньтесь после этого
```

### Шаг 2: Настройка
```bash
# Создайте .env файл
cp .env.example .env

# Сгенерируйте безопасный пароль
openssl rand -base64 32

# Отредактируйте .env и вставьте сгенерированные пароли в DB_PASSWORD и ADMIN_PASSWORD
nano .env
```

### Шаг 3: Запуск
```bash
# Запустите все сервисы
docker-compose up -d

# Дождитесь инициализации (30-60 секунд)
docker-compose logs -f postgres

# Когда увидите "database system is ready to accept connections" - нажмите Ctrl+C
```

### Шаг 4: Проверка
```bash
# Проверьте API
curl http://localhost:3000/health

# Ожидаемый ответ:
# {"status":"healthy","timestamp":"2025-11-19T...","version":"1.0.0"}

# Проверьте базу данных
curl -H "X-API-Key: dev_key_12345678" http://localhost:3000/api/v1/sync/status
```

### Шаг 5: Откройте админ-панель
Откройте в браузере: http://localhost:3001

Войдите под `admin` и паролем из `ADMIN_PASSWORD` в `.env`.

**Готово! 🎉**

---

## Первые данные

### 1. Создайте первый маршрут
Откройте админ-панель → Маршруты → "Добавить маршрут"

Или через API:
```bash
curl -X POST http://localhost:3000/api/v1/routes \
  -H "X-API-Key: dev_key_12345678" \
  -H "Content-Type: application/json" \
  -d '{
    "route_number": "1",
    "name": "Центр - Вокзал",
    "type": "bus",
    "color": "#FF6B6B"
  }'
```

### 2. Добавьте остановки
Откройте админ-панель → Остановки → Кликните на карту

Или через API:
```bash
curl -X POST http://localhost:3000/api/v1/stops \
  -H "X-API-Key: dev_key_12345678" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Площадь Свободы",
    "latitude": 55.4869,
    "longitude": 28.7856,
    "address": "Центр города"
  }'
```

### 3. Проверьте геопоиск
```bash
# Найдите остановки в радиусе 500м от центра Полоцка
curl -H "X-API-Key: dev_key_12345678" \
  "http://localhost:3000/api/v1/stops/nearby?lat=55.4869&lon=28.7856&radius=500"
```

---

## Доступ из локальной сети

### Вариант 1: Прямой доступ (не безопасно для интернета)
```bash
# Узнайте IP вашего сервера
ip addr show | grep "inet "

# Доступ с других устройств в той же сети:
# http://YOUR_SERVER_IP:3000 - API
# http://YOUR_SERVER_IP:3001 - Admin
```

### Вариант 2: Cloudflare Tunnel (рекомендуется для интернета)
```bash
# Установите cloudflared
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
sudo mv cloudflared /usr/local/bin/
sudo chmod +x /usr/local/bin/cloudflared

# Авторизуйтесь
cloudflared tunnel login

# Создайте туннель
cloudflared tunnel create polotsk-transit

# Создайте конфиг
cat > ~/.cloudflared/config.yml << EOF
tunnel: YOUR_TUNNEL_ID
credentials-file: /home/$USER/.cloudflared/YOUR_TUNNEL_ID.json

ingress:
  - hostname: api.yourdomain.com
    service: http://localhost:3000
  - hostname: admin.yourdomain.com
    service: http://localhost:3001
  - service: http_status:404
EOF

# Запустите туннель
cloudflared tunnel run polotsk-transit
```

---

## Создание API ключа для вашего приложения

```bash
# Войдите в PostgreSQL
docker exec -it polotsk-transit-db psql -U transit_admin -d polotsk_transit

# Создайте новый API ключ
INSERT INTO api_keys (key, app_name, rate_limit, is_active)
VALUES ('YOUR_GENERATED_KEY_HERE', 'My iOS App', 10000, true);

# Проверьте
SELECT * FROM api_keys;

# Выйдите
\q
```

Генерация безопасного ключа:
```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

---

## Остановка и удаление

```bash
# Остановить все сервисы
docker-compose down

# Удалить все данные (ОСТОРОЖНО!)
docker-compose down -v

# Удалить образы
docker-compose down --rmi all
```

---

## Частые проблемы

**"Cannot connect to database":**
```bash
# Проверьте, что PostgreSQL запущен
docker-compose ps
docker-compose logs postgres

# Перезапустите
docker-compose restart postgres
```

**"Port already in use":**
```bash
# Измените порты в docker-compose.yml
# Например, вместо "3000:3000" используйте "3001:3000"
```

**"Permission denied":**
```bash
# Убедитесь, что пользователь в группе docker
sudo usermod -aG docker $USER
# Перелогиньтесь
```

---

## Следующие шаги

1. Прочитайте полный README.md
2. Добавьте свои маршруты и остановки
3. Настройте расписания (в следующей версии)
4. Интегрируйте API в ваше мобильное приложение
5. Настройте безопасный доступ через Cloudflare

**Удачи! 🚀**