IT Valley Architecture Analyzer

Extensão VS Code para análise de arquitetura IT Valley - Arquitetura Limpa Didática Atualizada

Baseado no Guia IT Valley - Arquitetura Limpa Didática Atualizada (Domain + Factory + Service + Repo + API + Mapper)

🏗️ Arquitetura IT Valley

A arquitetura IT Valley é uma versão didática simplificada da Clean Architecture, focada em:

• Domain: Entidades ricas (regras puras) + Factory única para construir entidade a partir do DTO
• Service: Orquestra caso de uso (validações que dependem de repositório, transação, fluxo). Não mexe em campos
• Repository (Infra): Persistência concreta (em memória/SQL/ORM). Sem regra de negócio
• API: Recebe Request DTO, devolve Response DTO. Sem regra de negócio
• Mapper: Converte Entity→Response DTO na borda (API)

🔍 Regras Analisadas

1. API nunca contém regra de negócio

• ✅ Apenas Request DTO → Service e Mapper para Response
• ❌ Validações, lógica de negócio na API

2. Service não acessa campos do DTO

• ✅ Usa Factory para criar a Entity e helpers para extrair chaves de consulta
• ❌ dto.campo diretamente no Service

3. Factory é ÚNICA porta de criação

• ✅ criar_entidade(dto) - sem método estático na Entity
• ❌ Múltiplas formas de criar entidade

4. Entity SEM @staticmethod criar()

• ✅ Só Factory cria entidades
• ❌ Métodos estáticos de criação na Entity

5. Domain não importa Pydantic/FastAPI/ORM

• ✅ Usa dataclass/tipos nativos
• ❌ Imports de frameworks no Domain

6. Repository sem regra de negócio

• ✅ Apenas persistência. Mapeamentos _to_entity/_to_model privados
• ❌ Validações ou regras de negócio no Repository

7. Mapper localizado na API

• ✅ Entity → Response DTO. Preferir mapeamento explícito
• ❌ Retorno direto de Entity sem Mapper

8. Integrations/AI obrigatório

• ✅ Sempre criar integrations/ai/<entidade>/ com payloads.py e client.py
• ❌ Falta de estrutura de integração

9. Estrutura de arquivos correta

• ✅ Organização conforme guia IT Valley
• ❌ Arquivos fora da estrutura padrão

10. Única forma de criação

• ✅ Só criar_entidade() da Factory
• ❌ Múltiplos métodos de criação

📁 Estrutura de Projeto

app/
├── domain/
│   └── <feature>/
│       ├── *_entity.py
│       └── *_factory.py
├── services/
│   └── *_service.py
├── schemas/
│   └── <feature>/
│       ├── requests.py
│       └── responses.py
├── api/
│   └── *_api.py
├── mappers/
│   └── *_mapper.py
├── data/
│   ├── models/
│   │   └── *_model.py
│   └── repositories/
│       └── *_repository.py
└── integrations/
    └── ai/
        └── <feature>/
            ├── payloads.py
            └── client.py

🚀 Funcionalidades

✅ Análise Automática

• Análise em tempo real de arquivos Python
• Detecção de violações das regras IT Valley
• Integração com VS Code Problems para visualização de erros
• Sugestões de correção automáticas

🛠️ Correção Automática

• Fix automático para problemas comuns
• Refatoração guiada seguindo as regras
• Aplicação em lote de correções

🏗️ Geração de Código

• Geração completa de entidades seguindo IT Valley
• Estrutura completa: Entity, Factory, Service, Repository, API, Mapper
• Integração AI automática com payloads e client
• Schemas Pydantic para Request/Response

📊 Painéis Integrados

• Painel de Problemas: Lista todos os problemas encontrados
• Painel de Sugestões: Recomendações de melhoria
• Checklist IT Valley: Verificação completa da arquitetura

🎯 Comandos Disponíveis

📋 Exemplo de Uso

1. Análise Automática

A extensão detecta automaticamente problemas como:

# ❌ PROBLEMA: Service acessando DTO diretamente
def criar_cliente(self, dto: ClienteCreateRequest):
    nome = dto.nome  # ← Será detectado como erro
    
# ✅ CORRETO: Usando Factory helper
def criar_cliente(self, dto: ClienteCreateRequest):
    nome = ClienteFactory.nome_from(dto)  # ← Padrão IT Valley

2. Geração de Entidade

# Comando: IT Valley: Gerar Entidade Completa
# Input: Cliente
# Campos: nome (str), email (EmailStr), telefone (Optional[str])

# Gera automaticamente:
# - app/domain/cliente/cliente_entity.py
# - app/domain/cliente/cliente_factory.py  
# - app/services/cliente_service.py
# - app/schemas/cliente/requests.py
# - app/schemas/cliente/responses.py
# - app/api/clientes_api.py
# - app/mappers/cliente_mapper.py
# - app/data/models/cliente_model.py
# - app/data/repositories/cliente_repository.py
# - app/integrations/ai/cliente/payloads.py
# - app/integrations/ai/cliente/client.py

🔧 Instalação

Opção 1: Desenvolvimento

# 1. Extrair o ZIP do projeto
# 2. Instalar dependências
npm install

# 3. Compilar TypeScript
npm run compile

# 4. Abrir no VS Code e pressionar F5 para debug

Opção 2: Instalação como Extensão

# 1. Gerar pacote VSIX
npx vsce package

# 2. Instalar no VS Code
# Ctrl+Shift+P → "Extensions: Install from VSIX"

📖 Baseado no Guia IT Valley

Esta extensão implementa fielmente as regras do Guia IT Valley - Arquitetura Limpa Didática Atualizada, incluindo:

• Princípios de separação de responsabilidades
• Fluxo de ponta a ponta (Request → Service → Factory → Entity → Repository)
• Desacoplamento através de Factory e helpers
• Nomenclatura e estrutura de pastas padronizada
• Pitfalls comuns e como evitá-los
• Testes direcionadores rápidos
• Prompts para IA para geração e auditoria

🤝 Contribuição

Contribuições são bem-vindas! Esta extensão segue rigorosamente o guia IT Valley e qualquer melhoria deve manter a compatibilidade com os princípios estabelecidos.

📄 Licença

MIT License - Baseado no Guia IT Valley - Arquitetura Limpa Didática Atualizada

Desenvolvido seguindo os princípios do Guia IT Valley
Arquitetura Limpa Didática Atualizada - Domain + Factory + Service + Repo + API + Mapper