Add files via upload
This commit is contained in:
Marcos Lohmann
353
GenAI/mcp/sample1/vibe/09-VALIDATION.md
Normal file
353
GenAI/mcp/sample1/vibe/09-VALIDATION.md
Normal file
@@ -0,0 +1,353 @@
|
||||
# 09 - Validação Final do Projeto
|
||||
|
||||
## 🎯 Objetivo
|
||||
|
||||
Fornecer um checklist completo e comandos para validar que o projeto foi gerado corretamente e está funcional.
|
||||
|
||||
## 📋 Contexto
|
||||
|
||||
Esta é a última etapa do processo de Vibe Coding. Aqui você verifica se todos os componentes foram gerados corretamente e se o sistema funciona como esperado.
|
||||
|
||||
## 🔧 Especificações Técnicas
|
||||
|
||||
- **Tipo:** Checklist de validação
|
||||
- **Comandos:** Bash para verificação
|
||||
- **Resultado:** Confirmação de sucesso ou identificação de problemas
|
||||
|
||||
---
|
||||
|
||||
## 💬 PROMPT PARA O LLM
|
||||
|
||||
```
|
||||
Crie um guia de validação completo para verificar se um projeto Python MCP foi gerado corretamente.
|
||||
|
||||
O guia deve incluir:
|
||||
|
||||
1. CHECKLIST DE ARQUIVOS
|
||||
Lista de todos os arquivos que devem existir com tamanho aproximado em linhas
|
||||
|
||||
2. COMANDOS DE VERIFICAÇÃO
|
||||
Comandos bash para:
|
||||
- Listar arquivos do projeto
|
||||
- Verificar sintaxe Python de cada arquivo .py
|
||||
- Contar linhas de cada arquivo
|
||||
- Verificar permissões executáveis
|
||||
|
||||
3. VALIDAÇÃO DE CONTEÚDO
|
||||
Para cada arquivo principal, lista de verificações:
|
||||
- Imports esperados
|
||||
- Funções/classes principais
|
||||
- Configurações importantes
|
||||
|
||||
4. TESTE DE INSTALAÇÃO
|
||||
Comandos para:
|
||||
- Criar ambiente virtual
|
||||
- Instalar dependências
|
||||
- Verificar instalação
|
||||
|
||||
5. TESTE FUNCIONAL
|
||||
Comandos para:
|
||||
- Executar testes automatizados
|
||||
- Verificar saída esperada
|
||||
|
||||
6. TROUBLESHOOTING
|
||||
Problemas comuns e soluções
|
||||
|
||||
Formato: Markdown com blocos de código bash e checklists.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ CHECKLIST DE VALIDAÇÃO MANUAL
|
||||
|
||||
Use este checklist para validar seu projeto:
|
||||
|
||||
### 📁 Arquivos Obrigatórios
|
||||
|
||||
```bash
|
||||
# Verificar estrutura do projeto
|
||||
cd mcp_project
|
||||
ls -la
|
||||
```
|
||||
|
||||
**Arquivos esperados:**
|
||||
- [ ] `mcp_server.py` (~253 linhas)
|
||||
- [ ] `mcp_client.py` (~294 linhas)
|
||||
- [ ] `test_system.py` (~97 linhas)
|
||||
- [ ] `requirements.txt` (2 linhas)
|
||||
- [ ] `run.sh` (~29 linhas, executável)
|
||||
- [ ] `README.md` (~472 linhas)
|
||||
- [ ] `QUICKSTART.md` (~202 linhas)
|
||||
- [ ] `CHANGELOG.md` (~128 linhas)
|
||||
- [ ] `venv/` (diretório do ambiente virtual)
|
||||
|
||||
### 🔍 Validação de Sintaxe
|
||||
|
||||
```bash
|
||||
# Verificar sintaxe de todos os arquivos Python
|
||||
python -m py_compile mcp_server.py
|
||||
python -m py_compile mcp_client.py
|
||||
python -m py_compile test_system.py
|
||||
|
||||
# Se não houver erro, sintaxe está correta
|
||||
echo "✅ Sintaxe validada"
|
||||
```
|
||||
|
||||
### 📊 Contagem de Linhas
|
||||
|
||||
```bash
|
||||
# Verificar tamanho dos arquivos
|
||||
wc -l *.py *.md *.txt *.sh 2>/dev/null
|
||||
```
|
||||
|
||||
**Saída esperada:**
|
||||
```
|
||||
253 mcp_server.py
|
||||
294 mcp_client.py
|
||||
97 test_system.py
|
||||
472 README.md
|
||||
202 QUICKSTART.md
|
||||
128 CHANGELOG.md
|
||||
29 run.sh
|
||||
2 requirements.txt
|
||||
1477 total
|
||||
```
|
||||
|
||||
### 🔧 Validação de Conteúdo
|
||||
|
||||
#### mcp_server.py
|
||||
```bash
|
||||
# Verificar imports e estrutura
|
||||
grep -E "from mcp.server import|@app.list_tools|@app.call_tool" mcp_server.py
|
||||
```
|
||||
|
||||
**Esperado:**
|
||||
- ✅ `from mcp.server import Server`
|
||||
- ✅ `@app.list_tools()`
|
||||
- ✅ `@app.call_tool()`
|
||||
|
||||
#### mcp_client.py
|
||||
```bash
|
||||
# Verificar configurações da API
|
||||
grep -E "API_BASE_URL|API_KEY|MODEL_NAME" mcp_client.py
|
||||
```
|
||||
|
||||
**Esperado:**
|
||||
- ✅ `API_BASE_URL = "https://api.xptoai.com.br/genai/grokcode/v1"`
|
||||
- ✅ `API_KEY = "biasb986lk657fsdv6d3543vs5b65s7v373sd321vsdv4sdv34bv3f4hb5f4j6mn546tu"`
|
||||
- ✅ `MODEL_NAME = "grok-2-1212"`
|
||||
|
||||
#### test_system.py
|
||||
```bash
|
||||
# Verificar casos de teste
|
||||
grep -c "descricao" test_system.py
|
||||
```
|
||||
|
||||
**Esperado:** 8 (8 casos de teste)
|
||||
|
||||
#### requirements.txt
|
||||
```bash
|
||||
# Verificar dependências
|
||||
cat requirements.txt
|
||||
```
|
||||
|
||||
**Esperado:**
|
||||
```
|
||||
mcp==1.23.1
|
||||
openai==2.8.1
|
||||
```
|
||||
|
||||
#### run.sh
|
||||
```bash
|
||||
# Verificar se é executável
|
||||
ls -l run.sh | grep -E "^-rwxr"
|
||||
```
|
||||
|
||||
**Esperado:** Permissões de execução presentes
|
||||
|
||||
### 🚀 Teste de Instalação
|
||||
|
||||
```bash
|
||||
# 1. Criar ambiente virtual (se ainda não existe)
|
||||
python3.11 -m venv venv
|
||||
|
||||
# 2. Ativar ambiente virtual
|
||||
source venv/bin/activate
|
||||
|
||||
# 3. Instalar dependências
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 4. Verificar instalação
|
||||
pip list | grep -E "mcp|openai"
|
||||
```
|
||||
|
||||
**Saída esperada:**
|
||||
```
|
||||
mcp 1.23.1
|
||||
openai 2.8.1
|
||||
```
|
||||
|
||||
### 🧪 Teste Funcional
|
||||
|
||||
```bash
|
||||
# Executar testes automatizados
|
||||
source venv/bin/activate
|
||||
python test_system.py
|
||||
```
|
||||
|
||||
**Saída esperada:**
|
||||
```
|
||||
============================================================
|
||||
TESTE AUTOMATIZADO - Sistema MCP
|
||||
============================================================
|
||||
|
||||
✓ Conectado ao servidor MCP
|
||||
✓ Ferramentas disponíveis: ['soma', 'subtracao', 'multiplicacao', 'divisao']
|
||||
|
||||
📝 Executando sequência de testes...
|
||||
|
||||
[Teste 1/8] Teste de Soma
|
||||
...
|
||||
[Teste 8/8] Teste de Linguagem Natural - Subtração
|
||||
...
|
||||
|
||||
✅ Todos os testes concluídos!
|
||||
|
||||
Resumo dos testes:
|
||||
✓ Soma
|
||||
✓ Subtração
|
||||
✓ Multiplicação
|
||||
✓ Divisão
|
||||
✓ Tratamento de erro (divisão por zero)
|
||||
✓ Operação não implementada
|
||||
✓ Interpretação de linguagem natural
|
||||
```
|
||||
|
||||
### ✅ Validação Final
|
||||
|
||||
Se todos os itens acima passaram:
|
||||
|
||||
```bash
|
||||
echo "🎉 PROJETO VALIDADO COM SUCESSO!"
|
||||
echo "✅ Todos os arquivos presentes"
|
||||
echo "✅ Sintaxe Python correta"
|
||||
echo "✅ Dependências instaladas"
|
||||
echo "✅ Testes funcionais passando"
|
||||
echo ""
|
||||
echo "Você pode agora usar o sistema:"
|
||||
echo " ./run.sh"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Problema: Arquivo faltando
|
||||
**Solução:** Volte ao prompt correspondente e gere novamente
|
||||
|
||||
### Problema: Erro de sintaxe Python
|
||||
**Solução:**
|
||||
```bash
|
||||
# Ver detalhes do erro
|
||||
python -m py_compile arquivo.py
|
||||
# Corrija o erro ou regenere o arquivo
|
||||
```
|
||||
|
||||
### Problema: Dependências não instalam
|
||||
**Solução:**
|
||||
```bash
|
||||
# Atualizar pip
|
||||
pip install --upgrade pip
|
||||
|
||||
# Tentar novamente
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Problema: Testes falham
|
||||
**Solução:**
|
||||
1. Verifique se API key está correta em mcp_client.py
|
||||
2. Verifique conexão com internet
|
||||
3. Confirme que mcp_server.py está no mesmo diretório
|
||||
|
||||
### Problema: "Permission denied" ao executar run.sh
|
||||
**Solução:**
|
||||
```bash
|
||||
chmod +x run.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Resumo de Validação
|
||||
|
||||
| Componente | Validação | Status |
|
||||
|------------|-----------|--------|
|
||||
| Arquivos | 8 arquivos presentes | ⬜ |
|
||||
| Sintaxe | Python válido | ⬜ |
|
||||
| Linhas | ~1.477 linhas total | ⬜ |
|
||||
| Dependências | mcp + openai instalados | ⬜ |
|
||||
| Testes | 8 testes passando | ⬜ |
|
||||
|
||||
**Marque cada item quando validado!**
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Próximos Passos
|
||||
|
||||
Após validação bem-sucedida:
|
||||
|
||||
1. **Explorar o sistema:**
|
||||
```bash
|
||||
./run.sh
|
||||
```
|
||||
|
||||
2. **Testar diferentes operações:**
|
||||
- Soma: "Quanto é 10 mais 5?"
|
||||
- Subtração: "Subtraia 3 de 20"
|
||||
- Multiplicação: "Multiplique 7 por 8"
|
||||
- Divisão: "Divida 50 por 2"
|
||||
|
||||
3. **Experimentar linguagem natural:**
|
||||
- "Eu tenho 30 laranjas e dei 12"
|
||||
- "Se eu ganho 1500 e gasto 800"
|
||||
|
||||
4. **Testar casos de erro:**
|
||||
- "Divida 10 por 0"
|
||||
- "Calcule raiz quadrada de 16"
|
||||
|
||||
5. **Customizar o projeto:**
|
||||
- Adicionar novas operações
|
||||
- Modificar o system prompt
|
||||
- Criar novos testes
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Conclusão
|
||||
|
||||
Se você chegou até aqui e todos os testes passaram:
|
||||
|
||||
**PARABÉNS! 🎊**
|
||||
|
||||
Você recriou com sucesso o projeto **Sistema MCP com AI Agent - Calculadora Inteligente v2.0** usando **Vibe Coding**!
|
||||
|
||||
O projeto está:
|
||||
- ✅ Completo
|
||||
- ✅ Funcional
|
||||
- ✅ Testado
|
||||
- ✅ Documentado
|
||||
- ✅ Pronto para uso
|
||||
|
||||
**Divirta-se explorando e expandindo o sistema!** 🚀✨
|
||||
|
||||
---
|
||||
|
||||
## 📞 Suporte
|
||||
|
||||
Se encontrar problemas:
|
||||
1. Revise o checklist acima
|
||||
2. Consulte a seção de troubleshooting
|
||||
3. Verifique os prompts originais
|
||||
4. Regenere arquivos problemáticos
|
||||
|
||||
---
|
||||
|
||||
**Fim do Guia de Vibe Coding** 🎨
|
||||
Reference in New Issue
Block a user