testes/prafrota_fe-main/prafrota_fe-main/.mcp

Model Context Protocol (MCP) - Guia de Uso

Este diretório contém a configuração do Model Context Protocol (MCP) para o workspace Angular PraFrota.

📖 Visão Geral

O MCP organiza o contexto do projeto de forma estruturada, facilitando a colaboração entre desenvolvedores e sistemas de IA. Ele define:

• Estrutura de projetos e domínios
• Padrões de desenvolvimento
• Configurações de APIs
• Mapeamentos de dados
• Convenções de código

🗂️ Estrutura dos Arquivos MCP

.mcp/
├── config.json          # Configuração principal do MCP
├── README.md            # Este arquivo - guia de uso
└── contexts/            # Contextos específicos (futuro)

Raiz do Projeto

MCP.md                   # Documentação principal do MCP

🎯 Como Usar o MCP

1. Consulta Rápida de Contexto

Para entender rapidamente um domínio específico:

# Ver estrutura de veículos
projects/idt_app/src/app/domain/vehicles/

# Ver serviços compartilhados  
projects/idt_app/src/app/shared/services/

# Template perfeito para novos domínios
projects/idt_app/src/app/domain/drivers/drivers.component.ts

2. Onboarding de Novos Desenvolvedores

🚀 CRIAÇÃO AUTOMÁTICA DE DOMÍNIOS

Para novos desenvolvedores, use o sistema de onboarding interativo:

# Comando principal para criar novos domínios (V1 - Simples)
npm run create:domain

# Ou diretamente
node scripts/create-domain.js

# 🆕 Create-Domain V2.0 (Avançado com API Analyzer)
node scripts/create-domain-v2.js

Sistema de Onboarding Inclui:

• ✅ Verificação automática de pré-requisitos
• ✅ Questionário interativo guiado
• ✅ Geração automática de toda estrutura
• ✅ Validação de configuração Git (@grupopralog.com.br)
• ✅ Framework de telas completo

Documentação Completa:

• 📖 Guia Rápido V1 - Sistema simples
• 🚀 Create-Domain V2.0 - Sistema avançado com API Analyzer
• 🧠 Demo API Real - Como usar dados reais da API
• 📚 Onboarding Completo
• 🛠️ Scripts

3. Desenvolvimento de Novos Features

🚀 PADRÃO: BaseDomainComponent + Registry Pattern

Para novos domínios ERP, use o template otimizado com auto-registro:

# Copiar template perfeito (recomendado)
cp projects/idt_app/src/app/domain/drivers/drivers.component.ts projects/idt_app/src/app/domain/clients/clients.component.ts

Domínio com BaseDomainComponent + Auto-registro:

@Component({
  selector: 'app-clients',
  standalone: true,
  imports: [CommonModule, TabSystemComponent],
  template: `<app-tab-system #tabSystem [config]="tabConfig"></app-tab-system>`
})
export class ClientsComponent extends BaseDomainComponent<Client> {
  
  constructor(
    clientsService: ClientsService,
    titleService: TitleService,
    headerActionsService: HeaderActionsService,
    cdr: ChangeDetectorRef,
    private tabFormConfigService: TabFormConfigService // ← INJETAR
  ) {
    super(titleService, headerActionsService, cdr, new ClientsServiceAdapter(clientsService));
    
    // 🚀 AUTO-REGISTRO da configuração
    this.registerClientFormConfig();
  }

  // 🏗️ Configuração da tabela
  protected override getDomainConfig(): DomainConfig {
    return {
      domain: 'client',
      title: 'Clientes', 
      entityName: 'cliente',
      subTabs: ['dados', 'contatos'],
      columns: [/* configuração das colunas */]
    };
  }

  // 📋 Configuração do formulário (AUTO-REGISTRADA!)
  getClientFormConfig(): TabFormConfig {
    return {
      title: 'Dados do Cliente',
      entityType: 'client',
      fields: [/* configuração específica */]
    };
  }

  // 🔗 Registro automático no service (PRIVADO)
  private registerClientFormConfig(): void {
    this.tabFormConfigService.registerFormConfig('client', () => this.getClientFormConfig());
  }
}

🎯 Registry Pattern - Como Funciona:

1. Auto-registro: Component registra sua configuração no construtor
2. Registry inteligente: TabFormConfigService.getFormConfig() consulta registry primeiro
3. Prioridades: Registry > Service genérico > Default
4. Escalabilidade: Infinitos domínios sem modificar código central
5. Zero configuração: Tudo automático após implementação

Fluxo de Funcionamento:

Component → Auto-registro → Registry → Service → Sistema ✅

3. Mapeamento de Dados

Para APIs que precisam de consolidação (como Mercado Live):

// 1. Definir interfaces tipadas
interface SourceDataType {
  // campos específicos da API
}

// 2. Criar mapper
private mapSourceToTarget(source: SourceDataType): TargetType {
  return {
    id: source.sourceId,
    name: source.sourceName,
    // outros mapeamentos
  };
}

// 3. Aplicar paginação local se necessário
private applyLocalPagination(data: any[], page: number, pageSize: number) {
  const startIndex = (page - 1) * pageSize;
  const endIndex = startIndex + pageSize;
  return data.slice(startIndex, endIndex);
}

4. Desenvolvimento por Projeto

IDT App (PraFrota):

npm run serve:prafrota

Sistema de Escala:

npm run ESCALA_development

Build de Produção:

npm run build:prafrota

🔧 Configuração de APIs

Adicionando Nova API

1. Atualizar proxy.conf.json:

{
  "/api/nova-api/*": {
    "target": "https://nova-api.exemplo.com",
    "secure": true,
    "changeOrigin": true
  }
}

2. Criar service:

@Injectable({
  providedIn: 'root'
})
export class NovaApiService {
  private baseUrl = '/api/nova-api';

  constructor(private http: HttpClient) {}

  getData(): Observable<ResponseType> {
    return this.http.get<ResponseType>(`${this.baseUrl}/data`);
  }
}

3. Atualizar MCP config.json:

{
  "apis": {
    "nova-api": {
      "name": "Nova API",
      "baseUrl": "https://nova-api.exemplo.com",
      "proxy": "/api/nova-api/*"
    }
  }
}

🎨 Padrões de UI

Componente de Tabela

// Usar DataTableComponent compartilhado
<app-data-table
  [data]="tableData"
  [columns]="columnConfig"
  [pagination]="paginationConfig"
  (pageChange)="onPageChange($event)">
</app-data-table>

Formulários Reativos

// Sempre usar FormBuilder
this.form = this.fb.group({
  campo: ['', [Validators.required, Validators.minLength(3)]],
  email: ['', [Validators.required, Validators.email]]
});

Material Design

// Importar apenas os módulos necessários
imports: [
  MatTableModule,
  MatPaginatorModule,
  MatSortModule,
  MatFormFieldModule,
  MatInputModule
]

📊 Estrutura de Domínios

Criando Novo Domínio

domain/novo-dominio/
├── components/
│   ├── novo-dominio-list/
│   ├── novo-dominio-form/
│   └── novo-dominio-detail/
├── services/
│   └── novo-dominio.service.ts
├── interfaces/
│   └── novo-dominio.interface.ts
└── novo-dominio.routes.ts

Interface Padrão

export interface NovoDominio {
  id: string;
  name: string;
  status: 'active' | 'inactive';
  createdAt: Date;
  updatedAt: Date;
}

🔍 Logger Service

Uso do Logger

import { Logger } from '../shared/services/logger.service';

export class MyComponent {
  private logger = Logger.getInstance();

  ngOnInit() {
    this.logger.info('Componente inicializado', { component: 'MyComponent' });
  }

  onError(error: any) {
    this.logger.error('Erro no componente', error);
  }
}

📝 Convenções de Nomenclatura

Arquivos e Diretórios

• Componentes: vehicle-form.component.ts
• Serviços: vehicle.service.ts
• Interfaces: vehicle.interface.ts
• Diretórios: kebab-case

Classes e Propriedades

• Classes: VehicleFormComponent
• Propriedades: vehicleName
• Constantes: API_BASE_URL
• Enums: VehicleStatus

🚀 Comandos Úteis

Desenvolvimento

# Servir aplicação específica
ng serve idt_app --configuration development

# Gerar componente em domínio
ng generate component domain/vehicles/components/vehicle-detail --standalone

# Gerar service
ng generate service domain/vehicles/services/vehicle

# Executar testes
ng test idt_app

Build e Deploy

# Build de produção
ng build idt_app --configuration production

# Analisar bundle
ng build --stats-json
npx webpack-bundle-analyzer dist/idt_app/stats.json

🛡️ Proteções e Performance

Sistema Anti-Loop Infinito

O BaseDomainComponent possui proteções automáticas contra loops infinitos:

// ✅ Proteções automáticas incluídas:
- Controle de inicialização (ngOnInit único)
- Throttling de requisições (mín. 100ms)
- Estado de loading duplo
- Setup domain único
- Logs de monitoramento

// ✅ Logs de debug:
[BaseDomainComponent] Tentativa de carregamento rejeitada - já está carregando
[BaseDomainComponent] Tentativa de carregamento rejeitada - chamada muito frequente

Monitoramento de Performance

Para verificar se um domínio está funcionando corretamente:

1. DevTools → Network: Apenas 1 requisição inicial
2. Console: Sem warnings de loop
3. CPU: Performance normal
4. UX: Interface responsiva

Documentação de Proteções

• base-domain/LOOP_PREVENTION_GUIDE.md: Detalhes técnicos
• base-domain/DOMAIN_CREATION_GUIDE.md: Guia atualizado
• drivers.component.ts: Template com proteções ativas

📚 Documentação Relacionada

• MCP.md: Documentação principal do Model Context Protocol
• projects/idt_app/CURSOR.md: Documentação específica do IDT App
• README.md: Documentação geral do projeto
• base-domain/: Guias de criação de domínios e proteções

🔄 Atualizações do MCP

Quando adicionar novos padrões ou configurações:

1. Atualize config.json com as novas definições
2. Documente no MCP.md principal
3. Adicione exemplos neste README.md
4. Atualize a documentação específica do projeto se necessário

🤖 OTIMIZAÇÃO DE CONTEXTO PARA IA

Arquivos de Configuração

O projeto possui configurações específicas para otimizar o contexto da IA:

.cursorrules                 # Regras principais do Cursor
.cursor/instructions.md      # Instruções detalhadas para IA
.mcp/ai-context.json        # Contexto estruturado em JSON
.mcp/config.json            # Configuração do MCP

🎯 Configuração Implementada

1. Template de Referência OBRIGATÓRIO

• Arquivo: projects/idt_app/src/app/domain/drivers/drivers.component.ts
• Uso: Modelo perfeito para novos domínios ERP
• Contém: BaseDomainComponent + configuração completa + formatações + tratamento de erros

2. Padrões Obrigatórios para IA

// ✅ Componente Standalone
@Component({
  selector: 'app-exemplo',
  standalone: true,
  imports: [CommonModule, TabSystemComponent],
  templateUrl: './exemplo.component.html',
  styleUrl: './exemplo.component.scss'
})

// ✅ Service com Observable
@Injectable({
  providedIn: 'root'
})
export class ExemploService {
  constructor(private http: HttpClient) {}
  
  getData(): Observable<DataType[]> {
    return this.http.get<DataType[]>('/api/endpoint');
  }
}

// ✅ Interface TypeScript
export interface ExemploData {
  id: number;
  name: string;
  status: 'active' | 'inactive';
}

3. Regras Específicas para Sugestões da IA

SEMPRE Fazer:

• ✅ Verificar se existe componente similar em shared/components/
• ✅ Usar BaseDomainComponent para novos domínios ERP
• ✅ Seguir padrão do drivers.component.ts
• ✅ Incluir tratamento de erro null-safe
• ✅ Adicionar comentários em português
• ✅ Usar tipagem TypeScript forte

NUNCA Fazer:

• ❌ Componentes sem standalone: true
• ❌ Services sem Observable
• ❌ Template-driven forms
• ❌ Console.log em produção
• ❌ Imports desnecessários

🚀 Como a IA Deve Responder

Estrutura Ideal de Resposta:

## 📋 Solução:

### 1. Interface TypeScript
[código da interface]

### 2. Service
[código do service]

### 3. Component
[código do component seguindo drivers pattern]

### 4. Template (se necessário)
[código do template]

## 💡 Explicação:
[explicação clara em português do que foi implementado]

## 🔧 Como usar:
[instruções práticas de implementação]

🎨 Componentes Compartilhados Prioritários

DataTableComponent

• Path: shared/components/data-table/
• Uso: Tabela reutilizável com paginação server-side
• Features: Filtros, ordenação, ações customizáveis

TabSystemComponent

• Path: shared/components/tab-system/
• Uso: Sistema de abas para formulários complexos
• Integração: Funciona com BaseDomainComponent

BaseDomainComponent

• Path: shared/components/base-domain/
• Uso: Classe base para domínios ERP
• Configuração: Via método getDomainConfig()

🔗 APIs e Integrações

PraFrota Backend

// Response padrão esperado
interface ApiResponse<T> {
  data: T[];
  totalCount: number;
  pageCount: number;
  currentPage: number;
}

// Headers obrigatórios
headers: {
  'Authorization': 'Bearer <token>',
  'Content-Type': 'application/json'
}

ViaCEP Integration

// Proxy configurado em proxy.conf.json
// Uso: Busca de endereços por CEP
// Endpoint: /api/ws/{cep}/json/

🎯 Contexto de Desenvolvimento Atual

Domínios Principais:

1. Vehicles - Gestão completa de frota
2. Drivers - Cadastro e gestão de motoristas (TEMPLATE PERFEITO)
3. Routes - Integração com Mercado Live
4. Finances - Contas a pagar e receber

Componentes Prioritários:

1. DataTable - Performance crítica para grandes datasets
2. TabSystem - Formulários complexos com sub-abas
3. AddressForm - Integração ViaCEP
4. BaseDomain - Padrão ERP escalável

📝 Comandos de Desenvolvimento

# Servidor de desenvolvimento PraFrota
ng serve idt_app --configuration development

# Sistema de Escala
ng serve escala --configuration development

# Build de produção
ng build idt_app --configuration production

🔧 Validação de Contexto

Para garantir que a IA está aplicando corretamente os padrões:

1. Verificar standalone components: Todos os componentes devem ter standalone: true
2. Verificar BaseDomainComponent: Domínios ERP devem extends BaseDomainComponent
3. Verificar Observable: Services devem retornar Observable
4. Verificar imports: Apenas imports necessários
5. Verificar tipagem: TypeScript strong typing obrigatório

💡 Benefícios da Otimização

Para IA:

• 🤖 Respostas mais precisas baseadas no contexto específico
• 🎯 Sugestões alinhadas com padrões do projeto
• 📋 Menos iterações para chegar ao código correto
• ✨ Qualidade consistente nas sugestões

Para Desenvolvimento:

• ⚡ Produtividade aumentada com contexto claro
• 🎨 Padrões consistentes automaticamente aplicados
• 📚 Onboarding acelerado para novos desenvolvedores
• 🔧 Manutenção simplificada com documentação viva

🎯 Exemplos Práticos

Criar novo domínio:

"Crie um novo domínio 'produtos' seguindo o padrão do drivers"

Componentizar código:

"Transforme este código em componente shared reutilizável"

Otimizar performance:

"Otimize esta tabela seguindo os padrões DataTable"

🔧 CORREÇÕES DA GERAÇÃO AUTOMÁTICA DE DOMÍNIOS

📋 Problemas Identificados e Documentados

Arquivos de Documentação:

• scripts/FIXES_DOMAIN_GENERATION.md: Detalhes técnicos completos das correções
• DOMAIN_GENERATION_FIXES_SUMMARY.md: Resumo executivo das 5 correções principais

5 Erros Principais Identificados:

1. 🎨 HTML Template Incorreto

   • Problema: Template minimalista diferente do drivers.component.html
   • Correção: Usar template padrão com eventos conectados

   <div class="domain-container">
     <div class="main-content">
       <app-tab-system #tabSystem [config]="tabConfig" [events]="tabEvents" 
                       (tableEvent)="onTableEvent($event)">
       </app-tab-system>
     </div>
   </div>
   

2. 📋 SideCard Incompleto

   • Problema: Configuração sideCard faltando ou incompleta
   • Correção: SideCard completo com statusConfig, displayFields e imageField

3. 📑 Sub-abas Não Controladas

   • Problema: Múltiplas sub-abas criadas automaticamente
   • Correção: Criar apenas sub-abas solicitadas pelo usuário

4. 📊 Estrutura de Campos Legacy

   • Problema: Campos fora das sub-abas (padrão antigo)
   • Correção: Campos organizados dentro das sub-abas (padrão moderno)

5. 📖 Campos Sem Validação Swagger

   • Problema: Campos criados sem consultar documentação da API
   • Correção: Consulta obrigatória ao Swagger antes da criação

🎯 Processo de Correção Implementado:

1. Consulta Swagger Obrigatória: Validar campos na API antes da criação
2. Template Padrão: Enforçar uso do drivers.component.html pattern
3. SideCard Completo: Configuração automática com todos os elementos
4. Controle de Sub-abas: Baseado estritamente no input do usuário
5. Estrutura Moderna: Campos organizados dentro das sub-abas

✅ Qualidade Assegurada:

• Compare HTML gerado com drivers.component.html
• Verifique completude do sideCard (status, image, display)
• Valide existência dos campos no Swagger
• Teste funcionalidade das sub-abas
• Confirme binding de eventos no template

📚 Documentação Atualizada

Onboarding Melhorado:

• projects/idt_app/docs/ONBOARDING_NEW_DOMAIN.md: Adicionada seção de consulta Swagger
• scripts/README.md: Expandido troubleshooting e correções

Métricas de Qualidade:

• Tempo: 8 minutos vs 3+ horas manual
• Consistência: 100% padrões automáticos
• Produtividade: 400% aumento
• Qualidade: Templates validados e testados

---

Este guia deve ser mantido atualizado conforme a evolução do projeto e novos padrões sejam estabelecidos.