cubenet_backend/QUICKSTART.md

# 🚀 Quickstart - Cubenet Backend

## Структура архитектуры (готовая к использованию!)

```
REST Client → API Gateway (8000) ──gRPC→ API (8001) ──gRPC→ Microservices (13000+)
                                         ↓
                                   User Service (13001)
```

## 🎯 Три простых шага для запуска

### Шаг 1: Откройте три терминала

**Терминал 1 - User Service (gRPC на порту 13001):**
```bash
cargo run -p user_service
```

**Терминал 2 - API (на порту 8001):**
```bash
cargo run -p api
```

**Терминал 3 - API Gateway (REST + Swagger на порту 8000):**
```bash
cargo run -p api_gateway
```

## ✨ Доступ к API

### 📊 Swagger UI (интерактивная документация)
```
http://localhost:8000/swagger-ui
```

### 📋 OpenAPI JSON docs
```
http://localhost:8000/api-docs
```

### 🧪 Тестирование endpoints

**Health Check:**
```bash
curl http://localhost:8000/api/health
# Ответ: {"status":"OK"}
```

**Получить пользователей:**
```bash
curl http://localhost:8000/api/users
# Ответ: [{"id":1,"name":"Alice",...}, ...]
```

**Создать пользователя:**
```bash
curl -X POST http://localhost:8000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Charlie","email":"charlie@example.com"}'
```

## 📚 Документация

| Файл | Назначение |
|------|-----------|
| **README.md** | Главная документация |
| **ARCHITECTURE.md** | Подробная архитектура системы |
| **MICROSERVICE_GUIDE.md** | Создание новых микросервисов |
| **PORT_ALLOCATION.md** | Управление портами |

## 🛠️ Создание нового микросервиса

### Быстро (5 минут)

```bash
# 1. Копировать шаблон
cp -r microservices/template_service microservices/my_service

# 2. Обновить Cargo.toml
sed -i 's/template_service/my_service/g' microservices/my_service/Cargo.toml

# 3. Добавить в Cargo.toml (workspace members):
# "microservices/my_service"

# 4. Выбрать порт (13002-14000)
# 5. Реализовать логику
# 6. Скомпилировать
cargo check
```

Подробнее см. **MICROSERVICE_GUIDE.md**

## 🔐 Порты (выделенные диапазоны)

| Компонент | Порт | Статус |
|-----------|------|--------|
| API Gateway | 8000 | ✓ REST |
| API | 8001 | ✓ REST |
| User Service | 13001 | ✓ gRPC |
| Микросервисы | 13002-14000 | ✓ Доступны |

## 📦 Что входит в проект

✅ **REST API** - Axum веб-фреймворк  
✅ **Swagger UI** - Автоматическая документация  
✅ **gRPC** - Inter-service communication (Tonic)  
✅ **Proto Buffers** - Типобезопасные структуры  
✅ **Microservices** - User Service как пример  
✅ **Template** - Шаблон для новых сервисов  
✅ **Logging** - Встроенный Tracing  

## 🐛 Отладка

### Включить подробные логи
```bash
RUST_LOG=debug cargo run -p api_gateway
```

### Проверить что порты свободны (Linux/Mac)
```bash
lsof -i :8000
lsof -i :13001
```

### Проверить gRPC endpoints
```bash
grpcurl -plaintext localhost:13001 list
```

## ⚡ Полезные команды

```bash
# Проверить что всё компилируется
cargo check

# Собрать всё
cargo build

# Собрать оптимизированный релиз
cargo build --release

# Запустить тесты
cargo test

# Форматировать код
cargo fmt

# Проверить ошибки линтера
cargo clippy
```

## 🎓 Примеры использования

### Пример 1: Вызвать gRPC User Service напрямую

```bash
# Если установлен grpcurl
grpcurl -plaintext \
  -d '{}' \
  localhost:13001 user.UserService/GetUsers
```

### Пример 2: Создать Product Service

```bash
# 1. Копировать шаблон
cp -r microservices/template_service microservices/product_service

# 2. Создать proto файл
cat > shared_proto/proto/product.proto << 'EOF'
syntax = "proto3";
package product;

service ProductService {
  rpc GetProducts(Empty) returns (ProductList);
}

message Empty {}
message Product { int32 id = 1; string name = 2; }
message ProductList { repeated Product products = 1; }
EOF

# 3. Обновить shared_proto/src/lib.rs
# 4. Обновить shared_proto/build.rs
# 5. Реализовать сервис на 13002
# 6. Скомпилировать и запустить
```

## 💡 Советы

1. **Используйте Swagger UI** для тестирования - очень удобно
2. **Читайте логи** - там видны все подключения и ошибки
3. **Proto files** - это контракт между сервисами, храните их в `shared_proto`
4. **Порты** - не забудьте обновить `PORT_ALLOCATION.md` при добавлении нового сервиса
5. **Логирование** - используйте `tracing::info!()` вместо `println!()`

## ❓ Часто задаваемые вопросы

**Q: Какие требования для запуска?**  
A: Rust 1.70+ и Cargo. Всё остальное установится автоматически.

**Q: Почему 13000-14000 для микросервисов?**  
A: Это стандартный диапазон для внутреннего использования, 8000+ зарезервирован для REST.

**Q: Как добавить свой микросервис?**  
A: Читайте MICROSERVICE_GUIDE.md - там всё подробно описано.

**Q: Как изменить порты?**  
A: Отредактируйте `src/main.rs` в каждом компоненте и обновите `PORT_ALLOCATION.md`.

## 📞 Поддержка

Если что-то не работает:
1. Проверьте что все терминалы открыты
2. Посмотрите логи (особенно при `RUST_LOG=debug`)
3. Убедитесь что порты свободны (`lsof -i`)
4. Читайте документацию в ARCHITECTURE.md

---

**Готово к использованию! 🎉**

Откройте Swagger UI в браузере и начните тестировать API:
```
http://localhost:8000/swagger-ui
```