🚀 Guia de Setup Completo - C-Suite

Este guia fornece instruções passo a passo para configurar todo o ecossistema C-Suite do zero.

📋 Índice

Pré-requisitos
Setup Inicial
Configuração do Ambiente
Setup por App
Verificação e Testes
Troubleshooting
Próximos Passos

🔧 Pré-requisitos

Software Necessário

Python 3.11+ - Para apps Python
Docker & Docker Compose - Para containerização (recomendado)
MySQL 8.0+ - Banco de dados (ou acesso ao RDS)
Git - Para clonar repositórios
Acesso ao RDS - vallery.catmgckfixum.sa-east-1.rds.amazonaws.com (produção)

Opcional (mas recomendado)

Redis - Para cache (pode usar Docker)
ClickHouse - Para telemetria (pode usar Docker)
Kafka - Para eventos CDC (pode usar Docker)

Permissões Necessárias

Acesso de leitura/escrita ao banco MySQL
Permissão para criar schemas e tabelas
Permissão para executar procedures
Acesso SSH ao servidor (se deploy remoto)

🏁 Setup Inicial

1. Clonar/Navegar para o Repositório

cd /home/ec2-user/enviroment/apps/c-suite

2. Verificar Estrutura

ls -la
# Deve mostrar:
# - 4c/
# - 4c-suite/
# - csuite-context/
# - csuite-executive/
# - csuite-sales-manager/
# - .env (será criado)

⚙️ Configuração do Ambiente

1. Criar Arquivo .env

# Na raiz do projeto
cd /home/ec2-user/enviroment/apps/c-suite

# Se existir .env.example, copie:
cp .env.example .env

# Ou crie manualmente:
touch .env

2. Configurar Variáveis de Ambiente

Edite o arquivo .env com suas credenciais:

# ============================================
# Banco de Dados MySQL (RDS)
# ============================================
DB_HOST=vallery.catmgckfixum.sa-east-1.rds.amazonaws.com
DB_PORT=3306
DB_USER=core
DB_PASSWORD=sua_senha_real_aqui
DB_NAME=csuite

# C-Suite Database (alias para compatibilidade)
CSUITE_DB_HOST=vallery.catmgckfixum.sa-east-1.rds.amazonaws.com
CSUITE_DB_PORT=3306
CSUITE_DB_USER=core
CSUITE_DB_PASSWORD=sua_senha_real_aqui
CSUITE_DB_NAME=csuite
CSUITE_DB_STAGING_NAME=csuite_staging

# 4C Database
MYSQL_HOST=vallery.catmgckfixum.sa-east-1.rds.amazonaws.com
MYSQL_PORT=3306
MYSQL_USER=core
MYSQL_PASSWORD=sua_senha_real_aqui
MYSQL_DB=core

# ============================================
# URLs de APIs (para desenvolvimento local)
# ============================================
FOURC_DECISION_API_URL=http://localhost:8001
CSUITE_API_URL=http://localhost:8002

# ============================================
# Redis (opcional, para desenvolvimento)
# ============================================
REDIS_HOST=localhost
REDIS_PORT=6379

# ============================================
# ClickHouse (opcional)
# ============================================
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123

# ============================================
# LLM Configuration (opcional)
# ============================================
LLM_ENABLED=false
LLM_PROVIDER=
LLM_OLLAMA_URL=http://localhost:11434

3. Verificar Permissões do Arquivo

chmod 600 .env  # Apenas o dono pode ler/escrever

⚠️ IMPORTANTE: Nunca commite o arquivo .env no git!

📦 Setup por App

1. 4c (Córtex Comercial)

Opção A: Docker Compose (Recomendado)

cd 4c

# Criar .env específico do 4c (se necessário)
cp .env.example .env  # Se existir
# Edite com as credenciais do banco

# Iniciar serviços
docker-compose up -d

# Verificar logs
docker-compose logs -f

Opção B: Desenvolvimento Local

cd 4c

# Criar ambiente virtual
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# ou
.venv\Scripts\activate  # Windows

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

# Configurar .env (na raiz do 4c)
# Edite 4c/.env com as variáveis necessárias

# Iniciar serviços individualmente
# Feature Service
cd api/feature_service
uvicorn main:app --host 0.0.0.0 --port 8081

# Scoring Service
cd api/scoring_service
uvicorn main:app --host 0.0.0.0 --port 8082

# Decision API
cd api/decision_api
uvicorn main:app --host 0.0.0.0 --port 8083

Verificação:

curl http://localhost:8083/health
# Deve retornar: {"status":"ok"}

2. csuite-executive (Córtex Executivo)

cd csuite-executive

# Criar ambiente virtual
python3 -m venv .venv
source .venv/bin/activate

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

# O app já carrega .env da raiz do projeto
# Certifique-se de que o .env na raiz está configurado

# Executar aplicação
cd csuite-api
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Verificação:

curl http://localhost:8000/health
# Deve retornar: {"status":"ok"}

# Acessar dashboard
# http://localhost:8000/ui/

Setup Inicial do Banco (se necessário):

cd csuite-api
python -m app.cli check-health
python -m app.cli provision-data --seed-org-id 1

3. 4c-suite (Orquestrador)

cd 4c-suite

# Criar ambiente virtual
python3 -m venv .venv
source .venv/bin/activate

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

# O app carrega .env da raiz
# Certifique-se de que FOURC_DECISION_API_URL e CSUITE_API_URL estão configurados

# Executar aplicação
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Verificação:

curl http://localhost:8000/health
# Deve retornar: {"status":"ok"}

# Testar orquestração (requer 4c e csuite-executive rodando)
curl http://localhost:8000/organismo/1/status

4. csuite-context (API de Contexto)

cd csuite-context/approot

# Criar ambiente virtual
python3 -m venv .venv
source .venv/bin/activate

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

# O app carrega .env da raiz (parents[2])
# Certifique-se de que o .env está configurado

# Executar aplicação
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Verificação:

curl http://localhost:8000/health
# Deve retornar: {"status":"ok"}

# Testar endpoints
curl "http://localhost:8000/api/csuite/events?org_id=1&limit=10"

Jobs Automatizados (Opcional):

# Detecção de tendências
python3 scripts/run_trends_detection.py

# Detecção de context shift
python3 scripts/run_context_shift_detection.py 1

5. csuite-sales-manager (Gerente de Vendas)

Opção A: Docker Compose (Recomendado)

cd csuite-sales-manager

# Configurar variáveis (usa .env da raiz ou variáveis de ambiente)
export DB_HOST=vallery.catmgckfixum.sa-east-1.rds.amazonaws.com
export DB_USER=core
export DB_PASSWORD=sua_senha
export DB_NAME=csuite

# Iniciar serviços
docker-compose up -d --build

# Verificar logs
docker-compose logs -f manager-api
docker-compose logs -f decision-api

Opção B: Desenvolvimento Local

cd csuite-sales-manager

# Manager API
cd manager-api
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

# Decision API (em outro terminal)
cd decision-api
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8002

Verificação:

# Manager API
curl http://localhost:8001/health
# Deve retornar: {"status":"ok"}

# Decision API
curl http://localhost:8002/health
# Deve retornar: {"status":"ok"}

# Testar endpoints
curl http://localhost:8001/manager/today
curl -X POST http://localhost:8002/4c/decide -H "Content-Type: application/json" -d '{"revenda_id": 1}'

Executar Job de Refresh:

cd context-jobs
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python job_refresh_radar.py

✅ Verificação e Testes

Checklist de Verificação

Execute este checklist para garantir que tudo está funcionando:

# 1. Verificar conexão com banco
mysql -h vallery.catmgckfixum.sa-east-1.rds.amazonaws.com -u core -p
# Deve conectar sem erros

# 2. Verificar schemas existentes
mysql> SHOW DATABASES;
# Deve mostrar: staging, core, csuite_staging, csuite, context_radar

# 3. Testar cada app
curl http://localhost:8083/health  # 4c Decision API
curl http://localhost:8000/health  # csuite-executive
curl http://localhost:8000/health  # 4c-suite
curl http://localhost:8000/health  # csuite-context
curl http://localhost:8001/health  # sales-manager (Manager API)
curl http://localhost:8002/health  # sales-manager (Decision API)

# 4. Verificar documentação Swagger
# Abra no navegador:
# - http://localhost:8083/docs (4c)
# - http://localhost:8000/docs (csuite-executive, 4c-suite, csuite-context)
# - http://localhost:8001/docs (sales-manager Manager API)
# - http://localhost:8002/docs (sales-manager Decision API)

Testes de Integração

# Testar orquestração completa (requer todos os apps rodando)
curl http://localhost:8000/organismo/1/status
# Deve retornar status consolidado

# Testar sales manager
curl http://localhost:8001/seller/1/today
# Deve retornar tasks do vendedor (se houver dados)

🔧 Troubleshooting

Problema: Erro de Conexão com Banco

Sintomas:

MySQLdb.OperationalError: (2002, "Can't connect to server")

Soluções:
1. Verificar se o host está correto no .env
2. Verificar se a porta está aberta (firewall)
3. Testar conexão manual:
bash mysql -h vallery.catmgckfixum.sa-east-1.rds.amazonaws.com -u core -p
4. Verificar se o IP está autorizado no RDS (Security Groups)

Problema: Módulo não encontrado

Sintomas:

ModuleNotFoundError: No module named 'fastapi'

Soluções:
1. Verificar se o ambiente virtual está ativado:
bash which python # Deve apontar para .venv/bin/python
2. Reinstalar dependências:
bash pip install -r requirements.txt
3. Verificar se está no diretório correto do app

Problema: Porta já em uso

Sintomas:

OSError: [Errno 98] Address already in use

Soluções:
1. Encontrar processo usando a porta:
bash lsof -i :8000 # Linux/Mac netstat -ano | findstr :8000 # Windows
2. Matar o processo ou usar outra porta:
bash uvicorn app.main:app --port 8001

Problema: .env não está sendo carregado

Sintomas:
- Apps usam valores padrão ao invés dos do .env

Soluções:
1. Verificar se o .env está na raiz do projeto:
bash ls -la /home/ec2-user/enviroment/apps/c-suite/.env
2. Verificar se python-dotenv está instalado:
bash pip list | grep python-dotenv
3. Verificar caminho relativo no código (deve ser parents[N] correto)
4. Testar carregamento manual:
python from dotenv import load_dotenv from pathlib import Path load_dotenv(Path(__file__).resolve().parents[2] / ".env") print(os.getenv("DB_HOST"))

Problema: Erro ao compilar mysqlclient

Sintomas:

error: subprocess-exited-with-error
Exception: Can not find valid pkg-config name.

Soluções:
1. Instalar dependências do sistema:
bash sudo apt-get update sudo apt-get install -y pkg-config default-libmysqlclient-dev build-essential
2. Ou usar Docker (já tem dependências instaladas)

Problema: Schemas não existem no banco

Sintomas:

Unknown database 'csuite'

Soluções:
1. Criar schemas manualmente:
sql CREATE DATABASE IF NOT EXISTS csuite; CREATE DATABASE IF NOT EXISTS csuite_staging; CREATE DATABASE IF NOT EXISTS context_radar;
2. Executar scripts de schema (se existirem):
bash # csuite-executive cd csuite-executive mysql -h ... -u ... -p < schema.sql mysql -h ... -u ... -p < staging.sql

Problema: Apps não se comunicam

Sintomas:
- 4c-suite retorna erros ao chamar outros apps

Soluções:
1. Verificar se todos os apps estão rodando:
bash curl http://localhost:8001/health # 4c curl http://localhost:8002/health # csuite-executive
2. Verificar URLs no .env:
bash grep FOURC_DECISION_API_URL .env grep CSUITE_API_URL .env
3. Verificar se as portas estão corretas
4. Verificar firewall/network policies

Problema: Docker build falha

Sintomas:

ERROR: failed to solve: process did not complete successfully

Soluções:
1. Limpar cache do Docker:
bash docker system prune -a
2. Rebuild sem cache:
bash docker-compose build --no-cache
3. Verificar Dockerfile para erros de sintaxe
4. Verificar se todas as dependências estão no requirements.txt

📝 Próximos Passos

Após o setup inicial:

Configurar Schemas do Banco
Executar scripts SQL de criação de tabelas
Popular dados iniciais (se necessário)
Configurar Jobs Automatizados
Cron jobs para refresh do radar (sales-manager)
Jobs de detecção de tendências (csuite-context)
Sincronização 4C → C-Suite
Configurar Monitoramento
Prometheus/Grafana (já configurado no 4c)
Logs centralizados
Alertas
Deploy em Produção
Usar Docker Swarm stacks
Configurar Traefik
Configurar secrets do Docker Swarm
Ver: RUNBOOKS_OPERACIONAIS.md para procedimentos detalhados
Documentação Adicional
Ler manuais específicos de cada app
Configurar integrações externas (CRM, WhatsApp, etc.)

📚 Referências

RELACAO_ENTRE_APPS.md - Visão geral dos apps
ARQUITETURA.md - Diagramas de arquitetura
CONFIGURACAO_ENV.md - Configuração de variáveis
GLOSSARIO.md - Glossário de termos
API_DOCUMENTATION.md - Documentação de APIs
RUNBOOKS_OPERACIONAIS.md - Runbooks operacionais
MELHORIAS_SUGERIDAS.md - Melhorias futuras

🆘 Suporte

Se encontrar problemas não listados aqui:

Verificar logs dos apps:
```bash
# Docker
docker-compose logs -f [service-name]

# Local
# Logs geralmente aparecem no console
```

Verificar documentação específica de cada app:
4c/docs/ - Documentação do 4c
csuite-executive/MANUAL_USUARIO.md - Manual do C-Suite
csuite-sales-manager/README.md - Documentação do Sales Manager
Verificar issues conhecidos nos documentos de troubleshooting de cada app

Última atualização: 2025-12-01

🚀 Guia de Setup Completo - C-Suite

📋 Índice

🔧 Pré-requisitos

Software Necessário

Opcional (mas recomendado)

Permissões Necessárias

🏁 Setup Inicial

1. Clonar/Navegar para o Repositório

2. Verificar Estrutura

⚙️ Configuração do Ambiente

1. Criar Arquivo .env

2. Configurar Variáveis de Ambiente

3. Verificar Permissões do Arquivo

📦 Setup por App

1. 4c (Córtex Comercial)

Opção A: Docker Compose (Recomendado)

Opção B: Desenvolvimento Local

2. csuite-executive (Córtex Executivo)

3. 4c-suite (Orquestrador)

4. csuite-context (API de Contexto)

5. csuite-sales-manager (Gerente de Vendas)

Opção A: Docker Compose (Recomendado)

Opção B: Desenvolvimento Local

✅ Verificação e Testes

Checklist de Verificação

Testes de Integração

🔧 Troubleshooting

Problema: Erro de Conexão com Banco

Problema: Módulo não encontrado

Problema: Porta já em uso

Problema: .env não está sendo carregado

Problema: Erro ao compilar mysqlclient

Problema: Schemas não existem no banco

Problema: Apps não se comunicam

Problema: Docker build falha

📝 Próximos Passos

📚 Referências

🆘 Suporte

🔊 Text-to-Speech