# 🚀 Guia Completo: Configure e Faça Deploy do Orquestrador

**Tempo total: ~30 minutos**

Este guia leva você desde a configuração no Google Cloud Console até o deploy da aplicação online.

---

## 📋 Índice

1. [Pré-requisitos](#pré-requisitos)
2. [FASE 1: Google Cloud Console](#fase-1-google-cloud-console)
3. [FASE 2: Configurar Ambiente Local](#fase-2-configurar-ambiente-local)
4. [FASE 3: Testar Localmente](#fase-3-testar-localmente-opcional)
5. [FASE 4: Deploy no Cloud Run](#fase-4-deploy-no-cloud-run)
6. [FASE 5: Verificar e Testar](#fase-5-verificar-e-testar)
7. [Troubleshooting](#troubleshooting)

---

## ✅ Pré-requisitos

Antes de começar, você já deve ter:

- [ ] Google Cloud SDK instalado no seu PC
  - Windows: https://cloud.google.com/sdk/docs/install-windows
  - Verificar: Abra terminal e digite `gcloud --version`

- [ ] Acesso a um projeto GCP fornecido pela sua empresa
- [ ] Docker instalado (para testar localmente - opcional)
  - Download: https://www.docker.com/products/docker-desktop

- [ ] Git instalado no seu PC
- [ ] Python 3.11+ instalado

**Se não tiver algum, instale antes de continuar!**

---

# FASE 1: Google Cloud Console

**⏱️ Tempo: ~10 minutos**

Você vai configurar todos os recursos no Google Cloud Console. Siga cada passo na ordem.

---

## PASSO 1: Identificar Seu Projeto

1. Acesse: https://console.cloud.google.com/
2. No topo esquerdo, clique no **seletor de projeto**
3. Selecione o projeto fornecido pela sua empresa
4. **Copie e anote o Project ID** que aparece no topo
   ```
   Seu Project ID: _________________________________
   ```

---

## PASSO 2: Ativar APIs Necessárias

**Local:** Menu ☰ → "APIs e Serviços" → "APIs e serviços ativados"

Você vai ativar 6 APIs. Para cada uma:

1. Clique **"Ativar APIs e Serviços"** (botão azul no topo)
2. Digite o nome da API na caixa de busca
3. Clique na API
4. Clique **"Ativar"**
5. Aguarde ~1-2 minutos
6. Volte e repita para a próxima

### APIs para Ativar:

- [ ] **Cloud Run API**
- [ ] **Cloud Build API**
- [ ] **Cloud SQL Admin API**
- [ ] **Artifact Registry API** ⚠️ (busque em inglês)
- [ ] **Vertex AI API** (para usar LLM/Gemini)
- [ ] **Compute Engine API**

**✅ Confirmação:** Você deve ver todas as 6 APIs listadas em "APIs e serviços ativados"

---

## PASSO 3: Criar Cloud SQL (Banco de Dados PostgreSQL)

Seu banco de dados onde a aplicação vai armazenar dados.

### 3.1 - Acessar Cloud SQL

Menu ☰ → **"SQL"** (dentro de "Bancos de Dados")

### 3.2 - Criar Nova Instância

1. Clique **"Criar instância"**
2. Selecione **"PostgreSQL"**

### 3.3 - Configurar Instância

Preencha com os seguintes valores:

- **ID da instância**: `orquestrador-db`
- **Senha da instância**: Escolha uma senha **SEGURA** (ex: `Abc@123xyz!`)
  - ⚠️ **Copie e guarde em local seguro!**
  - Senha raiz: `_________________________________`

- **Versão do PostgreSQL**: `16` (ou `15`)
- **Região**: `us-central1` (mesmo de Cloud Run depois)
- **Disponibilidade zonal**: `Zona única` (está ok para começar)

### 3.4 - Configurar Conectividade

Na seção **"Conectividade"**:

1. Clique para expandir **"Conectividade"**
2. Marque ✓ **"IP público"**
3. Na seção **"Conexões autorizadas de redes"**, clique **"Criar rede"**
   - Nome: `cloudsql-network` (ou deixe padrão)
   - Clique **"Criar e voltar"**

⚠️ **Importante:** Isso permite que Cloud Run se conecte ao banco de dados.

### 3.5 - Criar Instância

1. Clique **"Criar"** (botão azul no final)
2. Aguarde **5-10 minutos** (status mudará de "criando..." para verde ✓)

---

## PASSO 4: Configurar Cloud SQL - Usuários e Banco de Dados

Quando a instância estiver **verde/pronta**:

### 4.1 - Obter Dados de Conexão

1. Clique no nome `orquestrador-db`
2. Copie o **Nome da conexão** (aparece parte superior):
   - Formato: `seu-projeto-id:us-central1:orquestrador-db`
   - Copie: `_________________________________`

3. Na aba **"Visão geral"**, encontre **"IP público"** na seção **"Conectividade"**
   - Copie: `_________________________________`

### 4.2 - Criar Usuário do Banco

Na aba **"Usuários e bancos de dados"**:

1. Clique **"Criar usuário"**
2. Preencha:
   - **Nome do usuário**: `orquestrador`
   - **Senha**: Escolha uma senha (ex: `Orm@2026!`)
   - ⚠️ **Copie e guarde!**
   - Senha do usuário orquestrador: `_________________________________`

3. Clique **"Criar"**

### 4.3 - Criar Banco de Dados

Na aba **"Usuários e bancos de dados"**, clique em **"Bancos de dados"**:

1. Clique **"Criar banco de dados"**
2. Preencha:
   - **Nome do banco de dados**: `orquestrador_db`
   - **Conjunto de caracteres**: `utf8mb4`
3. Clique **"Criar"**

---

## PASSO 5: Criar Conta de Serviço (Service Account)

Isso permite que Cloud Run se autentique no GCP.

### 5.1 - Ir para Credenciais

Menu ☰ → **"APIs e Serviços"** → **"Credenciais"**

### 5.2 - Criar Conta de Serviço

1. Clique **"Criar credenciais"** → **"Conta de serviço"**
2. Preencha:
   - **Nome da conta de serviço**: `orquestrador-app`
   - **ID da conta de serviço**: `orquestrador-app` (preenchido automaticamente)
3. Clique **"Criar e continuar"**

### 5.3 - Atribuir Permissões

Na tela de permissões:

1. Clique **"Selecionar uma função"**
2. Procure e selecione cada uma das funções abaixo. **Adicione todas**:
   - `Cliente do Cloud SQL`
   - `Desenvolvedor do Cloud Run`
   - `Gravador do Registro de Artefatos`

3. Clique **"Continuar"**
4. Clique **"Concluído"**

### 5.4 - Gerar Chave JSON

1. Volte para **"Credenciais"**
2. Clique na conta de serviço `orquestrador-app` (em "Contas de serviço")
3. Vá para a aba **"Chaves"**
4. Clique **"Adicionar chave"** → **"Criar nova chave"**
5. Selecione **"JSON"**
6. Clique **"Criar"**

⚠️ **Um arquivo JSON será baixado automaticamente!**

- Salve em: `D:\vitor\Pessoal\PJ\Orquestrador\service-account-key.json`
- **Não compartilhe este arquivo com ninguém!**

---

## PASSO 6: Criar Registro de Artefatos (Container Registry)

Repository para armazenar suas imagens Docker.

### 6.1 - Acessar Registro

Menu ☰ → **"Registro de Artefatos"** → **"Repositórios"**

### 6.2 - Criar Repositório

1. Clique **"Criar repositório"**
2. Preencha:
   - **Nome**: `orquestrador`
   - **Formato**: `Docker`
   - **Localização**: `us-central1` (mesmo do Cloud SQL)
3. Clique **"Criar"**

---

## ✅ Checklist - Fase 1 Concluída

Você deve ter anotado:

- [ ] Project ID: `_________________________________`
- [ ] Cloud SQL Connection Name: `_________________________________`
- [ ] Cloud SQL Public IP: `_________________________________`
- [ ] Cloud SQL User: `orquestrador`
- [ ] Cloud SQL Password: `_________________________________`
- [ ] Cloud SQL Root Password: `_________________________________`
- [ ] Cloud SQL Database: `orquestrador_db`
- [ ] Service Account JSON file baixado e salvo
- [ ] 6 APIs ativadas
- [ ] Registro de Artefatos criado

**Próximo: Fase 2 - Configurar Ambiente Local**

---

# FASE 2: Configurar Ambiente Local

**⏱️ Tempo: ~5 minutos**

Agora você vai configurar seu PC para comunicar com o GCP.

---

## PASSO 1: Autenticar com Google Cloud SDK

Abra **PowerShell** e execute:

```powershell
# Fazer login no Google Cloud
gcloud auth login

# Definir projeto padrão
gcloud config set project SEU-PROJECT-ID

# Exemplo:
gcloud config set project orquestrador-mvp-12345
```

Siga as instruções no navegador que abrir.

---

## PASSO 2: Configurar Autenticação de Conta de Serviço

Ainda no **PowerShell**:

```powershell
# Definir variável de ambiente para usar a conta de serviço
$env:GOOGLE_APPLICATION_CREDENTIALS = "D:\vitor\Pessoal\PJ\Orquestrador\service-account-key.json"

# Verificar que funcionou
gcloud auth list
```

---

## PASSO 3: Criar Arquivo `.env`

Este arquivo contém suas credenciais e configurações.

### 3.1 - Criar o Arquivo

Na raiz do projeto (`D:\vitor\Pessoal\PJ\Orquestrador\`), crie um arquivo chamado `.env` com:

```env
# ============================================
# CONFIGURAÇÕES DO GOOGLE CLOUD
# ============================================

PROJECT_ID=SEU-PROJECT-ID
GCP_REGION=us-central1

# ============================================
# CONFIGURAÇÕES DO BANCO DE DADOS
# ============================================

# URL de conexão direta (para testes locais)
DATABASE_URL=postgresql://orquestrador:SUA_SENHA@SEU_IP_PUBLICO:5432/orquestrador_db

# Nome da conexão Cloud SQL (para Cloud Run)
CLOUD_SQL_CONNECTION_NAME=seu-projeto:us-central1:orquestrador-db

# ============================================
# CONFIGURAÇÕES DE API
# ============================================

# Se usar Generative AI (Gemini)
# GOOGLE_API_KEY=sua-chave-api-aqui

# Se usar Mockaroo (dados fictícios)
# MOCKAROO_API_KEY=sua-chave-mockaroo-aqui

# ============================================
# OUTRAS CONFIGURAÇÕES
# ============================================

ENVIRONMENT=development
DEBUG=true
```

### 3.2 - Preencher com Seus Dados

Substitua os valores acima com:

- `SEU-PROJECT-ID` → seu Project ID do GCP
- `SUA_SENHA` → senha do usuário `orquestrador` no Cloud SQL
- `SEU_IP_PUBLICO` → IP público do Cloud SQL

**Exemplo completo:**

```env
PROJECT_ID=orquestrador-mvp-12345
GCP_REGION=us-central1
DATABASE_URL=postgresql://orquestrador:Orm@2026!@35.192.120.50:5432/orquestrador_db
CLOUD_SQL_CONNECTION_NAME=orquestrador-mvp-12345:us-central1:orquestrador-db
ENVIRONMENT=development
DEBUG=true
```

⚠️ **IMPORTANTE:** Nunca compartilhe este arquivo `.env`! Ele contém suas senhas!

---

## PASSO 4: Instalar Dependências Python

Abra **PowerShell** na pasta do projeto:

```powershell
# Ativar ambiente virtual (já deve estar ativo)
# & .\venv\Scripts\Activate.ps1

# Instalar dependências
pip install -r requirements.txt

# Verificar que funcionou
pip list | Select-String "fastapi|psycopg2"
```

---

## ✅ Checklist - Fase 2 Concluída

- [ ] Autenticado no Google Cloud (`gcloud auth list` mostra sua conta)
- [ ] Project ID configurado como padrão
- [ ] Arquivo `.env` criado e preenchido
- [ ] `GOOGLE_APPLICATION_CREDENTIALS` configurado
- [ ] Dependências instaladas

**Próximo: Fase 3 - Testar Localmente (opcional)**

---

# FASE 3: Testar Localmente (Opcional)

**⏱️ Tempo: ~5 minutos**

Teste a aplicação no seu PC antes de fazer deploy.

---

## PASSO 1: Testar Conexão com Banco de Dados

```powershell
# Instalar psql (client PostgreSQL) se não tiver
# Windows: https://www.postgresql.org/download/windows/

# Testar conexão
psql -h SEU_IP_PUBLICO -U orquestrador -d orquestrador_db -c "SELECT 1"

# Exemplo:
psql -h 35.192.120.50 -U orquestrador -d orquestrador_db -c "SELECT 1"
```

Se aparecer `1`, conectou com sucesso! ✅

---

## PASSO 2: Rodar a Aplicação Localmente

```powershell
# Ir para a pasta do projeto
cd D:\vitor\Pessoal\PJ\Orquestrador

# Rodar a aplicação FastAPI
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

Seu terminal mostrará:

```
INFO:     Uvicorn running on http://127.0.0.1:8000
```

Deixe rodar!

---

## PASSO 3: Testar Endpoints

Abra outro **PowerShell** (enquanto a aplicação está rodando):

```powershell
# Testar endpoint de saúde
curl -X GET "http://localhost:8000/docs"

# Ou abra no navegador: http://localhost:8000/docs
```

Você verá a **Swagger UI** (interface visual da API).

---

## PASSO 4: Testar Chat Endpoint

```powershell
# Fazer uma requisição POST
curl -X POST "http://localhost:8000/chat" `
  -H "Content-Type: application/json" `
  -d @'{
    "message": "Quero um carro até 50000 reais",
    "user_id": "test"
  }'
```

Se receber resposta → Aplicação está funcionando! ✅

---

## PASSO 5: Parar a Aplicação

No PowerShell onde a aplicação está rodando:

```powershell
# Pressione: Ctrl + C
```

---

## ✅ Checklist - Fase 3 Concluída

- [ ] Conectou ao banco de dados com sucesso
- [ ] Aplicação rodou localmente
- [ ] Swagger UI acessível em http://localhost:8000/docs
- [ ] Endpoint de chat respondeu

**Próximo: Fase 4 - Deploy no Cloud Run**

---

# FASE 4: Deploy no Cloud Run

**⏱️ Tempo: ~10 minutos**

Colocar sua aplicação online no Google Cloud!

---

## PASSO 1: Usar o Script de Deploy

Na raiz do projeto, existe um script `deploy.sh` que faz tudo automaticamente.

### Para Windows (PowerShell):

```powershell
# Ir para a pasta do projeto
cd D:\vitor\Pessoal\PJ\Orquestrador

# Executar deploy
bash deploy.sh SEU-PROJECT-ID us-central1

# Exemplo:
bash deploy.sh orquestrador-mvp-12345 us-central1
```

### O que este script faz:

1. Faz build da imagem Docker
2. Envia a imagem para o Registro de Artefatos
3. Deploy automático no Cloud Run
4. Configura variáveis de ambiente
5. Libera acesso público

**Aguarde ~5-10 minutos** enquanto o script roda.

---

## PASSO 2: Monitorar o Deploy

Você verá logs na tela mostrando o progresso:

```
Building Docker image...
Building image gcr.io/seu-projeto/orquestrador:latest
...
Pushing image to Container Registry...
...
Deploying to Cloud Run...
...
Deployment completed!
```

---

## PASSO 3: Obter URL de Acesso

Quando o deploy terminar, execute:

```powershell
# Obter URL do Cloud Run
gcloud run services describe orquestrador `
  --region=us-central1 `
  --format='value(status.url)'
```

Você verá algo como:

```
https://orquestrador-xxxxx.a.run.app
```

**Copie esta URL!** Você usará para acessar a aplicação.

---

## ✅ Checklist - Fase 4 Concluída

- [ ] Deploy script executado sem erros
- [ ] Imagem Docker criada
- [ ] Imagem enviada para Registro de Artefatos
- [ ] Serviço Cloud Run criado
- [ ] URL de acesso obtida
- [ ] URL de acesso: `_________________________________`

**Próximo: Fase 5 - Verificar e Testar**

---

# FASE 5: Verificar e Testar

**⏱️ Tempo: ~3 minutos**

Validar que tudo está funcionando online.

---

## PASSO 1: Testar Swagger UI Online

No navegador, acesse:

```
https://SUA-URL-DO-CLOUD-RUN/docs
```

Exemplo:

```
https://orquestrador-xxxxx.a.run.app/docs
```

Você deve ver a interface Swagger UI com todos os endpoints.

---

## PASSO 2: Testar Chat Endpoint

Na Swagger UI:

1. Clique em **POST /chat**
2. Clique **"Try it out"**
3. No campo **"Request body"**, preencha:
   ```json
   {
     "message": "Quero um carro até 50000 reais",
     "user_id": "test"
   }
   ```
4. Clique **"Execute"**

Você deve receber uma resposta do LLM integrado! ✅

---

## PASSO 3: Testar via Curl (Terminal)

```powershell
# Substituir pela sua URL
$URL = "https://orquestrador-xxxxx.a.run.app"

curl -X POST "$URL/chat" `
  -H "Content-Type: application/json" `
  -d @'{
    "message": "Quero um carro até 50000 reais",
    "user_id": "test"
  }'
```

---

## PASSO 4: Ver Logs

Para debugar se algo não funcionar:

```powershell
# Ver últimos 50 logs
gcloud run logs read orquestrador --region=us-central1 --limit=50

# Ver logs em tempo real (streaming)
gcloud run logs read orquestrador --region=us-central1 --follow
```

---

## ✅ Checklist - Fase 5 Concluída

- [ ] Swagger UI acessível online
- [ ] Chat endpoint respondeu
- [ ] Curl funcionou
- [ ] Aplicação está ONLINE! 🎉

---

## 🎉 Sucesso!

Sua aplicação está **online e funcionando**!

### Resumo do que você fez:

1. ✅ Ativou 6 APIs no Google Cloud
2. ✅ Criou Cloud SQL PostgreSQL com usuário e banco
3. ✅ Criou Service Account com permissões
4. ✅ Criou Registro de Artefatos
5. ✅ Configurou arquivo `.env` localmente
6. ✅ Testou localmente
7. ✅ Fez deploy no Cloud Run
8. ✅ Validou que funciona online

---

## 📋 Referência Rápida para Próximas Vezes

### Fazer novo deploy após mudanças:

```powershell
cd D:\vitor\Pessoal\PJ\Orquestrador
bash deploy.sh SEU-PROJECT-ID us-central1
```

### Ver status do serviço:

```powershell
gcloud run services describe orquestrador --region=us-central1
```

### Ver logs:

```powershell
gcloud run logs read orquestrador --region=us-central1 --limit=50 --follow
```

### Parar o serviço:

```powershell
gcloud run services delete orquestrador --region=us-central1
```

---

# Troubleshooting

## Problema: "Erro ao conectar ao banco de dados"

**Solução:**

1. Verifique se IP público está correto: `gcloud sql instances describe orquestrador-db --format="value(ipAddresses[0].ipAddress)"`
2. Verifique arquivo `.env` - DATABASE_URL está correto?
3. Verifique se usuário `orquestrador` foi criado
4. Teste: `psql -h IP -U orquestrador -d orquestrador_db -c "SELECT 1"`

## Problema: "Cloud Run não consegue conectar ao banco"

**Solução:**

1. Verifique se Cloud SQL Connection Name está correto no `.env`
2. Verifique se a rede foi criada
3. Cloud Run precisa estar na mesma região do Cloud SQL

## Problema: "Imagem Docker não está sendo enviada"

**Solução:**

1. Verifique se Docker está instalado: `docker --version`
2. Verifique se Registro de Artefatos foi criado no console
3. Verifique autenticação: `gcloud auth login`

## Problema: "Erro ao ativar API"

**Solução:**

1. Confirme que você tem permissão no projeto (pedir ao admin)
2. Espere 1-2 minutos e tente novamente
3. Ao comando: `gcloud services enable cloudrun.googleapis.com`

## Problema: "404 - Endpoint não encontrado"

**Solução:**

1. Confirme a URL está correta: `gcloud run services describe orquestrador --region=us-central1 --format="value(status.url)"`
2. Verifique se o deploy completou: `gcloud run services describe orquestrador --region=us-central1`
3. Aguarde ~1 minuto após o deploy terminar

---

## 📞 Próximos Passos

- **Integrar com Banco de Dados Real**: Configurar seeders de dados
- **CI/CD Automático**: GitHub Actions para deploy automático
- **Monitoramento**: Configurar alertas e dashboards
- **Escalabilidade**: Ajustar autoscaling de Cloud Run

---

**Dúvidas? Refer-se a:**

- [DEPLOY_5_PASSOS.md](DEPLOY_5_PASSOS.md) - Resumo rápido
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Problemas específicos
- [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) - Estrutura do projeto

**Bom deployment! 🚀**